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

Commit 0fc3463

Browse files
ovflowdgithub-actions[bot]
authored andcommitted
chore(api): sync auto-generated docs
1 parent b0e41c6 commit 0fc3463

Some content is hidden

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

99 files changed

+2613
-5229
lines changed

content/api/v16/assert.en.md

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

content/api/v16/async_context.en.md

Lines changed: 14 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,9 @@ in other languages.
2626
The `AsyncLocalStorage` and `AsyncResource` classes are part of the
2727
`node:async_hooks` module:
2828

29-
```mjs
29+
```mjs|cjs
3030
import { AsyncLocalStorage, AsyncResource } from 'node:async_hooks';
31-
```
32-
33-
```cjs
31+
--------------
3432
const { AsyncLocalStorage, AsyncResource } = require('node:async_hooks');
3533
```
3634

@@ -49,7 +47,7 @@ The following example uses `AsyncLocalStorage` to build a simple logger
4947
that assigns IDs to incoming HTTP requests and includes them in messages
5048
logged within each request.
5149

52-
```mjs
50+
```mjs|cjs
5351
import http from 'node:http';
5452
import { AsyncLocalStorage } from 'node:async_hooks';
5553
@@ -79,9 +77,7 @@ http.get('http://localhost:8080');
7977
// 1: start
8078
// 0: finish
8179
// 1: finish
82-
```
83-
84-
```cjs
80+
--------------
8581
const http = require('node:http');
8682
const { AsyncLocalStorage } = require('node:async_hooks');
8783
@@ -331,7 +327,7 @@ The `init` hook will trigger when an `AsyncResource` is instantiated.
331327

332328
The following is an overview of the `AsyncResource` API.
333329

334-
```mjs
330+
```mjs|cjs
335331
import { AsyncResource, executionAsyncId } from 'node:async_hooks';
336332
337333
// AsyncResource() is meant to be extended. Instantiating a
@@ -357,9 +353,7 @@ asyncResource.asyncId();
357353
358354
// Return the trigger ID for the AsyncResource instance.
359355
asyncResource.triggerAsyncId();
360-
```
361-
362-
```cjs
356+
--------------
363357
const { AsyncResource, executionAsyncId } = require('node:async_hooks');
364358
365359
// AsyncResource() is meant to be extended. Instantiating a
@@ -492,14 +486,12 @@ database connection pools, can follow a similar model.
492486
Assuming that the task is adding two numbers, using a file named
493487
`task_processor.js` with the following content:
494488

495-
```mjs
489+
```mjs|cjs
496490
import { parentPort } from 'node:worker_threads';
497491
parentPort.on('message', (task) => {
498492
parentPort.postMessage(task.a + task.b);
499493
});
500-
```
501-
502-
```cjs
494+
--------------
503495
const { parentPort } = require('node:worker_threads');
504496
parentPort.on('message', (task) => {
505497
parentPort.postMessage(task.a + task.b);
@@ -508,7 +500,7 @@ parentPort.on('message', (task) => {
508500

509501
a Worker pool around it could use the following structure:
510502

511-
```mjs
503+
```mjs|cjs
512504
import { AsyncResource } from 'node:async_hooks';
513505
import { EventEmitter } from 'node:events';
514506
import path from 'node:path';
@@ -594,9 +586,7 @@ export default class WorkerPool extends EventEmitter {
594586
for (const worker of this.workers) worker.terminate();
595587
}
596588
}
597-
```
598-
599-
```cjs
589+
--------------
600590
const { AsyncResource } = require('node:async_hooks');
601591
const { EventEmitter } = require('node:events');
602592
const path = require('node:path');
@@ -694,7 +684,7 @@ were scheduled.
694684

695685
This pool could be used as follows:
696686

697-
```mjs
687+
```mjs|cjs
698688
import WorkerPool from './worker_pool.js';
699689
import os from 'node:os';
700690
@@ -708,9 +698,7 @@ for (let i = 0; i < 10; i++) {
708698
pool.close();
709699
});
710700
}
711-
```
712-
713-
```cjs
701+
--------------
714702
const WorkerPool = require('./worker_pool.js');
715703
const os = require('node:os');
716704
@@ -736,7 +724,7 @@ The following example shows how to use the `AsyncResource` class to properly
736724
associate an event listener with the correct execution context. The same
737725
approach can be applied to a [`Stream`][] or a similar event-driven class.
738726

739-
```mjs
727+
```mjs|cjs
740728
import { createServer } from 'node:http';
741729
import { AsyncResource, executionAsyncId } from 'node:async_hooks';
742730
@@ -749,9 +737,7 @@ const server = createServer((req, res) => {
749737
});
750738
res.end();
751739
}).listen(3000);
752-
```
753-
754-
```cjs
740+
--------------
755741
const { createServer } = require('node:http');
756742
const { AsyncResource, executionAsyncId } = require('node:async_hooks');
757743

content/api/v16/async_hooks.en.md

Lines changed: 24 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,9 @@ Experimental
1818
The `node:async_hooks` module provides an API to track asynchronous resources.
1919
It can be accessed using:
2020

21-
```mjs
21+
```mjs|cjs
2222
import async_hooks from 'node:async_hooks';
23-
```
24-
25-
```cjs
23+
--------------
2624
const async_hooks = require('node:async_hooks');
2725
```
2826

@@ -42,7 +40,7 @@ interface, and each thread will use a new set of async IDs.
4240

4341
Following is a simple overview of the public API.
4442

45-
```mjs
43+
```mjs|cjs
4644
import async_hooks from 'node:async_hooks';
4745
4846
// Return the ID of the current execution context.
@@ -88,9 +86,7 @@ function destroy(asyncId) { }
8886
// resolve() function passed to the Promise constructor is invoked
8987
// (either directly or through other means of resolving a promise).
9088
function promiseResolve(asyncId) { }
91-
```
92-
93-
```cjs
89+
--------------
9490
const async_hooks = require('node:async_hooks');
9591
9692
// Return the ID of the current execution context.
@@ -161,16 +157,14 @@ be tracked, then only the `destroy` callback needs to be passed. The
161157
specifics of all functions that can be passed to `callbacks` is in the
162158
[Hook Callbacks][] section.
163159

164-
```mjs
160+
```mjs|cjs
165161
import { createHook } from 'node:async_hooks';
166162
167163
const asyncHook = createHook({
168164
init(asyncId, type, triggerAsyncId, resource) { },
169165
destroy(asyncId) { }
170166
});
171-
```
172-
173-
```cjs
167+
--------------
174168
const async_hooks = require('node:async_hooks');
175169
176170
const asyncHook = async_hooks.createHook({
@@ -226,17 +220,15 @@ synchronous logging operation such as `fs.writeFileSync(file, msg, flag)`.
226220
This will print to the file and will not invoke `AsyncHook` recursively because
227221
it is synchronous.
228222

229-
```mjs
223+
```mjs|cjs
230224
import { writeFileSync } from 'node:fs';
231225
import { format } from 'node:util';
232226
233227
function debug(...args) {
234228
// Use a function like this one when debugging inside an AsyncHook callback
235229
writeFileSync('log.out', `${format(...args)}\n`, { flag: 'a' });
236230
}
237-
```
238-
239-
```cjs
231+
--------------
240232
const fs = require('node:fs');
241233
const util = require('node:util');
242234
@@ -267,13 +259,11 @@ provided, enabling is a no-op.
267259
The `AsyncHook` instance is disabled by default. If the `AsyncHook` instance
268260
should be enabled immediately after creation, the following pattern can be used.
269261

270-
```mjs
262+
```mjs|cjs
271263
import { createHook } from 'node:async_hooks';
272264
273265
const hook = createHook(callbacks).enable();
274-
```
275-
276-
```cjs
266+
--------------
277267
const async_hooks = require('node:async_hooks');
278268
279269
const hook = async_hooks.createHook(callbacks).enable();
@@ -313,15 +303,13 @@ This behavior can be observed by doing something like opening a resource then
313303
closing it before the resource can be used. The following snippet demonstrates
314304
this.
315305

316-
```mjs
306+
```mjs|cjs
317307
import { createServer } from 'node:net';
318308
319309
createServer().listen(function() { this.close(); });
320310
// OR
321311
clearTimeout(setTimeout(() => {}, 10));
322-
```
323-
324-
```cjs
312+
--------------
325313
require('node:net').createServer().listen(function() { this.close(); });
326314
// OR
327315
clearTimeout(setTimeout(() => {}, 10));
@@ -367,7 +355,7 @@ created, while `triggerAsyncId` shows _why_ a resource was created.
367355

368356
The following is a simple demonstration of `triggerAsyncId`:
369357

370-
```mjs
358+
```mjs|cjs
371359
import { createHook, executionAsyncId } from 'node:async_hooks';
372360
import { stdout } from 'node:process';
373361
import net from 'node:net';
@@ -382,9 +370,7 @@ createHook({
382370
}).enable();
383371
384372
net.createServer((conn) => {}).listen(8080);
385-
```
386-
387-
```cjs
373+
--------------
388374
const { createHook, executionAsyncId } = require('node:async_hooks');
389375
const { stdout } = require('node:process');
390376
const net = require('node:net');
@@ -619,17 +605,15 @@ Using `executionAsyncResource()` in the top-level execution context will
619605
return an empty object as there is no handle or request object to use,
620606
but having an object representing the top-level can be helpful.
621607

622-
```mjs
608+
```mjs|cjs
623609
import { open } from 'node:fs';
624610
import { executionAsyncId, executionAsyncResource } from 'node:async_hooks';
625611
626612
console.log(executionAsyncId(), executionAsyncResource()); // 1 {}
627613
open(new URL(import.meta.url), 'r', (err, fd) => {
628614
console.log(executionAsyncId(), executionAsyncResource()); // 7 FSReqWrap
629615
});
630-
```
631-
632-
```cjs
616+
--------------
633617
const { open } = require('node:fs');
634618
const { executionAsyncId, executionAsyncResource } = require('node:async_hooks');
635619
@@ -642,7 +626,7 @@ open(__filename, 'r', (err, fd) => {
642626
This can be used to implement continuation local storage without the
643627
use of a tracking `Map` to store the metadata:
644628

645-
```mjs
629+
```mjs|cjs
646630
import { createServer } from 'node:http';
647631
import {
648632
executionAsyncId,
@@ -666,9 +650,7 @@ const server = createServer((req, res) => {
666650
res.end(JSON.stringify(executionAsyncResource()[sym]));
667651
}, 100);
668652
}).listen(3000);
669-
```
670-
671-
```cjs
653+
--------------
672654
const { createServer } = require('node:http');
673655
const {
674656
executionAsyncId,
@@ -701,16 +683,14 @@ const server = createServer((req, res) => {
701683
* Returns: [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The `asyncId` of the current execution context. Useful to
702684
track when something calls.
703685

704-
```mjs
686+
```mjs|cjs
705687
import { executionAsyncId } from 'node:async_hooks';
706688
707689
console.log(executionAsyncId()); // 1 - bootstrap
708690
fs.open(path, 'r', (err, fd) => {
709691
console.log(executionAsyncId()); // 6 - open()
710692
});
711-
```
712-
713-
```cjs
693+
--------------
714694
const async_hooks = require('node:async_hooks');
715695
716696
console.log(async_hooks.executionAsyncId()); // 1 - bootstrap
@@ -778,17 +758,15 @@ expensive nature of the [promise introspection API][PromiseHooks] provided by
778758
V8. This means that programs using promises or `async`/`await` will not get
779759
correct execution and trigger ids for promise callback contexts by default.
780760

781-
```mjs
761+
```mjs|cjs
782762
import { executionAsyncId, triggerAsyncId } from 'node:async_hooks';
783763
784764
Promise.resolve(1729).then(() => {
785765
console.log(`eid ${executionAsyncId()} tid ${triggerAsyncId()}`);
786766
});
787767
// produces:
788768
// eid 1 tid 0
789-
```
790-
791-
```cjs
769+
--------------
792770
const { executionAsyncId, triggerAsyncId } = require('node:async_hooks');
793771
794772
Promise.resolve(1729).then(() => {
@@ -806,17 +784,15 @@ the resource that caused (triggered) the `then()` callback to be executed.
806784
Installing async hooks via `async_hooks.createHook` enables promise execution
807785
tracking:
808786

809-
```mjs
787+
```mjs|cjs
810788
import { createHook, executionAsyncId, triggerAsyncId } from 'node:async_hooks';
811789
createHook({ init() {} }).enable(); // forces PromiseHooks to be enabled.
812790
Promise.resolve(1729).then(() => {
813791
console.log(`eid ${executionAsyncId()} tid ${triggerAsyncId()}`);
814792
});
815793
// produces:
816794
// eid 7 tid 6
817-
```
818-
819-
```cjs
795+
--------------
820796
const { createHook, executionAsyncId, triggerAsyncId } = require('node:async_hooks');
821797
822798
createHook({ init() {} }).enable(); // forces PromiseHooks to be enabled.

0 commit comments

Comments
 (0)