From c98494bda00cfcbb1df164eb5785e7af756a0cd9 Mon Sep 17 00:00:00 2001 From: Rob Hogan Date: Tue, 30 Dec 2025 09:32:11 -0800 Subject: [PATCH] Add Flow lib defs for newer Node.js fs APIs (#54992) Summary: Pull Request resolved: https://github.com/facebook/react-native/pull/54992 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 fbshipit-source-id: 1ad0ef2f7fedb6416471461b8be7bc418afcd28f --- 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 dce7b718159..b6b1f6e3dd6 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,