UNPKG

@types/node

Version:
1,274 lines (1,271 loc) 186 kB
/** * The `node:fs` module enables interacting with the file system in a * way modeled on standard POSIX functions. * * To use the promise-based APIs: * * ```js * import * as fs from 'node:fs/promises'; * ``` * * To use the callback and sync APIs: * * ```js * import * as fs from 'node:fs'; * ``` * * 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/v22.x/lib/fs.js) */ declare module "fs" { import * as stream from "node:stream"; import { Abortable, EventEmitter } from "node:events"; import { URL } from "node:url"; import * as promises from "node:fs/promises"; export { promises }; /** * Valid types for path values in "fs". */ export type PathLike = string | Buffer | URL; export type PathOrFileDescriptor = PathLike | number; export type TimeLike = string | number | Date; export type NoParamCallback = (err: NodeJS.ErrnoException | null) => void; export type BufferEncodingOption = | "buffer" | { encoding: "buffer"; }; export interface ObjectEncodingOptions { encoding?: BufferEncoding | null | undefined; } export type EncodingOption = ObjectEncodingOptions | BufferEncoding | undefined | null; export type OpenMode = number | string; export type Mode = number | string; export interface StatsBase<T> { isFile(): boolean; isDirectory(): boolean; isBlockDevice(): boolean; isCharacterDevice(): boolean; isSymbolicLink(): boolean; isFIFO(): boolean; isSocket(): boolean; dev: T; ino: T; mode: T; nlink: T; uid: T; gid: T; rdev: T; size: T; blksize: T; blocks: T; atimeMs: T; mtimeMs: T; ctimeMs: T; birthtimeMs: T; atime: Date; mtime: Date; ctime: Date; birthtime: Date; } export interface Stats extends StatsBase<number> {} /** * A `fs.Stats` object provides information about a file. * * Objects returned from {@link stat}, {@link lstat}, {@link fstat}, and * their synchronous counterparts are of this type. * If `bigint` in the `options` passed to those methods is true, the numeric values * will be `bigint` instead of `number`, and the object will contain additional * nanosecond-precision properties suffixed with `Ns`. `Stat` objects are not to be created directly using the `new` keyword. * * ```console * Stats { * dev: 2114, * ino: 48064969, * mode: 33188, * nlink: 1, * uid: 85, * gid: 100, * rdev: 0, * size: 527, * blksize: 4096, * blocks: 8, * atimeMs: 1318289051000.1, * mtimeMs: 1318289051000.1, * ctimeMs: 1318289051000.1, * birthtimeMs: 1318289051000.1, * atime: Mon, 10 Oct 2011 23:24:11 GMT, * mtime: Mon, 10 Oct 2011 23:24:11 GMT, * ctime: Mon, 10 Oct 2011 23:24:11 GMT, * birthtime: Mon, 10 Oct 2011 23:24:11 GMT } * ``` * * `bigint` version: * * ```console * BigIntStats { * dev: 2114n, * ino: 48064969n, * mode: 33188n, * nlink: 1n, * uid: 85n, * gid: 100n, * rdev: 0n, * size: 527n, * blksize: 4096n, * blocks: 8n, * atimeMs: 1318289051000n, * mtimeMs: 1318289051000n, * ctimeMs: 1318289051000n, * birthtimeMs: 1318289051000n, * atimeNs: 1318289051000000000n, * mtimeNs: 1318289051000000000n, * ctimeNs: 1318289051000000000n, * birthtimeNs: 1318289051000000000n, * atime: Mon, 10 Oct 2011 23:24:11 GMT, * mtime: Mon, 10 Oct 2011 23:24:11 GMT, * ctime: Mon, 10 Oct 2011 23:24:11 GMT, * birthtime: Mon, 10 Oct 2011 23:24:11 GMT } * ``` * @since v0.1.21 */ export class Stats { private constructor(); } export interface StatsFsBase<T> { /** Type of file system. */ type: T; /** Optimal transfer block size. */ bsize: T; /** Total data blocks in file system. */ blocks: T; /** Free blocks in file system. */ bfree: T; /** Available blocks for unprivileged users */ bavail: T; /** Total file nodes in file system. */ files: T; /** Free file nodes in file system. */ ffree: T; } export interface StatsFs extends StatsFsBase<number> {} /** * Provides information about a mounted file system. * * Objects returned from {@link statfs} and its synchronous counterpart are of * this type. If `bigint` in the `options` passed to those methods is `true`, the * numeric values will be `bigint` instead of `number`. * * ```console * StatFs { * type: 1397114950, * bsize: 4096, * blocks: 121938943, * bfree: 61058895, * bavail: 61058895, * files: 999, * ffree: 1000000 * } * ``` * * `bigint` version: * * ```console * StatFs { * type: 1397114950n, * bsize: 4096n, * blocks: 121938943n, * bfree: 61058895n, * bavail: 61058895n, * files: 999n, * ffree: 1000000n * } * ``` * @since v19.6.0, v18.15.0 */ export class StatsFs {} export interface BigIntStatsFs extends StatsFsBase<bigint> {} export interface StatFsOptions { bigint?: boolean | undefined; } /** * A representation of a directory entry, which can be a file or a subdirectory * within the directory, as returned by reading from an `fs.Dir`. The * directory entry is a combination of the file name and file type pairs. * * Additionally, when {@link readdir} or {@link readdirSync} is called with * the `withFileTypes` option set to `true`, the resulting array is filled with `fs.Dirent` objects, rather than strings or `Buffer` s. * @since v10.10.0 */ export class Dirent { /** * Returns `true` if the `fs.Dirent` object describes a regular file. * @since v10.10.0 */ isFile(): boolean; /** * Returns `true` if the `fs.Dirent` object describes a file system * directory. * @since v10.10.0 */ isDirectory(): boolean; /** * Returns `true` if the `fs.Dirent` object describes a block device. * @since v10.10.0 */ isBlockDevice(): boolean; /** * Returns `true` if the `fs.Dirent` object describes a character device. * @since v10.10.0 */ isCharacterDevice(): boolean; /** * Returns `true` if the `fs.Dirent` object describes a symbolic link. * @since v10.10.0 */ isSymbolicLink(): boolean; /** * Returns `true` if the `fs.Dirent` object describes a first-in-first-out * (FIFO) pipe. * @since v10.10.0 */ isFIFO(): boolean; /** * Returns `true` if the `fs.Dirent` object describes a socket. * @since v10.10.0 */ isSocket(): boolean; /** * The file name that this `fs.Dirent` object refers to. The type of this * value is determined by the `options.encoding` passed to {@link readdir} or {@link readdirSync}. * @since v10.10.0 */ name: string; /** * The base path that this `fs.Dirent` object refers to. * @since v20.12.0 */ parentPath: string; /** * Alias for `dirent.parentPath`. * @since v20.1.0 * @deprecated Since v20.12.0 */ path: string; } /** * A class representing a directory stream. * * Created by {@link opendir}, {@link opendirSync}, or `fsPromises.opendir()`. * * ```js * import { opendir } from 'node: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 */ export class Dir implements AsyncIterable<Dirent> { /** * The read-only path of this directory as was provided to {@link opendir},{@link opendirSync}, or `fsPromises.opendir()`. * @since v12.12.0 */ readonly path: string; /** * Asynchronously iterates over the directory via `readdir(3)` until all entries have been read. */ [Symbol.asyncIterator](): NodeJS.AsyncIterator<Dirent>; /** * Asynchronously close the directory's underlying resource handle. * Subsequent reads will result in errors. * * A promise is returned that will be fulfilled after the resource has been * closed. * @since v12.12.0 */ close(): Promise<void>; close(cb: NoParamCallback): void; /** * Synchronously close the directory's underlying resource handle. * Subsequent reads will result in errors. * @since v12.12.0 */ closeSync(): void; /** * Asynchronously read the next directory entry via [`readdir(3)`](http://man7.org/linux/man-pages/man3/readdir.3.html) as an `fs.Dirent`. * * A promise is returned that will be fulfilled with an `fs.Dirent`, or `null` if there are no more directory entries to read. * * Directory entries returned by this function are in no particular order as * provided by the operating system's underlying directory mechanisms. * Entries added or removed while iterating over the directory might not be * included in the iteration results. * @since v12.12.0 * @return containing {fs.Dirent|null} */ read(): Promise<Dirent | null>; read(cb: (err: NodeJS.ErrnoException | null, dirEnt: Dirent | null) => void): void; /** * Synchronously read the next directory entry as an `fs.Dirent`. See the * POSIX [`readdir(3)`](http://man7.org/linux/man-pages/man3/readdir.3.html) documentation for more detail. * * If there are no more directory entries to read, `null` will be returned. * * Directory entries returned by this function are in no particular order as * provided by the operating system's underlying directory mechanisms. * Entries added or removed while iterating over the directory might not be * included in the iteration results. * @since v12.12.0 */ readSync(): Dirent | null; } /** * Class: fs.StatWatcher * @since v14.3.0, v12.20.0 * Extends `EventEmitter` * A successful call to {@link watchFile} method will return a new fs.StatWatcher object. */ 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 */ 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 */ unref(): this; } export interface FSWatcher extends EventEmitter { /** * Stop watching for changes on the given `fs.FSWatcher`. Once stopped, the `fs.FSWatcher` object is no longer usable. * @since v0.5.8 */ close(): void; /** * When called, requests that the Node.js event loop _not_ exit so long as the `fs.FSWatcher` is active. Calling `watcher.ref()` multiple times will have * no effect. * * By default, all `fs.FSWatcher` 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 */ ref(): this; /** * When called, the active `fs.FSWatcher` 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.FSWatcher` object's * callback is invoked. Calling `watcher.unref()` multiple times will have * no effect. * @since v14.3.0, v12.20.0 */ unref(): this; /** * events.EventEmitter * 1. change * 2. close * 3. error */ addListener(event: string, listener: (...args: any[]) => void): this; addListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; addListener(event: "close", listener: () => void): this; addListener(event: "error", listener: (error: Error) => void): this; on(event: string, listener: (...args: any[]) => void): this; on(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; on(event: "close", listener: () => void): this; on(event: "error", listener: (error: Error) => void): this; once(event: string, listener: (...args: any[]) => void): this; once(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; once(event: "close", listener: () => void): this; once(event: "error", listener: (error: Error) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; prependListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; prependListener(event: "close", listener: () => void): this; prependListener(event: "error", listener: (error: Error) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; prependOnceListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; prependOnceListener(event: "close", listener: () => void): this; prependOnceListener(event: "error", listener: (error: Error) => void): this; } /** * Instances of `fs.ReadStream` are created and returned using the {@link createReadStream} function. * @since v0.1.93 */ export class ReadStream extends stream.Readable { close(callback?: (err?: NodeJS.ErrnoException | null) => void): void; /** * The number of bytes that have been read so far. * @since v6.4.0 */ bytesRead: number; /** * The path to the file the stream is reading from as specified in the first * argument to `fs.createReadStream()`. If `path` is passed as a string, then`readStream.path` will be a string. If `path` is passed as a `Buffer`, then`readStream.path` will be a * `Buffer`. If `fd` is specified, then`readStream.path` will be `undefined`. * @since v0.1.93 */ path: string | Buffer; /** * This property is `true` if the underlying file has not been opened yet, * i.e. before the `'ready'` event is emitted. * @since v11.2.0, v10.16.0 */ pending: boolean; /** * events.EventEmitter * 1. open * 2. close * 3. ready */ addListener<K extends keyof ReadStreamEvents>(event: K, listener: ReadStreamEvents[K]): this; on<K extends keyof ReadStreamEvents>(event: K, listener: ReadStreamEvents[K]): this; once<K extends keyof ReadStreamEvents>(event: K, listener: ReadStreamEvents[K]): this; prependListener<K extends keyof ReadStreamEvents>(event: K, listener: ReadStreamEvents[K]): this; prependOnceListener<K extends keyof ReadStreamEvents>(event: K, listener: ReadStreamEvents[K]): this; } /** * The Keys are events of the ReadStream and the values are the functions that are called when the event is emitted. */ type ReadStreamEvents = { close: () => void; data: (chunk: Buffer | string) => void; end: () => void; error: (err: Error) => void; open: (fd: number) => void; pause: () => void; readable: () => void; ready: () => void; resume: () => void; } & CustomEvents; /** * string & {} allows to allow any kind of strings for the event * but still allows to have auto completion for the normal events. */ type CustomEvents = { [Key in string & {} | symbol]: (...args: any[]) => void }; /** * The Keys are events of the WriteStream and the values are the functions that are called when the event is emitted. */ type WriteStreamEvents = { close: () => void; drain: () => void; error: (err: Error) => void; finish: () => void; open: (fd: number) => void; pipe: (src: stream.Readable) => void; ready: () => void; unpipe: (src: stream.Readable) => void; } & CustomEvents; /** * * Extends `stream.Writable` * * Instances of `fs.WriteStream` are created and returned using the {@link createWriteStream} function. * @since v0.1.93 */ export class WriteStream extends stream.Writable { /** * Closes `writeStream`. Optionally accepts a * callback that will be executed once the `writeStream`is closed. * @since v0.9.4 */ close(callback?: (err?: NodeJS.ErrnoException | null) => void): void; /** * The number of bytes written so far. Does not include data that is still queued * for writing. * @since v0.4.7 */ bytesWritten: number; /** * The path to the file the stream is writing to as specified in the first * argument to {@link createWriteStream}. If `path` is passed as a string, then`writeStream.path` will be a string. If `path` is passed as a `Buffer`, then`writeStream.path` will be a * `Buffer`. * @since v0.1.93 */ path: string | Buffer; /** * This property is `true` if the underlying file has not been opened yet, * i.e. before the `'ready'` event is emitted. * @since v11.2.0 */ pending: boolean; /** * events.EventEmitter * 1. open * 2. close * 3. ready */ addListener<K extends keyof WriteStreamEvents>(event: K, listener: WriteStreamEvents[K]): this; on<K extends keyof WriteStreamEvents>(event: K, listener: WriteStreamEvents[K]): this; once<K extends keyof WriteStreamEvents>(event: K, listener: WriteStreamEvents[K]): this; prependListener<K extends keyof WriteStreamEvents>(event: K, listener: WriteStreamEvents[K]): this; prependOnceListener<K extends keyof WriteStreamEvents>(event: K, listener: WriteStreamEvents[K]): this; } /** * Asynchronously rename file at `oldPath` to the pathname provided * as `newPath`. In the case that `newPath` already exists, it will * be overwritten. If there is a directory at `newPath`, an error will * be raised instead. No arguments other than a possible exception are * given to the completion callback. * * See also: [`rename(2)`](http://man7.org/linux/man-pages/man2/rename.2.html). * * ```js * import { rename } from 'node:fs'; * * rename('oldFile.txt', 'newFile.txt', (err) => { * if (err) throw err; * console.log('Rename complete!'); * }); * ``` * @since v0.0.2 */ export function rename(oldPath: PathLike, newPath: PathLike, callback: NoParamCallback): void; export namespace rename { /** * Asynchronous rename(2) - Change the name or location of a file or directory. * @param oldPath A path to a file. If a URL is provided, it must use the `file:` protocol. * URL support is _experimental_. * @param newPath A path to a file. If a URL is provided, it must use the `file:` protocol. * URL support is _experimental_. */ function __promisify__(oldPath: PathLike, newPath: PathLike): Promise<void>; } /** * Renames the file from `oldPath` to `newPath`. Returns `undefined`. * * See the POSIX [`rename(2)`](http://man7.org/linux/man-pages/man2/rename.2.html) documentation for more details. * @since v0.1.21 */ export function renameSync(oldPath: PathLike, newPath: PathLike): void; /** * Truncates the file. No arguments other than a possible exception are * given to the completion callback. A file descriptor can also be passed as the * first argument. In this case, `fs.ftruncate()` is called. * * ```js * import { truncate } from 'node:fs'; * // Assuming that 'path/file.txt' is a regular file. * truncate('path/file.txt', (err) => { * if (err) throw err; * console.log('path/file.txt was truncated'); * }); * ``` * * Passing a file descriptor is deprecated and may result in an error being thrown * in the future. * * See the POSIX [`truncate(2)`](http://man7.org/linux/man-pages/man2/truncate.2.html) documentation for more details. * @since v0.8.6 * @param [len=0] */ export function truncate(path: PathLike, len: number | undefined, callback: NoParamCallback): void; /** * Asynchronous truncate(2) - Truncate a file to a specified length. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ export function truncate(path: PathLike, callback: NoParamCallback): void; export namespace truncate { /** * Asynchronous truncate(2) - Truncate a file to a specified length. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param len If not specified, defaults to `0`. */ function __promisify__(path: PathLike, len?: number): Promise<void>; } /** * Truncates the file. Returns `undefined`. A file descriptor can also be * passed as the first argument. In this case, `fs.ftruncateSync()` is called. * * Passing a file descriptor is deprecated and may result in an error being thrown * in the future. * @since v0.8.6 * @param [len=0] */ export function truncateSync(path: PathLike, len?: number): void; /** * Truncates the file descriptor. No arguments other than a possible exception are * given to the completion callback. * * See the POSIX [`ftruncate(2)`](http://man7.org/linux/man-pages/man2/ftruncate.2.html) documentation for more detail. * * If the file referred to by the file descriptor was larger than `len` bytes, only * the first `len` bytes will be retained in the file. * * For example, the following program retains only the first four bytes of the * file: * * ```js * import { open, close, ftruncate } from 'node:fs'; * * function closeFd(fd) { * close(fd, (err) => { * if (err) throw err; * }); * } * * open('temp.txt', 'r+', (err, fd) => { * if (err) throw err; * * try { * ftruncate(fd, 4, (err) => { * closeFd(fd); * if (err) throw err; * }); * } catch (err) { * closeFd(fd); * if (err) throw err; * } * }); * ``` * * 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 v0.8.6 * @param [len=0] */ export function ftruncate(fd: number, len: number | undefined, callback: NoParamCallback): void; /** * Asynchronous ftruncate(2) - Truncate a file to a specified length. * @param fd A file descriptor. */ export function ftruncate(fd: number, callback: NoParamCallback): void; export namespace ftruncate { /** * Asynchronous ftruncate(2) - Truncate a file to a specified length. * @param fd A file descriptor. * @param len If not specified, defaults to `0`. */ function __promisify__(fd: number, len?: number): Promise<void>; } /** * Truncates the file descriptor. Returns `undefined`. * * For detailed information, see the documentation of the asynchronous version of * this API: {@link ftruncate}. * @since v0.8.6 * @param [len=0] */ export function ftruncateSync(fd: number, len?: number): void; /** * Asynchronously changes owner and group of a file. No arguments other than a * possible exception are given to the completion callback. * * See the POSIX [`chown(2)`](http://man7.org/linux/man-pages/man2/chown.2.html) documentation for more detail. * @since v0.1.97 */ export function chown(path: PathLike, uid: number, gid: number, callback: NoParamCallback): void; export namespace chown { /** * Asynchronous chown(2) - Change ownership of a file. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ function __promisify__(path: PathLike, uid: number, gid: number): Promise<void>; } /** * Synchronously changes owner and group of a file. Returns `undefined`. * This is the synchronous version of {@link chown}. * * See the POSIX [`chown(2)`](http://man7.org/linux/man-pages/man2/chown.2.html) documentation for more detail. * @since v0.1.97 */ export function chownSync(path: PathLike, uid: number, gid: number): void; /** * Sets the owner of the file. No arguments other than a possible exception are * given to the completion callback. * * See the POSIX [`fchown(2)`](http://man7.org/linux/man-pages/man2/fchown.2.html) documentation for more detail. * @since v0.4.7 */ export function fchown(fd: number, uid: number, gid: number, callback: NoParamCallback): void; export namespace fchown { /** * Asynchronous fchown(2) - Change ownership of a file. * @param fd A file descriptor. */ function __promisify__(fd: number, uid: number, gid: number): Promise<void>; } /** * Sets the owner of the file. Returns `undefined`. * * See the POSIX [`fchown(2)`](http://man7.org/linux/man-pages/man2/fchown.2.html) documentation for more detail. * @since v0.4.7 * @param uid The file's new owner's user id. * @param gid The file's new group's group id. */ export function fchownSync(fd: number, uid: number, gid: number): void; /** * Set the owner of the symbolic link. No arguments other than a possible * exception are given to the completion callback. * * See the POSIX [`lchown(2)`](http://man7.org/linux/man-pages/man2/lchown.2.html) documentation for more detail. */ export function lchown(path: PathLike, uid: number, gid: number, callback: NoParamCallback): void; export namespace lchown { /** * Asynchronous lchown(2) - Change ownership of a file. Does not dereference symbolic links. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ function __promisify__(path: PathLike, uid: number, gid: number): Promise<void>; } /** * Set the owner for the path. Returns `undefined`. * * See the POSIX [`lchown(2)`](http://man7.org/linux/man-pages/man2/lchown.2.html) documentation for more details. * @param uid The file's new owner's user id. * @param gid The file's new group's group id. */ export function lchownSync(path: PathLike, uid: number, gid: number): void; /** * Changes the access and modification times of a file in the same way as {@link 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. * * No arguments other than a possible exception are given to the completion * callback. * @since v14.5.0, v12.19.0 */ export function lutimes(path: PathLike, atime: TimeLike, mtime: TimeLike, callback: NoParamCallback): void; export namespace lutimes { /** * 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. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param atime The last access time. If a string is provided, it will be coerced to number. * @param mtime The last modified time. If a string is provided, it will be coerced to number. */ function __promisify__(path: PathLike, atime: TimeLike, mtime: TimeLike): Promise<void>; } /** * Change the file system timestamps of the symbolic link referenced by `path`. * Returns `undefined`, or throws an exception when parameters are incorrect or * the operation fails. This is the synchronous version of {@link lutimes}. * @since v14.5.0, v12.19.0 */ export function lutimesSync(path: PathLike, atime: TimeLike, mtime: TimeLike): void; /** * Asynchronously changes the permissions of a file. No arguments other than a * possible exception are given to the completion callback. * * See the POSIX [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html) documentation for more detail. * * ```js * import { chmod } from 'node:fs'; * * chmod('my_file.txt', 0o775, (err) => { * if (err) throw err; * console.log('The permissions for file "my_file.txt" have been changed!'); * }); * ``` * @since v0.1.30 */ export function chmod(path: PathLike, mode: Mode, callback: NoParamCallback): void; export namespace chmod { /** * Asynchronous chmod(2) - Change permissions of a file. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param mode A file mode. If a string is passed, it is parsed as an octal integer. */ function __promisify__(path: PathLike, mode: Mode): Promise<void>; } /** * For detailed information, see the documentation of the asynchronous version of * this API: {@link chmod}. * * See the POSIX [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html) documentation for more detail. * @since v0.6.7 */ export function chmodSync(path: PathLike, mode: Mode): void; /** * Sets the permissions on the file. No arguments other than a possible exception * are given to the completion callback. * * See the POSIX [`fchmod(2)`](http://man7.org/linux/man-pages/man2/fchmod.2.html) documentation for more detail. * @since v0.4.7 */ export function fchmod(fd: number, mode: Mode, callback: NoParamCallback): void; export namespace fchmod { /** * Asynchronous fchmod(2) - Change permissions of a file. * @param fd A file descriptor. * @param mode A file mode. If a string is passed, it is parsed as an octal integer. */ function __promisify__(fd: number, mode: Mode): Promise<void>; } /** * Sets the permissions on the file. Returns `undefined`. * * See the POSIX [`fchmod(2)`](http://man7.org/linux/man-pages/man2/fchmod.2.html) documentation for more detail. * @since v0.4.7 */ export function fchmodSync(fd: number, mode: Mode): void; /** * Changes the permissions on a symbolic link. No arguments other than a possible * exception are given to the completion callback. * * This method is only implemented on macOS. * * See the POSIX [`lchmod(2)`](https://www.freebsd.org/cgi/man.cgi?query=lchmod&sektion=2) documentation for more detail. * @deprecated Since v0.4.7 */ export function lchmod(path: PathLike, mode: Mode, callback: NoParamCallback): void; /** @deprecated */ export namespace lchmod { /** * Asynchronous lchmod(2) - Change permissions of a file. Does not dereference symbolic links. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param mode A file mode. If a string is passed, it is parsed as an octal integer. */ function __promisify__(path: PathLike, mode: Mode): Promise<void>; } /** * Changes the permissions on a symbolic link. Returns `undefined`. * * This method is only implemented on macOS. * * See the POSIX [`lchmod(2)`](https://www.freebsd.org/cgi/man.cgi?query=lchmod&sektion=2) documentation for more detail. * @deprecated Since v0.4.7 */ export function lchmodSync(path: PathLike, mode: Mode): void; /** * Asynchronous [`stat(2)`](http://man7.org/linux/man-pages/man2/stat.2.html). The callback gets two arguments `(err, stats)` where`stats` is an `fs.Stats` object. * * In case of an error, the `err.code` will be one of `Common System Errors`. * * {@link stat} follows symbolic links. Use {@link lstat} to look at the * links themselves. * * Using `fs.stat()` to check for the existence of a file before calling`fs.open()`, `fs.readFile()`, or `fs.writeFile()` is not recommended. * Instead, user code should open/read/write the file directly and handle the * error raised if the file is not available. * * To check if a file exists without manipulating it afterwards, {@link access} is recommended. * * For example, given the following directory structure: * * ```text * - txtDir * -- file.txt * - app.js * ``` * * The next program will check for the stats of the given paths: * * ```js * import { stat } from 'node:fs'; * * const pathsToCheck = ['./txtDir', './txtDir/file.txt']; * * for (let i = 0; i < pathsToCheck.length; i++) { * stat(pathsToCheck[i], (err, stats) => { * console.log(stats.isDirectory()); * console.log(stats); * }); * } * ``` * * The resulting output will resemble: * * ```console * true * Stats { * dev: 16777220, * mode: 16877, * nlink: 3, * uid: 501, * gid: 20, * rdev: 0, * blksize: 4096, * ino: 14214262, * size: 96, * blocks: 0, * atimeMs: 1561174653071.963, * mtimeMs: 1561174614583.3518, * ctimeMs: 1561174626623.5366, * birthtimeMs: 1561174126937.2893, * atime: 2019-06-22T03:37:33.072Z, * mtime: 2019-06-22T03:36:54.583Z, * ctime: 2019-06-22T03:37:06.624Z, * birthtime: 2019-06-22T03:28:46.937Z * } * false * Stats { * dev: 16777220, * mode: 33188, * nlink: 1, * uid: 501, * gid: 20, * rdev: 0, * blksize: 4096, * ino: 14214074, * size: 8, * blocks: 8, * atimeMs: 1561174616618.8555, * mtimeMs: 1561174614584, * ctimeMs: 1561174614583.8145, * birthtimeMs: 1561174007710.7478, * atime: 2019-06-22T03:36:56.619Z, * mtime: 2019-06-22T03:36:54.584Z, * ctime: 2019-06-22T03:36:54.584Z, * birthtime: 2019-06-22T03:26:47.711Z * } * ``` * @since v0.0.2 */ export function stat(path: PathLike, callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void): void; export function stat( path: PathLike, options: | (StatOptions & { bigint?: false | undefined; }) | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void, ): void; export function stat( path: PathLike, options: StatOptions & { bigint: true; }, callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void, ): void; export function stat( path: PathLike, options: StatOptions | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void, ): void; export namespace stat { /** * Asynchronous stat(2) - Get file status. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ function __promisify__( path: PathLike, options?: StatOptions & { bigint?: false | undefined; }, ): Promise<Stats>; function __promisify__( path: PathLike, options: StatOptions & { bigint: true; }, ): Promise<BigIntStats>; function __promisify__(path: PathLike, options?: StatOptions): Promise<Stats | BigIntStats>; } export interface StatSyncFn extends Function { (path: PathLike, options?: undefined): Stats; ( path: PathLike, options?: StatSyncOptions & { bigint?: false | undefined; throwIfNoEntry: false; }, ): Stats | undefined; ( path: PathLike, options: StatSyncOptions & { bigint: true; throwIfNoEntry: false; }, ): BigIntStats | undefined; ( path: PathLike, options?: StatSyncOptions & { bigint?: false | undefined; }, ): Stats; ( path: PathLike, options: StatSyncOptions & { bigint: true; }, ): BigIntStats; ( path: PathLike, options: StatSyncOptions & { bigint: boolean; throwIfNoEntry?: false | undefined; }, ): Stats | BigIntStats; (path: PathLike, options?: StatSyncOptions): Stats | BigIntStats | undefined; } /** * Synchronous stat(2) - Get file status. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ export const statSync: StatSyncFn; /** * Invokes the callback with 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 fstat(fd: number, callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void): void; export function fstat( fd: number, options: | (StatOptions & { bigint?: false | undefined; }) | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void, ): void; export function fstat( fd: number, options: StatOptions & { bigint: true; }, callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void, ): void; export function fstat( fd: number, options: StatOptions | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void, ): void; export namespace fstat { /** * Asynchronous fstat(2) - Get file status. * @param fd A file descriptor. */ function __promisify__( fd: number, options?: StatOptions & { bigint?: false | undefined; }, ): Promise<Stats>; function __promisify__( fd: number, options: StatOptions & { bigint: true; }, ): Promise<BigIntStats>; function __promisify__(fd: number, options?: StatOptions): Promise<Stats | BigIntStats>; } /** * 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, options?: StatOptions & { bigint?: false | undefined; }, ): Stats; export function fstatSync( fd: number, options: StatOptions & { bigint: true; }, ): 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 * link, then the link itself is stat-ed, not the file that it refers to. * * See the POSIX [`lstat(2)`](http://man7.org/linux/man-pages/man2/lstat.2.html) documentation for more details. * @since v0.1.30 */ export function lstat(path: PathLike, callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void): void; export function lstat( path: PathLike, options: | (StatOptions & { bigint?: false | undefined; }) | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void, ): void; export function lstat( path: PathLike, options: StatOptions & { bigint: true; }, callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void, ): void; export function lstat( path: PathLike, options: StatOptions | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void, ): void; export namespace lstat { /** * Asynchronous lstat(2) - Get file status. Does not dereference symbolic links. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ function __promisify__( path: PathLike, options?: StatOptions & { bigint?: false | undefined; }, ): Promise<Stats>; function __promisify__( path: PathLike, options: StatOptions & { bigint: true; }, ): Promise<BigIntStats>; function __promisify__(path: PathLike, options?: StatOptions): Promise<Stats | BigIntStats>; } /** * Asynchronous [`statfs(2)`](http://man7.org/linux/man-pages/man2/statfs.2.html). Returns information about the mounted file system which * contains `path`. The callback gets two arguments `(err, stats)` where `stats`is an `fs.StatFs` object. * * In case of an error, the `err.code` will be one of `Common System Errors`. * @since v19.6.0, v18.15.0 * @param path A path to an existing file or directory on the file system to be queried. */ export function statfs(path: PathLike, callback: (err: NodeJS.ErrnoException | null, stats: StatsFs) => void): void; export function statfs( path: PathLike, options: | (StatFsOptions & { bigint?: false | undefined; }) | undefined, callback: (err: NodeJS.ErrnoException | null, stats: StatsFs) => void, ): void; export function statfs( path: PathLike, options: StatFsOptions & { bigint: true; }, callback: (err: NodeJS.ErrnoException | null, stats: BigIntStatsFs) => void, ): void; export function statfs( path: PathLike, options: StatFsOptions | undefined, callback: (err: NodeJS.ErrnoException | null, stats: StatsFs | BigIntStatsFs) => void, ): void; export namespace statfs { /** * Asynchronous statfs(2) - Returns information about the mounted file system which contains path. The callback gets two arguments (err, stats) where stats is an <fs.StatFs> object. * @param path A path to an existing file or directory on the file system to be queried. */ function __promisify__( path: PathLike, options?: StatFsOptions & { bigint?: false | undefined; }, ): Promise<StatsFs>; function __promisify__( path: PathLike, options: StatFsOptions & { bigint: true; }, ): Promise<BigIntStatsFs>; function __promisify__(path: PathLike, options?: StatFsOptions): Promise<StatsFs | BigIntStatsFs>; } /** * Synchronous [`statfs(2)`](http://man7.org/linux/man-pages/man2/statfs.2.html). Returns information about the mounted file system which * contains `path`. * * In case of an error, the `err.code` will be one of `Common System Errors`. * @since v19.6.0, v18.15.0 * @param path A path to an existing file or directory on the file system to be queried. */ export function statfsSync( path: PathLike, options?: StatFsOptions & { bigint?: false | undefined; }, ): StatsFs; export function statfsSync( path: PathLike, options: StatFsOptions & { bigint: true; }, ): BigIntStatsFs; export function statfsSync(path: PathLike, options?: StatFsOptions): StatsFs | BigIntStatsFs; /** * Synchronous lstat(2) - Get file status. Does not dereference symbolic links. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ export const lstatSync: StatSyncFn; /** * 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. No arguments other than * a possible * exception are given to the completion callback. * @since v0.1.31 */ export function link(existingPath: PathLike, newPath: PathLike, callback: NoParamCallback): void; export namespace link { /** * Asynchronous link(2) - Create a new link (also known as a hard link) to an existing file. * @param existingPath A path to a file. If a URL is provided, it must use the `file:` protocol. * @param newPath A path to a file. If a URL is provided, it must use the `file:` protocol. */ function __promisify__(existingPath: PathLike, newPath: PathLike): Promise<void>; } /** * 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. Returns `undefined`. * @since v0.1.31 */ export function linkSync(existingPath: PathLike, newPath: PathLike): void; /** * Creates the link called `path` pointing to `target`. No arguments other than a * possible exception are given to the completion callback. * * See the POSIX [`symlink(2)`](http://man7.org/linux/man-pages/man2/symlink.2.html) documentation for more details. * * The `type` argument is only available on Windows and ignored on other platforms. * It can be set to `'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. Junction * points on NTFS volumes can only point to directories. * * Relative targets are relative to the link's parent directory. * * ```js * import { symlink } from 'node:fs'; * * symlink('./mew', './mewtwo', callback); * ``` * * The above example creates a symbolic link `mewtwo` which points to `mew` in the * same directory: * * ```bash * $ tree . * . * ├── mew * └── mewtwo -> ./mew * ``` * @since v0.1.31 * @param [type='null'] */ export function symlink( target: PathLike, path: PathLike, type: symlink.Type | undefined | null, callback: NoParamCallback, ): void; /** * Asynchronous symlink(2) - Create a new symbolic link to an existing file. * @param target A path to an existing file. If a URL is provided, it must use t