@types/node 18.16.3 → 20.0.0

node/events.d.ts

@@ -22,7 +22,7 @@
  * the `eventEmitter.emit()` method is used to trigger the event.
  *
  * ```js
- * const EventEmitter = require('events');
+ * import { EventEmitter } from 'node:events';
  *
  * class MyEmitter extends EventEmitter {}
  *
@@ -32,13 +32,12 @@
  * });
  * myEmitter.emit('event');
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/events.js)
+ * @see [source](https://github.com/nodejs/node/blob/v20.0.0/lib/events.js)
  */
 declare module 'events' {
     // NOTE: This class is in the docs but is **not actually exported** by Node.
     // If https://github.com/nodejs/node/issues/39903 gets resolved and Node
     // actually starts exporting the class, uncomment below.
-
     // import { EventListener, EventListenerObject } from '__dom-events';
     // /** The NodeEventTarget is a Node.js-specific extension to EventTarget that emulates a subset of the EventEmitter API. */
     // interface NodeEventTarget extends EventTarget {
@@ -69,7 +68,6 @@ declare module 'events' {
     //      */
     //     removeListener(type: string, listener: EventListener | EventListenerObject): this;
     // }
-
     interface EventEmitterOptions {
         /**
          * Enables automatic capturing of promise rejection.
@@ -95,10 +93,10 @@ declare module 'events' {
     }
     interface EventEmitter extends NodeJS.EventEmitter {}
     /**
-     * The `EventEmitter` class is defined and exposed by the `events` module:
+     * The `EventEmitter` class is defined and exposed by the `node:events` module:
      *
      * ```js
-     * const EventEmitter = require('events');
+     * import { EventEmitter } from 'node:events';
      * ```
      *
      * All `EventEmitter`s emit the event `'newListener'` when new listeners are
@@ -119,31 +117,28 @@ declare module 'events' {
          * semantics and does not listen to the `'error'` event.
          *
          * ```js
-         * const { once, EventEmitter } = require('events');
+         * import { once, EventEmitter } from 'node:events';
+         * import process from 'node:process';
          *
-         * async function run() {
-         *   const ee = new EventEmitter();
+         * const ee = new EventEmitter();
          *
-         *   process.nextTick(() => {
-         *     ee.emit('myevent', 42);
-         *   });
+         * process.nextTick(() => {
+         *   ee.emit('myevent', 42);
+         * });
          *
-         *   const [value] = await once(ee, 'myevent');
-         *   console.log(value);
+         * const [value] = await once(ee, 'myevent');
+         * console.log(value);
          *
-         *   const err = new Error('kaboom');
-         *   process.nextTick(() => {
-         *     ee.emit('error', err);
-         *   });
+         * const err = new Error('kaboom');
+         * process.nextTick(() => {
+         *   ee.emit('error', err);
+         * });
          *
-         *   try {
-         *     await once(ee, 'myevent');
-         *   } catch (err) {
-         *     console.log('error happened', err);
-         *   }
+         * try {
+         *   await once(ee, 'myevent');
+         * } catch (err) {
+         *   console.error('error happened', err);
          * }
-         *
-         * run();
          * ```
          *
          * The special handling of the `'error'` event is only used when `events.once()`is used to wait for another event. If `events.once()` is used to wait for the
@@ -151,13 +146,13 @@ declare module 'events' {
          * special handling:
          *
          * ```js
-         * const { EventEmitter, once } = require('events');
+         * import { EventEmitter, once } from 'node:events';
          *
          * const ee = new EventEmitter();
          *
          * once(ee, 'error')
          *   .then(([err]) => console.log('ok', err.message))
-         *   .catch((err) => console.log('error', err.message));
+         *   .catch((err) => console.error('error', err.message));
          *
          * ee.emit('error', new Error('boom'));
          *
@@ -167,7 +162,7 @@ declare module 'events' {
          * An `AbortSignal` can be used to cancel waiting for the event:
          *
          * ```js
-         * const { EventEmitter, once } = require('events');
+         * import { EventEmitter, once } from 'node:events';
          *
          * const ee = new EventEmitter();
          * const ac = new AbortController();
@@ -195,25 +190,24 @@ declare module 'events' {
         static once(emitter: _DOMEventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise<any[]>;
         /**
          * ```js
-         * const { on, EventEmitter } = require('events');
-         *
-         * (async () => {
-         *   const ee = new EventEmitter();
+         * import { on, EventEmitter } from 'node:events';
+         * import process from 'node:process';
          *
-         *   // Emit later on
-         *   process.nextTick(() => {
-         *     ee.emit('foo', 'bar');
-         *     ee.emit('foo', 42);
-         *   });
+         * const ee = new EventEmitter();
          *
-         *   for await (const event of on(ee, 'foo')) {
-         *     // The execution of this inner block is synchronous and it
-         *     // processes one event at a time (even with await). Do not use
-         *     // if concurrent execution is required.
-         *     console.log(event); // prints ['bar'] [42]
-         *   }
-         *   // Unreachable here
-         * })();
+         * // Emit later on
+         * process.nextTick(() => {
+         *   ee.emit('foo', 'bar');
+         *   ee.emit('foo', 42);
+         * });
+         *
+         * for await (const event of on(ee, 'foo')) {
+         *   // The execution of this inner block is synchronous and it
+         *   // processes one event at a time (even with await). Do not use
+         *   // if concurrent execution is required.
+         *   console.log(event); // prints ['bar'] [42]
+         * }
+         * // Unreachable here
          * ```
          *
          * Returns an `AsyncIterator` that iterates `eventName` events. It will throw
@@ -224,7 +218,9 @@ declare module 'events' {
          * An `AbortSignal` can be used to cancel waiting on events:
          *
          * ```js
-         * const { on, EventEmitter } = require('events');
+         * import { on, EventEmitter } from 'node:events';
+         * import process from 'node:process';
+         *
          * const ac = new AbortController();
          *
          * (async () => {
@@ -256,7 +252,8 @@ declare module 'events' {
          * A class method that returns the number of listeners for the given `eventName`registered on the given `emitter`.
          *
          * ```js
-         * const { EventEmitter, listenerCount } = require('events');
+         * import { EventEmitter, listenerCount } from 'node:events';
+         *
          * const myEmitter = new EventEmitter();
          * myEmitter.on('event', () => {});
          * myEmitter.on('event', () => {});
@@ -279,19 +276,19 @@ declare module 'events' {
          * event target. This is useful for debugging and diagnostic purposes.
          *
          * ```js
-         * const { getEventListeners, EventEmitter } = require('events');
+         * import { getEventListeners, EventEmitter } from 'node:events';
          *
          * {
          *   const ee = new EventEmitter();
          *   const listener = () => console.log('Events are fun');
          *   ee.on('foo', listener);
-         *   getEventListeners(ee, 'foo'); // [listener]
+         *   console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
          * }
          * {
          *   const et = new EventTarget();
          *   const listener = () => console.log('Events are fun');
          *   et.addEventListener('foo', listener);
-         *   getEventListeners(et, 'foo'); // [listener]
+         *   console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
          * }
          * ```
          * @since v15.2.0, v14.17.0
@@ -299,10 +296,7 @@ declare module 'events' {
         static getEventListeners(emitter: _DOMEventTarget | NodeJS.EventEmitter, name: string | symbol): Function[];
         /**
          * ```js
-         * const {
-         *   setMaxListeners,
-         *   EventEmitter
-         * } = require('events');
+         * import { setMaxListeners, EventEmitter } from 'node:events';
          *
          * const target = new EventTarget();
          * const emitter = new EventEmitter();
@@ -370,6 +364,7 @@ declare module 'events' {
                  * event listener to the beginning of the listeners array.
                  *
                  * ```js
+                 * import { EventEmitter } from 'node:events';
                  * const myEE = new EventEmitter();
                  * myEE.on('foo', () => console.log('a'));
                  * myEE.prependListener('foo', () => console.log('b'));
@@ -399,6 +394,7 @@ declare module 'events' {
                  * event listener to the beginning of the listeners array.
                  *
                  * ```js
+                 * import { EventEmitter } from 'node:events';
                  * const myEE = new EventEmitter();
                  * myEE.once('foo', () => console.log('a'));
                  * myEE.prependOnceListener('foo', () => console.log('b'));
@@ -434,6 +430,8 @@ declare module 'events' {
                  * will not remove them from`emit()` in progress. Subsequent events behave as expected.
                  *
                  * ```js
+                 * import { EventEmitter } from 'node:events';
+                 * class MyEmitter extends EventEmitter {}
                  * const myEmitter = new MyEmitter();
                  *
                  * const callbackA = () => {
@@ -474,6 +472,7 @@ declare module 'events' {
                  * recently added instance. In the example the `once('ping')`listener is removed:
                  *
                  * ```js
+                 * import { EventEmitter } from 'node:events';
                  * const ee = new EventEmitter();
                  *
                  * function pong() {
@@ -542,6 +541,7 @@ declare module 'events' {
                  * including any wrappers (such as those created by `.once()`).
                  *
                  * ```js
+                 * import { EventEmitter } from 'node:events';
                  * const emitter = new EventEmitter();
                  * emitter.once('log', () => console.log('log once'));
                  *
@@ -574,7 +574,7 @@ declare module 'events' {
                  * Returns `true` if the event had listeners, `false` otherwise.
                  *
                  * ```js
-                 * const EventEmitter = require('events');
+                 * import { EventEmitter } from 'node:events';
                  * const myEmitter = new EventEmitter();
                  *
                  * // First listener
@@ -609,10 +609,9 @@ declare module 'events' {
                  */
                 emit(eventName: string | symbol, ...args: any[]): boolean;
                 /**
-                 * Returns the number of listeners listening to the event named `eventName`.
-                 *
-                 * If `listener` is provided, it will return how many times the listener
-                 * is found in the list of the listeners of the event.
+                 * Returns the number of listeners listening for the event named `eventName`.
+                 * If `listener` is provided, it will return how many times the listener is found
+                 * in the list of the listeners of the event.
                  * @since v3.2.0
                  * @param eventName The name of the event being listened for
                  * @param listener The event handler function
@@ -657,7 +656,8 @@ declare module 'events' {
                  * listeners. The values in the array are strings or `Symbol`s.
                  *
                  * ```js
-                 * const EventEmitter = require('events');
+                 * import { EventEmitter } from 'node:events';
+                 *
                  * const myEE = new EventEmitter();
                  * myEE.on('foo', () => {});
                  * myEE.on('bar', () => {});

node/fs/promises.d.ts

@@ -41,7 +41,6 @@ declare module 'fs/promises' {
         WriteVResult,
     } from 'node:fs';
     import { Interface as ReadlineInterface } from 'node:readline';
-
     interface FileChangeInfo<T extends string | Buffer> {
         eventType: WatchEventType;
         filename: T;
@@ -115,8 +114,8 @@ declare module 'fs/promises' {
          */
         chmod(mode: Mode): Promise<void>;
         /**
-         * Unlike the 16 kb default `highWaterMark` for a `stream.Readable`, the stream
-         * returned by this method has a default `highWaterMark` of 64 kb.
+         * Unlike the 16 KiB default `highWaterMark` for a `stream.Readable`, the stream
+         * returned by this method has a default `highWaterMark` of 64 KiB.
          *
          * `options` can include `start` and `end` values to read a range of bytes from
          * the file instead of the entire file. Both `start` and `end` are inclusive and
@@ -134,7 +133,7 @@ declare module 'fs/promises' {
          * destroyed.  Set the `emitClose` option to `false` to change this behavior.
          *
          * ```js
-         * import { open } from 'fs/promises';
+         * import { open } from 'node:fs/promises';
          *
          * const fd = await open('/dev/input/event0');
          * // Create a stream from some character device.
@@ -160,7 +159,7 @@ declare module 'fs/promises' {
          * An example to read the last 10 bytes of a file which is 100 bytes long:
          *
          * ```js
-         * import { open } from 'fs/promises';
+         * import { open } from 'node:fs/promises';
          *
          * const fd = await open('sample.txt');
          * fd.createReadStream({ start: 90, end: 99 });
@@ -199,7 +198,7 @@ declare module 'fs/promises' {
          * device. The specific implementation is operating system and device specific.
          * Refer to the POSIX [`fsync(2)`](http://man7.org/linux/man-pages/man2/fsync.2.html) documentation for more detail.
          * @since v10.0.0
-         * @return Fufills with `undefined` upon success.
+         * @return Fulfills with `undefined` upon success.
          */
         sync(): Promise<void>;
         /**
@@ -220,11 +219,13 @@ declare module 'fs/promises' {
         /**
          * Returns a `ReadableStream` that may be used to read the files data.
          *
-         * An error will be thrown if this method is called more than once or is called after the `FileHandle` is closed
-         * or closing.
+         * An error will be thrown if this method is called more than once or is called
+         * after the `FileHandle` is closed or closing.
          *
          * ```js
-         * import { open } from 'node:fs/promises';
+         * import {
+         *   open,
+         * } from 'node:fs/promises';
          *
          * const file = await open('./some/file/to/read');
          *
@@ -234,8 +235,8 @@ declare module 'fs/promises' {
          * await file.close();
          * ```
          *
-         * While the `ReadableStream` will read the file to completion, it will not close the `FileHandle` automatically. User code must still call the `fileHandle.close()` method.
-         *
+         * While the `ReadableStream` will read the file to completion, it will not
+         * close the `FileHandle` automatically. User code must still call the`fileHandle.close()` method.
          * @since v17.0.0
          * @experimental
          */
@@ -289,7 +290,8 @@ declare module 'fs/promises' {
                 | null
         ): Promise<string | Buffer>;
         /**
-         * Convenience method to create a `readline` interface and stream over the file. For example:
+         * Convenience method to create a `readline` interface and stream over the file.
+         * See `filehandle.createReadStream()` for the options.
          *
          * ```js
          * import { open } from 'node:fs/promises';
@@ -300,9 +302,7 @@ declare module 'fs/promises' {
          *   console.log(line);
          * }
          * ```
-         *
          * @since v18.11.0
-         * @param options See `filehandle.createReadStream()` for the options.
          */
         readLines(options?: CreateReadStreamOptions): ReadlineInterface;
         /**
@@ -329,7 +329,7 @@ declare module 'fs/promises' {
          * The following example retains only the first four bytes of the file:
          *
          * ```js
-         * import { open } from 'fs/promises';
+         * import { open } from 'node:fs/promises';
          *
          * let filehandle = null;
          * try {
@@ -356,7 +356,7 @@ declare module 'fs/promises' {
         utimes(atime: TimeLike, mtime: TimeLike): Promise<void>;
         /**
          * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an
-         * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface) or
+         * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface), or an
          * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object.
          * The promise is resolved with no arguments upon success.
          *
@@ -386,10 +386,10 @@ declare module 'fs/promises' {
          * The kernel ignores the position argument and always appends the data to
          * the end of the file.
          * @since v10.0.0
-         * @param [offset=0] The start position from within `buffer` where the data to write begins.
+         * @param offset The start position from within `buffer` where the data to write begins.
          * @param [length=buffer.byteLength - offset] The number of bytes from `buffer` to write.
-         * @param position The offset from the beginning of the file where the data from `buffer` should be written. If `position` is not a `number`, the data will be written at the current position.
-         * See the POSIX pwrite(2) documentation for more detail.
+         * @param [position='null'] The offset from the beginning of the file where the data from `buffer` should be written. If `position` is not a `number`, the data will be written at the current
+         * position. See the POSIX pwrite(2) documentation for more detail.
          */
         write<TBuffer extends Uint8Array>(
             buffer: TBuffer,
@@ -420,14 +420,14 @@ declare module 'fs/promises' {
          * The kernel ignores the position argument and always appends the data to
          * the end of the file.
          * @since v12.9.0
-         * @param position The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current
+         * @param [position='null'] The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current
          * position.
          */
         writev(buffers: ReadonlyArray<NodeJS.ArrayBufferView>, position?: number): Promise<WriteVResult>;
         /**
          * Read from a file and write to an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s
          * @since v13.13.0, v12.17.0
-         * @param position The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position.
+         * @param [position='null'] The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position.
          * @return Fulfills upon success an object containing two properties:
          */
         readv(buffers: ReadonlyArray<NodeJS.ArrayBufferView>, position?: number): Promise<ReadVResult>;
@@ -436,7 +436,7 @@ declare module 'fs/promises' {
          * complete.
          *
          * ```js
-         * import { open } from 'fs/promises';
+         * import { open } from 'node:fs/promises';
          *
          * let filehandle;
          * try {
@@ -450,9 +450,7 @@ declare module 'fs/promises' {
          */
         close(): Promise<void>;
     }
-
     const constants: typeof fsConstants;
-
     /**
      * Tests a user's permissions for the file or directory specified by `path`.
      * The `mode` argument is an optional integer that specifies the accessibility
@@ -466,8 +464,7 @@ declare module 'fs/promises' {
      * written by the current process.
      *
      * ```js
-     * import { access } from 'fs/promises';
-     * import { constants } from 'fs';
+     * import { access, constants } from 'node:fs/promises';
      *
      * try {
      *   await access('/etc/passwd', constants.R_OK | constants.W_OK);
@@ -496,14 +493,13 @@ declare module 'fs/promises' {
      * will be made to remove the destination.
      *
      * ```js
-     * import { constants } from 'fs';
-     * import { copyFile } from 'fs/promises';
+     * import { copyFile, constants } from 'node:fs/promises';
      *
      * try {
      *   await copyFile('source.txt', 'destination.txt');
      *   console.log('source.txt was copied to destination.txt');
      * } catch {
-     *   console.log('The file could not be copied');
+     *   console.error('The file could not be copied');
      * }
      *
      * // By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
@@ -511,7 +507,7 @@ declare module 'fs/promises' {
      *   await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL);
      *   console.log('source.txt was copied to destination.txt');
      * } catch {
-     *   console.log('The file could not be copied');
+     *   console.error('The file could not be copied');
      * }
      * ```
      * @since v10.0.0
@@ -573,6 +569,19 @@ declare module 'fs/promises' {
      * and sticky bits), or an object with a `mode` property and a `recursive`property indicating whether parent directories should be created. Calling`fsPromises.mkdir()` when `path` is a directory
      * that exists results in a
      * rejection only when `recursive` is false.
+     *
+     * ```js
+     * import { mkdir } from 'node:fs/promises';
+     *
+     * try {
+     *   const projectFolder = new URL('./test/project/', import.meta.url);
+     *   const createDir = await mkdir(projectFolder, { recursive: true });
+     *
+     *   console.log(`created ${createDir}`);
+     * } catch (err) {
+     *   console.error(err.message);
+     * }
+     * ```
      * @since v10.0.0
      * @return Upon success, fulfills with `undefined` if `recursive` is `false`, or the first directory path created if `recursive` is `true`.
      */
@@ -615,7 +624,7 @@ declare module 'fs/promises' {
      * If `options.withFileTypes` is set to `true`, the resolved array will contain `fs.Dirent` objects.
      *
      * ```js
-     * import { readdir } from 'fs/promises';
+     * import { readdir } from 'node:fs/promises';
      *
      * try {
      *   const files = await readdir(path);
@@ -703,11 +712,13 @@ declare module 'fs/promises' {
     /**
      * Creates a symbolic link.
      *
-     * The `type` argument is only used on Windows platforms and can be one of `'dir'`,`'file'`, or `'junction'`. Windows junction points require the destination path
-     * to be absolute. When using `'junction'`, the `target` argument will
+     * The `type` argument is only used on Windows platforms and can be one of `'dir'`,`'file'`, or `'junction'`. If the `type` argument is not a string, Node.js will
+     * autodetect `target` type and use `'file'` or `'dir'`. If the `target` does not
+     * exist, `'file'` will be used. Windows junction points require the destination
+     * path to be absolute. When using `'junction'`, the `target` argument will
      * automatically be normalized to absolute path.
      * @since v10.0.0
-     * @param [type='file']
+     * @param [type='null']
      * @return Fulfills with `undefined` upon success.
      */
     function symlink(target: PathLike, path: PathLike, type?: string | null): Promise<void>;
@@ -749,8 +760,8 @@ declare module 'fs/promises' {
     ): Promise<BigIntStats>;
     function stat(path: PathLike, opts?: StatOptions): Promise<Stats | BigIntStats>;
     /**
-     * @since v18.15.0
-     * @return Fulfills with an {fs.StatFs} for the file system.
+     * @since v19.6.0, v18.15.0
+     * @return Fulfills with the {fs.StatFs} object for the given `path`.
      */
     function statfs(
         path: PathLike,
@@ -765,7 +776,6 @@ declare module 'fs/promises' {
         }
     ): Promise<BigIntStatsFs>;
     function statfs(path: PathLike, opts?: StatFsOptions): Promise<StatsFs | BigIntStatsFs>;
-
     /**
      * Creates a new link from the `existingPath` to the `newPath`. See the POSIX [`link(2)`](http://man7.org/linux/man-pages/man2/link.2.html) documentation for more detail.
      * @since v10.0.0
@@ -821,7 +831,7 @@ declare module 'fs/promises' {
      *
      * * Values can be either numbers representing Unix epoch time, `Date`s, or a
      * numeric string like `'123456789.0'`.
-     * * If the value can not be converted to a number, or is `NaN`, `Infinity` or`-Infinity`, an `Error` will be thrown.
+     * * If the value can not be converted to a number, or is `NaN`, `Infinity`, or`-Infinity`, an `Error` will be thrown.
      * @since v10.0.0
      * @return Fulfills with `undefined` upon success.
      */
@@ -866,10 +876,12 @@ declare module 'fs/promises' {
      * object with an `encoding` property specifying the character encoding to use.
      *
      * ```js
-     * import { mkdtemp } from 'fs/promises';
+     * import { mkdtemp } from 'node:fs/promises';
+     * import { join } from 'node:path';
+     * import { tmpdir } from 'node:os';
      *
      * try {
-     *   await mkdtemp(path.join(os.tmpdir(), 'foo-'));
+     *   await mkdtemp(join(tmpdir(), 'foo-'));
      * } catch (err) {
      *   console.error(err);
      * }
@@ -878,9 +890,9 @@ declare module 'fs/promises' {
      * The `fsPromises.mkdtemp()` method will append the six randomly selected
      * characters directly to the `prefix` string. For instance, given a directory`/tmp`, if the intention is to create a temporary directory _within_`/tmp`, the`prefix` must end with a trailing
      * platform-specific path separator
-     * (`require('path').sep`).
+     * (`require('node:path').sep`).
      * @since v10.0.0
-     * @return Fulfills with a string containing the filesystem path of the newly created temporary directory.
+     * @return Fulfills with a string containing the file system path of the newly created temporary directory.
      */
     function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string>;
     /**
@@ -897,7 +909,7 @@ declare module 'fs/promises' {
     function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string | Buffer>;
     /**
      * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an
-     * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface) or
+     * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface), or an
      * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object.
      *
      * The `encoding` option is ignored if `data` is a buffer.
@@ -920,8 +932,8 @@ declare module 'fs/promises' {
      * to be written.
      *
      * ```js
-     * import { writeFile } from 'fs/promises';
-     * import { Buffer } from 'buffer';
+     * import { writeFile } from 'node:fs/promises';
+     * import { Buffer } from 'node:buffer';
      *
      * try {
      *   const controller = new AbortController();
@@ -984,11 +996,25 @@ declare module 'fs/promises' {
      * with an error. On FreeBSD, a representation of the directory's contents will be
      * returned.
      *
+     * An example of reading a `package.json` file located in the same directory of the
+     * running code:
+     *
+     * ```js
+     * import { readFile } from 'node:fs/promises';
+     * try {
+     *   const filePath = new URL('./package.json', import.meta.url);
+     *   const contents = await readFile(filePath, { encoding: 'utf8' });
+     *   console.log(contents);
+     * } catch (err) {
+     *   console.error(err.message);
+     * }
+     * ```
+     *
      * It is possible to abort an ongoing `readFile` using an `AbortSignal`. If a
      * request is aborted the promise returned is rejected with an `AbortError`:
      *
      * ```js
-     * import { readFile } from 'fs/promises';
+     * import { readFile } from 'node:fs/promises';
      *
      * try {
      *   const controller = new AbortController();
@@ -1067,7 +1093,7 @@ declare module 'fs/promises' {
      * Example using async iteration:
      *
      * ```js
-     * import { opendir } from 'fs/promises';
+     * import { opendir } from 'node:fs/promises';
      *
      * try {
      *   const dir = await opendir('./');
@@ -1088,7 +1114,7 @@ declare module 'fs/promises' {
      * Returns an async iterator that watches for changes on `filename`, where `filename`is either a file or a directory.
      *
      * ```js
-     * const { watch } = require('fs/promises');
+     * const { watch } = require('node:fs/promises');
      *
      * const ac = new AbortController();
      * const { signal } = ac;