The use() method of AsyncDisposableStack instances registers a value that implements the async disposable protocol to the stack.

See DisposableStack.prototype.use() for general information about the use() method.

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()