AsyncDisposableStack.prototype.use()

Syntax

use(value)

Parameters

value

The value to register to the stack. Must either contain a [Symbol.asyncDispose]() or [Symbol.dispose]() method, or be null or undefined.

Return value

The same value that was passed in.

Exceptions

TypeError

Thrown if value is not null or undefined, and does not contain a [Symbol.asyncDispose]() or [Symbol.dispose]() method.

ReferenceError

Thrown if the stack is already disposed.

Examples

Using use()

This function reads a file (as a Node.js FileHandle) and returns its contents. The file handle is automatically closed when the function completes, given that the FileHandle class implements a [Symbol.asyncDispose]() method that asynchronously closes the file.

async function readFileContents(path) {
  await using disposer = new AsyncDisposableStack();
  const handle = disposer.use(await fs.open(path));
  const data = await handle.read();
  return data;
  // The disposer is disposed here, which causes handle to be closed too
}

Specifications

Browser compatibility

See also

• JavaScript resource management
• AsyncDisposableStack
• AsyncDisposableStack.prototype.adopt()
• AsyncDisposableStack.prototype.defer()