diff --git a/doc/api/util.md b/doc/api/util.md index 49e4d231d05179..bddfae17cbeca0 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -1989,6 +1989,51 @@ const channel = new MessageChannel(); channel.port2.postMessage(signal, [signal]); ``` +## `util.aborted(signal, resource)` + + + +> Stability: 1 - Experimental + +* `signal` {AbortSignal} +* `resource` {Object} Any non-null entity, reference to which is held weakly. +* 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. + +```cjs +const { aborted } = require('node:util'); + +const dependent = obtainSomethingAbortable(); + +aborted(dependent.signal, dependent).then(() => { + // Do something when dependent is aborted. +}); + +dependent.on('event', () => { + dependent.abort(); +}); +``` + +```mjs +import { aborted } from 'node:util'; + +const dependent = obtainSomethingAbortable(); + +aborted(dependent.signal, dependent).then(() => { + // Do something when dependent is aborted. +}); + +dependent.on('event', () => { + dependent.abort(); +}); +``` + ## `util.types`