@types/node 22.15.21 → 22.18.10

node/fs/promises.d.ts → node v22.18/fs/promises.d.ts

@@ -29,6 +29,7 @@ declare module "fs/promises" {
         OpenDirOptions,
         OpenMode,
         PathLike,
+        ReadPosition,
         ReadStream,
         ReadVResult,
         RmDirOptions,
@@ -39,7 +40,7 @@ declare module "fs/promises" {
         StatsFs,
         TimeLike,
         WatchEventType,
-        WatchOptions,
+        WatchOptions as _WatchOptions,
         WriteStream,
         WriteVResult,
     } from "node:fs";
@@ -69,7 +70,7 @@ declare module "fs/promises" {
          * @default `buffer.byteLength`
          */
         length?: number | null;
-        position?: number | null;
+        position?: ReadPosition | null;
     }
     interface CreateReadStreamOptions extends Abortable {
         encoding?: BufferEncoding | null | undefined;
@@ -87,6 +88,9 @@ declare module "fs/promises" {
         highWaterMark?: number | undefined;
         flush?: boolean | undefined;
     }
+    interface ReadableWebStreamOptions {
+        autoClose?: boolean | undefined;
+    }
     // TODO: Add `EventEmitter` close
     interface FileHandle {
         /**
@@ -229,7 +233,7 @@ declare module "fs/promises" {
             buffer: T,
             offset?: number | null,
             length?: number | null,
-            position?: number | null,
+            position?: ReadPosition | null,
         ): Promise<FileReadResult<T>>;
         read<T extends NodeJS.ArrayBufferView = Buffer>(
             buffer: T,
@@ -259,9 +263,8 @@ declare module "fs/promises" {
          * 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
          */
-        readableWebStream(): ReadableStream;
+        readableWebStream(options?: ReadableWebStreamOptions): ReadableStream;
         /**
          * Asynchronously reads the entire contents of a file.
          *
@@ -474,7 +477,8 @@ declare module "fs/promises" {
          */
         close(): Promise<void>;
         /**
-         * An alias for {@link FileHandle.close()}.
+         * Calls `filehandle.close()` and returns a promise that fulfills when the
+         * filehandle is closed.
          * @since v20.4.0
          */
         [Symbol.asyncDispose](): Promise<void>;
@@ -1178,6 +1182,16 @@ declare module "fs/promises" {
      * @return Fulfills with an {fs.Dir}.
      */
     function opendir(path: PathLike, options?: OpenDirOptions): Promise<Dir>;
+    interface WatchOptions extends _WatchOptions {
+        maxQueue?: number | undefined;
+        overflow?: "ignore" | "throw" | undefined;
+    }
+    interface WatchOptionsWithBufferEncoding extends WatchOptions {
+        encoding: "buffer";
+    }
+    interface WatchOptionsWithStringEncoding extends WatchOptions {
+        encoding?: BufferEncoding | undefined;
+    }
     /**
      * Returns an async iterator that watches for changes on `filename`, where `filename`is either a file or a directory.
      *
@@ -1210,33 +1224,16 @@ declare module "fs/promises" {
      */
     function watch(
         filename: PathLike,
-        options:
-            | (WatchOptions & {
-                encoding: "buffer";
-            })
-            | "buffer",
-    ): AsyncIterable<FileChangeInfo<Buffer>>;
-    /**
-     * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
-     * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
-     * @param options Either the encoding for the filename provided to the listener, or an object optionally specifying encoding, persistent, and recursive options.
-     * If `encoding` is not supplied, the default of `'utf8'` is used.
-     * If `persistent` is not supplied, the default of `true` is used.
-     * If `recursive` is not supplied, the default of `false` is used.
-     */
-    function watch(filename: PathLike, options?: WatchOptions | BufferEncoding): AsyncIterable<FileChangeInfo<string>>;
-    /**
-     * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
-     * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
-     * @param options Either the encoding for the filename provided to the listener, or an object optionally specifying encoding, persistent, and recursive options.
-     * If `encoding` is not supplied, the default of `'utf8'` is used.
-     * If `persistent` is not supplied, the default of `true` is used.
-     * If `recursive` is not supplied, the default of `false` is used.
-     */
+        options?: WatchOptionsWithStringEncoding | BufferEncoding,
+    ): NodeJS.AsyncIterator<FileChangeInfo<string>>;
     function watch(
         filename: PathLike,
-        options: WatchOptions | string,
-    ): AsyncIterable<FileChangeInfo<string>> | AsyncIterable<FileChangeInfo<Buffer>>;
+        options: WatchOptionsWithBufferEncoding | "buffer",
+    ): NodeJS.AsyncIterator<FileChangeInfo<Buffer>>;
+    function watch(
+        filename: PathLike,
+        options: WatchOptions | BufferEncoding | "buffer",
+    ): NodeJS.AsyncIterator<FileChangeInfo<string | Buffer>>;
     /**
      * Asynchronously copies the entire directory structure from `src` to `dest`,
      * including subdirectories and files.
@@ -1251,20 +1248,28 @@ declare module "fs/promises" {
      */
     function cp(source: string | URL, destination: string | URL, opts?: CopyOptions): Promise<void>;
     /**
-     * Retrieves the files matching the specified pattern.
+     * ```js
+     * import { glob } from 'node:fs/promises';
+     *
+     * for await (const entry of glob('*.js'))
+     *   console.log(entry);
+     * ```
+     * @since v22.0.0
+     * @returns An AsyncIterator that yields the paths of files
+     * that match the pattern.
      */
-    function glob(pattern: string | string[]): NodeJS.AsyncIterator<string>;
+    function glob(pattern: string | readonly string[]): NodeJS.AsyncIterator<string>;
     function glob(
-        pattern: string | string[],
-        opt: GlobOptionsWithFileTypes,
+        pattern: string | readonly string[],
+        options: GlobOptionsWithFileTypes,
     ): NodeJS.AsyncIterator<Dirent>;
     function glob(
-        pattern: string | string[],
-        opt: GlobOptionsWithoutFileTypes,
+        pattern: string | readonly string[],
+        options: GlobOptionsWithoutFileTypes,
     ): NodeJS.AsyncIterator<string>;
     function glob(
-        pattern: string | string[],
-        opt: GlobOptions,
+        pattern: string | readonly string[],
+        options: GlobOptions,
     ): NodeJS.AsyncIterator<Dirent | string>;
 }
 declare module "node:fs/promises" {

node/fs.d.ts → node v22.18/fs.d.ts

@@ -243,8 +243,8 @@ declare module "fs" {
          */
         name: Name;
         /**
-         * The base path that this `fs.Dirent` object refers to.
-         * @since v20.12.0
+         * The path to the parent directory of the file this `fs.Dirent` object refers to.
+         * @since v20.12.0, v18.20.0
          */
         parentPath: string;
         /**
@@ -328,6 +328,20 @@ declare module "fs" {
          * @since v12.12.0
          */
         readSync(): Dirent | null;
+        /**
+         * Calls `dir.close()` if the directory handle is open, and returns a promise that
+         * fulfills when disposal is complete.
+         * @since v22.17.0
+         * @experimental
+         */
+        [Symbol.asyncDispose](): Promise<void>;
+        /**
+         * Calls `dir.closeSync()` if the directory handle is open, and returns
+         * `undefined`.
+         * @since v22.17.0
+         * @experimental
+         */
+        [Symbol.dispose](): void;
     }
     /**
      * Class: fs.StatWatcher
@@ -2371,7 +2385,7 @@ declare module "fs" {
         /**
          * @default null
          */
-        position?: number | undefined | null;
+        position?: number | null | undefined;
     }
     /**
      * Write `buffer` to the file specified by `fd`.
@@ -2656,7 +2670,7 @@ declare module "fs" {
             buffer: TBuffer,
             offset: number,
             length: number,
-            position: number | null,
+            position: ReadPosition | null,
         ): Promise<{
             bytesRead: number;
             buffer: TBuffer;
@@ -3327,6 +3341,12 @@ declare module "fs" {
         persistent?: boolean | undefined;
         recursive?: boolean | undefined;
     }
+    export interface WatchOptionsWithBufferEncoding extends WatchOptions {
+        encoding: "buffer";
+    }
+    export interface WatchOptionsWithStringEncoding extends WatchOptions {
+        encoding?: BufferEncoding | undefined;
+    }
     export type WatchEventType = "rename" | "change";
     export type WatchListener<T> = (event: WatchEventType, filename: T | null) => void;
     export type StatsListener = (curr: Stats, prev: Stats) => void;
@@ -3353,44 +3373,20 @@ declare module "fs" {
      */
     export function watch(
         filename: PathLike,
-        options:
-            | (WatchOptions & {
-                encoding: "buffer";
-            })
-            | "buffer",
-        listener?: WatchListener<Buffer>,
+        options?: WatchOptionsWithStringEncoding | BufferEncoding | null,
+        listener?: WatchListener<string>,
     ): FSWatcher;
-    /**
-     * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
-     * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
-     * @param options Either the encoding for the filename provided to the listener, or an object optionally specifying encoding, persistent, and recursive options.
-     * If `encoding` is not supplied, the default of `'utf8'` is used.
-     * If `persistent` is not supplied, the default of `true` is used.
-     * If `recursive` is not supplied, the default of `false` is used.
-     */
     export function watch(
         filename: PathLike,
-        options?: WatchOptions | BufferEncoding | null,
-        listener?: WatchListener<string>,
+        options: WatchOptionsWithBufferEncoding | "buffer",
+        listener: WatchListener<Buffer>,
     ): FSWatcher;
-    /**
-     * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
-     * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
-     * @param options Either the encoding for the filename provided to the listener, or an object optionally specifying encoding, persistent, and recursive options.
-     * If `encoding` is not supplied, the default of `'utf8'` is used.
-     * If `persistent` is not supplied, the default of `true` is used.
-     * If `recursive` is not supplied, the default of `false` is used.
-     */
     export function watch(
         filename: PathLike,
-        options: WatchOptions | string,
-        listener?: WatchListener<string | Buffer>,
+        options: WatchOptions | BufferEncoding | "buffer" | null,
+        listener: WatchListener<string | Buffer>,
     ): FSWatcher;
-    /**
-     * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`.
-     * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
-     */
-    export function watch(filename: PathLike, listener?: WatchListener<string>): FSWatcher;
+    export function watch(filename: PathLike, listener: WatchListener<string>): FSWatcher;
     /**
      * Test whether or not the given path exists by checking with the file system.
      * Then call the `callback` argument with either true or false:
@@ -4200,7 +4196,6 @@ declare module "fs" {
      * blob.stream();
      * ```
      * @since v19.8.0
-     * @experimental
      */
     export function openAsBlob(path: PathLike, options?: OpenAsBlobOptions): Promise<Blob>;
 
@@ -4219,7 +4214,7 @@ declare module "fs" {
         /**
          * @default false
          */
-        recursive?: boolean;
+        recursive?: boolean | undefined;
     }
     /**
      * Synchronously open a directory. See [`opendir(3)`](http://man7.org/linux/man-pages/man3/opendir.3.html).
@@ -4272,54 +4267,54 @@ declare module "fs" {
          * Dereference symlinks
          * @default false
          */
-        dereference?: boolean;
+        dereference?: boolean | undefined;
         /**
          * When `force` is `false`, and the destination
          * exists, throw an error.
          * @default false
          */
-        errorOnExist?: boolean;
+        errorOnExist?: boolean | undefined;
         /**
          * Overwrite existing file or directory. _The copy
          * operation will ignore errors if you set this to false and the destination
          * exists. Use the `errorOnExist` option to change this behavior.
          * @default true
          */
-        force?: boolean;
+        force?: boolean | undefined;
         /**
          * Modifiers for copy operation. See `mode` flag of {@link copyFileSync()}
          */
-        mode?: number;
+        mode?: number | undefined;
         /**
          * When `true` timestamps from `src` will
          * be preserved.
          * @default false
          */
-        preserveTimestamps?: boolean;
+        preserveTimestamps?: boolean | undefined;
         /**
          * Copy directories recursively.
          * @default false
          */
-        recursive?: boolean;
+        recursive?: boolean | undefined;
         /**
          * When true, path resolution for symlinks will be skipped
          * @default false
          */
-        verbatimSymlinks?: boolean;
+        verbatimSymlinks?: boolean | undefined;
     }
     export interface CopyOptions extends CopyOptionsBase {
         /**
          * Function to filter copied files/directories. Return
          * `true` to copy the item, `false` to ignore it.
          */
-        filter?(source: string, destination: string): boolean | Promise<boolean>;
+        filter?: ((source: string, destination: string) => boolean | Promise<boolean>) | undefined;
     }
     export interface CopySyncOptions extends CopyOptionsBase {
         /**
          * Function to filter copied files/directories. Return
          * `true` to copy the item, `false` to ignore it.
          */
-        filter?(source: string, destination: string): boolean;
+        filter?: ((source: string, destination: string) => boolean) | undefined;
     }
     /**
      * Asynchronously copies the entire directory structure from `src` to `dest`,
@@ -4361,7 +4356,7 @@ declare module "fs" {
          * Current working directory.
          * @default process.cwd()
          */
-        cwd?: string | undefined;
+        cwd?: string | URL | undefined;
         /**
          * `true` if the glob should return paths as `Dirent`s, `false` otherwise.
          * @default false
@@ -4386,13 +4381,23 @@ declare module "fs" {
 
     /**
      * Retrieves the files matching the specified pattern.
+     *
+     * ```js
+     * import { glob } from 'node:fs';
+     *
+     * glob('*.js', (err, matches) => {
+     *   if (err) throw err;
+     *   console.log(matches);
+     * });
+     * ```
+     * @since v22.0.0
      */
     export function glob(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         callback: (err: NodeJS.ErrnoException | null, matches: string[]) => void,
     ): void;
     export function glob(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptionsWithFileTypes,
         callback: (
             err: NodeJS.ErrnoException | null,
@@ -4400,7 +4405,7 @@ declare module "fs" {
         ) => void,
     ): void;
     export function glob(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptionsWithoutFileTypes,
         callback: (
             err: NodeJS.ErrnoException | null,
@@ -4408,7 +4413,7 @@ declare module "fs" {
         ) => void,
     ): void;
     export function glob(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptions,
         callback: (
             err: NodeJS.ErrnoException | null,
@@ -4416,19 +4421,25 @@ declare module "fs" {
         ) => void,
     ): void;
     /**
-     * Retrieves the files matching the specified pattern.
+     * ```js
+     * import { globSync } from 'node:fs';
+     *
+     * console.log(globSync('*.js'));
+     * ```
+     * @since v22.0.0
+     * @returns paths of files that match the pattern.
      */
-    export function globSync(pattern: string | string[]): string[];
+    export function globSync(pattern: string | readonly string[]): string[];
     export function globSync(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptionsWithFileTypes,
     ): Dirent[];
     export function globSync(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptionsWithoutFileTypes,
     ): string[];
     export function globSync(
-        pattern: string | string[],
+        pattern: string | readonly string[],
         options: GlobOptions,
     ): Dirent[] | string[];
 }

node v22.18/globals.d.ts

@@ -0,0 +1,172 @@
+declare var global: typeof globalThis;
+
+declare var process: NodeJS.Process;
+declare var console: Console;
+
+interface ErrorConstructor {
+    /**
+     * Creates a `.stack` property on `targetObject`, which when accessed returns
+     * a string representing the location in the code at which
+     * `Error.captureStackTrace()` was called.
+     *
+     * ```js
+     * const myObject = {};
+     * Error.captureStackTrace(myObject);
+     * myObject.stack;  // Similar to `new Error().stack`
+     * ```
+     *
+     * The first line of the trace will be prefixed with
+     * `${myObject.name}: ${myObject.message}`.
+     *
+     * The optional `constructorOpt` argument accepts a function. If given, all frames
+     * above `constructorOpt`, including `constructorOpt`, will be omitted from the
+     * generated stack trace.
+     *
+     * The `constructorOpt` argument is useful for hiding implementation
+     * details of error generation from the user. For instance:
+     *
+     * ```js
+     * function a() {
+     *   b();
+     * }
+     *
+     * function b() {
+     *   c();
+     * }
+     *
+     * function c() {
+     *   // Create an error without stack trace to avoid calculating the stack trace twice.
+     *   const { stackTraceLimit } = Error;
+     *   Error.stackTraceLimit = 0;
+     *   const error = new Error();
+     *   Error.stackTraceLimit = stackTraceLimit;
+     *
+     *   // Capture the stack trace above function b
+     *   Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+     *   throw error;
+     * }
+     *
+     * a();
+     * ```
+     */
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    /**
+     * @see https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+     */
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    /**
+     * The `Error.stackTraceLimit` property specifies the number of stack frames
+     * collected by a stack trace (whether generated by `new Error().stack` or
+     * `Error.captureStackTrace(obj)`).
+     *
+     * The default value is `10` but may be set to any valid JavaScript number. Changes
+     * will affect any stack trace captured _after_ the value has been changed.
+     *
+     * If set to a non-number value, or set to a negative number, stack traces will
+     * not capture any frames.
+     */
+    stackTraceLimit: number;
+}
+
+/**
+ * Enable this API with the `--expose-gc` CLI flag.
+ */
+declare var gc: NodeJS.GCFunction | undefined;
+
+declare namespace NodeJS {
+    interface CallSite {
+        getColumnNumber(): number | null;
+        getEnclosingColumnNumber(): number | null;
+        getEnclosingLineNumber(): number | null;
+        getEvalOrigin(): string | undefined;
+        getFileName(): string | null;
+        getFunction(): Function | undefined;
+        getFunctionName(): string | null;
+        getLineNumber(): number | null;
+        getMethodName(): string | null;
+        getPosition(): number;
+        getPromiseIndex(): number | null;
+        getScriptHash(): string;
+        getScriptNameOrSourceURL(): string | null;
+        getThis(): unknown;
+        getTypeName(): string | null;
+        isAsync(): boolean;
+        isConstructor(): boolean;
+        isEval(): boolean;
+        isNative(): boolean;
+        isPromiseAll(): boolean;
+        isToplevel(): boolean;
+    }
+
+    interface ErrnoException extends Error {
+        errno?: number | undefined;
+        code?: string | undefined;
+        path?: string | undefined;
+        syscall?: string | undefined;
+    }
+
+    interface ReadableStream extends EventEmitter {
+        readable: boolean;
+        read(size?: number): string | Buffer;
+        setEncoding(encoding: BufferEncoding): this;
+        pause(): this;
+        resume(): this;
+        isPaused(): boolean;
+        pipe<T extends WritableStream>(destination: T, options?: { end?: boolean | undefined }): T;
+        unpipe(destination?: WritableStream): this;
+        unshift(chunk: string | Uint8Array, encoding?: BufferEncoding): void;
+        wrap(oldStream: ReadableStream): this;
+        [Symbol.asyncIterator](): AsyncIterableIterator<string | Buffer>;
+    }
+
+    interface WritableStream extends EventEmitter {
+        writable: boolean;
+        write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean;
+        write(str: string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean;
+        end(cb?: () => void): this;
+        end(data: string | Uint8Array, cb?: () => void): this;
+        end(str: string, encoding?: BufferEncoding, cb?: () => void): this;
+    }
+
+    interface ReadWriteStream extends ReadableStream, WritableStream {}
+
+    interface RefCounted {
+        ref(): this;
+        unref(): this;
+    }
+
+    interface Dict<T> {
+        [key: string]: T | undefined;
+    }
+
+    interface ReadOnlyDict<T> {
+        readonly [key: string]: T | undefined;
+    }
+
+    type PartialOptions<T> = { [K in keyof T]?: T[K] | undefined };
+
+    interface GCFunction {
+        (minor?: boolean): void;
+        (options: NodeJS.GCOptions & { execution: "async" }): Promise<void>;
+        (options: NodeJS.GCOptions): void;
+    }
+
+    interface GCOptions {
+        execution?: "sync" | "async" | undefined;
+        flavor?: "regular" | "last-resort" | undefined;
+        type?: "major-snapshot" | "major" | "minor" | undefined;
+        filename?: string | undefined;
+    }
+
+    /** An iterable iterator returned by the Node.js API. */
+    // Default TReturn/TNext in v22 is `any`, for compatibility with the previously-used IterableIterator.
+    interface Iterator<T, TReturn = any, TNext = any> extends IteratorObject<T, TReturn, TNext> {
+        [Symbol.iterator](): NodeJS.Iterator<T, TReturn, TNext>;
+    }
+
+    /** An async iterable iterator returned by the Node.js API. */
+    // Default TReturn/TNext in v22 is `any`, for compatibility with the previously-used AsyncIterableIterator.
+    interface AsyncIterator<T, TReturn = any, TNext = any> extends AsyncIteratorObject<T, TReturn, TNext> {
+        [Symbol.asyncIterator](): NodeJS.AsyncIterator<T, TReturn, TNext>;
+    }
+}