@types/node 16.11.39 → 18.11.2

node v16.11/fs.d.ts → node/fs.d.ts

@@ -16,7 +16,7 @@
  *
  * All file system operations have synchronous, callback, and promise-based
  * forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM).
- * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/fs.js)
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/fs.js)
  */
 declare module 'fs' {
     import * as stream from 'node:stream';
@@ -268,18 +268,22 @@ declare module 'fs' {
      */
     export interface StatWatcher extends EventEmitter {
         /**
+         * When called, requests that the Node.js event loop _not_ exit so long as the `fs.StatWatcher` is active. Calling `watcher.ref()` multiple times will have
+         * no effect.
+         *
+         * By default, all `fs.StatWatcher` objects are "ref'ed", making it normally
+         * unnecessary to call `watcher.ref()` unless `watcher.unref()` had been
+         * called previously.
          * @since v14.3.0, v12.20.0
-         * When called, requests that the Node.js event loop not exit so long as the `fs.StatWatcher` is active.
-         * Calling `watcher.ref()` multiple times will have no effect.
-         * By default, all `fs.StatWatcher`` objects are "ref'ed", making it normally unnecessary to call `watcher.ref()`
-         * unless `watcher.unref()` had been called previously.
          */
         ref(): this;
         /**
+         * When called, the active `fs.StatWatcher` object will not require the Node.js
+         * event loop to remain active. If there is no other activity keeping the
+         * event loop running, the process may exit before the `fs.StatWatcher` object's
+         * callback is invoked. Calling `watcher.unref()` multiple times will have
+         * no effect.
          * @since v14.3.0, v12.20.0
-         * When called, the active `fs.StatWatcher`` object will not require the Node.js event loop to remain active.
-         * If there is no other activity keeping the event loop running, the process may exit before the `fs.StatWatcher`` object's callback is invoked.
-         * `Calling watcher.unref()` multiple times will have no effect.
          */
         unref(): this;
     }
@@ -1014,8 +1018,10 @@ declare module 'fs' {
         function __promisify__(fd: number, options?: StatOptions): Promise<Stats | BigIntStats>;
     }
     /**
-     * Synchronous fstat(2) - Get file status.
-     * @param fd A file descriptor.
+     * Retrieves the `fs.Stats` for the file descriptor.
+     *
+     * See the POSIX [`fstat(2)`](http://man7.org/linux/man-pages/man2/fstat.2.html) documentation for more detail.
+     * @since v0.1.95
      */
     export function fstatSync(
         fd: number,
@@ -1030,7 +1036,6 @@ declare module 'fs' {
         }
     ): BigIntStats;
     export function fstatSync(fd: number, options?: StatOptions): Stats | BigIntStats;
-
     /**
      * Retrieves the `fs.Stats` for the symbolic link referred to by the path.
      * The callback gets two arguments `(err, stats)` where `stats` is a `fs.Stats` object. `lstat()` is identical to `stat()`, except that if `path` is a symbolic
@@ -1118,15 +1123,15 @@ declare module 'fs' {
      * ```js
      * import { symlink } from 'fs';
      *
-     * symlink('./mew', './example/mewtwo', callback);
+     * symlink('./mew', './mewtwo', callback);
      * ```
      *
-     * The above example creates a symbolic link `mewtwo` in the `example` which points
-     * to `mew` in the same directory:
+     * The above example creates a symbolic link `mewtwo` which points to `mew` in the
+     * same directory:
      *
      * ```bash
-     * $ tree example/
-     * example/
+     * $ tree .
+     * .
      * ├── mew
      * └── mewtwo -> ./mew
      * ```
@@ -1390,7 +1395,7 @@ declare module 'fs' {
          * Use `fs.rm(path, { recursive: true, force: true })` instead.
          *
          * If `true`, perform a recursive directory removal. In
-         * recursive mode soperations are retried on failure.
+         * recursive mode, operations are retried on failure.
          * @default false
          */
         recursive?: boolean | undefined;
@@ -1996,8 +2001,8 @@ declare module 'fs' {
     export function open(path: PathLike, flags: OpenMode | undefined, mode: Mode | undefined | null, callback: (err: NodeJS.ErrnoException | null, fd: number) => void): void;
     /**
      * Asynchronous open(2) - open and possibly create a file. If the file is created, its mode will be `0o666`.
-     * @param [flags='r'] See `support of file system `flags``.
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
+     * @param [flags='r'] See `support of file system `flags``.
      */
     export function open(path: PathLike, flags: OpenMode | undefined, callback: (err: NodeJS.ErrnoException | null, fd: number) => void): void;
     /**
@@ -2005,6 +2010,7 @@ declare module 'fs' {
      * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
      */
     export function open(path: PathLike, callback: (err: NodeJS.ErrnoException | null, fd: number) => void): void;
+
     export namespace open {
         /**
          * Asynchronous open(2) - open and possibly create a file.
@@ -2093,8 +2099,7 @@ declare module 'fs' {
      */
     export function fsyncSync(fd: number): void;
     /**
-     * Write `buffer` to the file specified by `fd`. If `buffer` is a normal object, it
-     * must have an own `toString` function property.
+     * Write `buffer` to the file specified by `fd`.
      *
      * `offset` determines the part of the buffer to be written, and `length` is
      * an integer specifying the number of bytes to write.
@@ -2217,8 +2222,6 @@ declare module 'fs' {
         }>;
     }
     /**
-     * If `buffer` is a plain object, it must have an own (not inherited) `toString`function property.
-     *
      * For detailed information, see the documentation of the asynchronous version of
      * this API: {@link write}.
      * @since v0.1.21
@@ -2234,6 +2237,23 @@ declare module 'fs' {
      */
     export function writeSync(fd: number, string: string, position?: number | null, encoding?: BufferEncoding | null): number;
     export type ReadPosition = number | bigint;
+    export interface ReadSyncOptions {
+        /**
+         * @default 0
+         */
+        offset?: number | undefined;
+        /**
+         * @default `length of buffer`
+         */
+        length?: number | undefined;
+        /**
+         * @default null
+         */
+        position?: ReadPosition | null | undefined;
+    }
+    export interface ReadAsyncOptions<TBuffer extends NodeJS.ArrayBufferView> extends ReadSyncOptions {
+        buffer?: TBuffer;
+    }
     /**
      * Read data from the file specified by `fd`.
      *
@@ -2259,6 +2279,21 @@ declare module 'fs' {
         position: ReadPosition | null,
         callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void
     ): void;
+    /**
+     * Similar to the above `fs.read` function, this version takes an optional `options` object.
+     * If not otherwise specified in an `options` object,
+     * `buffer` defaults to `Buffer.alloc(16384)`,
+     * `offset` defaults to `0`,
+     * `length` defaults to `buffer.byteLength`, `- offset` as of Node 17.6.0
+     * `position` defaults to `null`
+     * @since v12.17.0, 13.11.0
+     */
+    export function read<TBuffer extends NodeJS.ArrayBufferView>(
+        fd: number,
+        options: ReadAsyncOptions<TBuffer>,
+        callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void
+    ): void;
+    export function read(fd: number, callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: NodeJS.ArrayBufferView) => void): void;
     export namespace read {
         /**
          * @param fd A file descriptor.
@@ -2277,20 +2312,17 @@ declare module 'fs' {
             bytesRead: number;
             buffer: TBuffer;
         }>;
-    }
-    export interface ReadSyncOptions {
-        /**
-         * @default 0
-         */
-        offset?: number | undefined;
-        /**
-         * @default `length of buffer`
-         */
-        length?: number | undefined;
-        /**
-         * @default null
-         */
-        position?: ReadPosition | null | undefined;
+        function __promisify__<TBuffer extends NodeJS.ArrayBufferView>(
+            fd: number,
+            options: ReadAsyncOptions<TBuffer>
+        ): Promise<{
+            bytesRead: number;
+            buffer: TBuffer;
+        }>;
+        function __promisify__(fd: number): Promise<{
+            bytesRead: number;
+            buffer: NodeJS.ArrayBufferView;
+        }>;
     }
     /**
      * Returns the number of `bytesRead`.
@@ -2555,8 +2587,6 @@ declare module 'fs' {
      *
      * The `mode` option only affects the newly created file. See {@link open} for more details.
      *
-     * If `data` is a plain object, it must have an own (not inherited) `toString`function property.
-     *
      * ```js
      * import { writeFile } from 'fs';
      * import { Buffer } from 'buffer';
@@ -2633,8 +2663,6 @@ declare module 'fs' {
     /**
      * Returns `undefined`.
      *
-     * If `data` is a plain object, it must have an own (not inherited) `toString`function property.
-     *
      * The `mode` option only affects the newly created file. See {@link open} for more details.
      *
      * For detailed information, see the documentation of the asynchronous version of
@@ -2818,6 +2846,52 @@ declare module 'fs' {
         persistent?: boolean | undefined;
         interval?: number | undefined;
     }
+    /**
+     * Watch for changes on `filename`. The callback `listener` will be called each
+     * time the file is accessed.
+     *
+     * The `options` argument may be omitted. If provided, it should be an object. The`options` object may contain a boolean named `persistent` that indicates
+     * whether the process should continue to run as long as files are being watched.
+     * The `options` object may specify an `interval` property indicating how often the
+     * target should be polled in milliseconds.
+     *
+     * The `listener` gets two arguments the current stat object and the previous
+     * stat object:
+     *
+     * ```js
+     * import { watchFile } from 'fs';
+     *
+     * watchFile('message.text', (curr, prev) => {
+     *   console.log(`the current mtime is: ${curr.mtime}`);
+     *   console.log(`the previous mtime was: ${prev.mtime}`);
+     * });
+     * ```
+     *
+     * These stat objects are instances of `fs.Stat`. If the `bigint` option is `true`,
+     * the numeric values in these objects are specified as `BigInt`s.
+     *
+     * To be notified when the file was modified, not just accessed, it is necessary
+     * to compare `curr.mtimeMs` and `prev.mtimeMs`.
+     *
+     * When an `fs.watchFile` operation results in an `ENOENT` error, it
+     * will invoke the listener once, with all the fields zeroed (or, for dates, the
+     * Unix Epoch). If the file is created later on, the listener will be called
+     * again, with the latest stat objects. This is a change in functionality since
+     * v0.10.
+     *
+     * Using {@link watch} is more efficient than `fs.watchFile` and`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and`fs.unwatchFile` when possible.
+     *
+     * When a file being watched by `fs.watchFile()` disappears and reappears,
+     * then the contents of `previous` in the second callback event (the file's
+     * reappearance) will be the same as the contents of `previous` in the first
+     * callback event (its disappearance).
+     *
+     * This happens when:
+     *
+     * * the file is deleted, followed by a restore
+     * * the file is renamed and then renamed a second time back to its original name
+     * @since v0.1.31
+     */
     export function watchFile(
         filename: PathLike,
         options:
@@ -3186,9 +3260,9 @@ declare module 'fs' {
     /**
      * Tests a user's permissions for the file or directory specified by `path`.
      * The `mode` argument is an optional integer that specifies the accessibility
-     * checks to be performed. Check `File access constants` for possible values
-     * of `mode`. It is possible to create a mask consisting of the bitwise OR of
-     * two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`).
+     * checks to be performed. `mode` should be either the value `fs.constants.F_OK`or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`,`fs.constants.W_OK`, and `fs.constants.X_OK`
+     * (e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for
+     * possible values of `mode`.
      *
      * The final argument, `callback`, is a callback function that is invoked with
      * a possible error argument. If any of the accessibility checks fail, the error
@@ -3214,14 +3288,9 @@ declare module 'fs' {
      *   console.log(`${file} ${err ? 'is not writable' : 'is writable'}`);
      * });
      *
-     * // Check if the file exists in the current directory, and if it is writable.
-     * access(file, constants.F_OK | constants.W_OK, (err) => {
-     *   if (err) {
-     *     console.error(
-     *       `${file} ${err.code === 'ENOENT' ? 'does not exist' : 'is read-only'}`);
-     *   } else {
-     *     console.log(`${file} exists, and it is writable`);
-     *   }
+     * // Check if the file is readable and writable.
+     * access(file, constants.R_OK | constants.W_OK, (err) => {
+     *   console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`);
      * });
      * ```
      *
@@ -3365,10 +3434,9 @@ declare module 'fs' {
     /**
      * Synchronously tests a user's permissions for the file or directory specified
      * by `path`. The `mode` argument is an optional integer that specifies the
-     * accessibility checks to be performed. Check `File access constants` for
-     * possible values of `mode`. It is possible to create a mask consisting of
-     * the bitwise OR of two or more values
-     * (e.g. `fs.constants.W_OK | fs.constants.R_OK`).
+     * accessibility checks to be performed. `mode` should be either the value`fs.constants.F_OK` or a mask consisting of the bitwise OR of any of`fs.constants.R_OK`, `fs.constants.W_OK`, and
+     * `fs.constants.X_OK` (e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for
+     * possible values of `mode`.
      *
      * If any of the accessibility checks fail, an `Error` will be thrown. Otherwise,
      * the method will return `undefined`.
@@ -3471,9 +3539,9 @@ declare module 'fs' {
     /**
      * `options` may also include a `start` option to allow writing data at some
      * position past the beginning of the file, allowed values are in the
-     * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than replacing
-     * it may require the `flags` option to be set to `r+` rather than the default `w`.
-     * The `encoding` can be any one of those accepted by `Buffer`.
+     * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than
+     * replacing it may require the `flags` option to be set to `r+` rather than the
+     * default `w`. The `encoding` can be any one of those accepted by `Buffer`.
      *
      * If `autoClose` is set to true (default behavior) on `'error'` or `'finish'`the file descriptor will be closed automatically. If `autoClose` is false,
      * then the file descriptor won't be closed, even if there's an error.
@@ -3723,7 +3791,7 @@ declare module 'fs' {
     export interface StatSyncOptions extends StatOptions {
         throwIfNoEntry?: boolean | undefined;
     }
-    export interface CopyOptions {
+    interface CopyOptionsBase {
         /**
          * Dereference symlinks
          * @default false
@@ -3735,11 +3803,6 @@ declare module 'fs' {
          * @default false
          */
         errorOnExist?: boolean;
-        /**
-         * Function to filter copied files/directories. Return
-         * `true` to copy the item, `false` to ignore it.
-         */
-        filter?(source: string, destination: string): boolean;
         /**
          * Overwrite existing file or directory. _The copy
          * operation will ignore errors if you set this to false and the destination
@@ -3758,6 +3821,25 @@ declare module 'fs' {
          * @default false
          */
         recursive?: boolean;
+        /**
+         * When true, path resolution for symlinks will be skipped
+         * @default false
+         */
+        verbatimSymlinks?: boolean;
+    }
+    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>;
+    }
+    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;
     }
     /**
      * Asynchronously copies the entire directory structure from `src` to `dest`,
@@ -3770,8 +3852,8 @@ declare module 'fs' {
      * @param src source path to copy.
      * @param dest destination path to copy to.
      */
-    export function cp(source: string, destination: string, callback: (err: NodeJS.ErrnoException | null) => void): void;
-    export function cp(source: string, destination: string, opts: CopyOptions, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    export function cp(source: string | URL, destination: string | URL, callback: (err: NodeJS.ErrnoException | null) => void): void;
+    export function cp(source: string | URL, destination: string | URL, opts: CopyOptions, callback: (err: NodeJS.ErrnoException | null) => void): void;
     /**
      * Synchronously copies the entire directory structure from `src` to `dest`,
      * including subdirectories and files.
@@ -3783,7 +3865,7 @@ declare module 'fs' {
      * @param src source path to copy.
      * @param dest destination path to copy to.
      */
-    export function cpSync(source: string, destination: string, opts?: CopyOptions): void;
+    export function cpSync(source: string | URL, destination: string | URL, opts?: CopySyncOptions): void;
 }
 declare module 'node:fs' {
     export * from 'fs';