| /** |
| * The `fs/promises` API provides asynchronous file system methods that return |
| * promises. |
| * |
| * The promise APIs use the underlying Node.js threadpool to perform file |
| * system operations off the event loop thread. These operations are not |
| * synchronized or threadsafe. Care must be taken when performing multiple |
| * concurrent modifications on the same file or data corruption may occur. |
| * @since v10.0.0 |
| */ |
| declare module 'fs/promises' { |
| import { Abortable } from 'node:events'; |
| import { Stream } from 'node:stream'; |
| import { |
| Stats, |
| BigIntStats, |
| StatOptions, |
| WriteVResult, |
| ReadVResult, |
| PathLike, |
| RmDirOptions, |
| RmOptions, |
| MakeDirectoryOptions, |
| Dirent, |
| OpenDirOptions, |
| Dir, |
| ObjectEncodingOptions, |
| BufferEncodingOption, |
| OpenMode, |
| Mode, |
| WatchOptions, |
| WatchEventType, |
| CopyOptions, |
| ReadStream, |
| WriteStream, |
| } from 'node:fs'; |
| interface FileChangeInfo<T extends string | Buffer> { |
| eventType: WatchEventType; |
| filename: T; |
| } |
| interface FlagAndOpenMode { |
| mode?: Mode | undefined; |
| flag?: OpenMode | undefined; |
| } |
| interface FileReadResult<T extends NodeJS.ArrayBufferView> { |
| bytesRead: number; |
| buffer: T; |
| } |
| interface FileReadOptions<T extends NodeJS.ArrayBufferView = Buffer> { |
| /** |
| * @default `Buffer.alloc(0xffff)` |
| */ |
| buffer?: T; |
| /** |
| * @default 0 |
| */ |
| offset?: number | null; |
| /** |
| * @default `buffer.byteLength` |
| */ |
| length?: number | null; |
| position?: number | null; |
| } |
| interface CreateReadStreamOptions { |
| encoding?: BufferEncoding | null | undefined; |
| autoClose?: boolean | undefined; |
| emitClose?: boolean | undefined; |
| start?: number | undefined; |
| end?: number | undefined; |
| highWaterMark?: number | undefined; |
| } |
| interface CreateWriteStreamOptions { |
| encoding?: BufferEncoding | null | undefined; |
| autoClose?: boolean | undefined; |
| emitClose?: boolean | undefined; |
| start?: number | undefined; |
| } |
| // TODO: Add `EventEmitter` close |
| interface FileHandle { |
| /** |
| * The numeric file descriptor managed by the {FileHandle} object. |
| * @since v10.0.0 |
| */ |
| readonly fd: number; |
| /** |
| * Alias of `filehandle.writeFile()`. |
| * |
| * When operating on file handles, the mode cannot be changed from what it was set |
| * to with `fsPromises.open()`. Therefore, this is equivalent to `filehandle.writeFile()`. |
| * @since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| appendFile(data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null): Promise<void>; |
| /** |
| * Changes the ownership of the file. A wrapper for [`chown(2)`](http://man7.org/linux/man-pages/man2/chown.2.html). |
| * @since v10.0.0 |
| * @param uid The file's new owner's user id. |
| * @param gid The file's new group's group id. |
| * @return Fulfills with `undefined` upon success. |
| */ |
| chown(uid: number, gid: number): Promise<void>; |
| /** |
| * Modifies the permissions on the file. See [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html). |
| * @since v10.0.0 |
| * @param mode the file mode bit mask. |
| * @return Fulfills with `undefined` upon success. |
| */ |
| 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. |
| * |
| * `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 |
| * start counting at 0, 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. If `start` is |
| * omitted or `undefined`, `filehandle.createReadStream()` reads sequentially from |
| * the current file position. The `encoding` can be any one of those accepted by `Buffer`. |
| * |
| * If the `FileHandle` points to a character device that only supports blocking |
| * reads (such as keyboard or sound card), read operations do not finish until data |
| * is available. This can prevent the process from exiting and the stream from |
| * closing naturally. |
| * |
| * By default, the stream will emit a `'close'` event after it has been |
| * destroyed. Set the `emitClose` option to `false` to change this behavior. |
| * |
| * ```js |
| * import { open } from 'fs/promises'; |
| * |
| * const fd = await open('/dev/input/event0'); |
| * // Create a stream from some character device. |
| * const stream = fd.createReadStream(); |
| * setTimeout(() => { |
| * stream.close(); // This may not close the stream. |
| * // Artificially marking end-of-stream, as if the underlying resource had |
| * // indicated end-of-file by itself, allows the stream to close. |
| * // This does not cancel pending read operations, and if there is such an |
| * // operation, the process may still not be able to exit successfully |
| * // until it finishes. |
| * stream.push(null); |
| * stream.read(0); |
| * }, 100); |
| * ``` |
| * |
| * If `autoClose` is false, then the file descriptor won't be closed, even if |
| * there's an error. It is the application's responsibility to close it and make |
| * sure there's no file descriptor leak. If `autoClose` is set to true (default |
| * behavior), on `'error'` or `'end'` the file descriptor will be closed |
| * automatically. |
| * |
| * An example to read the last 10 bytes of a file which is 100 bytes long: |
| * |
| * ```js |
| * import { open } from 'fs/promises'; |
| * |
| * const fd = await open('sample.txt'); |
| * fd.createReadStream({ start: 90, end: 99 }); |
| * ``` |
| * @since v16.11.0 |
| */ |
| createReadStream(options?: CreateReadStreamOptions): ReadStream; |
| /** |
| * `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` `open` option to be set to `r+` rather than the |
| * default `r`. 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. |
| * It is the application's responsibility to close it and make sure there's no |
| * file descriptor leak. |
| * |
| * By default, the stream will emit a `'close'` event after it has been |
| * destroyed. Set the `emitClose` option to `false` to change this behavior. |
| * @since v16.11.0 |
| */ |
| createWriteStream(options?: CreateWriteStreamOptions): WriteStream; |
| /** |
| * Forces all currently queued I/O operations associated with the file to the |
| * operating system's synchronized I/O completion state. Refer to the POSIX [`fdatasync(2)`](http://man7.org/linux/man-pages/man2/fdatasync.2.html) documentation for details. |
| * |
| * Unlike `filehandle.sync` this method does not flush modified metadata. |
| * @since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| datasync(): Promise<void>; |
| /** |
| * Request that all data for the open file descriptor is flushed to the storage |
| * 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. |
| */ |
| sync(): Promise<void>; |
| /** |
| * Reads data from the file and stores that in the given buffer. |
| * |
| * If the file is not modified concurrently, the end-of-file is reached when the |
| * number of bytes read is zero. |
| * @since v10.0.0 |
| * @param buffer A buffer that will be filled with the file data read. |
| * @param offset The location in the buffer at which to start filling. |
| * @param length The number of bytes to read. |
| * @param position The location where to begin reading data from the file. If `null`, data will be read from the current file position, and the position will be updated. If `position` is an |
| * integer, the current file position will remain unchanged. |
| * @return Fulfills upon success with an object with two properties: |
| */ |
| read<T extends NodeJS.ArrayBufferView>(buffer: T, offset?: number | null, length?: number | null, position?: number | null): Promise<FileReadResult<T>>; |
| read<T extends NodeJS.ArrayBufferView = Buffer>(options?: FileReadOptions<T>): Promise<FileReadResult<T>>; |
| /** |
| * Asynchronously reads the entire contents of a file. |
| * |
| * If `options` is a string, then it specifies the `encoding`. |
| * |
| * The `FileHandle` has to support reading. |
| * |
| * If one or more `filehandle.read()` calls are made on a file handle and then a`filehandle.readFile()` call is made, the data will be read from the current |
| * position till the end of the file. It doesn't always read from the beginning |
| * of the file. |
| * @since v10.0.0 |
| * @return Fulfills upon a successful read with the contents of the file. If no encoding is specified (using `options.encoding`), the data is returned as a {Buffer} object. Otherwise, the |
| * data will be a string. |
| */ |
| readFile( |
| options?: { |
| encoding?: null | undefined; |
| flag?: OpenMode | undefined; |
| } | null |
| ): Promise<Buffer>; |
| /** |
| * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically. |
| * The `FileHandle` must have been opened for reading. |
| * @param options An object that may contain an optional flag. |
| * If a flag is not provided, it defaults to `'r'`. |
| */ |
| readFile( |
| options: |
| | { |
| encoding: BufferEncoding; |
| flag?: OpenMode | undefined; |
| } |
| | BufferEncoding |
| ): Promise<string>; |
| /** |
| * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically. |
| * The `FileHandle` must have been opened for reading. |
| * @param options An object that may contain an optional flag. |
| * If a flag is not provided, it defaults to `'r'`. |
| */ |
| readFile( |
| options?: |
| | (ObjectEncodingOptions & { |
| flag?: OpenMode | undefined; |
| }) |
| | BufferEncoding |
| | null |
| ): Promise<string | Buffer>; |
| /** |
| * @since v10.0.0 |
| * @return Fulfills with an {fs.Stats} for the file. |
| */ |
| stat( |
| opts?: StatOptions & { |
| bigint?: false | undefined; |
| } |
| ): Promise<Stats>; |
| stat( |
| opts: StatOptions & { |
| bigint: true; |
| } |
| ): Promise<BigIntStats>; |
| stat(opts?: StatOptions): Promise<Stats | BigIntStats>; |
| /** |
| * Truncates the file. |
| * |
| * If the file was larger than `len` bytes, only the first `len` bytes will be |
| * retained in the file. |
| * |
| * The following example retains only the first four bytes of the file: |
| * |
| * ```js |
| * import { open } from 'fs/promises'; |
| * |
| * let filehandle = null; |
| * try { |
| * filehandle = await open('temp.txt', 'r+'); |
| * await filehandle.truncate(4); |
| * } finally { |
| * await filehandle?.close(); |
| * } |
| * ``` |
| * |
| * If the file previously was shorter than `len` bytes, it is extended, and the |
| * extended part is filled with null bytes (`'\0'`): |
| * |
| * If `len` is negative then `0` will be used. |
| * @since v10.0.0 |
| * @param [len=0] |
| * @return Fulfills with `undefined` upon success. |
| */ |
| truncate(len?: number): Promise<void>; |
| /** |
| * Change the file system timestamps of the object referenced by the `FileHandle` then resolves the promise with no arguments upon success. |
| * @since v10.0.0 |
| */ |
| utimes(atime: string | number | Date, mtime: string | number | Date): 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 |
| * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object, or an |
| * object with an own `toString` function |
| * property. The promise is resolved with no arguments upon success. |
| * |
| * If `options` is a string, then it specifies the `encoding`. |
| * |
| * The `FileHandle` has to support writing. |
| * |
| * It is unsafe to use `filehandle.writeFile()` multiple times on the same file |
| * without waiting for the promise to be resolved (or rejected). |
| * |
| * If one or more `filehandle.write()` calls are made on a file handle and then a`filehandle.writeFile()` call is made, the data will be written from the |
| * current position till the end of the file. It doesn't always write from the |
| * beginning of the file. |
| * @since v10.0.0 |
| */ |
| writeFile(data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode & Abortable) | BufferEncoding | null): Promise<void>; |
| /** |
| * Write `buffer` to the file. |
| * |
| * If `buffer` is a plain object, it must have an own (not inherited) `toString`function property. |
| * |
| * The promise is resolved with an object containing two properties: |
| * |
| * It is unsafe to use `filehandle.write()` multiple times on the same file |
| * without waiting for the promise to be resolved (or rejected). For this |
| * scenario, use `fs.createWriteStream()`. |
| * |
| * On Linux, positional writes do not work when the file is opened in append mode. |
| * 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 [length=buffer.byteLength] 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. |
| */ |
| write<TBuffer extends Uint8Array>( |
| buffer: TBuffer, |
| offset?: number | null, |
| length?: number | null, |
| position?: number | null |
| ): Promise<{ |
| bytesWritten: number; |
| buffer: TBuffer; |
| }>; |
| write( |
| data: string, |
| position?: number | null, |
| encoding?: BufferEncoding | null |
| ): Promise<{ |
| bytesWritten: number; |
| buffer: string; |
| }>; |
| /** |
| * Write an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s to the file. |
| * |
| * The promise is resolved with an object containing a two properties: |
| * |
| * It is unsafe to call `writev()` multiple times on the same file without waiting |
| * for the promise to be resolved (or rejected). |
| * |
| * On Linux, positional writes don't work when the file is opened in append mode. |
| * 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 |
| * 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. |
| * @return Fulfills upon success an object containing two properties: |
| */ |
| readv(buffers: ReadonlyArray<NodeJS.ArrayBufferView>, position?: number): Promise<ReadVResult>; |
| /** |
| * Closes the file handle after waiting for any pending operation on the handle to |
| * complete. |
| * |
| * ```js |
| * import { open } from 'fs/promises'; |
| * |
| * let filehandle; |
| * try { |
| * filehandle = await open('thefile.txt', 'r'); |
| * } finally { |
| * await filehandle?.close(); |
| * } |
| * ``` |
| * @since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| close(): Promise<void>; |
| } |
| /** |
| * 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`). |
| * |
| * If the accessibility check is successful, the promise is resolved with no |
| * value. If any of the accessibility checks fail, the promise is rejected |
| * with an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object. The following example checks if the file`/etc/passwd` can be read and |
| * written by the current process. |
| * |
| * ```js |
| * import { access } from 'fs/promises'; |
| * import { constants } from 'fs'; |
| * |
| * try { |
| * await access('/etc/passwd', constants.R_OK | constants.W_OK); |
| * console.log('can access'); |
| * } catch { |
| * console.error('cannot access'); |
| * } |
| * ``` |
| * |
| * Using `fsPromises.access()` to check for the accessibility of a file before |
| * calling `fsPromises.open()` is not recommended. Doing so introduces a race |
| * condition, since other processes may change the file's state between the two |
| * calls. Instead, user code should open/read/write the file directly and handle |
| * the error raised if the file is not accessible. |
| * @since v10.0.0 |
| * @param [mode=fs.constants.F_OK] |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function access(path: PathLike, mode?: number): Promise<void>; |
| /** |
| * Asynchronously copies `src` to `dest`. By default, `dest` is overwritten if it |
| * already exists. |
| * |
| * No guarantees are made about the atomicity of the copy operation. If an |
| * error occurs after the destination file has been opened for writing, an attempt |
| * will be made to remove the destination. |
| * |
| * ```js |
| * import { constants } from 'fs'; |
| * import { copyFile } from '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'); |
| * } |
| * |
| * // By using COPYFILE_EXCL, the operation will fail if destination.txt exists. |
| * try { |
| * 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'); |
| * } |
| * ``` |
| * @since v10.0.0 |
| * @param src source filename to copy |
| * @param dest destination filename of the copy operation |
| * @param [mode=0] Optional modifiers that specify the behavior of the copy operation. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. |
| * `fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`) |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function copyFile(src: PathLike, dest: PathLike, mode?: number): Promise<void>; |
| /** |
| * Opens a `FileHandle`. |
| * |
| * Refer to the POSIX [`open(2)`](http://man7.org/linux/man-pages/man2/open.2.html) documentation for more detail. |
| * |
| * Some characters (`< > : " / \ | ? *`) are reserved under Windows as documented |
| * by [Naming Files, Paths, and Namespaces](https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file). Under NTFS, if the filename contains |
| * a colon, Node.js will open a file system stream, as described by [this MSDN page](https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams). |
| * @since v10.0.0 |
| * @param [flags='r'] See `support of file system `flags``. |
| * @param [mode=0o666] Sets the file mode (permission and sticky bits) if the file is created. |
| * @return Fulfills with a {FileHandle} object. |
| */ |
| function open(path: PathLike, flags: string | number, mode?: Mode): Promise<FileHandle>; |
| /** |
| * Renames `oldPath` to `newPath`. |
| * @since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function rename(oldPath: PathLike, newPath: PathLike): Promise<void>; |
| /** |
| * Truncates (shortens or extends the length) of the content at `path` to `len`bytes. |
| * @since v10.0.0 |
| * @param [len=0] |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function truncate(path: PathLike, len?: number): Promise<void>; |
| /** |
| * Removes the directory identified by `path`. |
| * |
| * Using `fsPromises.rmdir()` on a file (not a directory) results in the |
| * promise being rejected with an `ENOENT` error on Windows and an `ENOTDIR`error on POSIX. |
| * |
| * To get a behavior similar to the `rm -rf` Unix command, use `fsPromises.rm()` with options `{ recursive: true, force: true }`. |
| * @since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function rmdir(path: PathLike, options?: RmDirOptions): Promise<void>; |
| /** |
| * Removes files and directories (modeled on the standard POSIX `rm` utility). |
| * @since v14.14.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function rm(path: PathLike, options?: RmOptions): Promise<void>; |
| /** |
| * Asynchronously creates a directory. |
| * |
| * The optional `options` argument can be an integer specifying `mode` (permission |
| * 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. |
| * @since v10.0.0 |
| * @return Upon success, fulfills with `undefined` if `recursive` is `false`, or the first directory path created if `recursive` is `true`. |
| */ |
| function mkdir( |
| path: PathLike, |
| options: MakeDirectoryOptions & { |
| recursive: true; |
| } |
| ): Promise<string | undefined>; |
| /** |
| * Asynchronous mkdir(2) - create a directory. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders |
| * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`. |
| */ |
| function mkdir( |
| path: PathLike, |
| options?: |
| | Mode |
| | (MakeDirectoryOptions & { |
| recursive?: false | undefined; |
| }) |
| | null |
| ): Promise<void>; |
| /** |
| * Asynchronous mkdir(2) - create a directory. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders |
| * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`. |
| */ |
| function mkdir(path: PathLike, options?: Mode | MakeDirectoryOptions | null): Promise<string | undefined>; |
| /** |
| * Reads the contents of a directory. |
| * |
| * The optional `options` argument can be a string specifying an encoding, or an |
| * object with an `encoding` property specifying the character encoding to use for |
| * the filenames. If the `encoding` is set to `'buffer'`, the filenames returned |
| * will be passed as `Buffer` objects. |
| * |
| * If `options.withFileTypes` is set to `true`, the resolved array will contain `fs.Dirent` objects. |
| * |
| * ```js |
| * import { readdir } from 'fs/promises'; |
| * |
| * try { |
| * const files = await readdir(path); |
| * for (const file of files) |
| * console.log(file); |
| * } catch (err) { |
| * console.error(err); |
| * } |
| * ``` |
| * @since v10.0.0 |
| * @return Fulfills with an array of the names of the files in the directory excluding `'.'` and `'..'`. |
| */ |
| function readdir( |
| path: PathLike, |
| options?: |
| | (ObjectEncodingOptions & { |
| withFileTypes?: false | undefined; |
| }) |
| | BufferEncoding |
| | null |
| ): Promise<string[]>; |
| /** |
| * Asynchronous readdir(3) - read a directory. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. |
| */ |
| function readdir( |
| path: PathLike, |
| options: |
| | { |
| encoding: 'buffer'; |
| withFileTypes?: false | undefined; |
| } |
| | 'buffer' |
| ): Promise<Buffer[]>; |
| /** |
| * Asynchronous readdir(3) - read a directory. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. |
| */ |
| function readdir( |
| path: PathLike, |
| options?: |
| | (ObjectEncodingOptions & { |
| withFileTypes?: false | undefined; |
| }) |
| | BufferEncoding |
| | null |
| ): Promise<string[] | Buffer[]>; |
| /** |
| * Asynchronous readdir(3) - read a directory. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * @param options If called with `withFileTypes: true` the result data will be an array of Dirent. |
| */ |
| function readdir( |
| path: PathLike, |
| options: ObjectEncodingOptions & { |
| withFileTypes: true; |
| } |
| ): Promise<Dirent[]>; |
| /** |
| * Reads the contents of the symbolic link referred to by `path`. See the POSIX [`readlink(2)`](http://man7.org/linux/man-pages/man2/readlink.2.html) documentation for more detail. The promise is |
| * resolved with the`linkString` upon success. |
| * |
| * The optional `options` argument can be a string specifying an encoding, or an |
| * object with an `encoding` property specifying the character encoding to use for |
| * the link path returned. If the `encoding` is set to `'buffer'`, the link path |
| * returned will be passed as a `Buffer` object. |
| * @since v10.0.0 |
| * @return Fulfills with the `linkString` upon success. |
| */ |
| function readlink(path: PathLike, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string>; |
| /** |
| * Asynchronous readlink(2) - read value of a symbolic link. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. |
| */ |
| function readlink(path: PathLike, options: BufferEncodingOption): Promise<Buffer>; |
| /** |
| * Asynchronous readlink(2) - read value of a symbolic link. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. |
| */ |
| function readlink(path: PathLike, options?: ObjectEncodingOptions | string | null): Promise<string | Buffer>; |
| /** |
| * 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 |
| * automatically be normalized to absolute path. |
| * @since v10.0.0 |
| * @param [type='file'] |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function symlink(target: PathLike, path: PathLike, type?: string | null): Promise<void>; |
| /** |
| * Equivalent to `fsPromises.stat()` unless `path` refers to a symbolic link, |
| * in which case the link itself is stat-ed, not the file that it refers to. |
| * Refer to the POSIX [`lstat(2)`](http://man7.org/linux/man-pages/man2/lstat.2.html) document for more detail. |
| * @since v10.0.0 |
| * @return Fulfills with the {fs.Stats} object for the given symbolic link `path`. |
| */ |
| function lstat( |
| path: PathLike, |
| opts?: StatOptions & { |
| bigint?: false | undefined; |
| } |
| ): Promise<Stats>; |
| function lstat( |
| path: PathLike, |
| opts: StatOptions & { |
| bigint: true; |
| } |
| ): Promise<BigIntStats>; |
| function lstat(path: PathLike, opts?: StatOptions): Promise<Stats | BigIntStats>; |
| /** |
| * @since v10.0.0 |
| * @return Fulfills with the {fs.Stats} object for the given `path`. |
| */ |
| function stat( |
| path: PathLike, |
| opts?: StatOptions & { |
| bigint?: false | undefined; |
| } |
| ): Promise<Stats>; |
| function stat( |
| path: PathLike, |
| opts: StatOptions & { |
| bigint: true; |
| } |
| ): Promise<BigIntStats>; |
| function stat(path: PathLike, opts?: StatOptions): Promise<Stats | BigIntStats>; |
| /** |
| * 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 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function link(existingPath: PathLike, newPath: PathLike): Promise<void>; |
| /** |
| * If `path` refers to a symbolic link, then the link is removed without affecting |
| * the file or directory to which that link refers. If the `path` refers to a file |
| * path that is not a symbolic link, the file is deleted. See the POSIX [`unlink(2)`](http://man7.org/linux/man-pages/man2/unlink.2.html) documentation for more detail. |
| * @since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function unlink(path: PathLike): Promise<void>; |
| /** |
| * Changes the permissions of a file. |
| * @since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function chmod(path: PathLike, mode: Mode): Promise<void>; |
| /** |
| * Changes the permissions on a symbolic link. |
| * |
| * This method is only implemented on macOS. |
| * @deprecated Since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function lchmod(path: PathLike, mode: Mode): Promise<void>; |
| /** |
| * Changes the ownership on a symbolic link. |
| * @since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function lchown(path: PathLike, uid: number, gid: number): Promise<void>; |
| /** |
| * Changes the access and modification times of a file in the same way as `fsPromises.utimes()`, with the difference that if the path refers to a |
| * symbolic link, then the link is not dereferenced: instead, the timestamps of |
| * the symbolic link itself are changed. |
| * @since v14.5.0, v12.19.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function lutimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date): Promise<void>; |
| /** |
| * Changes the ownership of a file. |
| * @since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function chown(path: PathLike, uid: number, gid: number): Promise<void>; |
| /** |
| * Change the file system timestamps of the object referenced by `path`. |
| * |
| * The `atime` and `mtime` arguments follow these rules: |
| * |
| * * 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. |
| * @since v10.0.0 |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function utimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date): Promise<void>; |
| /** |
| * Determines the actual location of `path` using the same semantics as the`fs.realpath.native()` function. |
| * |
| * Only paths that can be converted to UTF8 strings are supported. |
| * |
| * The optional `options` argument can be a string specifying an encoding, or an |
| * object with an `encoding` property specifying the character encoding to use for |
| * the path. If the `encoding` is set to `'buffer'`, the path returned will be |
| * passed as a `Buffer` object. |
| * |
| * On Linux, when Node.js is linked against musl libc, the procfs file system must |
| * be mounted on `/proc` in order for this function to work. Glibc does not have |
| * this restriction. |
| * @since v10.0.0 |
| * @return Fulfills with the resolved path upon success. |
| */ |
| function realpath(path: PathLike, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string>; |
| /** |
| * Asynchronous realpath(3) - return the canonicalized absolute pathname. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. |
| */ |
| function realpath(path: PathLike, options: BufferEncodingOption): Promise<Buffer>; |
| /** |
| * Asynchronous realpath(3) - return the canonicalized absolute pathname. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. |
| */ |
| function realpath(path: PathLike, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string | Buffer>; |
| /** |
| * Creates a unique temporary directory. A unique directory name is generated by |
| * appending six random characters to the end of the provided `prefix`. Due to |
| * platform inconsistencies, avoid trailing `X` characters in `prefix`. Some |
| * platforms, notably the BSDs, can return more than six random characters, and |
| * replace trailing `X` characters in `prefix` with random characters. |
| * |
| * The optional `options` argument can be a string specifying an encoding, or an |
| * object with an `encoding` property specifying the character encoding to use. |
| * |
| * ```js |
| * import { mkdtemp } from 'fs/promises'; |
| * |
| * try { |
| * await mkdtemp(path.join(os.tmpdir(), 'foo-')); |
| * } catch (err) { |
| * console.error(err); |
| * } |
| * ``` |
| * |
| * 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`). |
| * @since v10.0.0 |
| * @return Fulfills with a string containing the filesystem path of the newly created temporary directory. |
| */ |
| function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string>; |
| /** |
| * Asynchronously creates a unique temporary directory. |
| * Generates six random characters to be appended behind a required `prefix` to create a unique temporary directory. |
| * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. |
| */ |
| function mkdtemp(prefix: string, options: BufferEncodingOption): Promise<Buffer>; |
| /** |
| * Asynchronously creates a unique temporary directory. |
| * Generates six random characters to be appended behind a required `prefix` to create a unique temporary directory. |
| * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. |
| */ |
| 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`, or, an object with an own (not inherited)`toString` function property. |
| * |
| * The `encoding` option is ignored if `data` is a buffer. |
| * |
| * If `options` is a string, then it specifies the encoding. |
| * |
| * The `mode` option only affects the newly created file. See `fs.open()` for more details. |
| * |
| * Any specified `FileHandle` has to support writing. |
| * |
| * It is unsafe to use `fsPromises.writeFile()` multiple times on the same file |
| * without waiting for the promise to be settled. |
| * |
| * Similarly to `fsPromises.readFile` \- `fsPromises.writeFile` is a convenience |
| * method that performs multiple `write` calls internally to write the buffer |
| * passed to it. For performance sensitive code consider using `fs.createWriteStream()`. |
| * |
| * It is possible to use an `AbortSignal` to cancel an `fsPromises.writeFile()`. |
| * Cancelation is "best effort", and some amount of data is likely still |
| * to be written. |
| * |
| * ```js |
| * import { writeFile } from 'fs/promises'; |
| * import { Buffer } from 'buffer'; |
| * |
| * try { |
| * const controller = new AbortController(); |
| * const { signal } = controller; |
| * const data = new Uint8Array(Buffer.from('Hello Node.js')); |
| * const promise = writeFile('message.txt', data, { signal }); |
| * |
| * // Abort the request before the promise settles. |
| * controller.abort(); |
| * |
| * await promise; |
| * } catch (err) { |
| * // When a request is aborted - err is an AbortError |
| * console.error(err); |
| * } |
| * ``` |
| * |
| * Aborting an ongoing request does not abort individual operating |
| * system requests but rather the internal buffering `fs.writeFile` performs. |
| * @since v10.0.0 |
| * @param file filename or `FileHandle` |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function writeFile( |
| file: PathLike | FileHandle, |
| data: string | NodeJS.ArrayBufferView | Iterable<string | NodeJS.ArrayBufferView> | AsyncIterable<string | NodeJS.ArrayBufferView> | Stream, |
| options?: |
| | (ObjectEncodingOptions & { |
| mode?: Mode | undefined; |
| flag?: OpenMode | undefined; |
| } & Abortable) |
| | BufferEncoding |
| | null |
| ): Promise<void>; |
| /** |
| * Asynchronously append data to a file, creating the file if it does not yet |
| * exist. `data` can be a string or a `Buffer`. |
| * |
| * If `options` is a string, then it specifies the `encoding`. |
| * |
| * The `mode` option only affects the newly created file. See `fs.open()` for more details. |
| * |
| * The `path` may be specified as a `FileHandle` that has been opened |
| * for appending (using `fsPromises.open()`). |
| * @since v10.0.0 |
| * @param path filename or {FileHandle} |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function appendFile(path: PathLike | FileHandle, data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null): Promise<void>; |
| /** |
| * Asynchronously reads the entire contents of a file. |
| * |
| * If no encoding is specified (using `options.encoding`), the data is returned |
| * as a `Buffer` object. Otherwise, the data will be a string. |
| * |
| * If `options` is a string, then it specifies the encoding. |
| * |
| * When the `path` is a directory, the behavior of `fsPromises.readFile()` is |
| * platform-specific. On macOS, Linux, and Windows, the promise will be rejected |
| * with an error. On FreeBSD, a representation of the directory's contents will be |
| * returned. |
| * |
| * 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'; |
| * |
| * try { |
| * const controller = new AbortController(); |
| * const { signal } = controller; |
| * const promise = readFile(fileName, { signal }); |
| * |
| * // Abort the request before the promise settles. |
| * controller.abort(); |
| * |
| * await promise; |
| * } catch (err) { |
| * // When a request is aborted - err is an AbortError |
| * console.error(err); |
| * } |
| * ``` |
| * |
| * Aborting an ongoing request does not abort individual operating |
| * system requests but rather the internal buffering `fs.readFile` performs. |
| * |
| * Any specified `FileHandle` has to support reading. |
| * @since v10.0.0 |
| * @param path filename or `FileHandle` |
| * @return Fulfills with the contents of the file. |
| */ |
| function readFile( |
| path: PathLike | FileHandle, |
| options?: |
| | ({ |
| encoding?: null | undefined; |
| flag?: OpenMode | undefined; |
| } & Abortable) |
| | null |
| ): Promise<Buffer>; |
| /** |
| * Asynchronously reads the entire contents of a file. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * If a `FileHandle` is provided, the underlying file will _not_ be closed automatically. |
| * @param options An object that may contain an optional flag. |
| * If a flag is not provided, it defaults to `'r'`. |
| */ |
| function readFile( |
| path: PathLike | FileHandle, |
| options: |
| | ({ |
| encoding: BufferEncoding; |
| flag?: OpenMode | undefined; |
| } & Abortable) |
| | BufferEncoding |
| ): Promise<string>; |
| /** |
| * Asynchronously reads the entire contents of a file. |
| * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. |
| * If a `FileHandle` is provided, the underlying file will _not_ be closed automatically. |
| * @param options An object that may contain an optional flag. |
| * If a flag is not provided, it defaults to `'r'`. |
| */ |
| function readFile( |
| path: PathLike | FileHandle, |
| options?: |
| | (ObjectEncodingOptions & |
| Abortable & { |
| flag?: OpenMode | undefined; |
| }) |
| | BufferEncoding |
| | null |
| ): Promise<string | Buffer>; |
| /** |
| * Asynchronously open a directory for iterative scanning. See the POSIX [`opendir(3)`](http://man7.org/linux/man-pages/man3/opendir.3.html) documentation for more detail. |
| * |
| * Creates an `fs.Dir`, which contains all further functions for reading from |
| * and cleaning up the directory. |
| * |
| * The `encoding` option sets the encoding for the `path` while opening the |
| * directory and subsequent read operations. |
| * |
| * Example using async iteration: |
| * |
| * ```js |
| * import { opendir } from 'fs/promises'; |
| * |
| * try { |
| * const dir = await opendir('./'); |
| * for await (const dirent of dir) |
| * console.log(dirent.name); |
| * } catch (err) { |
| * console.error(err); |
| * } |
| * ``` |
| * |
| * When using the async iterator, the `fs.Dir` object will be automatically |
| * closed after the iterator exits. |
| * @since v12.12.0 |
| * @return Fulfills with an {fs.Dir}. |
| */ |
| function opendir(path: PathLike, options?: OpenDirOptions): Promise<Dir>; |
| /** |
| * 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 ac = new AbortController(); |
| * const { signal } = ac; |
| * setTimeout(() => ac.abort(), 10000); |
| * |
| * (async () => { |
| * try { |
| * const watcher = watch(__filename, { signal }); |
| * for await (const event of watcher) |
| * console.log(event); |
| * } catch (err) { |
| * if (err.name === 'AbortError') |
| * return; |
| * throw err; |
| * } |
| * })(); |
| * ``` |
| * |
| * On most platforms, `'rename'` is emitted whenever a filename appears or |
| * disappears in the directory. |
| * |
| * All the `caveats` for `fs.watch()` also apply to `fsPromises.watch()`. |
| * @since v15.9.0, v14.18.0 |
| * @return of objects with the properties: |
| */ |
| 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. |
| */ |
| function watch(filename: PathLike, options: WatchOptions | string): AsyncIterable<FileChangeInfo<string>> | AsyncIterable<FileChangeInfo<Buffer>>; |
| /** |
| * Asynchronously copies the entire directory structure from `src` to `dest`, |
| * including subdirectories and files. |
| * |
| * When copying a directory to another directory, globs are not supported and |
| * behavior is similar to `cp dir1/ dir2/`. |
| * @since v16.7.0 |
| * @experimental |
| * @param src source path to copy. |
| * @param dest destination path to copy to. |
| * @return Fulfills with `undefined` upon success. |
| */ |
| function cp(source: string, destination: string, opts?: CopyOptions): Promise<void>; |
| } |
| declare module 'node:fs/promises' { |
| export * from 'fs/promises'; |
| } |