Reference for stage 3 explicit-resource-management

files/en-us/web/javascript/guide/internationalization/index.md

@@ -5,7 +5,7 @@ page-type: guide
 sidebar: jssidebar
 ---
 
-{{PreviousNext("Web/JavaScript/Guide/Iterators_and_generators", "Web/JavaScript/Guide/Modules")}}
+{{PreviousNext("Web/JavaScript/Guide/Resource_management", "Web/JavaScript/Guide/Modules")}}
 
 The {{jsxref("Intl")}} object is the namespace for the ECMAScript Internationalization API, which provides a wide range of locale- and culture-sensitive data and operations.
 
@@ -846,4 +846,4 @@ setInterval(renderTime, 500);
 
 {{EmbedLiveSample("display_names", "", 300)}}
 
-{{PreviousNext("Web/JavaScript/Guide/Iterators_and_generators", "Web/JavaScript/Guide/Modules")}}
+{{PreviousNext("Web/JavaScript/Guide/Resource_management", "Web/JavaScript/Guide/Modules")}}

files/en-us/web/javascript/guide/iterators_and_generators/index.md

@@ -5,7 +5,7 @@ page-type: guide
 sidebar: jssidebar
 ---
 
-{{PreviousNext("Web/JavaScript/Guide/Typed_arrays", "Web/JavaScript/Guide/Internationalization")}}
+{{PreviousNext("Web/JavaScript/Guide/Typed_arrays", "Web/JavaScript/Guide/Resource_management")}}
 
 Iterators and Generators bring the concept of iteration directly into the core language and provide a mechanism for customizing the behavior of {{jsxref("Statements/for...of", "for...of")}} loops.
 
@@ -235,4 +235,4 @@ If the exception is not caught from within the generator, it will propagate up t
 
 Generators have a {{jsxref("Generator/return", "return()")}} method that returns the given value and finishes the generator itself.
 
-{{PreviousNext("Web/JavaScript/Guide/Typed_arrays", "Web/JavaScript/Guide/Internationalization")}}
+{{PreviousNext("Web/JavaScript/Guide/Typed_arrays", "Web/JavaScript/Guide/Resource_management")}}

files/en-us/web/javascript/reference/global_objects/asyncdisposablestack/adopt/index.md

@@ -0,0 +1,69 @@
+---
+title: AsyncDisposableStack.prototype.adopt()
+slug: Web/JavaScript/Reference/Global_Objects/AsyncDisposableStack/adopt
+page-type: javascript-instance-method
+browser-compat: javascript.builtins.AsyncDisposableStack.adopt
+sidebar: jsref
+---
+
+The **`adopt()`** method of {{jsxref("AsyncDisposableStack")}} instances registers a value that doesn't implement the async disposable protocol to the stack by providing a custom disposer function.
+
+See {{jsxref("DisposableStack.prototype.adopt()")}} for general information about the `adopt()` method.
+
+## Syntax
+
+```js-nolint
+adopt(value, onDispose)
+```
+
+### Parameters
+
+- `value`
+  - : Any value to be registered to the stack.
+- `onDispose`
+  - : A function that will be called when the stack is disposed. The function receives `value` as its only argument, and it can return a promise which gets awaited.
+
+### Return value
+
+The same `value` that was passed in.
+
+### Exceptions
+
+- {{jsxref("TypeError")}}
+  - : Thrown if `onDispose` is not a function.
+- {{jsxref("ReferenceError")}}
+  - : Thrown if the stack is already disposed.
+
+## Examples
+
+### Using adopt()
+
+This function creates a file handle (as a Node.js [`FileHandle`](https://nodejs.org/api/fs.html#class-filehandle)), that gets closed when the function completes. We suppose that the file handle does not implement the async disposable protocol (in reality it does), so we use `adopt()` to register it to the stack. Because the `handle.close()` method returns a promise, we need to use an `AsyncDisposableStack` so that the disposal gets awaited.
+
+```js
+async function readFile(path) {
+  await using disposer = new AsyncDisposableStack();
+  const handle = disposer.adopt(
+    fs.open(path),
+    async (handle) => await handle.close(),
+  );
+  const data = await handle.read();
+  // The handle.close() method is called and awaited here before exiting
+  return data;
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [JavaScript resource management](/en-US/docs/Web/JavaScript/Guide/Resource_management)
+- {{jsxref("AsyncDisposableStack")}}
+- {{jsxref("AsyncDisposableStack.prototype.defer()")}}
+- {{jsxref("AsyncDisposableStack.prototype.use()")}}

files/en-us/web/javascript/reference/global_objects/asyncdisposablestack/asyncdisposablestack/index.md

@@ -0,0 +1,49 @@
+---
+title: AsyncDisposableStack() constructor
+slug: Web/JavaScript/Reference/Global_Objects/AsyncDisposableStack/AsyncDisposableStack
+page-type: javascript-constructor
+browser-compat: javascript.builtins.AsyncDisposableStack.AsyncDisposableStack
+sidebar: jsref
+---
+
+The **`AsyncDisposableStack()`** constructor creates {{jsxref("AsyncDisposableStack")}} objects.
+
+## Syntax
+
+```js-nolint
+new AsyncDisposableStack()
+```
+
+> [!NOTE]
+> `AsyncDisposableStack()` can only be constructed with [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new). Attempting to call it without `new` throws a {{jsxref("TypeError")}}.
+
+### Parameters
+
+None.
+
+### Return value
+
+A new `AsyncDisposableStack` object.
+
+## Examples
+
+### Creating an AsyncDisposableStack
+
+```js
+const disposer = new AsyncDisposableStack();
+disposer.defer(() => console.log("Disposed!"));
+await disposer.disposeAsync();
+// Logs: Disposed!
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [JavaScript resource management](/en-US/docs/Web/JavaScript/Guide/Resource_management)

files/en-us/web/javascript/reference/global_objects/asyncdisposablestack/defer/index.md

@@ -0,0 +1,64 @@
+---
+title: AsyncDisposableStack.prototype.defer()
+slug: Web/JavaScript/Reference/Global_Objects/AsyncDisposableStack/defer
+page-type: javascript-instance-method
+browser-compat: javascript.builtins.AsyncDisposableStack.defer
+sidebar: jsref
+---
+
+The **`defer()`** method of {{jsxref("AsyncDisposableStack")}} instances takes a callback function to be called and awaited when the stack is disposed.
+
+See {{jsxref("DisposableStack.prototype.defer()")}} for general information about the `defer()` method.
+
+## Syntax
+
+```js-nolint
+defer(onDispose)
+```
+
+### Parameters
+
+- `onDispose`
+  - : A function that will be called when the stack is disposed. The function receives no arguments and can return a promise which gets awaited.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+### Exceptions
+
+- {{jsxref("TypeError")}}
+  - : Thrown if `onDispose` is not a function.
+- {{jsxref("ReferenceError")}}
+  - : Thrown if the stack is already disposed.
+
+## Examples
+
+### Using defer()
+
+One use case of `defer()` is to do something unrelated to resource freeing during scope exit, such as logging a message.
+
+```js
+async function doSomething() {
+  await using disposer = new AsyncDisposableStack();
+  disposer.defer(async () => {
+    await fs.writeFile("log.txt", "All resources freed successfully");
+  });
+  // Other code that claims and frees more data
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [JavaScript resource management](/en-US/docs/Web/JavaScript/Guide/Resource_management)
+- {{jsxref("AsyncDisposableStack")}}
+- {{jsxref("AsyncDisposableStack.prototype.adopt()")}}
+- {{jsxref("AsyncDisposableStack.prototype.use()")}}

files/en-us/web/javascript/reference/global_objects/asyncdisposablestack/disposeasync/index.md

@@ -0,0 +1,92 @@
+---
+title: AsyncDisposableStack.prototype.disposeAsync()
+slug: Web/JavaScript/Reference/Global_Objects/AsyncDisposableStack/disposeAsync
+page-type: javascript-instance-method
+browser-compat: javascript.builtins.AsyncDisposableStack.disposeAsync
+sidebar: jsref
+---
+
+The **`disposeAsync()`** method of {{jsxref("AsyncDisposableStack")}} instances disposes this stack by calling all disposers registered to it in reverse order of registration, awaiting for each one's completion before calling the next one. If the stack is already disposed, this method does nothing.
+
+It performs the same action as `await using disposer = new AsyncDisposableStack()` at scope exit. It can be used if you need to clean up at a point other than scope exit.
+
+## Syntax
+
+```js-nolint
+disposeAsync()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A new {{jsxref("Promise")}} that resolves with `undefined` when all registered disposers have completed in sequence.
+
+### Exceptions
+
+`disposeAsync()` never synchronously throws an error. The returned promise may reject with one of the following errors:
+
+- {{jsxref("SuppressedError")}}
+  - : Thrown if multiple disposers in the stack threw an error. If only one error is thrown, it is rethrown as-is. Otherwise, for each additional error, a new {{jsxref("SuppressedError")}} is created, with the original error as the `suppressed` property, and the new error as the `error` property.
+
+## Examples
+
+### Disposing a stack
+
+Here we push three disposers to the stack, using the {{jsxref("AsyncDisposableStack/use", "use()")}}, {{jsxref("AsyncDisposableStack/adopt", "adopt()")}}, and {{jsxref("AsyncDisposableStack/defer", "defer()")}} methods. When `disposeAsync()` is called, the disposers are called in reverse order of registration.
+
+Note that usually you don't need to call `disposeAsync()` manually. Declare the stack with {{jsxref("Statements/await_using", "await using")}}, and its [`[Symbol.asyncDispose]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncDisposableStack/Symbol.asyncDispose) method will be automatically called when the stack goes out of scope.
+
+```js
+class Resource {
+  #doDisposal() {
+    // Imagine more meaningful disposal logic here
+    return new Promise((resolve) => {
+      setTimeout(resolve, 1000);
+    });
+  }
+  async dispose() {
+    await this.#doDisposal();
+    console.log("Resource disposed");
+  }
+  async [Symbol.asyncDispose]() {
+    await this.#doDisposal();
+    console.log("Resource disposed via Symbol.asyncDispose");
+  }
+}
+
+async function doSomething() {
+  const disposer = new AsyncDisposableStack();
+  const resource = disposer.use(new Resource());
+  const resource2 = disposer.adopt(new Resource(), (resource) =>
+    resource.dispose(),
+  );
+  disposer.defer(() => console.log("Deferred disposer"));
+  disposer.disposeAsync();
+  // Logs in order:
+  // Deferred disposer
+  // Resource disposed
+  // Resource disposed via Symbol.dispose
+}
+
+doSomething();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [JavaScript resource management](/en-US/docs/Web/JavaScript/Guide/Resource_management)
+- {{jsxref("AsyncDisposableStack")}}
+- {{jsxref("AsyncDisposableStack.prototype.adopt()")}}
+- {{jsxref("AsyncDisposableStack.prototype.defer()")}}
+- {{jsxref("AsyncDisposableStack.prototype.use()")}}
+- [`AsyncDisposableStack.prototype[Symbol.asyncDispose]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncDisposableStack/Symbol.asyncDispose)

files/en-us/web/javascript/reference/global_objects/asyncdisposablestack/disposed/index.md

@@ -0,0 +1,36 @@
+---
+title: AsyncDisposableStack.prototype.disposed
+slug: Web/JavaScript/Reference/Global_Objects/AsyncDisposableStack/disposed
+page-type: javascript-instance-accessor-property
+browser-compat: javascript.builtins.AsyncDisposableStack.disposed
+sidebar: jsref
+---
+
+The **`disposed`** accessor property of {{jsxref("AsyncDisposableStack")}} instances returns a boolean indicating whether or not this `AsyncDisposableStack` has been disposed or moved by doing any of the following:
+
+- Calling its {{jsxref("AsyncDisposableStack/disposeAsync", "disposeAsync()")}} method
+- Calling its {{jsxref("AsyncDisposableStack/move", "move()")}} method
+- Declaring it with {{jsxref("Statements/await_using", "await using")}} and letting the variable go out of scope, which automatically calls the [`[Symbol.asyncDispose]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncDisposableStack/Symbol.asyncDispose) method.
+
+## Examples
+
+### Checking if a stack is disposed
+
+```js
+const disposer = new AsyncDisposableStack();
+console.log(disposer.disposed); // false
+await disposer.disposeAsync();
+console.log(disposer.disposed); // true
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [JavaScript resource management](/en-US/docs/Web/JavaScript/Guide/Resource_management)