doc: esm examples /w imports for process, Buffer

PR-URL: #39043
Reviewed-By: Bradley Farias <[email protected]>

Author: guybedford

.eslintrc.js

@@ -98,6 +98,14 @@ module.exports = {
           name: 'require',
           message: 'Use import instead',
         },
+        {
+          name: 'Buffer',
+          message: 'Import Buffer instead of using the global'
+        },
+        {
+          name: 'process',
+          message: 'Import process instead of using the global'
+        },
       ] },
     },
   ],

doc/api/assert.md

@@ -240,6 +240,7 @@ for the verification to take place. The usual pattern would be to call it in a
 
 ```mjs
 import assert from 'assert';
+import process from 'process';
 
 const tracker = new assert.CallTracker();
 

doc/api/async_context.md

@@ -14,7 +14,11 @@ in other languages.
 The `AsyncLocalStorage` and `AsyncResource` classes are part of the
 `async_hooks` module:
 
-```js
+```mjs
+import async_hooks from 'async_hooks';
+```
+
+```cjs
 const async_hooks = require('async_hooks');
 ```
 
@@ -40,7 +44,39 @@ The following example uses `AsyncLocalStorage` to build a simple logger
 that assigns IDs to incoming HTTP requests and includes them in messages
 logged within each request.
 
-```js
+```mjs
+import http from 'http';
+import { AsyncLocalStorage } from 'async_hooks';
+
+const asyncLocalStorage = new AsyncLocalStorage();
+
+function logWithId(msg) {
+  const id = asyncLocalStorage.getStore();
+  console.log(`${id !== undefined ? id : '-'}:`, msg);
+}
+
+let idSeq = 0;
+http.createServer((req, res) => {
+  asyncLocalStorage.run(idSeq++, () => {
+    logWithId('start');
+    // Imagine any chain of async operations here
+    setImmediate(() => {
+      logWithId('finish');
+      res.end();
+    });
+  });
+}).listen(8080);
+
+http.get('http://localhost:8080');
+http.get('http://localhost:8080');
+// Prints:
+//   0: start
+//   1: start
+//   0: finish
+//   1: finish
+```
+
+```cjs
 const http = require('http');
 const { AsyncLocalStorage } = require('async_hooks');
 
@@ -299,7 +335,35 @@ The `init` hook will trigger when an `AsyncResource` is instantiated.
 
 The following is an overview of the `AsyncResource` API.
 
-```js
+```mjs
+import { AsyncResource, executionAsyncId } from 'async_hooks';
+
+// AsyncResource() is meant to be extended. Instantiating a
+// new AsyncResource() also triggers init. If triggerAsyncId is omitted then
+// async_hook.executionAsyncId() is used.
+const asyncResource = new AsyncResource(
+  type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false }
+);
+
+// Run a function in the execution context of the resource. This will
+// * establish the context of the resource
+// * trigger the AsyncHooks before callbacks
+// * call the provided function `fn` with the supplied arguments
+// * trigger the AsyncHooks after callbacks
+// * restore the original execution context
+asyncResource.runInAsyncScope(fn, thisArg, ...args);
+
+// Call AsyncHooks destroy callbacks.
+asyncResource.emitDestroy();
+
+// Return the unique ID assigned to the AsyncResource instance.
+asyncResource.asyncId();
+
+// Return the trigger ID for the AsyncResource instance.
+asyncResource.triggerAsyncId();
+```
+
+```cjs
 const { AsyncResource, executionAsyncId } = require('async_hooks');
 
 // AsyncResource() is meant to be extended. Instantiating a
@@ -446,7 +510,14 @@ database connection pools, can follow a similar model.
 Assuming that the task is adding two numbers, using a file named
 `task_processor.js` with the following content:
 
-```js
+```mjs
+import { parentPort } from 'worker_threads';
+parentPort.on('message', (task) => {
+  parentPort.postMessage(task.a + task.b);
+});
+```
+
+```cjs
 const { parentPort } = require('worker_threads');
 parentPort.on('message', (task) => {
   parentPort.postMessage(task.a + task.b);
@@ -455,7 +526,95 @@ parentPort.on('message', (task) => {
 
 a Worker pool around it could use the following structure:
 
-```js
+```mjs
+import { AsyncResource } from 'async_hooks';
+import { EventEmitter } from 'events';
+import path from 'path';
+import { Worker } from 'worker_threads';
+
+const kTaskInfo = Symbol('kTaskInfo');
+const kWorkerFreedEvent = Symbol('kWorkerFreedEvent');
+
+class WorkerPoolTaskInfo extends AsyncResource {
+  constructor(callback) {
+    super('WorkerPoolTaskInfo');
+    this.callback = callback;
+  }
+
+  done(err, result) {
+    this.runInAsyncScope(this.callback, null, err, result);
+    this.emitDestroy();  // `TaskInfo`s are used only once.
+  }
+}
+
+export default class WorkerPool extends EventEmitter {
+  constructor(numThreads) {
+    super();
+    this.numThreads = numThreads;
+    this.workers = [];
+    this.freeWorkers = [];
+    this.tasks = [];
+
+    for (let i = 0; i < numThreads; i++)
+      this.addNewWorker();
+
+    // Any time the kWorkerFreedEvent is emitted, dispatch
+    // the next task pending in the queue, if any.
+    this.on(kWorkerFreedEvent, () => {
+      if (this.tasks.length > 0) {
+        const { task, callback } = this.tasks.shift();
+        this.runTask(task, callback);
+      }
+    });
+  }
+
+  addNewWorker() {
+    const worker = new Worker(new URL('task_processer.js', import.meta.url));
+    worker.on('message', (result) => {
+      // In case of success: Call the callback that was passed to `runTask`,
+      // remove the `TaskInfo` associated with the Worker, and mark it as free
+      // again.
+      worker[kTaskInfo].done(null, result);
+      worker[kTaskInfo] = null;
+      this.freeWorkers.push(worker);
+      this.emit(kWorkerFreedEvent);
+    });
+    worker.on('error', (err) => {
+      // In case of an uncaught exception: Call the callback that was passed to
+      // `runTask` with the error.
+      if (worker[kTaskInfo])
+        worker[kTaskInfo].done(err, null);
+      else
+        this.emit('error', err);
+      // Remove the worker from the list and start a new Worker to replace the
+      // current one.
+      this.workers.splice(this.workers.indexOf(worker), 1);
+      this.addNewWorker();
+    });
+    this.workers.push(worker);
+    this.freeWorkers.push(worker);
+    this.emit(kWorkerFreedEvent);
+  }
+
+  runTask(task, callback) {
+    if (this.freeWorkers.length === 0) {
+      // No free threads, wait until a worker thread becomes free.
+      this.tasks.push({ task, callback });
+      return;
+    }
+
+    const worker = this.freeWorkers.pop();
+    worker[kTaskInfo] = new WorkerPoolTaskInfo(callback);
+    worker.postMessage(task);
+  }
+
+  close() {
+    for (const worker of this.workers) worker.terminate();
+  }
+}
+```
+
+```cjs
 const { AsyncResource } = require('async_hooks');
 const { EventEmitter } = require('events');
 const path = require('path');
@@ -553,7 +712,23 @@ were scheduled.
 
 This pool could be used as follows:
 
-```js
+```mjs
+import WorkerPool from './worker_pool.js';
+import os from 'os';
+
+const pool = new WorkerPool(os.cpus().length);
+
+let finished = 0;
+for (let i = 0; i < 10; i++) {
+  pool.runTask({ a: 42, b: 100 }, (err, result) => {
+    console.log(i, err, result);
+    if (++finished === 10)
+      pool.close();
+  });
+}
+```
+
+```cjs
 const WorkerPool = require('./worker_pool.js');
 const os = require('os');
 
@@ -579,7 +754,22 @@ The following example shows how to use the `AsyncResource` class to properly
 associate an event listener with the correct execution context. The same
 approach can be applied to a [`Stream`][] or a similar event-driven class.
 
-```js
+```mjs
+import { createServer } from 'http';
+import { AsyncResource, executionAsyncId } from 'async_hooks';
+
+const server = createServer((req, res) => {
+  req.on('close', AsyncResource.bind(() => {
+    // Execution context is bound to the current outer scope.
+  }));
+  req.on('close', () => {
+    // Execution context is bound to the scope that caused 'close' to emit.
+  });
+  res.end();
+}).listen(3000);
+```
+
+```cjs
 const { createServer } = require('http');
 const { AsyncResource, executionAsyncId } = require('async_hooks');
 
@@ -593,6 +783,7 @@ const server = createServer((req, res) => {
   res.end();
 }).listen(3000);
 ```
+
 [`AsyncResource`]: #async_context_class_asyncresource
 [`EventEmitter`]: events.md#events_class_eventemitter
 [`Stream`]: stream.md#stream_stream