Skip to content

Commit cb2bdc6

Browse files
targostargos
committed
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>
1 parent ee669a0 commit cb2bdc6

File tree

6 files changed

+279
-1
lines changed

6 files changed

+279
-1
lines changed

‎lib/internal/fs/promises.js

+3
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,9 @@ const getDirectoryEntriesPromise = promisify(getDirents);
9797
const validateRmOptionsPromise = promisify(validateRmOptions);
9898

9999
class FileHandle extends EventEmitterMixin(JSTransferable) {
100+
/**
101+
* @param {InternalFSBinding.FileHandle | undefined} filehandle
102+
*/
100103
constructor(filehandle) {
101104
super();
102105
this[kHandle] = filehandle;

‎lib/internal/fs/utils.js

+8
Original file line numberDiff line numberDiff line change
@@ -333,6 +333,9 @@ function getOptions(options, defaultOptions) {
333333
return options;
334334
}
335335

336+
/**
337+
* @param {InternalFSBinding.FSSyncContext} ctx
338+
*/
336339
function handleErrorFromBinding(ctx) {
337340
if (ctx.errno !== undefined) { // libuv error numbers
338341
const err = uvException(ctx);
@@ -518,6 +521,11 @@ Stats.prototype._checkModeProperty = function(property) {
518521
return (this.mode & S_IFMT) === property;
519522
};
520523

524+
/**
525+
* @param {Float64Array | BigUint64Array} stats
526+
* @param {number} offset
527+
* @returns
528+
*/
521529
function getStatsFromBinding(stats, offset = 0) {
522530
if (isBigUint64Array(stats)) {
523531
return new BigIntStats(

‎lib/internal/validators.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ const modeDesc = 'must be a 32-bit unsigned integer or an octal string';
5252
*
5353
* @param {*} value Values to be validated
5454
* @param {string} name Name of the argument
55-
* @param {number} def If specified, will be returned for invalid values
55+
* @param {number} [def] If specified, will be returned for invalid values
5656
* @returns {number}
5757
*/
5858
function parseFileMode(value, name, def) {

‎lib/path.js

+8
Original file line numberDiff line numberDiff line change
@@ -579,6 +579,10 @@ const win32 = {
579579
return StringPrototypeSlice(toOrig, toStart, toEnd);
580580
},
581581

582+
/**
583+
* @param {string} path
584+
* @returns {string}
585+
*/
582586
toNamespacedPath(path) {
583587
// Note: this will *probably* throw somewhere.
584588
if (typeof path !== 'string')
@@ -1183,6 +1187,10 @@ const posix = {
11831187
return `${out}${StringPrototypeSlice(to, toStart + lastCommonSep)}`;
11841188
},
11851189

1190+
/**
1191+
* @param {string} path
1192+
* @returns {string}
1193+
*/
11861194
toNamespacedPath(path) {
11871195
// Non-op on posix systems
11881196
return path;

‎tsconfig.json

+1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
"include": ["lib","doc"],
33
"exclude": ["src","tools","out"],
44
"files": [
5+
"./typings/internalBinding/fs.d.ts",
56
"./typings/internalBinding.d.ts",
67
"./typings/primordials.d.ts"
78
],

‎typings/internalBinding/fs.d.ts

+258
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
declare namespace InternalFSBinding {
2+
class FSReqCallback<ResultType = unknown> {
3+
constructor(bigint?: boolean);
4+
oncomplete: ((error: Error) => void) | ((error: null, result: ResultType) => void);
5+
context: any;
6+
}
7+
8+
interface FSSyncContext {
9+
fd?: number;
10+
path?: string;
11+
dest?: string;
12+
errno?: string;
13+
message?: string;
14+
syscall?: string;
15+
error?: Error;
16+
}
17+
18+
type Buffer = Uint8Array;
19+
type StringOrBuffer = string | Buffer;
20+
21+
const kUsePromises: symbol;
22+
23+
class FileHandle {
24+
constructor(fd: number, offset: number, length: number);
25+
fd: number;
26+
getAsyncId(): number;
27+
close(): Promise<void>;
28+
onread: () => void;
29+
stream: unknown;
30+
}
31+
32+
class StatWatcher {
33+
constructor(useBigint: boolean);
34+
initialized: boolean;
35+
start(path: string, interval: number): number;
36+
getAsyncId(): number;
37+
close(): void;
38+
ref(): void;
39+
unref(): void;
40+
onchange: (status: number, eventType: string, filename: string | Buffer) => void;
41+
}
42+
43+
function access(path: StringOrBuffer, mode: number, req: FSReqCallback): void;
44+
function access(path: StringOrBuffer, mode: number, req: undefined, ctx: FSSyncContext): void;
45+
function access(path: StringOrBuffer, mode: number, usePromises: typeof kUsePromises): Promise<void>;
46+
47+
function chmod(path: string, mode: number, req: FSReqCallback): void;
48+
function chmod(path: string, mode: number, req: undefined, ctx: FSSyncContext): void;
49+
function chmod(path: string, mode: number, usePromises: typeof kUsePromises): Promise<void>;
50+
51+
function chown(path: string, uid: number, gid: number, req: FSReqCallback): void;
52+
function chown(path: string, uid: number, gid: number, req: undefined, ctx: FSSyncContext): void;
53+
function chown(path: string, uid: number, gid: number, usePromises: typeof kUsePromises): Promise<void>;
54+
55+
function close(fd: number, req: FSReqCallback): void;
56+
function close(fd: number, req: undefined, ctx: FSSyncContext): void;
57+
58+
function copyFile(src: StringOrBuffer, dest: StringOrBuffer, mode: number, req: FSReqCallback): void;
59+
function copyFile(src: StringOrBuffer, dest: StringOrBuffer, mode: number, req: undefined, ctx: FSSyncContext): void;
60+
function copyFile(src: StringOrBuffer, dest: StringOrBuffer, mode: number, usePromises: typeof kUsePromises): Promise<void>;
61+
62+
function fchmod(fd: number, mode: number, req: FSReqCallback): void;
63+
function fchmod(fd: number, mode: number, req: undefined, ctx: FSSyncContext): void;
64+
function fchmod(fd: number, mode: number, usePromises: typeof kUsePromises): Promise<void>;
65+
66+
function fchown(fd: number, uid: number, gid: number, req: FSReqCallback): void;
67+
function fchown(fd: number, uid: number, gid: number, req: undefined, ctx: FSSyncContext): void;
68+
function fchown(fd: number, uid: number, gid: number, usePromises: typeof kUsePromises): Promise<void>;
69+
70+
function fdatasync(fd: number, req: FSReqCallback): void;
71+
function fdatasync(fd: number, req: undefined, ctx: FSSyncContext): void;
72+
function fdatasync(fd: number, usePromises: typeof kUsePromises): Promise<void>;
73+
74+
function fstat(fd: number, useBigint: boolean, req: FSReqCallback<Float64Array | BigUint64Array>): void;
75+
function fstat(fd: number, useBigint: true, req: FSReqCallback<BigUint64Array>): void;
76+
function fstat(fd: number, useBigint: false, req: FSReqCallback<Float64Array>): void;
77+
function fstat(fd: number, useBigint: boolean, req: undefined, ctx: FSSyncContext): Float64Array | BigUint64Array;
78+
function fstat(fd: number, useBigint: true, req: undefined, ctx: FSSyncContext): BigUint64Array;
79+
function fstat(fd: number, useBigint: false, req: undefined, ctx: FSSyncContext): Float64Array;
80+
function fstat(fd: number, useBigint: boolean, usePromises: typeof kUsePromises): Promise<Float64Array | BigUint64Array>;
81+
function fstat(fd: number, useBigint: true, usePromises: typeof kUsePromises): Promise<BigUint64Array>;
82+
function fstat(fd: number, useBigint: false, usePromises: typeof kUsePromises): Promise<Float64Array>;
83+
84+
function fsync(fd: number, req: FSReqCallback): void;
85+
function fsync(fd: number, req: undefined, ctx: FSSyncContext): void;
86+
function fsync(fd: number, usePromises: typeof kUsePromises): Promise<void>;
87+
88+
function ftruncate(fd: number, len: number, req: FSReqCallback): void;
89+
function ftruncate(fd: number, len: number, req: undefined, ctx: FSSyncContext): void;
90+
function ftruncate(fd: number, len: number, usePromises: typeof kUsePromises): Promise<void>;
91+
92+
function futimes(fd: number, atime: number, mtime: number, req: FSReqCallback): void;
93+
function futimes(fd: number, atime: number, mtime: number, req: undefined, ctx: FSSyncContext): void;
94+
function futimes(fd: number, atime: number, mtime: number, usePromises: typeof kUsePromises): Promise<void>;
95+
96+
function internalModuleReadJSON(path: string): [] | [string, boolean];
97+
function internalModuleStat(path: string): number;
98+
99+
function lchown(path: string, uid: number, gid: number, req: FSReqCallback): void;
100+
function lchown(path: string, uid: number, gid: number, req: undefined, ctx: FSSyncContext): void;
101+
function lchown(path: string, uid: number, gid: number, usePromises: typeof kUsePromises): Promise<void>;
102+
103+
function link(existingPath: string, newPath: string, req: FSReqCallback): void;
104+
function link(existingPath: string, newPath: string, req: undefined, ctx: FSSyncContext): void;
105+
function link(existingPath: string, newPath: string, usePromises: typeof kUsePromises): Promise<void>;
106+
107+
function lstat(path: StringOrBuffer, useBigint: boolean, req: FSReqCallback<Float64Array | BigUint64Array>): void;
108+
function lstat(path: StringOrBuffer, useBigint: true, req: FSReqCallback<BigUint64Array>): void;
109+
function lstat(path: StringOrBuffer, useBigint: false, req: FSReqCallback<Float64Array>): void;
110+
function lstat(path: StringOrBuffer, useBigint: boolean, req: undefined, ctx: FSSyncContext): Float64Array | BigUint64Array;
111+
function lstat(path: StringOrBuffer, useBigint: true, req: undefined, ctx: FSSyncContext): BigUint64Array;
112+
function lstat(path: StringOrBuffer, useBigint: false, req: undefined, ctx: FSSyncContext): Float64Array;
113+
function lstat(path: StringOrBuffer, useBigint: boolean, usePromises: typeof kUsePromises): Promise<Float64Array | BigUint64Array>;
114+
function lstat(path: StringOrBuffer, useBigint: true, usePromises: typeof kUsePromises): Promise<BigUint64Array>;
115+
function lstat(path: StringOrBuffer, useBigint: false, usePromises: typeof kUsePromises): Promise<Float64Array>;
116+
117+
function lutimes(path: string, atime: number, mtime: number, req: FSReqCallback): void;
118+
function lutimes(path: string, atime: number, mtime: number, req: undefined, ctx: FSSyncContext): void;
119+
function lutimes(path: string, atime: number, mtime: number, usePromises: typeof kUsePromises): Promise<void>;
120+
121+
function mkdtemp(prefix: string, encoding: unknown, req: FSReqCallback<string>): void;
122+
function mkdtemp(prefix: string, encoding: unknown, req: undefined, ctx: FSSyncContext): string;
123+
function mkdtemp(prefix: string, encoding: unknown, usePromises: typeof kUsePromises): Promise<string>;
124+
125+
function mkdir(path: string, mode: number, recursive: boolean, req: FSReqCallback<void | string>): void;
126+
function mkdir(path: string, mode: number, recursive: true, req: FSReqCallback<string>): void;
127+
function mkdir(path: string, mode: number, recursive: false, req: FSReqCallback<void>): void;
128+
function mkdir(path: string, mode: number, recursive: boolean, req: undefined, ctx: FSSyncContext): void | string;
129+
function mkdir(path: string, mode: number, recursive: true, req: undefined, ctx: FSSyncContext): string;
130+
function mkdir(path: string, mode: number, recursive: false, req: undefined, ctx: FSSyncContext): void;
131+
function mkdir(path: string, mode: number, recursive: boolean, usePromises: typeof kUsePromises): Promise<void | string>;
132+
function mkdir(path: string, mode: number, recursive: true, usePromises: typeof kUsePromises): Promise<string>;
133+
function mkdir(path: string, mode: number, recursive: false, usePromises: typeof kUsePromises): Promise<void>;
134+
135+
function open(path: StringOrBuffer, flags: number, mode: number, req: FSReqCallback<number>): void;
136+
function open(path: StringOrBuffer, flags: number, mode: number, req: undefined, ctx: FSSyncContext): number;
137+
138+
function openFileHandle(path: StringOrBuffer, flags: number, mode: number, usePromises: typeof kUsePromises): Promise<FileHandle>;
139+
140+
function read(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number, req: FSReqCallback<number>): void;
141+
function read(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number, req: undefined, ctx: FSSyncContext): number;
142+
function read(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number, usePromises: typeof kUsePromises): Promise<number>;
143+
144+
function readBuffers(fd: number, buffers: ArrayBufferView[], position: number, req: FSReqCallback<number>): void;
145+
function readBuffers(fd: number, buffers: ArrayBufferView[], position: number, req: undefined, ctx: FSSyncContext): number;
146+
function readBuffers(fd: number, buffers: ArrayBufferView[], position: number, usePromises: typeof kUsePromises): Promise<number>;
147+
148+
function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: boolean, req: FSReqCallback<string[] | [string[], number[]]>): void;
149+
function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: true, req: FSReqCallback<[string[], number[]]>): void;
150+
function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: false, req: FSReqCallback<string[]>): void;
151+
function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: boolean, req: undefined, ctx: FSSyncContext): string[] | [string[], number[]];
152+
function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: true, req: undefined, ctx: FSSyncContext): [string[], number[]];
153+
function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: false, req: undefined, ctx: FSSyncContext): string[];
154+
function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: boolean, usePromises: typeof kUsePromises): Promise<string[] | [string[], number[]]>;
155+
function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: true, usePromises: typeof kUsePromises): Promise<[string[], number[]]>;
156+
function readdir(path: StringOrBuffer, encoding: unknown, withFileTypes: false, usePromises: typeof kUsePromises): Promise<string[]>;
157+
158+
function readlink(path: StringOrBuffer, encoding: unknown, req: FSReqCallback<string | Buffer>): void;
159+
function readlink(path: StringOrBuffer, encoding: unknown, req: undefined, ctx: FSSyncContext): string | Buffer;
160+
function readlink(path: StringOrBuffer, encoding: unknown, usePromises: typeof kUsePromises): Promise<string | Buffer>;
161+
162+
function realpath(path: StringOrBuffer, encoding: unknown, req: FSReqCallback<string | Buffer>): void;
163+
function realpath(path: StringOrBuffer, encoding: unknown, req: undefined, ctx: FSSyncContext): string | Buffer;
164+
function realpath(path: StringOrBuffer, encoding: unknown, usePromises: typeof kUsePromises): Promise<string | Buffer>;
165+
166+
function rename(oldPath: string, newPath: string, req: FSReqCallback): void;
167+
function rename(oldPath: string, newPath: string, req: undefined, ctx: FSSyncContext): void;
168+
function rename(oldPath: string, newPath: string, usePromises: typeof kUsePromises): Promise<void>;
169+
170+
function rmdir(path: string, req: FSReqCallback): void;
171+
function rmdir(path: string, req: undefined, ctx: FSSyncContext): void;
172+
function rmdir(path: string, usePromises: typeof kUsePromises): Promise<void>;
173+
174+
function stat(path: StringOrBuffer, useBigint: boolean, req: FSReqCallback<Float64Array | BigUint64Array>): void;
175+
function stat(path: StringOrBuffer, useBigint: true, req: FSReqCallback<BigUint64Array>): void;
176+
function stat(path: StringOrBuffer, useBigint: false, req: FSReqCallback<Float64Array>): void;
177+
function stat(path: StringOrBuffer, useBigint: boolean, req: undefined, ctx: FSSyncContext): Float64Array | BigUint64Array;
178+
function stat(path: StringOrBuffer, useBigint: true, req: undefined, ctx: FSSyncContext): BigUint64Array;
179+
function stat(path: StringOrBuffer, useBigint: false, req: undefined, ctx: FSSyncContext): Float64Array;
180+
function stat(path: StringOrBuffer, useBigint: boolean, usePromises: typeof kUsePromises): Promise<Float64Array | BigUint64Array>;
181+
function stat(path: StringOrBuffer, useBigint: true, usePromises: typeof kUsePromises): Promise<BigUint64Array>;
182+
function stat(path: StringOrBuffer, useBigint: false, usePromises: typeof kUsePromises): Promise<Float64Array>;
183+
184+
function symlink(target: StringOrBuffer, path: StringOrBuffer, type: number, req: FSReqCallback): void;
185+
function symlink(target: StringOrBuffer, path: StringOrBuffer, type: number, req: undefined, ctx: FSSyncContext): void;
186+
function symlink(target: StringOrBuffer, path: StringOrBuffer, type: number, usePromises: typeof kUsePromises): Promise<void>;
187+
188+
function unlink(path: string, req: FSReqCallback): void;
189+
function unlink(path: string, req: undefined, ctx: FSSyncContext): void;
190+
function unlink(path: string, usePromises: typeof kUsePromises): Promise<void>;
191+
192+
function utimes(path: string, atime: number, mtime: number, req: FSReqCallback): void;
193+
function utimes(path: string, atime: number, mtime: number, req: undefined, ctx: FSSyncContext): void;
194+
function utimes(path: string, atime: number, mtime: number, usePromises: typeof kUsePromises): Promise<void>;
195+
196+
function writeBuffer(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number | null, req: FSReqCallback<number>): void;
197+
function writeBuffer(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number | null, req: undefined, ctx: FSSyncContext): number;
198+
function writeBuffer(fd: number, buffer: ArrayBufferView, offset: number, length: number, position: number | null, usePromises: typeof kUsePromises): Promise<number>;
199+
200+
function writeBuffers(fd: number, buffers: ArrayBufferView[], position: number, req: FSReqCallback<number>): void;
201+
function writeBuffers(fd: number, buffers: ArrayBufferView[], position: number, req: undefined, ctx: FSSyncContext): number;
202+
function writeBuffers(fd: number, buffers: ArrayBufferView[], position: number, usePromises: typeof kUsePromises): Promise<number>;
203+
204+
function writeString(fd: number, value: string, pos: unknown, encoding: unknown, req: FSReqCallback<number>): void;
205+
function writeString(fd: number, value: string, pos: unknown, encoding: unknown, req: undefined, ctx: FSSyncContext): number;
206+
function writeString(fd: number, value: string, pos: unknown, encoding: unknown, usePromises: typeof kUsePromises): Promise<number>;
207+
}
208+
209+
declare function InternalBinding(binding: 'fs'): {
210+
FSReqCallback: typeof InternalFSBinding.FSReqCallback;
211+
212+
FileHandle: typeof InternalFSBinding.FileHandle;
213+
214+
kUsePromises: typeof InternalFSBinding.kUsePromises;
215+
216+
statValues: Float64Array;
217+
bigintStatValues: BigUint64Array;
218+
219+
kFsStatsFieldsNumber: number;
220+
StatWatcher: typeof InternalFSBinding.StatWatcher;
221+
222+
access: typeof InternalFSBinding.access;
223+
chmod: typeof InternalFSBinding.chmod;
224+
chown: typeof InternalFSBinding.chown;
225+
close: typeof InternalFSBinding.close;
226+
copyFile: typeof InternalFSBinding.copyFile;
227+
fchmod: typeof InternalFSBinding.fchmod;
228+
fchown: typeof InternalFSBinding.fchown;
229+
fdatasync: typeof InternalFSBinding.fdatasync;
230+
fstat: typeof InternalFSBinding.fstat;
231+
fsync: typeof InternalFSBinding.fsync;
232+
ftruncate: typeof InternalFSBinding.ftruncate;
233+
futimes: typeof InternalFSBinding.futimes;
234+
internalModuleReadJSON: typeof InternalFSBinding.internalModuleReadJSON;
235+
internalModuleStat: typeof InternalFSBinding.internalModuleStat;
236+
lchown: typeof InternalFSBinding.lchown;
237+
link: typeof InternalFSBinding.link;
238+
lstat: typeof InternalFSBinding.lstat;
239+
lutimes: typeof InternalFSBinding.lutimes;
240+
mkdtemp: typeof InternalFSBinding.mkdtemp;
241+
mkdir: typeof InternalFSBinding.mkdir;
242+
open: typeof InternalFSBinding.open;
243+
openFileHandle: typeof InternalFSBinding.openFileHandle;
244+
read: typeof InternalFSBinding.read;
245+
readBuffers: typeof InternalFSBinding.readBuffers;
246+
readdir: typeof InternalFSBinding.readdir;
247+
readlink: typeof InternalFSBinding.readlink;
248+
realpath: typeof InternalFSBinding.realpath;
249+
rename: typeof InternalFSBinding.rename;
250+
rmdir: typeof InternalFSBinding.rmdir;
251+
stat: typeof InternalFSBinding.stat;
252+
symlink: typeof InternalFSBinding.symlink;
253+
unlink: typeof InternalFSBinding.unlink;
254+
utimes: typeof InternalFSBinding.utimes;
255+
writeBuffer: typeof InternalFSBinding.writeBuffer;
256+
writeBuffers: typeof InternalFSBinding.writeBuffers;
257+
writeString: typeof InternalFSBinding.writeString;
258+
};

0 commit comments

Comments
 (0)