@types/node 16.3.3 → 16.4.3

node/async_hooks.d.ts

@@ -1,16 +1,47 @@
 /**
- * Async Hooks module: https://nodejs.org/api/async_hooks.html
+ * The `async_hooks` module provides an API to track asynchronous resources. It
+ * can be accessed using:
+ *
+ * ```js
+ * const async_hooks = require('async_hooks');
+ * ```
+ * @experimental
+ * @see [source](https://github.com/nodejs/node/blob/v16.4.2/lib/async_hooks.js)
  */
 declare module 'async_hooks' {
     /**
-     * Returns the asyncId of the current execution context.
+     * ```js
+     * const async_hooks = require('async_hooks');
+     *
+     * console.log(async_hooks.executionAsyncId());  // 1 - bootstrap
+     * fs.open(path, 'r', (err, fd) => {
+     *   console.log(async_hooks.executionAsyncId());  // 6 - open()
+     * });
+     * ```
+     *
+     * The ID returned from `executionAsyncId()` is related to execution timing, not
+     * causality (which is covered by `triggerAsyncId()`):
+     *
+     * ```js
+     * const server = net.createServer((conn) => {
+     *   // Returns the ID of the server, not of the new connection, because the
+     *   // callback runs in the execution scope of the server's MakeCallback().
+     *   async_hooks.executionAsyncId();
+     *
+     * }).listen(port, () => {
+     *   // Returns the ID of a TickObject (process.nextTick()) because all
+     *   // callbacks passed to .listen() are wrapped in a nextTick().
+     *   async_hooks.executionAsyncId();
+     * });
+     * ```
+     *
+     * Promise contexts may not get precise `executionAsyncIds` by default.
+     * See the section on `promise execution tracking`.
+     * @since v8.1.0
+     * @return The `asyncId` of the current execution context. Useful to track when something calls.
      */
     function executionAsyncId(): number;
-
     /**
-     * The resource representing the current execution.
-     *  Useful to store data within the resource.
-     *
      * Resource objects returned by `executionAsyncResource()` are most often internal
      * Node.js handle objects with undocumented APIs. Using any functions or properties
      * on the object is likely to crash your application and should be avoided.
@@ -18,14 +49,70 @@ declare module 'async_hooks' {
      * Using `executionAsyncResource()` in the top-level execution context will
      * return an empty object as there is no handle or request object to use,
      * but having an object representing the top-level can be helpful.
+     *
+     * ```js
+     * const { open } = require('fs');
+     * const { executionAsyncId, executionAsyncResource } = require('async_hooks');
+     *
+     * console.log(executionAsyncId(), executionAsyncResource());  // 1 {}
+     * open(__filename, 'r', (err, fd) => {
+     *   console.log(executionAsyncId(), executionAsyncResource());  // 7 FSReqWrap
+     * });
+     * ```
+     *
+     * This can be used to implement continuation local storage without the
+     * use of a tracking `Map` to store the metadata:
+     *
+     * ```js
+     * const { createServer } = require('http');
+     * const {
+     *   executionAsyncId,
+     *   executionAsyncResource,
+     *   createHook
+     * } = require('async_hooks');
+     * const sym = Symbol('state'); // Private symbol to avoid pollution
+     *
+     * createHook({
+     *   init(asyncId, type, triggerAsyncId, resource) {
+     *     const cr = executionAsyncResource();
+     *     if (cr) {
+     *       resource[sym] = cr[sym];
+     *     }
+     *   }
+     * }).enable();
+     *
+     * const server = createServer((req, res) => {
+     *   executionAsyncResource()[sym] = { state: req.url };
+     *   setTimeout(function() {
+     *     res.end(JSON.stringify(executionAsyncResource()[sym]));
+     *   }, 100);
+     * }).listen(3000);
+     * ```
+     * @since v13.9.0, v12.17.0
+     * @return The resource representing the current execution. Useful to store data within the resource.
      */
     function executionAsyncResource(): object;
-
     /**
-     * Returns the ID of the resource responsible for calling the callback that is currently being executed.
+     * ```js
+     * const server = net.createServer((conn) => {
+     *   // The resource that caused (or triggered) this callback to be called
+     *   // was that of the new connection. Thus the return value of triggerAsyncId()
+     *   // is the asyncId of "conn".
+     *   async_hooks.triggerAsyncId();
+     *
+     * }).listen(port, () => {
+     *   // Even though all callbacks passed to .listen() are wrapped in a nextTick()
+     *   // the callback itself exists because the call to the server's .listen()
+     *   // was made. So the return value would be the ID of the server.
+     *   async_hooks.triggerAsyncId();
+     * });
+     * ```
+     *
+     * Promise contexts may not get valid `triggerAsyncId`s by default. See
+     * the section on `promise execution tracking`.
+     * @return The ID of the resource responsible for calling the callback that is currently being executed.
      */
     function triggerAsyncId(): number;
-
     interface HookCallbacks {
         /**
          * Called when a class is constructed that has the possibility to emit an asynchronous event.
@@ -35,73 +122,133 @@ declare module 'async_hooks' {
          * @param resource reference to the resource representing the async operation, needs to be released during destroy
          */
         init?(asyncId: number, type: string, triggerAsyncId: number, resource: object): void;
-
         /**
          * When an asynchronous operation is initiated or completes a callback is called to notify the user.
          * The before callback is called just before said callback is executed.
          * @param asyncId the unique identifier assigned to the resource about to execute the callback.
          */
         before?(asyncId: number): void;
-
         /**
          * Called immediately after the callback specified in before is completed.
          * @param asyncId the unique identifier assigned to the resource which has executed the callback.
          */
         after?(asyncId: number): void;
-
         /**
          * Called when a promise has resolve() called. This may not be in the same execution id
          * as the promise itself.
          * @param asyncId the unique id for the promise that was resolve()d.
          */
         promiseResolve?(asyncId: number): void;
-
         /**
          * Called after the resource corresponding to asyncId is destroyed
          * @param asyncId a unique ID for the async resource
          */
         destroy?(asyncId: number): void;
     }
-
     interface AsyncHook {
         /**
          * Enable the callbacks for a given AsyncHook instance. If no callbacks are provided enabling is a noop.
          */
         enable(): this;
-
         /**
          * Disable the callbacks for a given AsyncHook instance from the global pool of AsyncHook callbacks to be executed. Once a hook has been disabled it will not be called again until enabled.
          */
         disable(): this;
     }
-
     /**
-     * Registers functions to be called for different lifetime events of each async operation.
-     * @param options the callbacks to register
-     * @return an AsyncHooks instance used for disabling and enabling hooks
+     * Registers functions to be called for different lifetime events of each async
+     * operation.
+     *
+     * The callbacks `init()`/`before()`/`after()`/`destroy()` are called for the
+     * respective asynchronous event during a resource's lifetime.
+     *
+     * All callbacks are optional. For example, if only resource cleanup needs to
+     * be tracked, then only the `destroy` callback needs to be passed. The
+     * specifics of all functions that can be passed to `callbacks` is in the `Hook Callbacks` section.
+     *
+     * ```js
+     * const async_hooks = require('async_hooks');
+     *
+     * const asyncHook = async_hooks.createHook({
+     *   init(asyncId, type, triggerAsyncId, resource) { },
+     *   destroy(asyncId) { }
+     * });
+     * ```
+     *
+     * The callbacks will be inherited via the prototype chain:
+     *
+     * ```js
+     * class MyAsyncCallbacks {
+     *   init(asyncId, type, triggerAsyncId, resource) { }
+     *   destroy(asyncId) {}
+     * }
+     *
+     * class MyAddedCallbacks extends MyAsyncCallbacks {
+     *   before(asyncId) { }
+     *   after(asyncId) { }
+     * }
+     *
+     * const asyncHook = async_hooks.createHook(new MyAddedCallbacks());
+     * ```
+     *
+     * Because promises are asynchronous resources whose lifecycle is tracked
+     * via the async hooks mechanism, the `init()`, `before()`, `after()`, and`destroy()` callbacks _must not_ be async functions that return promises.
+     * @since v8.1.0
+     * @param callbacks The `Hook Callbacks` to register
+     * @return Instance used for disabling and enabling hooks
      */
     function createHook(options: HookCallbacks): AsyncHook;
-
     interface AsyncResourceOptions {
-      /**
-       * The ID of the execution context that created this async event.
-       * @default executionAsyncId()
-       */
-      triggerAsyncId?: number | undefined;
-
-      /**
-       * Disables automatic `emitDestroy` when the object is garbage collected.
-       * This usually does not need to be set (even if `emitDestroy` is called
-       * manually), unless the resource's `asyncId` is retrieved and the
-       * sensitive API's `emitDestroy` is called with it.
-       * @default false
-       */
-      requireManualDestroy?: boolean | undefined;
+        /**
+         * The ID of the execution context that created this async event.
+         * @default executionAsyncId()
+         */
+        triggerAsyncId?: number | undefined;
+        /**
+         * Disables automatic `emitDestroy` when the object is garbage collected.
+         * This usually does not need to be set (even if `emitDestroy` is called
+         * manually), unless the resource's `asyncId` is retrieved and the
+         * sensitive API's `emitDestroy` is called with it.
+         * @default false
+         */
+        requireManualDestroy?: boolean | undefined;
     }
-
     /**
-     * The class AsyncResource was designed to be extended by the embedder's async resources.
-     * Using this users can easily trigger the lifetime events of their own resources.
+     * The class `AsyncResource` is designed to be extended by the embedder's async
+     * resources. Using this, users can easily trigger the lifetime events of their
+     * own resources.
+     *
+     * The `init` hook will trigger when an `AsyncResource` is instantiated.
+     *
+     * The following is an overview of the `AsyncResource` API.
+     *
+     * ```js
+     * const { AsyncResource, executionAsyncId } = require('async_hooks');
+     *
+     * // AsyncResource() is meant to be extended. Instantiating a
+     * // new AsyncResource() also triggers init. If triggerAsyncId is omitted then
+     * // async_hook.executionAsyncId() is used.
+     * const asyncResource = new AsyncResource(
+     *   type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false }
+     * );
+     *
+     * // Run a function in the execution context of the resource. This will
+     * // * establish the context of the resource
+     * // * trigger the AsyncHooks before callbacks
+     * // * call the provided function `fn` with the supplied arguments
+     * // * trigger the AsyncHooks after callbacks
+     * // * restore the original execution context
+     * asyncResource.runInAsyncScope(fn, thisArg, ...args);
+     *
+     * // Call AsyncHooks destroy callbacks.
+     * asyncResource.emitDestroy();
+     *
+     * // Return the unique ID assigned to the AsyncResource instance.
+     * asyncResource.asyncId();
+     *
+     * // Return the trigger ID for the AsyncResource instance.
+     * asyncResource.triggerAsyncId();
+     * ```
      */
     class AsyncResource {
         /**
@@ -113,116 +260,238 @@ declare module 'async_hooks' {
          *   this async event (default: `executionAsyncId()`), or an
          *   AsyncResourceOptions object (since 9.3)
          */
-        constructor(type: string, triggerAsyncId?: number|AsyncResourceOptions);
-
+        constructor(type: string, triggerAsyncId?: number | AsyncResourceOptions);
         /**
          * Binds the given function to the current execution context.
+         *
+         * The returned function will have an `asyncResource` property referencing
+         * the `AsyncResource` to which the function is bound.
+         * @since v14.8.0, v12.19.0
          * @param fn The function to bind to the current execution context.
          * @param type An optional name to associate with the underlying `AsyncResource`.
          */
-        static bind<Func extends (this: ThisArg, ...args: any[]) => any, ThisArg>(fn: Func, type?: string, thisArg?: ThisArg): Func & { asyncResource: AsyncResource };
-
+        static bind<Func extends (this: ThisArg, ...args: any[]) => any, ThisArg>(
+            fn: Func,
+            type?: string,
+            thisArg?: ThisArg
+        ): Func & {
+            asyncResource: AsyncResource;
+        };
         /**
          * Binds the given function to execute to this `AsyncResource`'s scope.
+         *
+         * The returned function will have an `asyncResource` property referencing
+         * the `AsyncResource` to which the function is bound.
+         * @since v14.8.0, v12.19.0
          * @param fn The function to bind to the current `AsyncResource`.
          */
-        bind<Func extends (...args: any[]) => any>(fn: Func): Func & { asyncResource: AsyncResource };
-
+        bind<Func extends (...args: any[]) => any>(
+            fn: Func
+        ): Func & {
+            asyncResource: AsyncResource;
+        };
         /**
-         * Call the provided function with the provided arguments in the
-         * execution context of the async resource. This will establish the
-         * context, trigger the AsyncHooks before callbacks, call the function,
-         * trigger the AsyncHooks after callbacks, and then restore the original
-         * execution context.
-         * @param fn The function to call in the execution context of this
-         *   async resource.
+         * Call the provided function with the provided arguments in the execution context
+         * of the async resource. This will establish the context, trigger the AsyncHooks
+         * before callbacks, call the function, trigger the AsyncHooks after callbacks, and
+         * then restore the original execution context.
+         * @since v9.6.0
+         * @param fn The function to call in the execution context of this async resource.
          * @param thisArg The receiver to be used for the function call.
-         * @param args Optional arguments to pass to the function.
+         * @param ...args Optional arguments to pass to the function.
          */
         runInAsyncScope<This, Result>(fn: (this: This, ...args: any[]) => Result, thisArg?: This, ...args: any[]): Result;
-
         /**
-         * Call AsyncHooks destroy callbacks.
+         * Call all `destroy` hooks. This should only ever be called once. An error will
+         * be thrown if it is called more than once. This **must** be manually called. If
+         * the resource is left to be collected by the GC then the `destroy` hooks will
+         * never be called.
+         * @return A reference to `asyncResource`.
          */
         emitDestroy(): this;
-
         /**
-         * @return the unique ID assigned to this AsyncResource instance.
+         * @return The unique `asyncId` assigned to the resource.
          */
         asyncId(): number;
-
         /**
-         * @return the trigger ID for this AsyncResource instance.
+         *
+         * @return The same `triggerAsyncId` that is passed to the `AsyncResource` constructor.
          */
         triggerAsyncId(): number;
     }
-
     /**
-     * When having multiple instances of `AsyncLocalStorage`, they are independent
-     * from each other. It is safe to instantiate this class multiple times.
+     * This class creates stores that stay coherent through asynchronous operations.
+     *
+     * While you can create your own implementation on top of the `async_hooks` module,`AsyncLocalStorage` should be preferred as it is a performant and memory safe
+     * implementation that involves significant optimizations that are non-obvious to
+     * implement.
+     *
+     * The following example uses `AsyncLocalStorage` to build a simple logger
+     * that assigns IDs to incoming HTTP requests and includes them in messages
+     * logged within each request.
+     *
+     * ```js
+     * const http = require('http');
+     * const { AsyncLocalStorage } = require('async_hooks');
+     *
+     * const asyncLocalStorage = new AsyncLocalStorage();
+     *
+     * function logWithId(msg) {
+     *   const id = asyncLocalStorage.getStore();
+     *   console.log(`${id !== undefined ? id : '-'}:`, msg);
+     * }
+     *
+     * let idSeq = 0;
+     * http.createServer((req, res) => {
+     *   asyncLocalStorage.run(idSeq++, () => {
+     *     logWithId('start');
+     *     // Imagine any chain of async operations here
+     *     setImmediate(() => {
+     *       logWithId('finish');
+     *       res.end();
+     *     });
+     *   });
+     * }).listen(8080);
+     *
+     * http.get('http://localhost:8080');
+     * http.get('http://localhost:8080');
+     * // Prints:
+     * //   0: start
+     * //   1: start
+     * //   0: finish
+     * //   1: finish
+     * ```
+     *
+     * Each instance of `AsyncLocalStorage` maintains an independent storage context.
+     * Multiple instances can safely exist simultaneously without risk of interfering
+     * with each other data.
+     * @since v13.10.0, v12.17.0
      */
     class AsyncLocalStorage<T> {
         /**
-         * This method disables the instance of `AsyncLocalStorage`. All subsequent calls
-         * to `asyncLocalStorage.getStore()` will return `undefined` until
-         * `asyncLocalStorage.run()` is called again.
+         * Disables the instance of `AsyncLocalStorage`. All subsequent calls
+         * to `asyncLocalStorage.getStore()` will return `undefined` until`asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()` is called again.
          *
          * When calling `asyncLocalStorage.disable()`, all current contexts linked to the
          * instance will be exited.
          *
-         * Calling `asyncLocalStorage.disable()` is required before the
-         * `asyncLocalStorage` can be garbage collected. This does not apply to stores
+         * Calling `asyncLocalStorage.disable()` is required before the`asyncLocalStorage` can be garbage collected. This does not apply to stores
          * provided by the `asyncLocalStorage`, as those objects are garbage collected
          * along with the corresponding async resources.
          *
-         * This method is to be used when the `asyncLocalStorage` is not in use anymore
+         * Use this method when the `asyncLocalStorage` is not in use anymore
          * in the current process.
+         * @since v13.10.0, v12.17.0
+         * @experimental
          */
         disable(): void;
-
         /**
-         * This method returns the current store. If this method is called outside of an
-         * asynchronous context initialized by calling `asyncLocalStorage.run`, it will
-         * return `undefined`.
+         * Returns the current store.
+         * If called outside of an asynchronous context initialized by
+         * calling `asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()`, it
+         * returns `undefined`.
+         * @since v13.10.0, v12.17.0
          */
         getStore(): T | undefined;
-
         /**
-         * This methods runs a function synchronously within a context and return its
+         * Runs a function synchronously within a context and returns its
          * return value. The store is not accessible outside of the callback function or
          * the asynchronous operations created within the callback.
          *
-         * Optionally, arguments can be passed to the function. They will be passed to the
-         * callback function.
+         * The optional `args` are passed to the callback function.
          *
-         * I the callback function throws an error, it will be thrown by `run` too. The
-         * stacktrace will not be impacted by this call and the context will be exited.
+         * If the callback function throws an error, the error is thrown by `run()` too.
+         * The stacktrace is not impacted by this call and the context is exited.
+         *
+         * Example:
+         *
+         * ```js
+         * const store = { id: 2 };
+         * try {
+         *   asyncLocalStorage.run(store, () => {
+         *     asyncLocalStorage.getStore(); // Returns the store object
+         *     throw new Error();
+         *   });
+         * } catch (e) {
+         *   asyncLocalStorage.getStore(); // Returns undefined
+         *   // The error will be caught here
+         * }
+         * ```
+         * @since v13.10.0, v12.17.0
          */
         run<R, TArgs extends any[]>(store: T, callback: (...args: TArgs) => R, ...args: TArgs): R;
-
         /**
-         * This methods runs a function synchronously outside of a context and return its
-         * return value. The store is not accessible within the callback function or the
-         * asynchronous operations created within the callback.
+         * Runs a function synchronously outside of a context and returns its
+         * return value. The store is not accessible within the callback function or
+         * the asynchronous operations created within the callback. Any `getStore()`call done within the callback function will always return `undefined`.
+         *
+         * The optional `args` are passed to the callback function.
          *
-         * Optionally, arguments can be passed to the function. They will be passed to the
-         * callback function.
+         * If the callback function throws an error, the error is thrown by `exit()` too.
+         * The stacktrace is not impacted by this call and the context is re-entered.
          *
-         * If the callback function throws an error, it will be thrown by `exit` too. The
-         * stacktrace will not be impacted by this call and the context will be
-         * re-entered.
+         * Example:
+         *
+         * ```js
+         * // Within a call to run
+         * try {
+         *   asyncLocalStorage.getStore(); // Returns the store object or value
+         *   asyncLocalStorage.exit(() => {
+         *     asyncLocalStorage.getStore(); // Returns undefined
+         *     throw new Error();
+         *   });
+         * } catch (e) {
+         *   asyncLocalStorage.getStore(); // Returns the same object or value
+         *   // The error will be caught here
+         * }
+         * ```
+         * @since v13.10.0, v12.17.0
+         * @experimental
          */
         exit<R, TArgs extends any[]>(callback: (...args: TArgs) => R, ...args: TArgs): R;
-
         /**
-         * Calling `asyncLocalStorage.enterWith(store)` will transition into the context
-         * for the remainder of the current synchronous execution and will persist
-         * through any following asynchronous calls.
+         * Transitions into the context for the remainder of the current
+         * synchronous execution and then persists the store through any following
+         * asynchronous calls.
+         *
+         * Example:
+         *
+         * ```js
+         * const store = { id: 1 };
+         * // Replaces previous store with the given store object
+         * asyncLocalStorage.enterWith(store);
+         * asyncLocalStorage.getStore(); // Returns the store object
+         * someAsyncOperation(() => {
+         *   asyncLocalStorage.getStore(); // Returns the same object
+         * });
+         * ```
+         *
+         * This transition will continue for the _entire_ synchronous execution.
+         * This means that if, for example, the context is entered within an event
+         * handler subsequent event handlers will also run within that context unless
+         * specifically bound to another context with an `AsyncResource`. That is why`run()` should be preferred over `enterWith()` unless there are strong reasons
+         * to use the latter method.
+         *
+         * ```js
+         * const store = { id: 1 };
+         *
+         * emitter.on('my-event', () => {
+         *   asyncLocalStorage.enterWith(store);
+         * });
+         * emitter.on('my-event', () => {
+         *   asyncLocalStorage.getStore(); // Returns the same object
+         * });
+         *
+         * asyncLocalStorage.getStore(); // Returns undefined
+         * emitter.emit('my-event');
+         * asyncLocalStorage.getStore(); // Returns the same object
+         * ```
+         * @since v13.11.0, v12.17.0
+         * @experimental
          */
         enterWith(store: T): void;
     }
 }
-
 declare module 'node:async_hooks' {
     export * from 'async_hooks';
 }