diff --git a/doc/api/util.md b/doc/api/util.md index eb06e93c503811..03c1b621358fea 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -2244,39 +2244,55 @@ added: > Stability: 1 - Experimental * `signal` {AbortSignal} -* `resource` {Object} Any non-null entity, reference to which is held weakly. +* `resource` {Object} Any non-null object tied to the abortable operation and held weakly. + If `resource` is garbage collected before the `signal` aborts, the promise remains pending, + allowing Node.js to stop tracking it. + This helps prevent memory leaks in long-running or non-cancelable operations. * Returns: {Promise} -Listens to abort event on the provided `signal` and -returns a promise that is fulfilled when the `signal` is -aborted. If the passed `resource` is garbage collected before the `signal` is -aborted, the returned promise shall remain pending indefinitely. +Listens to abort event on the provided `signal` and returns a promise that resolves when the `signal` is aborted. +If `resource` is provided, it weakly references the operation's associated object, +so if `resource` is garbage collected before the `signal` aborts, +then returned promise shall remain pending. +This prevents memory leaks in long-running or non-cancelable operations. ```cjs const { aborted } = require('node:util'); +// Obtain an object with an abortable signal, like a custom resource or operation. const dependent = obtainSomethingAbortable(); +// Pass `dependent` as the resource, indicating the promise should only resolve +// if `dependent` is still in memory when the signal is aborted. aborted(dependent.signal, dependent).then(() => { - // Do something when dependent is aborted. + + // This code runs when `dependent` is aborted. + console.log('Dependent resource was aborted.'); }); +// Simulate an event that triggers the abort. dependent.on('event', () => { - dependent.abort(); + dependent.abort(); // This will cause the `aborted` promise to resolve. }); ``` ```mjs import { aborted } from 'node:util'; +// Obtain an object with an abortable signal, like a custom resource or operation. const dependent = obtainSomethingAbortable(); +// Pass `dependent` as the resource, indicating the promise should only resolve +// if `dependent` is still in memory when the signal is aborted. aborted(dependent.signal, dependent).then(() => { - // Do something when dependent is aborted. + + // This code runs when `dependent` is aborted. + console.log('Dependent resource was aborted.'); }); +// Simulate an event that triggers the abort. dependent.on('event', () => { - dependent.abort(); + dependent.abort(); // This will cause the `aborted` promise to resolve. }); ```