From cb2bdc632a802eed7ee8c5c9388811de73029602 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C3=ABl=20Zasso?= Date: Sat, 10 Apr 2021 06:35:09 +0200 Subject: [PATCH] typings: add types for internalBinding('fs') PR-URL: https://github.com/nodejs/node/pull/38198 Reviewed-By: James M Snell Reviewed-By: Bradley Farias Reviewed-By: Rich Trott --- lib/internal/fs/promises.js | 3 + lib/internal/fs/utils.js | 8 + lib/internal/validators.js | 2 +- lib/path.js | 8 + tsconfig.json | 1 + typings/internalBinding/fs.d.ts | 258 ++++++++++++++++++++++++++++++++ 6 files changed, 279 insertions(+), 1 deletion(-) create mode 100644 typings/internalBinding/fs.d.ts diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js index 8b864874eb1..5d51248c841 100644 --- a/lib/internal/fs/promises.js +++ b/lib/internal/fs/promises.js @@ -97,6 +97,9 @@ const getDirectoryEntriesPromise = promisify(getDirents); const validateRmOptionsPromise = promisify(validateRmOptions); class FileHandle extends EventEmitterMixin(JSTransferable) { + /** + * @param {InternalFSBinding.FileHandle | undefined} filehandle + */ constructor(filehandle) { super(); this[kHandle] = filehandle; diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js index 06cc5e26dd6..bf4d8457531 100644 --- a/lib/internal/fs/utils.js +++ b/lib/internal/fs/utils.js @@ -333,6 +333,9 @@ function getOptions(options, defaultOptions) { return options; } +/** + * @param {InternalFSBinding.FSSyncContext} ctx + */ function handleErrorFromBinding(ctx) { if (ctx.errno !== undefined) { // libuv error numbers const err = uvException(ctx); @@ -518,6 +521,11 @@ Stats.prototype._checkModeProperty = function(property) { return (this.mode & S_IFMT) === property; }; +/** + * @param {Float64Array | BigUint64Array} stats + * @param {number} offset + * @returns + */ function getStatsFromBinding(stats, offset = 0) { if (isBigUint64Array(stats)) { return new BigIntStats( diff --git a/lib/internal/validators.js b/lib/internal/validators.js index ec6c4e4056d..6abe332fc5f 100644 --- a/lib/internal/validators.js +++ b/lib/internal/validators.js @@ -52,7 +52,7 @@ const modeDesc = 'must be a 32-bit unsigned integer or an octal string'; * * @param {*} value Values to be validated * @param {string} name Name of the argument - * @param {number} def If specified, will be returned for invalid values + * @param {number} [def] If specified, will be returned for invalid values * @returns {number} */ function parseFileMode(value, name, def) { diff --git a/lib/path.js b/lib/path.js index 09c40b927ba..96898275499 100644 --- a/lib/path.js +++ b/lib/path.js @@ -579,6 +579,10 @@ const win32 = { return StringPrototypeSlice(toOrig, toStart, toEnd); }, + /** + * @param {string} path + * @returns {string} + */ toNamespacedPath(path) { // Note: this will *probably* throw somewhere. if (typeof path !== 'string') @@ -1183,6 +1187,10 @@ const posix = { return `${out}${StringPrototypeSlice(to, toStart + lastCommonSep)}`; }, + /** + * @param {string} path + * @returns {string} + */ toNamespacedPath(path) { // Non-op on posix systems return path; diff --git a/tsconfig.json b/tsconfig.json index 5d35e44222d..93abd26727e 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -2,6 +2,7 @@ "include": ["lib","doc"], "exclude": ["src","tools","out"], "files": [ + "./typings/internalBinding/fs.d.ts", "./typings/internalBinding.d.ts", "./typings/primordials.d.ts" ], diff --git a/typings/internalBinding/fs.d.ts b/typings/internalBinding/fs.d.ts new file mode 100644 index 00000000000..a7f086c258d --- /dev/null +++ b/typings/internalBinding/fs.d.ts @@ -0,0 +1,258 @@ +declare namespace InternalFSBinding { + class FSReqCallback { + constructor(bigint?: boolean); + oncomplete: ((error: Error) => void) | ((error: null, result: ResultType) => void); + context: any; + } + + interface FSSyncContext { + fd?: number; + path?: string; + dest?: string; + errno?: string; + message?: string; + syscall?: string; + error?: Error; + } + + type Buffer = Uint8Array; + type StringOrBuffer = string | Buffer; + + const kUsePromises: symbol; + + class FileHandle { + constructor(fd: number, offset: number, length: number); + fd: number; + getAsyncId(): number; + close(): Promise; + onread: () => void; + stream: unknown; + } + + class StatWatcher { + constructor(useBigint: boolean); + initialized: boolean; + start(path: string, interval: number): number; + getAsyncId(): number; + close(): void; + ref(): void; + unref(): void; + onchange: (status: number, eventType: string, filename: string | Buffer) => void; + } + + function access(path: StringOrBuffer, mode: number, req: FSReqCallback): void; + function access(path: StringOrBuffer, mode: number, req: undefined, ctx: FSSyncContext): void; + function access(path: StringOrBuffer, mode: number, usePromises: typeof kUsePromises): Promise; + + function chmod(path: string, mode: number, req: FSReqCallback): void; + function chmod(path: string, mode: number, req: undefined, ctx: FSSyncContext): void; + function chmod(path: string, mode: number, usePromises: typeof kUsePromises): Promise; + + function chown(path: string, uid: number, gid: number, req: FSReqCallback): void; + function chown(path: string, uid: number, gid: number, req: undefined, ctx: FSSyncContext): void; + function chown(path: string, uid: number, gid: number, usePromises: typeof kUsePromises): Promise; + + function close(fd: number, req: FSReqCallback): void; + function close(fd: number, req: undefined, ctx: FSSyncContext): void; + + function copyFile(src: StringOrBuffer, dest: StringOrBuffer, mode: number, req: FSReqCallback): void; + function copyFile(src: StringOrBuffer, dest: StringOrBuffer, mode: number, req: undefined, ctx: FSSyncContext): void; + function copyFile(src: StringOrBuffer, dest: StringOrBuffer, mode: number, usePromises: typeof kUsePromises): Promise; + + function fchmod(fd: number, mode: number, req: FSReqCallback): void; + function fchmod(fd: number, mode: number, req: undefined, ctx: FSSyncContext): void; + function fchmod(fd: number, mode: number, usePromises: typeof kUsePromises): Promise; + + function fchown(fd: number, uid: number, gid: number, req: FSReqCallback): void; + function fchown(fd: number, uid: number, gid: number, req: undefined, ctx: FSSyncContext): void; + function fchown(fd: number, uid: number, gid: number, usePromises: typeof kUsePromises): Promise; + + function fdatasync(fd: number, req: FSReqCallback): void; + function fdatasync(fd: number, req: undefined, ctx: FSSyncContext): void; + function fdatasync(fd: number, usePromises: typeof kUsePromises): Promise; + + function fstat(fd: number, useBigint: boolean, req: FSReqCallback): void; + function fstat(fd: number, useBigint: true, req: FSReqCallback): void; + function fstat(fd: number, useBigint: false, req: FSReqCallback): void; + function fstat(fd: number, useBigint: boolean, req: undefined, ctx: FSSyncContext): Float64Array | BigUint64Array; + function fstat(fd: number, useBigint: true, req: undefined, ctx: FSSyncContext): BigUint64Array; + function fstat(fd: number, useBigint: false, req: undefined, ctx: FSSyncContext): Float64Array; + function fstat(fd: number, useBigint: boolean, usePromises: typeof kUsePromises): Promise; + function fstat(fd: number, useBigint: true, usePromises: typeof kUsePromises): Promise; + function fstat(fd: number, useBigint: false, usePromises: typeof kUsePromises): Promise; + + function fsync(fd: number, req: FSReqCallback): void; + function fsync(fd: number, req: undefined, ctx: FSSyncContext): void; + function fsync(fd: number, usePromises: typeof kUsePromises): Promise; + + function ftruncate(fd: number, len: number, req: FSReqCallback): void; + function ftruncate(fd: number, len: number, req: undefined, ctx: FSSyncContext): void; + function ftruncate(fd: number, len: number, usePromises: typeof kUsePromises): Promise; + + function futimes(fd: number, atime: number, mtime: number, req: FSReqCallback): void; + function futimes(fd: number, atime: number, mtime: number, req: undefined, ctx: FSSyncContext): void; + function futimes(fd: number, atime: number, mtime: number, usePromises: typeof kUsePromises): Promise; + + function internalModuleReadJSON(path: string): [] | [string, boolean]; + function internalModuleStat(path: string): number; + + function lchown(path: string, uid: number, gid: number, req: FSReqCallback): void; + function lchown(path: string, uid: number, gid: number, req: undefined, ctx: FSSyncContext): void; + function lchown(path: string, uid: number, gid: number, usePromises: typeof kUsePromises): Promise; + + function link(existingPath: string, newPath: string, req: FSReqCallback): void; + function link(existingPath: string, newPath: string, req: undefined, ctx: FSSyncContext): void; + function link(existingPath: string, newPath: string, usePromises: typeof kUsePromises): Promise; + + function lstat(path: StringOrBuffer, useBigint: boolean, req: FSReqCallback): void; + function lstat(path: StringOrBuffer, useBigint: true, req: FSReqCallback): void; + function lstat(path: StringOrBuffer, useBigint: false, req: FSReqCallback): void; + function lstat(path: StringOrBuffer, useBigint: boolean, req: undefined, ctx: FSSyncContext): Float64Array | BigUint64Array; + function lstat(path: StringOrBuffer, useBigint: true, req: undefined, ctx: FSSyncContext): BigUint64Array; + function lstat(path: StringOrBuffer, useBigint: false, req: undefined, ctx: FSSyncContext): Float64Array; + function lstat(path: StringOrBuffer, useBigint: boolean, usePromises: typeof kUsePromises): Promise; + function lstat(path: StringOrBuffer, useBigint: true, usePromises: typeof kUsePromises): Promise; + function lstat(path: StringOrBuffer, useBigint: false, usePromises: typeof kUsePromises): Promise; + + function lutimes(path: string, atime: number, mtime: number, req: FSReqCallback): void; + function lutimes(path: string, atime: number, mtime: number, req: undefined, ctx: FSSyncContext): void; + function lutimes(path: string, atime: number, mtime: number, usePromises: typeof kUsePromises): Promise; + + function mkdtemp(prefix: string, encoding: unknown, req: FSReqCallback): void; + function mkdtemp(prefix: string, encoding: unknown, req: undefined, ctx: FSSyncContext): string; + function mkdtemp(prefix: string, encoding: unknown, usePromises: typeof kUsePromises): Promise; + + function mkdir(path: string, mode: number, recursive: boolean, req: FSReqCallback): void; + function mkdir(path: string, mode: number, recursive: true, req: FSReqCallback): void; + function mkdir(path: string, mode: number, recursive: false, req: FSReqCallback): void; + function mkdir(path: string, mode: number, recursive: boolean, req: undefined, ctx: FSSyncContext): void | string; + function mkdir(path: string, mode: number, recursive: true, req: undefined, ctx: FSSyncContext): string; + function mkdir(path: string, mode: number, recursive: false, req: undefined, ctx: FSSyncContext): void; + function mkdir(path: string, mode: number, recursive: boolean, usePromises: typeof kUsePromises): Promise; + function mkdir(path: string, mode: number, recursive: true, usePromises: typeof kUsePromises): Promise; + function mkdir(path: string, mode: number, recursive: false, usePromises: typeof kUsePromises): Promise; + + function open(path: StringOrBuffer, flags: number, mode: number, req: FSReqCallback): void; + function open(path: StringOrBuffer, flags: number, mode: number, req: undefined, ctx: FSSyncContext): number; + + function openFileHandle(path: StringOrBuffer, flags: number, mode: number, usePromises: typeof kUsePromises): Promise; + + function read(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number, req: FSReqCallback): void; + function read(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number, req: undefined, ctx: FSSyncContext): number; + function read(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number, usePromises: typeof kUsePromises): Promise; + + function readBuffers(fd: number, buffers: ArrayBufferView[], position: number, req: FSReqCallback): void; + function readBuffers(fd: number, buffers: ArrayBufferView[], position: number, req: undefined, ctx: FSSyncContext): number; + function readBuffers(fd: number, buffers: ArrayBufferView[], position: number, usePromises: typeof kUsePromises): Promise; + + function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: boolean, req: FSReqCallback): void; + function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: true, req: FSReqCallback<[string[], number[]]>): void; + function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: false, req: FSReqCallback): void; + function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: boolean, req: undefined, ctx: FSSyncContext): string[] | [string[], number[]]; + function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: true, req: undefined, ctx: FSSyncContext): [string[], number[]]; + function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: false, req: undefined, ctx: FSSyncContext): string[]; + function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: boolean, usePromises: typeof kUsePromises): Promise; + function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: true, usePromises: typeof kUsePromises): Promise<[string[], number[]]>; + function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: false, usePromises: typeof kUsePromises): Promise; + + function readlink(path: StringOrBuffer, encoding: unknown, req: FSReqCallback): void; + function readlink(path: StringOrBuffer, encoding: unknown, req: undefined, ctx: FSSyncContext): string | Buffer; + function readlink(path: StringOrBuffer, encoding: unknown, usePromises: typeof kUsePromises): Promise; + + function realpath(path: StringOrBuffer, encoding: unknown, req: FSReqCallback): void; + function realpath(path: StringOrBuffer, encoding: unknown, req: undefined, ctx: FSSyncContext): string | Buffer; + function realpath(path: StringOrBuffer, encoding: unknown, usePromises: typeof kUsePromises): Promise; + + function rename(oldPath: string, newPath: string, req: FSReqCallback): void; + function rename(oldPath: string, newPath: string, req: undefined, ctx: FSSyncContext): void; + function rename(oldPath: string, newPath: string, usePromises: typeof kUsePromises): Promise; + + function rmdir(path: string, req: FSReqCallback): void; + function rmdir(path: string, req: undefined, ctx: FSSyncContext): void; + function rmdir(path: string, usePromises: typeof kUsePromises): Promise; + + function stat(path: StringOrBuffer, useBigint: boolean, req: FSReqCallback): void; + function stat(path: StringOrBuffer, useBigint: true, req: FSReqCallback): void; + function stat(path: StringOrBuffer, useBigint: false, req: FSReqCallback): void; + function stat(path: StringOrBuffer, useBigint: boolean, req: undefined, ctx: FSSyncContext): Float64Array | BigUint64Array; + function stat(path: StringOrBuffer, useBigint: true, req: undefined, ctx: FSSyncContext): BigUint64Array; + function stat(path: StringOrBuffer, useBigint: false, req: undefined, ctx: FSSyncContext): Float64Array; + function stat(path: StringOrBuffer, useBigint: boolean, usePromises: typeof kUsePromises): Promise; + function stat(path: StringOrBuffer, useBigint: true, usePromises: typeof kUsePromises): Promise; + function stat(path: StringOrBuffer, useBigint: false, usePromises: typeof kUsePromises): Promise; + + function symlink(target: StringOrBuffer, path: StringOrBuffer, type: number, req: FSReqCallback): void; + function symlink(target: StringOrBuffer, path: StringOrBuffer, type: number, req: undefined, ctx: FSSyncContext): void; + function symlink(target: StringOrBuffer, path: StringOrBuffer, type: number, usePromises: typeof kUsePromises): Promise; + + function unlink(path: string, req: FSReqCallback): void; + function unlink(path: string, req: undefined, ctx: FSSyncContext): void; + function unlink(path: string, usePromises: typeof kUsePromises): Promise; + + function utimes(path: string, atime: number, mtime: number, req: FSReqCallback): void; + function utimes(path: string, atime: number, mtime: number, req: undefined, ctx: FSSyncContext): void; + function utimes(path: string, atime: number, mtime: number, usePromises: typeof kUsePromises): Promise; + + function writeBuffer(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number | null, req: FSReqCallback): void; + function writeBuffer(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number | null, req: undefined, ctx: FSSyncContext): number; + function writeBuffer(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number | null, usePromises: typeof kUsePromises): Promise; + + function writeBuffers(fd: number, buffers: ArrayBufferView[], position: number, req: FSReqCallback): void; + function writeBuffers(fd: number, buffers: ArrayBufferView[], position: number, req: undefined, ctx: FSSyncContext): number; + function writeBuffers(fd: number, buffers: ArrayBufferView[], position: number, usePromises: typeof kUsePromises): Promise; + + function writeString(fd: number, value: string, pos: unknown, encoding: unknown, req: FSReqCallback): void; + function writeString(fd: number, value: string, pos: unknown, encoding: unknown, req: undefined, ctx: FSSyncContext): number; + function writeString(fd: number, value: string, pos: unknown, encoding: unknown, usePromises: typeof kUsePromises): Promise; +} + +declare function InternalBinding(binding: 'fs'): { + FSReqCallback: typeof InternalFSBinding.FSReqCallback; + + FileHandle: typeof InternalFSBinding.FileHandle; + + kUsePromises: typeof InternalFSBinding.kUsePromises; + + statValues: Float64Array; + bigintStatValues: BigUint64Array; + + kFsStatsFieldsNumber: number; + StatWatcher: typeof InternalFSBinding.StatWatcher; + + access: typeof InternalFSBinding.access; + chmod: typeof InternalFSBinding.chmod; + chown: typeof InternalFSBinding.chown; + close: typeof InternalFSBinding.close; + copyFile: typeof InternalFSBinding.copyFile; + fchmod: typeof InternalFSBinding.fchmod; + fchown: typeof InternalFSBinding.fchown; + fdatasync: typeof InternalFSBinding.fdatasync; + fstat: typeof InternalFSBinding.fstat; + fsync: typeof InternalFSBinding.fsync; + ftruncate: typeof InternalFSBinding.ftruncate; + futimes: typeof InternalFSBinding.futimes; + internalModuleReadJSON: typeof InternalFSBinding.internalModuleReadJSON; + internalModuleStat: typeof InternalFSBinding.internalModuleStat; + lchown: typeof InternalFSBinding.lchown; + link: typeof InternalFSBinding.link; + lstat: typeof InternalFSBinding.lstat; + lutimes: typeof InternalFSBinding.lutimes; + mkdtemp: typeof InternalFSBinding.mkdtemp; + mkdir: typeof InternalFSBinding.mkdir; + open: typeof InternalFSBinding.open; + openFileHandle: typeof InternalFSBinding.openFileHandle; + read: typeof InternalFSBinding.read; + readBuffers: typeof InternalFSBinding.readBuffers; + readdir: typeof InternalFSBinding.readdir; + readlink: typeof InternalFSBinding.readlink; + realpath: typeof InternalFSBinding.realpath; + rename: typeof InternalFSBinding.rename; + rmdir: typeof InternalFSBinding.rmdir; + stat: typeof InternalFSBinding.stat; + symlink: typeof InternalFSBinding.symlink; + unlink: typeof InternalFSBinding.unlink; + utimes: typeof InternalFSBinding.utimes; + writeBuffer: typeof InternalFSBinding.writeBuffer; + writeBuffers: typeof InternalFSBinding.writeBuffers; + writeString: typeof InternalFSBinding.writeString; +};