Skip to content
This repository was archived by the owner on Apr 26, 2024. It is now read-only.

Commit 2fb7e8a

Browse files
ovflowdgithub-actions[bot]
ovflowd
authored and
github-actions[bot]
committed
chore(api): sync auto-generated docs
1 parent 3664460 commit 2fb7e8a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+3851
-3709
lines changed

‎content/api/v19/addons.en.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@ category: 'api'
55
version: 'v19'
66
---
77

8-
<Metadata version="v19.1.0" data={{"update":{"type":"introduced_in","version":["v0.10.0"]}}} />
8+
<Metadata version="v19.2.0" data={{"update":{"type":"introduced_in","version":["v0.10.0"]}}} />
99

10-
<Metadata version="v19.1.0" data={{"type":"misc"}} />
10+
<Metadata version="v19.2.0" data={{"type":"misc"}} />
1111

1212
_Addons_ are dynamically-linked shared objects written in C++. The
1313
[`require()`][require] function can load addons as ordinary Node.js modules.
@@ -241,7 +241,7 @@ NODE_MODULE_INIT(/* exports, module, context */) {
241241
242242
##### Worker support
243243
244-
<Metadata version="v19.1.0" data={{"changes":[{"version":["v14.8.0","v12.19.0"],"pr-url":"https://github.com/nodejs/node/pull/34572","description":"Cleanup hooks may now be asynchronous."}]}} />
244+
<Metadata version="v19.2.0" data={{"changes":[{"version":["v14.8.0","v12.19.0"],"pr-url":"https://github.com/nodejs/node/pull/34572","description":"Cleanup hooks may now be asynchronous."}]}} />
245245
246246
In order to be loaded from multiple Node.js environments,
247247
such as a main thread and a Worker thread, an add-on needs to either:
@@ -440,7 +440,7 @@ illustration of how it can be used.
440440

441441
### Node-API
442442

443-
<Metadata version="v19.1.0" data={{"stability":{"level":2,"text":" - Stable"}}} />
443+
<Metadata version="v19.2.0" data={{"stability":{"level":2,"text":" - Stable"}}} />
444444

445445
Node-API is an API for building native addons. It is independent from
446446
the underlying JavaScript runtime (e.g. V8) and is maintained as part of

‎content/api/v19/assert.en.md‎

Lines changed: 103 additions & 103 deletions
Large diffs are not rendered by default.

‎content/api/v19/async_context.en.md‎

Lines changed: 35 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,11 @@ category: 'api'
55
version: 'v19'
66
---
77

8-
<Metadata version="v19.1.0" data={{"update":{"type":"introduced_in","version":["v16.4.0"]}}} />
8+
<Metadata version="v19.2.0" data={{"update":{"type":"introduced_in","version":["v16.4.0"]}}} />
99

10-
<Metadata version="v19.1.0" data={{"stability":{"level":2,"text":" - Stable"}}} />
10+
<Metadata version="v19.2.0" data={{"stability":{"level":2,"text":" - Stable"}}} />
1111

12-
<Metadata version="v19.1.0" data={{"source_link":"lib/async_hooks.js"}} />
12+
<Metadata version="v19.2.0" data={{"source_link":"lib/async_hooks.js"}} />
1313

1414
### Introduction
1515

@@ -32,7 +32,7 @@ const { AsyncLocalStorage, AsyncResource } = require('node:async_hooks');
3232

3333
### <DataTag tag="C" /> `AsyncLocalStorage`
3434

35-
<Metadata version="v19.1.0" data={{"changes":[{"version":"v16.4.0","pr-url":"https://github.com/nodejs/node/pull/37675","description":"AsyncLocalStorage is now Stable. Previously, it had been Experimental."}],"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
35+
<Metadata version="v19.2.0" data={{"changes":[{"version":"v16.4.0","pr-url":"https://github.com/nodejs/node/pull/37675","description":"AsyncLocalStorage is now Stable. Previously, it had been Experimental."}],"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
3636

3737
This class creates stores that stay coherent through asynchronous operations.
3838

@@ -113,18 +113,32 @@ Each instance of `AsyncLocalStorage` maintains an independent storage context.
113113
Multiple instances can safely exist simultaneously without risk of interfering
114114
with each other's data.
115115

116-
#### <DataTag tag="M" /> `new AsyncLocalStorage()`
116+
#### <DataTag tag="M" /> `new AsyncLocalStorage([options])`
117117

118-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
118+
<Metadata version="v19.2.0" data={{"changes":[{"version":"v19.2.0","pr-url":"https://github.com/nodejs/node/pull/45386","description":"Add option onPropagate."}],"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
119+
120+
<Metadata version="v19.2.0" data={{"stability":{"level":1,"text":" - `options.onPropagate` is experimental."}}} />
121+
122+
* `options` [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
123+
* `onPropagate` [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) Optional callback invoked before a store is
124+
propagated to a new async resource. Returning `true` allows propagation,
125+
returning `false` avoids it. Default is to propagate always.
119126

120127
Creates a new instance of `AsyncLocalStorage`. Store is only provided within a
121128
`run()` call or after an `enterWith()` call.
122129

130+
The `onPropagate` is called during creation of an async resource. Throwing at
131+
this time will print the stack trace and exit. See
132+
[`async_hooks` Error handling][] for details.
133+
134+
Creating an async resource within the `onPropagate` callback will result in
135+
a recursive call to `onPropagate`.
136+
123137
#### <DataTag tag="M" /> `asyncLocalStorage.disable()`
124138

125-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
139+
<Metadata version="v19.2.0" data={{"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
126140

127-
<Metadata version="v19.1.0" data={{"stability":{"level":1,"text":" - Experimental"}}} />
141+
<Metadata version="v19.2.0" data={{"stability":{"level":1,"text":" - Experimental"}}} />
128142

129143
Disables the instance of `AsyncLocalStorage`. All subsequent calls
130144
to `asyncLocalStorage.getStore()` will return `undefined` until
@@ -143,7 +157,7 @@ in the current process.
143157

144158
#### <DataTag tag="M" /> `asyncLocalStorage.getStore()`
145159

146-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
160+
<Metadata version="v19.2.0" data={{"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
147161

148162
* Returns: [`any`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types)
149163

@@ -154,9 +168,9 @@ returns `undefined`.
154168

155169
#### <DataTag tag="M" /> `asyncLocalStorage.enterWith(store)`
156170

157-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v13.11.0","v12.17.0"]}}} />
171+
<Metadata version="v19.2.0" data={{"update":{"type":"added","version":["v13.11.0","v12.17.0"]}}} />
158172

159-
<Metadata version="v19.1.0" data={{"stability":{"level":1,"text":" - Experimental"}}} />
173+
<Metadata version="v19.2.0" data={{"stability":{"level":1,"text":" - Experimental"}}} />
160174

161175
* `store` [`any`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types)
162176

@@ -200,7 +214,7 @@ asyncLocalStorage.getStore(); // Returns the same object
200214

201215
#### <DataTag tag="M" /> `asyncLocalStorage.run(store, callback[, ...args])`
202216

203-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
217+
<Metadata version="v19.2.0" data={{"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
204218

205219
* `store` [`any`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types)
206220
* `callback` [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
@@ -236,9 +250,9 @@ try {
236250

237251
#### <DataTag tag="M" /> `asyncLocalStorage.exit(callback[, ...args])`
238252

239-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
253+
<Metadata version="v19.2.0" data={{"update":{"type":"added","version":["v13.10.0","v12.17.0"]}}} />
240254

241-
<Metadata version="v19.1.0" data={{"stability":{"level":1,"text":" - Experimental"}}} />
255+
<Metadata version="v19.2.0" data={{"stability":{"level":1,"text":" - Experimental"}}} />
242256

243257
* `callback` [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
244258
* `...args` [`any`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types)
@@ -305,7 +319,7 @@ probably responsible for the context loss.
305319

306320
### <DataTag tag="C" /> `AsyncResource`
307321

308-
<Metadata version="v19.1.0" data={{"changes":[{"version":"v16.4.0","pr-url":"https://github.com/nodejs/node/pull/37675","description":"AsyncResource is now Stable. Previously, it had been Experimental."}]}} />
322+
<Metadata version="v19.2.0" data={{"changes":[{"version":"v16.4.0","pr-url":"https://github.com/nodejs/node/pull/37675","description":"AsyncResource is now Stable. Previously, it had been Experimental."}]}} />
309323

310324
The class `AsyncResource` is designed to be extended by the embedder's async
311325
resources. Using this, users can easily trigger the lifetime events of their
@@ -322,7 +336,7 @@ import { AsyncResource, executionAsyncId } from 'node:async_hooks';
322336
// new AsyncResource() also triggers init. If triggerAsyncId is omitted then
323337
// async_hook.executionAsyncId() is used.
324338
const asyncResource = new AsyncResource(
325-
type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false }
339+
type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false },
326340
);
327341

328342
// Run a function in the execution context of the resource. This will
@@ -350,7 +364,7 @@ const { AsyncResource, executionAsyncId } = require('node:async_hooks');
350364
// new AsyncResource() also triggers init. If triggerAsyncId is omitted then
351365
// async_hook.executionAsyncId() is used.
352366
const asyncResource = new AsyncResource(
353-
type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false }
367+
type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false },
354368
);
355369

356370
// Run a function in the execution context of the resource. This will
@@ -409,7 +423,7 @@ class DBQuery extends AsyncResource {
409423

410424
#### Static method: `AsyncResource.bind(fn[, type[, thisArg]])`
411425

412-
<Metadata version="v19.1.0" data={{"changes":[{"version":["v17.8.0","v16.15.0"],"pr-url":"https://github.com/nodejs/node/pull/42177","description":"Changed the default when `thisArg` is undefined to use `this` from the caller."},{"version":"v16.0.0","pr-url":"https://github.com/nodejs/node/pull/36782","description":"Added optional thisArg."}],"update":{"type":"added","version":["v14.8.0","v12.19.0"]}}} />
426+
<Metadata version="v19.2.0" data={{"changes":[{"version":["v17.8.0","v16.15.0"],"pr-url":"https://github.com/nodejs/node/pull/42177","description":"Changed the default when `thisArg` is undefined to use `this` from the caller."},{"version":"v16.0.0","pr-url":"https://github.com/nodejs/node/pull/36782","description":"Added optional thisArg."}],"update":{"type":"added","version":["v14.8.0","v12.19.0"]}}} />
413427

414428
* `fn` [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) The function to bind to the current execution context.
415429
* `type` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) An optional name to associate with the underlying
@@ -423,7 +437,7 @@ the `AsyncResource` to which the function is bound.
423437

424438
#### <DataTag tag="M" /> `asyncResource.bind(fn[, thisArg])`
425439

426-
<Metadata version="v19.1.0" data={{"changes":[{"version":["v17.8.0","v16.15.0"],"pr-url":"https://github.com/nodejs/node/pull/42177","description":"Changed the default when `thisArg` is undefined to use `this` from the caller."},{"version":"v16.0.0","pr-url":"https://github.com/nodejs/node/pull/36782","description":"Added optional thisArg."}],"update":{"type":"added","version":["v14.8.0","v12.19.0"]}}} />
440+
<Metadata version="v19.2.0" data={{"changes":[{"version":["v17.8.0","v16.15.0"],"pr-url":"https://github.com/nodejs/node/pull/42177","description":"Changed the default when `thisArg` is undefined to use `this` from the caller."},{"version":"v16.0.0","pr-url":"https://github.com/nodejs/node/pull/36782","description":"Added optional thisArg."}],"update":{"type":"added","version":["v14.8.0","v12.19.0"]}}} />
427441

428442
* `fn` [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) The function to bind to the current `AsyncResource`.
429443
* `thisArg` [`any`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types)
@@ -435,7 +449,7 @@ the `AsyncResource` to which the function is bound.
435449

436450
#### <DataTag tag="M" /> `asyncResource.runInAsyncScope(fn[, thisArg, ...args])`
437451

438-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v9.6.0"]}}} />
452+
<Metadata version="v19.2.0" data={{"update":{"type":"added","version":["v9.6.0"]}}} />
439453

440454
* `fn` [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) The function to call in the execution context of this async
441455
resource.
@@ -754,4 +768,5 @@ const server = createServer((req, res) => {
754768
[`EventEmitter`]: /api/v19/events#class-eventemitter
755769
[`Stream`]: /api/v19/stream#stream
756770
[`Worker`]: worker_threads.md#class-worker
771+
[`async_hooks` Error handling]: async_hooks.md#error-handling
757772
[`util.promisify()`]: /api/v19/util#utilpromisifyoriginal

‎content/api/v19/async_hooks.en.md‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,11 @@ category: 'api'
55
version: 'v19'
66
---
77

8-
<Metadata version="v19.1.0" data={{"update":{"type":"introduced_in","version":["v8.1.0"]}}} />
8+
<Metadata version="v19.2.0" data={{"update":{"type":"introduced_in","version":["v8.1.0"]}}} />
99

10-
<Metadata version="v19.1.0" data={{"stability":{"level":1,"text":" - Experimental"}}} />
10+
<Metadata version="v19.2.0" data={{"stability":{"level":1,"text":" - Experimental. Please migrate away from this API, if you can. We do not recommend using the `createHook`][], [`AsyncHook`, and\n> `executionAsyncResource` APIs as they have usability issues, safety risks,\n> and performance implications. Async context tracking use cases are better\n> served by the stable `AsyncLocalStorage` API. If you have a use case for\n> `createHook`, `AsyncHook`, or `executionAsyncResource` beyond the context\n> tracking need solved by `AsyncLocalStorage` or diagnostics data currently\n> provided by Diagnostics Channel, please open an issue at\n> <https://github.com/nodejs/node/issues> describing your use case so we can\n> create a more purpose-focused API."}}} />
1111

12-
<Metadata version="v19.1.0" data={{"source_link":"lib/async_hooks.js"}} />
12+
<Metadata version="v19.2.0" data={{"source_link":"lib/async_hooks.js"}} />
1313

1414
We strongly discourage the use of the `async_hooks` API.
1515
Other APIs that can cover most of its use cases include:
@@ -142,7 +142,7 @@ function promiseResolve(asyncId) { }
142142

143143
### <DataTag tag="M" /> `async_hooks.createHook(callbacks)`
144144

145-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v8.1.0"]}}} />
145+
<Metadata version="v19.2.0" data={{"update":{"type":"added","version":["v8.1.0"]}}} />
146146

147147
* `callbacks` [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) The [Hook Callbacks][] to register
148148
* `init` [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) The [`init` callback][].
@@ -168,7 +168,7 @@ import { createHook } from 'node:async_hooks';
168168

169169
const asyncHook = createHook({
170170
init(asyncId, type, triggerAsyncId, resource) { },
171-
destroy(asyncId) { }
171+
destroy(asyncId) { },
172172
});
173173
```
174174

@@ -177,7 +177,7 @@ const async_hooks = require('node:async_hooks');
177177

178178
const asyncHook = async_hooks.createHook({
179179
init(asyncId, type, triggerAsyncId, resource) { },
180-
destroy(asyncId) { }
180+
destroy(asyncId) { },
181181
});
182182
```
183183

@@ -376,7 +376,7 @@ createHook({
376376
fs.writeSync(
377377
stdout.fd,
378378
`${type}(${asyncId}): trigger: ${triggerAsyncId} execution: ${eid}\n`);
379-
}
379+
},
380380
}).enable();
381381

382382
net.createServer((conn) => {}).listen(8080);
@@ -393,7 +393,7 @@ createHook({
393393
fs.writeSync(
394394
stdout.fd,
395395
`${type}(${asyncId}): trigger: ${triggerAsyncId} execution: ${eid}\n`);
396-
}
396+
},
397397
}).enable();
398398

399399
net.createServer((conn) => {}).listen(8080);
@@ -578,7 +578,7 @@ tracking of `Promise` instances via the garbage collector.
578578

579579
##### <DataTag tag="M" /> `promiseResolve(asyncId)`
580580

581-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v8.6.0"]}}} />
581+
<Metadata version="v19.2.0" data={{"update":{"type":"added","version":["v8.6.0"]}}} />
582582

583583
* `asyncId` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
584584

@@ -607,7 +607,7 @@ init for PROMISE with id 6, trigger id: 5 # the Promise returned by then()
607607

608608
#### <DataTag tag="M" /> `async_hooks.executionAsyncResource()`
609609

610-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v13.9.0","v12.17.0"]}}} />
610+
<Metadata version="v19.2.0" data={{"update":{"type":"added","version":["v13.9.0","v12.17.0"]}}} />
611611

612612
* Returns: [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) The resource representing the current execution.
613613
Useful to store data within the resource.
@@ -648,7 +648,7 @@ import { createServer } from 'node:http';
648648
import {
649649
executionAsyncId,
650650
executionAsyncResource,
651-
createHook
651+
createHook,
652652
} from 'async_hooks';
653653
const sym = Symbol('state'); // Private symbol to avoid pollution
654654

@@ -658,7 +658,7 @@ createHook({
658658
if (cr) {
659659
resource[sym] = cr[sym];
660660
}
661-
}
661+
},
662662
}).enable();
663663

664664
const server = createServer((req, res) => {
@@ -674,7 +674,7 @@ const { createServer } = require('node:http');
674674
const {
675675
executionAsyncId,
676676
executionAsyncResource,
677-
createHook
677+
createHook,
678678
} = require('node:async_hooks');
679679
const sym = Symbol('state'); // Private symbol to avoid pollution
680680

@@ -684,7 +684,7 @@ createHook({
684684
if (cr) {
685685
resource[sym] = cr[sym];
686686
}
687-
}
687+
},
688688
}).enable();
689689

690690
const server = createServer((req, res) => {
@@ -697,7 +697,7 @@ const server = createServer((req, res) => {
697697
698698
#### <DataTag tag="M" /> `async_hooks.executionAsyncId()`
699699
700-
<Metadata version="v19.1.0" data={{"changes":[{"version":"v8.2.0","pr-url":"https://github.com/nodejs/node/pull/13490","description":"Renamed from `currentId`."}],"update":{"type":"added","version":["v8.1.0"]}}} />
700+
<Metadata version="v19.2.0" data={{"changes":[{"version":"v8.2.0","pr-url":"https://github.com/nodejs/node/pull/13490","description":"Renamed from `currentId`."}],"update":{"type":"added","version":["v8.1.0"]}}} />
701701
702702
* Returns: [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The `asyncId` of the current execution context. Useful to
703703
track when something calls.
@@ -764,7 +764,7 @@ the section on [promise execution tracking][].
764764
765765
#### <DataTag tag="M" /> `async_hooks.asyncWrapProviders`
766766
767-
<Metadata version="v19.1.0" data={{"update":{"type":"added","version":["v17.2.0","v16.14.0"]}}} />
767+
<Metadata version="v19.2.0" data={{"update":{"type":"added","version":["v17.2.0","v16.14.0"]}}} />
768768
769769
* Returns: A map of provider types to the corresponding numeric id.
770770
This map contains all the event types that might be emitted by the `async_hooks.init()` event.
@@ -856,14 +856,18 @@ The documentation for this class has moved [`AsyncResource`][].
856856
The documentation for this class has moved [`AsyncLocalStorage`][].
857857
858858
[DEP0111]: /api/v19/deprecations#dep0111-processbinding
859+
[Diagnostics Channel]: diagnostics_channel.md
859860
[Hook Callbacks]: #hook-callbacks
860861
[PromiseHooks]: https://docs.google.com/document/d/1rda3yKGHimKIhg5YeoAmCOtyURgsbTH_qaYR79FELlk/edit
862+
[`AsyncHook`]: #class-asynchook
861863
[`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage
862864
[`AsyncResource`]: async_context.md#class-asyncresource
863865
[`Worker`]: worker_threads.md#class-worker
864866
[`after` callback]: #afterasyncid
865867
[`before` callback]: #beforeasyncid
868+
[`createHook`]: #async_hookscreatehookcallbacks
866869
[`destroy` callback]: #destroyasyncid
870+
[`executionAsyncResource`]: #async_hooksexecutionasyncresource
867871
[`init` callback]: #initasyncid-type-triggerasyncid-resource
868872
[`process.getActiveResourcesInfo()`]: /api/v19/process#processgetactiveresourcesinfo
869873
[`promiseResolve` callback]: #promiseresolveasyncid

0 commit comments

Comments
 (0)