doc: clarify util.aborted resource usage · nodejs/node@0d08756

> 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.

});

```