diff --git a/doc/api/util.md b/doc/api/util.md index 71d3a9f32eae47..7318b0e3f76fdc 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -1983,6 +1983,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`