From 29445c58c53a6daa2de0e710ad7741d78a28b6b5 Mon Sep 17 00:00:00 2001 From: Rob Hogan Date: Tue, 30 Dec 2025 07:18:11 -0800 Subject: [PATCH] Add Flow lib defs for newer Node.js fs APIs Summary: Node.js's `fs` has been updated considerably since it was first covered with Flow, and so far we've only added new APIs piecemeal as we need them. This goes through the whole module top to bottom and attempts to update in line with the Node.js docs at v24. Changelog: [Internal] Reviewed By: vzaidman Differential Revision: D89605689 --- flow-typed/environment/node.js | 240 ++++++++++++++++++++++++++++++--- 1 file changed, 224 insertions(+), 16 deletions(-) diff --git a/flow-typed/environment/node.js b/flow-typed/environment/node.js index dce7b718159a..b6b1f6e3dd66 100644 --- a/flow-typed/environment/node.js +++ b/flow-typed/environment/node.js @@ -1050,6 +1050,8 @@ declare module 'fs' { declare class FSWatcher extends events$EventEmitter { close(): void; + ref(): this; + unref(): this; } declare class ReadStream extends stream$Readable { @@ -1063,6 +1065,7 @@ declare module 'fs' { declare class Dirent { name: string | Buffer; + parentPath: string; isBlockDevice(): boolean; isCharacterDevice(): boolean; @@ -1296,12 +1299,24 @@ declare module 'fs' { declare function mkdtempSync(prefix: string): string; declare function readdir( path: string, - options: string | {encoding?: string, withFileTypes?: false, ...}, + options: + | string + | $ReadOnly<{ + encoding?: string, + recursive?: boolean, + withFileTypes?: false, + ... + }>, callback: (err: ?ErrnoError, files: Array) => void, ): void; declare function readdir( path: string, - options: {encoding?: string, withFileTypes: true, ...}, + options: $ReadOnly<{ + encoding?: string, + recursive?: boolean, + withFileTypes: true, + ... + }>, callback: (err: ?ErrnoError, files: Array) => void, ): void; declare function readdir( @@ -1310,11 +1325,23 @@ declare module 'fs' { ): void; declare function readdirSync( path: string, - options?: string | {encoding?: string, withFileTypes?: false, ...}, + options?: + | string + | $ReadOnly<{ + encoding?: string, + recursive?: boolean, + withFileTypes?: false, + }>, ): Array; declare function readdirSync( path: string, - options?: string | {encoding?: string, withFileTypes: true, ...}, + options?: + | string + | $ReadOnly<{ + encoding?: string, + recursive?: boolean, + withFileTypes: true, + }>, ): Array; declare function close( fd: number, @@ -1332,6 +1359,29 @@ declare module 'fs' { flags: string | number, callback: (err: ?ErrnoError, fd: number) => void, ): void; + declare function openAsBlob( + path: string | Buffer | URL, + options?: $ReadOnly<{ + type?: string, // Optional MIME type hint + }>, + ): Promise; + declare function opendir( + path: string, + options?: $ReadOnly<{ + encoding?: string, + bufferSize?: number, + recursive?: boolean, + }>, + callback: (err: ?ErrnoError, dir: Dir) => void, + ): void; + declare function opendirSync( + path: string, + options?: $ReadOnly<{ + encoding?: string, + bufferSize?: number, + recursive?: boolean, + }>, + ): Dir; declare function openSync( path: string | Buffer, flags: string | number, @@ -1550,7 +1600,15 @@ declare module 'fs' { ): void; declare function watchFile( filename: string, - options?: Object, + listener?: (curr: Stats, prev: Stats) => void, + ): void; + declare function watchFile( + filename: string, + options?: $ReadOnly<{ + bigint?: boolean, + persistent?: boolean, + interval?: number, + }>, listener?: (curr: Stats, prev: Stats) => void, ): void; declare function unwatchFile( @@ -1559,7 +1617,16 @@ declare module 'fs' { ): void; declare function watch( filename: string, - options?: Object, + listener?: (event: string, filename: string) => void, + ): FSWatcher; + declare function watch( + filename: string, + options?: $ReadOnly<{ + persistent?: boolean, + recursive?: boolean, + encoding?: string, + signal?: AbortSignal, + }>, listener?: (event: string, filename: string) => void, ): FSWatcher; declare function exists( @@ -1599,6 +1666,40 @@ declare module 'fs' { dest: string, flags?: number, ): void; + declare function cp( + src: string | URL, + dest: string | URL, + options: $ReadOnly<{ + dereference?: boolean, + errorOnExist?: boolean, + filter?: (src: string, dest: string) => boolean | Promise, + force?: boolean, + mode?: number, + preserveTimestamps?: boolean, + recursive?: boolean, + verbatimSymlinks?: boolean, + }>, + callback: (err: ?Error) => void, + ): void; + declare function cp( + src: string | URL, + dest: string | URL, + callback: (err: ?Error) => void, + ): void; + declare function cpSync( + src: string | URL, + dest: string | URL, + options?: $ReadOnly<{ + dereference?: boolean, + errorOnExist?: boolean, + filter?: (src: string, dest: string) => boolean, + force?: boolean, + mode?: number, + preserveTimestamps?: boolean, + recursive?: boolean, + verbatimSymlinks?: boolean, + }>, + ): void; declare type GlobOptions = $ReadOnly<{ /** @@ -1729,14 +1830,52 @@ declare module 'fs' { retryDelay?: number, ... }; + declare class Dir { + +path: string; + close(): Promise; + closeSync(): void; + read(): Promise; + read(cb: (err?: Error, dirent: ?Dirent) => void): void; + readSync(): ?Dirent; + @@asyncIterator(): AsyncIterator; + } + type AppendOrWriteToFileHandle = ( + data: + | string + | Buffer + | Uint8Array + | DataView + | AsyncIterable + | Iterable + | stream$Readable, + options: WriteOptions | string, + ) => Promise; declare class FileHandle { - appendFile( - data: string | Buffer, - options: WriteOptions | string, - ): Promise; + appendFile: AppendOrWriteToFileHandle; chmod(mode: number): Promise; chown(uid: number, guid: number): Promise; close(): Promise; + createReadStream( + options?: $ReadOnly<{ + encoding?: string, + autoClose?: boolean, + emitClose?: boolean, + start?: number, + end?: number, + highWaterMark?: number, + signal?: AbortSignal, + }>, + ): ReadStream; + createWriteStream( + options?: $ReadOnly<{ + encoding?: string, + autoClose?: boolean, + emitClose?: boolean, + start?: number, + highWaterMark?: number, + flush?: boolean, + }>, + ): WriteStream; datasync(): Promise; fd: number; read( @@ -1749,8 +1888,25 @@ declare module 'fs' { buffer: T, ... }>; + readableWebStream( + options?: $ReadOnly<{autoClose?: boolean}>, + ): ReadableStream; readFile(options: EncodingFlag): Promise; readFile(options: string): Promise; + readLines( + options?: $ReadOnly<{ + encoding?: string, + autoClose?: boolean, + emitClose?: boolean, + start?: number, + end?: number, + highWaterMark?: number, + }>, + ): readline$Interface; + readv | Array | Array>( + buffers: T, + position?: number | null, + ): Promise<{buffers: T, bytesRead: number}>; stat(): Promise; sync(): Promise; truncate(len?: number): Promise; @@ -1759,15 +1915,24 @@ declare module 'fs' { mtime: number | string | Date, ): Promise; write( - buffer: Buffer | Uint8Array, + buffer: Buffer | Uint8Array | DataView, offset: number, length: number, position: number, ): Promise; - writeFile( - data: string | Buffer | Uint8Array, - options: WriteOptions | string, + write( + buffer: Buffer | Uint8Array | DataView, + options?: $ReadOnly<{ + offset?: number, + length?: number, + position?: number, + }>, ): Promise; + writeFile: AppendOrWriteToFileHandle; + writev | Array | Array>( + buffers: T, + position?: number | null, + ): Promise<{buffers: T, bytesWritten: number}>; } declare type FSPromisePath = string | Buffer | URL; @@ -1785,6 +1950,20 @@ declare module 'fs' { dest: FSPromisePath, flags?: number, ): Promise, + cp( + src: string | URL, + dest: string | URL, + options?: $ReadOnly<{ + dereference?: boolean, + errorOnExist?: boolean, + filter?: (src: string, dest: string) => boolean | Promise, + force?: boolean, + mode?: number, + preserveTimestamps?: boolean, + recursive?: boolean, + verbatimSymlinks?: boolean, + }>, + ): Promise, fchmod(filehandle: FileHandle, mode: number): Promise, fchown(filehandle: FileHandle, uid: number, guid: number): Promise, fdatasync(filehandle: FileHandle): Promise, @@ -1824,6 +2003,14 @@ declare module 'fs' { flags?: string | number, mode?: number, ): Promise, + opendir( + path: string, + options?: $ReadOnly<{ + encoding?: string, + bufferSize?: number, + recursive?: boolean, + }>, + ): Promise, read( filehandle: FileHandle, buffer: T, @@ -1837,11 +2024,21 @@ declare module 'fs' { }>, readdir: (( path: FSPromisePath, - options: string | {encoding?: string, withFileTypes?: false, ...}, + options: + | string + | $ReadOnly<{ + encoding?: string, + recursive?: boolean, + withFileTypes?: false, + }>, ) => Promise>) & (( path: FSPromisePath, - options: {encoding?: string, withFileTypes: true, ...}, + options: $ReadOnly<{ + encoding?: string, + recursive?: boolean, + withFileTypes: true, + }>, ) => Promise>) & ((path: FSPromisePath) => Promise>), readFile: (( @@ -1884,6 +2081,17 @@ declare module 'fs' { atime: number | string | Date, mtime: number | string | Date, ): Promise, + watch( + filename: FSPromisePath, + options?: $ReadOnly<{ + persistent?: boolean, + recursive?: boolean, + encoding?: string, + signal?: AbortSignal, + maxQueue?: number, + overflow?: 'ignore' | 'throw', + }>, + ): AsyncIterator<{eventType: string, filename: ?string}>, write( filehandle: FileHandle, buffer: T,