From 399580ff3bb1f1a5f584afb6bf7fc42d2f90a6d8 Mon Sep 17 00:00:00 2001 From: Dmitry Volyntsev Date: Mon, 22 Aug 2022 22:03:15 -0700 Subject: [PATCH] Types: added ts types for the recent fs API. --- test/ts/test.ts | 23 +++++- ts/njs_core.d.ts | 1 + ts/njs_modules/fs.d.ts | 174 ++++++++++++++++++++++++++++++++++++++--- 3 files changed, 185 insertions(+), 13 deletions(-) diff --git a/test/ts/test.ts b/test/ts/test.ts index 16f511db..4662f53f 100644 --- a/test/ts/test.ts +++ b/test/ts/test.ts @@ -103,13 +103,34 @@ async function http_module(r: NginxHTTPRequest) { r.done(); } -function fs_module() { +async function fs_module() { var s:string; s = fs.readFileSync('/path', 'utf8'); s = fs.readFileSync(Buffer.from('/path'), {encoding:'hex'}); fs.writeFileSync('/path', Buffer.from('abc')); + + let fh = await fs.promises.open('/path', 'r+'); + + let bw = await fh.write(Buffer.from('abc'), 0, 1, 3); + let bytes = bw.bytesWritten; + bw = await fh.write(Buffer.from('abc'), 2, 2, null); + let stat = fh.stat(); + + let buffer = Buffer.alloc(16); + let br = await fh.read(buffer, 0, 16, null); + bytes = br.bytesRead; + + await fh.close(); + + let fd = fs.openSync('/path', 'r+'); + let stat2 = fs.fstatSync(fd); + + fs.readSync(fd, buffer, 0, 16, 4); + buffer[1] += 2; + fs.writeSync(fd, buffer, 0, 16, 4); + fs.closeSync(fd); } function qs_module(str: NjsByteString) { diff --git a/ts/njs_core.d.ts b/ts/njs_core.d.ts index 7ac37e1b..5f8dbc68 100644 --- a/ts/njs_core.d.ts +++ b/ts/njs_core.d.ts @@ -595,6 +595,7 @@ declare class Buffer extends Uint8Array { } type NjsStringOrBuffer = NjsStringLike | Buffer | DataView | TypedArray | ArrayBuffer; +type NjsBuffer = Buffer | DataView | TypedArray; // Global objects diff --git a/ts/njs_modules/fs.d.ts b/ts/njs_modules/fs.d.ts index 02d22125..8d990a2f 100644 --- a/ts/njs_modules/fs.d.ts +++ b/ts/njs_modules/fs.d.ts @@ -34,7 +34,7 @@ declare module "fs" { * When `readdirSync()` is called with the `withFileTypes` option, the resulting array contains * `fs.Dirent` objects. */ - export interface Dirent { + export interface NjsDirent { /** * @returns `true` if the object describes a block device. */ @@ -75,7 +75,7 @@ declare module "fs" { * * The objects is returned from fs.stat(), fs.lstat() and friends. */ - export interface Stats { + export interface NjsStats { /** * @returns `true` if the object describes a block device. */ @@ -205,7 +205,7 @@ declare module "fs" { flag?: OpenMode; }; - type Constants = { + type NjsFsConstants = { /** * Indicates that the file is visible to the calling process, used by default if no mode * is specified. @@ -225,7 +225,7 @@ declare module "fs" { X_OK: 1; }; - interface Promises { + interface NjsFsPromises { /** * Asynchronously tests permissions for a file or directory specified in the `path`. * If the check fails, an error will be returned, otherwise, the method will return undefined. @@ -243,6 +243,21 @@ declare module "fs" { */ access(path: PathLike, mode?: number): Promise; + /** + * Asynchronously opens a file specified in the `path`. + * + * @example + * import fs from 'fs' + * let fh = await fs.promises.open('/file/path', 'w'); + * let bw = await fh.write("data to write", 10); + * + * @since 0.7.7 + * @param path A path to a file. + * @param flags File system flags, defaults to `r`. + * @param mode The file mode, defaults to 0o666. + */ + open(path: PathLike, flags?: OpenMode, mode?: number): Promise; + /** * Asynchronously appends specified `data` to a file with provided `filename`. * If the file does not exist, it will be created. @@ -266,7 +281,7 @@ declare module "fs" { * - `throwIfNoEntry` - Whether an exception will be thrown if no file system entry exists, * rather than returning undefined, defaults to `true`. */ - lstat(path: PathLike, options?: { throwIfNoEntry?: boolean; }): Promise; + lstat(path: PathLike, options?: { throwIfNoEntry?: boolean; }): Promise; /** * Asynchronously creates a directory at the specified `path`. @@ -289,7 +304,7 @@ declare module "fs" { */ readdir(path: PathLike, options?: { encoding?: "utf8"; withFileTypes?: false; } | "utf8"): Promise; readdir(path: PathLike, options: { encoding: "buffer"; withFileTypes?: false; } | "buffer"): Promise; - readdir(path: PathLike, options: { encoding?: "utf8" | "buffer"; withFileTypes: true; }): Promise; + readdir(path: PathLike, options: { encoding?: "utf8" | "buffer"; withFileTypes: true; }): Promise; /** * Asynchronously returns the contents of the file with provided `filename`. @@ -341,7 +356,7 @@ declare module "fs" { * - `throwIfNoEntry` - Whether an exception will be thrown if no file system entry exists, * rather than returning undefined, defaults to `true`. */ - stat(path: PathLike, options?: { throwIfNoEntry?: boolean; }): Promise; + stat(path: PathLike, options?: { throwIfNoEntry?: boolean; }): Promise; /** * Asynchronously creates the link called `path` pointing to `target` using `symlink(2)`. @@ -375,17 +390,95 @@ declare module "fs" { writeFile(path: PathLike, data: NjsStringOrBuffer, options?: WriteFileOptions): Promise; } + interface NjsFsBytesRead { + /** + * The number of bytes read. + */ + bytesRead: number; + + /** + * A reference to the passed in buffer argument. + */ + buffer: NjsBuffer; + } + + interface NjsFsBytesWritten { + /** + * The number of bytes written. + */ + bytesWritten: number; + + /** + * A reference to the buffer written. + */ + buffer: NjsBuffer; + } + + interface NjsFsFileHandle { + /** + * Asynchronously closes the file handle after waiting for any pending operation + * on the handle to complete. + */ + close(): Promise; + + /** + * The file descriptor number. + */ + fd: number; + + /** + * Asynchronously reads data from the file and stores that in the given buffer. + * + * @param buffer A buffer that will be filled with the file data read. + * @param offset The location in the buffer at which to start filling. + * @param length The number of bytes to read. + * @param position The location where to begin reading data from the file. + * If null, data will be read from the current file position, and the position will be updated. + * If position is an integer, the current file position will remain unchanged. + */ + read(buffer: NjsBuffer, offset: number, length: number, position: number | null): Promise; + + /** + * Asynchronously retrieves `fs.Stats` for the underlying descriptor. + */ + stat(): Promise; + + /** + * Asynchronously writes buffer to the file. + * + * @param buffer A buffer to write. + * @param offset The start position from within buffer where the data to write begins. + * @param The number of bytes from buffer to write. + * Defaults to buffer.byteLength - offset + * @param position The offset from the beginning of the file where the data from buffer + * should be written. If position is not a number, the data will be written at the current position. + * @param encoding One of the `'utf8'`, `'hex'`, `'base64'`, or `'base64url'`. + * Defaults to 'utf8'. + */ + write(buffer: NjsBuffer, offset: number, length?: number, position?: number | null): Promise; + write(buffer: NjsStringLike, position?: number | null, encoding?: FileEncoding): Promise; + } + interface NjsFS { /** * Promissified versions of file system methods. * * @since 0.3.9 */ - promises: Promises + promises: NjsFsPromises + + /** + * Synchronously closes specified file descriptor. + * + * @since 0.7.7 + * @param fd A file descriptor. + */ + closeSync(fd: number): undefined; + /** * File Access Constants */ - constants: Constants + constants: NjsFsConstants /** * Synchronously tests permissions for a file or directory specified in the `path`. @@ -419,6 +512,14 @@ declare module "fs" { */ appendFileSync(path: PathLike, data: NjsStringOrBuffer, options?: WriteFileOptions): void; + /** + * Synchronously retrieves `fs.Stats` object for specified file descriptor. + * + * @since 0.7.7 + * @param fd A file descriptor. + */ + fstatSync(fd: number): NjsStats; + /** * Synchronously retrieves `fs.Stats` object for the symbolic link referred to by path. * See `lstat(2)` for more details. @@ -429,7 +530,7 @@ declare module "fs" { * - `throwIfNoEntry` - Whether an exception will be thrown if no file system entry exists, * rather than returning undefined, defaults to `true`. */ - lstatSync(path: PathLike, options?: { throwIfNoEntry?: boolean; }): Stats; + lstatSync(path: PathLike, options?: { throwIfNoEntry?: boolean; }): NjsStats; /** * Synchronously creates a directory at the specified `path`. @@ -440,6 +541,21 @@ declare module "fs" { */ mkdirSync(path: PathLike, options?: { mode?: number } | number): void; + /** + * Synchronously opens a file specified in the `path`. + * + * @example + * import fs from 'fs' + * let fd = fs.openSync('/file/path', 'w'); + * let bytesWritten = fs.writeSync("data to write", 10); + * + * @since 0.7.7 + * @param path A path to a file. + * @param flags file system flags, defaults to `r`. + * @param mode Thre file mode, defaults to 0o666. + */ + openSync(path: PathLike, flags?: OpenMode, mode?: number): number; + /** * Synchronously reads the contents of a directory at the specified `path`. * @@ -453,7 +569,7 @@ declare module "fs" { */ readdirSync(path: PathLike, options?: { encoding?: "utf8"; withFileTypes?: false; } | "utf8"): string[]; readdirSync(path: PathLike, options: { encoding: "buffer"; withFileTypes?: false; } | "buffer"): Buffer[]; - readdirSync(path: PathLike, options: { encoding?: "utf8" | "buffer"; withFileTypes: true; }): Dirent[]; + readdirSync(path: PathLike, options: { encoding?: "utf8" | "buffer"; withFileTypes: true; }): NjsDirent[]; /** * Synchronously returns the contents of the file with provided `filename`. @@ -473,6 +589,23 @@ declare module "fs" { readFileSync(path: PathLike, options?: { flag?: OpenMode; }): Buffer; readFileSync(path: PathLike, options: { encoding?: FileEncoding; flag?: OpenMode; } | FileEncoding): string; + /** + * Synchronously reads data from the file and stores that in the given buffer. + * + * @since 0.7.7 + * @param fd A file descriptor. + * @param buffer A buffer that will be filled with the file data read. + * @param offset The location in the buffer at which to start filling. + * @param length The number of bytes to read. + * @param position The location where to begin reading data from the file. + * If null, data will be read from the current file position, and the position will be updated. + * If position is an integer, the current file position will remain unchanged. + * @param encoding One of the `'utf8'`, `'hex'`, `'base64'`, or `'base64url'`. + * Defaults to 'utf8'. + */ + readSync(fd: number, buffer: NjsBuffer, offset: number, length?: number, position?: number | null): number; + readSync(fd: number, string: NjsStringLike, position?: number | null, encoding?: FileEncoding): number; + /** * Synchronously computes the canonical pathname by resolving `.`, `..` and symbolic links using * `realpath(3)`. @@ -514,7 +647,7 @@ declare module "fs" { * - `throwIfNoEntry` - Whether an exception will be thrown if no file system entry exists, * rather than returning undefined, defaults to `true`. */ - statSync(path: PathLike, options?: { throwIfNoEntry?: boolean; }): Stats; + statSync(path: PathLike, options?: { throwIfNoEntry?: boolean; }): NjsStats; /** * Synchronously creates the link called `path` pointing to `target` using `symlink(2)`. @@ -550,6 +683,23 @@ declare module "fs" { * If `flag` is not supplied, the default of `'w'` is used. */ writeFileSync(path: PathLike, data: NjsStringOrBuffer, options?: WriteFileOptions): void; + + /** + * Synchronously writes `buffer` data to a file. + * + * @since 0.7.7 + * @param fd A file descriptor. + * @param buffer A buffer that will be filled with the file data read. + * @param offset The location in the buffer at which to start filling. + * @param length The number of bytes to read. + * @param position The location where to begin reading data from the file. + * If null, data will be read from the current file position, and the position will be updated. + * If position is an integer, the current file position will remain unchanged. + * @param encoding One of the `'utf8'`, `'hex'`, `'base64'`, or `'base64url'`. + * Defaults to 'utf8'. + */ + writeSync(fd: number, buffer: NjsBuffer, offset: number, length?: number, position?: number | null): number; + writeSync(fd: number, string: NjsStringLike, position?: number | null, encoding?: FileEncoding): number; } const fs: NjsFS; -- 2.47.3