typings: add types for internalBinding('fs')

PR-URL: #38198
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>

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;

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(

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) {

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;

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"
   ],

typings/internalBinding/fs.d.ts

@@ -0,0 +1,258 @@
+declare namespace InternalFSBinding {
+  class FSReqCallback<ResultType = unknown> {
+    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<void>;
+    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<void>;
+
+  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<void>;
+
+  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<void>;
+
+  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<void>;
+
+  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<void>;
+
+  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<void>;
+
+  function fdatasync(fd: number, req: FSReqCallback): void;
+  function fdatasync(fd: number, req: undefined, ctx: FSSyncContext): void;
+  function fdatasync(fd: number, usePromises: typeof kUsePromises): Promise<void>;
+
+  function fstat(fd: number, useBigint: boolean, req: FSReqCallback<Float64Array | BigUint64Array>): void;
+  function fstat(fd: number, useBigint: true, req: FSReqCallback<BigUint64Array>): void;
+  function fstat(fd: number, useBigint: false, req: FSReqCallback<Float64Array>): 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<Float64Array | BigUint64Array>;
+  function fstat(fd: number, useBigint: true, usePromises: typeof kUsePromises): Promise<BigUint64Array>;
+  function fstat(fd: number, useBigint: false, usePromises: typeof kUsePromises): Promise<Float64Array>;
+
+  function fsync(fd: number, req: FSReqCallback): void;
+  function fsync(fd: number, req: undefined, ctx: FSSyncContext): void;
+  function fsync(fd: number, usePromises: typeof kUsePromises): Promise<void>;
+
+  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<void>;
+
+  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<void>;
+
+  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<void>;
+
+  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<void>;
+
+  function lstat(path: StringOrBuffer, useBigint: boolean, req: FSReqCallback<Float64Array | BigUint64Array>): void;
+  function lstat(path: StringOrBuffer, useBigint: true, req: FSReqCallback<BigUint64Array>): void;
+  function lstat(path: StringOrBuffer, useBigint: false, req: FSReqCallback<Float64Array>): 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<Float64Array | BigUint64Array>;
+  function lstat(path: StringOrBuffer, useBigint: true, usePromises: typeof kUsePromises): Promise<BigUint64Array>;
+  function lstat(path: StringOrBuffer, useBigint: false, usePromises: typeof kUsePromises): Promise<Float64Array>;
+
+  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<void>;
+
+  function mkdtemp(prefix: string, encoding: unknown, req: FSReqCallback<string>): void;
+  function mkdtemp(prefix: string, encoding: unknown, req: undefined, ctx: FSSyncContext): string;
+  function mkdtemp(prefix: string, encoding: unknown, usePromises: typeof kUsePromises): Promise<string>;
+
+  function mkdir(path: string, mode: number, recursive: boolean, req: FSReqCallback<void | string>): void;
+  function mkdir(path: string, mode: number, recursive: true, req: FSReqCallback<string>): void;
+  function mkdir(path: string, mode: number, recursive: false, req: FSReqCallback<void>): 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<void | string>;
+  function mkdir(path: string, mode: number, recursive: true, usePromises: typeof kUsePromises): Promise<string>;
+  function mkdir(path: string, mode: number, recursive: false, usePromises: typeof kUsePromises): Promise<void>;
+
+  function open(path: StringOrBuffer, flags: number, mode: number, req: FSReqCallback<number>): 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<FileHandle>;
+
+  function read(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number, req: FSReqCallback<number>): 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<number>;
+
+  function readBuffers(fd: number, buffers: ArrayBufferView[], position: number, req: FSReqCallback<number>): 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<number>;
+
+  function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: boolean, req: FSReqCallback<string[] | [string[], number[]]>): void;
+  function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: true, req: FSReqCallback<[string[], number[]]>): void;
+  function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: false, req: FSReqCallback<string[]>): 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<string[] | [string[], number[]]>;
+  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<string[]>;
+
+  function readlink(path: StringOrBuffer, encoding: unknown, req: FSReqCallback<string | Buffer>): void;
+  function readlink(path: StringOrBuffer, encoding: unknown, req: undefined, ctx: FSSyncContext): string | Buffer;
+  function readlink(path: StringOrBuffer, encoding: unknown, usePromises: typeof kUsePromises): Promise<string | Buffer>;
+
+  function realpath(path: StringOrBuffer, encoding: unknown, req: FSReqCallback<string | Buffer>): void;
+  function realpath(path: StringOrBuffer, encoding: unknown, req: undefined, ctx: FSSyncContext): string | Buffer;
+  function realpath(path: StringOrBuffer, encoding: unknown, usePromises: typeof kUsePromises): Promise<string | Buffer>;
+
+  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<void>;
+
+  function rmdir(path: string, req: FSReqCallback): void;
+  function rmdir(path: string, req: undefined, ctx: FSSyncContext): void;
+  function rmdir(path: string, usePromises: typeof kUsePromises): Promise<void>;
+
+  function stat(path: StringOrBuffer, useBigint: boolean, req: FSReqCallback<Float64Array | BigUint64Array>): void;
+  function stat(path: StringOrBuffer, useBigint: true, req: FSReqCallback<BigUint64Array>): void;
+  function stat(path: StringOrBuffer, useBigint: false, req: FSReqCallback<Float64Array>): 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<Float64Array | BigUint64Array>;
+  function stat(path: StringOrBuffer, useBigint: true, usePromises: typeof kUsePromises): Promise<BigUint64Array>;
+  function stat(path: StringOrBuffer, useBigint: false, usePromises: typeof kUsePromises): Promise<Float64Array>;
+
+  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<void>;
+
+  function unlink(path: string, req: FSReqCallback): void;
+  function unlink(path: string, req: undefined, ctx: FSSyncContext): void;
+  function unlink(path: string, usePromises: typeof kUsePromises): Promise<void>;
+
+  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<void>;
+
+  function writeBuffer(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number | null, req: FSReqCallback<number>): 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<number>;
+
+  function writeBuffers(fd: number, buffers: ArrayBufferView[], position: number, req: FSReqCallback<number>): 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<number>;
+
+  function writeString(fd: number, value: string, pos: unknown, encoding: unknown, req: FSReqCallback<number>): 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<number>;
+}
+
+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;
+};