AsyncDisposableStack.prototype.use()

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

See 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
• adopt()
• defer()