@@ -2240,39 +2240,55 @@ added:
2240
2240
> Stability: 1 - Experimental
2241
2241
2242
2242
* ` signal` {AbortSignal}
2243
- * ` resource` {Object} Any non-null entity, reference to which is held weakly.
2243
+ * ` resource` {Object} Any non-null object tied to the abortable operation and held weakly.
2244
+ If ` resource` is garbage collected before the ` signal` aborts, the promise remains pending,
2245
+ allowing Node.js to stop tracking it.
2246
+ This helps prevent memory leaks in long-running or non-cancelable operations.
2244
2247
* Returns: {Promise}
2245
2248
2246
- Listens to abort event on the provided ` signal` and
2247
- returns a promise that is fulfilled when the ` signal` is
2248
- aborted. If the passed ` resource` is garbage collected before the ` signal` is
2249
- aborted, the returned promise shall remain pending indefinitely.
2249
+ Listens to abort event on the provided ` signal` and returns a promise that resolves when the ` signal` is aborted.
2250
+ If ` resource` is provided, it weakly references the operation's associated object,
2251
+ so if ` resource` is garbage collected before the ` signal` aborts,
2252
+ then returned promise shall remain pending.
2253
+ This prevents memory leaks in long-running or non-cancelable operations.
2250
2254
2251
2255
` ` ` cjs
2252
2256
const { aborted } = require (' node:util' );
2253
2257
2258
+ // Obtain an object with an abortable signal, like a custom resource or operation.
2254
2259
const dependent = obtainSomethingAbortable ();
2255
2260
2261
+ // Pass `dependent` as the resource, indicating the promise should only resolve
2262
+ // if `dependent` is still in memory when the signal is aborted.
2256
2263
aborted (dependent .signal , dependent).then (() => {
2257
- // Do something when dependent is aborted.
2264
+
2265
+ // This code runs when `dependent` is aborted.
2266
+ console .log (' Dependent resource was aborted.' );
2258
2267
});
2259
2268
2269
+ // Simulate an event that triggers the abort.
2260
2270
dependent .on (' event' , () => {
2261
- dependent .abort ();
2271
+ dependent .abort (); // This will cause the `aborted` promise to resolve.
2262
2272
});
2263
2273
` ` `
2264
2274
2265
2275
` ` ` mjs
2266
2276
import { aborted } from ' node:util' ;
2267
2277
2278
+ // Obtain an object with an abortable signal, like a custom resource or operation.
2268
2279
const dependent = obtainSomethingAbortable ();
2269
2280
2281
+ // Pass `dependent` as the resource, indicating the promise should only resolve
2282
+ // if `dependent` is still in memory when the signal is aborted.
2270
2283
aborted (dependent .signal , dependent).then (() => {
2271
- // Do something when dependent is aborted.
2284
+
2285
+ // This code runs when `dependent` is aborted.
2286
+ console .log (' Dependent resource was aborted.' );
2272
2287
});
2273
2288
2289
+ // Simulate an event that triggers the abort.
2274
2290
dependent .on (' event' , () => {
2275
- dependent .abort ();
2291
+ dependent .abort (); // This will cause the `aborted` promise to resolve.
2276
2292
});
2277
2293
` ` `
2278
2294
0 commit comments