[njs] Added TypeScript description for fs module.

Dmitry Volyntsev xeioex at nginx.com
Tue Oct 20 15:50:23 UTC 2020


details:   https://hg.nginx.org/njs/rev/6b84320e31d4
branches:  
changeset: 1543:6b84320e31d4
user:      Jakub Jirutka <jakub at jirutka.cz>
date:      Fri Oct 09 02:33:31 2020 +0200
description:
Added TypeScript description for fs module.

diffstat:

 src/ts/fs.d.ts  |  384 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 test/ts/test.ts |   10 +
 2 files changed, 394 insertions(+), 0 deletions(-)

diffs (413 lines):

diff -r 5eab7463f984 -r 6b84320e31d4 src/ts/fs.d.ts
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/ts/fs.d.ts	Fri Oct 09 02:33:31 2020 +0200
@@ -0,0 +1,384 @@
+/// <reference path="njs_core.d.ts" />
+
+declare module "fs" {
+
+    /**
+     * File system flag that controls opening of a file.
+     *
+     * - `'a'`   - Open a file for appending. The file is created if it does not exist.
+     * - `'ax'`  - The same as `'a'` but fails if the file already exists.
+     * - `'a+'`  - Open a file for reading and appending. If the file does not exist, it will be created.
+     * - `'ax+'` - The same as `'a+'` but fails if the file already exists.
+     * - `'as'`  - Open a file for appending in synchronous mode. If the file does not exist, it will be created.
+     * - `'as+'` - Open a file for reading and appending in synchronous mode. If the file does not exist, it will be created.
+     * - `'r'`   - Open a file for reading. An exception occurs if the file does not exist.
+     * - `'r+'`  - Open a file for reading and writing. An exception occurs if the file does not exist.
+     * - `'rs+'` - Open a file for reading and writing in synchronous mode. Instructs the operating system to bypass the local file system cache.
+     * - `'w'`   - Open a file for writing. If the file does not exist, it will be created. If the file exists, it will be replaced.
+     * - `'wx'`  - The same as `'w'` but fails if the file already exists.
+     * - `'w+'`  - Open a file for reading and writing. If the file does not exist, it will be created. If the file exists, it will be replaced.
+     * - `'wx+'` - The same as `'w+'` but fails if the file already exists.
+     */
+    export type OpenMode = "a" | "ax" | "a+" | "ax+" | "as" | "as+" | "r" | "r+" | "rs+" | "w" | "wx" | "w+" | "wx+";
+
+    export type FileEncoding = BufferEncoding;
+
+    /**
+     * Valid types for path values in "fs".
+     */
+    export type PathLike = string | Buffer;
+
+    /**
+     * A representation of a directory entry - a file or a subdirectory.
+     *
+     * When `readdirSync()` is called with the `withFileTypes` option, the resulting array contains
+     * `fs.Dirent` objects.
+     */
+    export interface Dirent {
+        /**
+         * @returns `true` if the object describes a block device.
+         */
+        isBlockDevice(): boolean;
+        /**
+         * @returns `true` if the object describes a character device.
+         */
+        isCharacterDevice(): boolean;
+        /**
+         * @returns `true` if the object describes a file system directory.
+         */
+        isDirectory(): boolean;
+        /**
+         * @returns `true` if the object describes a first-in-first-out (FIFO) pipe.
+         */
+        isFIFO(): boolean;
+        /**
+         * @returns `true` if the object describes a regular file.
+         */
+        isFile(): boolean;
+        /**
+         * @returns `true` if the object describes a socket.
+         */
+        isSocket(): boolean;
+        /**
+         * @returns `true` if the object describes a symbolic link.
+         */
+        isSymbolicLink(): boolean;
+
+        /**
+         * The name of the file this object refers to.
+         */
+        name: string;
+    }
+
+    type WriteFileOptions = {
+        mode?: number;
+        flag?: OpenMode;
+    };
+
+    type Constants = {
+        /**
+         * Indicates that the file is visible to the calling process, used by default if no mode
+         * is specified.
+         */
+        F_OK: 0;
+        /**
+         * Indicates that the file can be read by the calling process.
+         */
+        R_OK: 4;
+        /**
+         * Indicates that the file can be written by the calling process.
+         */
+        W_OK: 2;
+        /**
+         * Indicates that the file can be executed by the calling process.
+         */
+        X_OK: 1;
+    };
+
+    interface Promises {
+        /**
+         * 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.
+         *
+         * @example
+         *   import fs from 'fs'
+         *   fs.promises.access('/file/path', fs.constants.R_OK | fs.constants.W_OK)
+         *     .then(() => console.log('has access'))
+         *     .catch(() => console.log('no access'))
+         *
+         * @since 0.3.9
+         * @param path A path to a file or directory.
+         * @param mode An optional integer that specifies the accessibility checks to be performed.
+         *   Defaults to `fs.constants.F_OK`.
+         */
+        access(path: PathLike, mode?: number): Promise<void>;
+
+        /**
+         * Asynchronously appends specified `data` to a file with provided `filename`.
+         * If the file does not exist, it will be created.
+         *
+         * @since 0.4.4
+         * @param path A path to a file.
+         * @param data The data to write.
+         * @param options An object optionally specifying the file mode and flag.
+         *   If `mode` is not supplied, the default of `0o666` is used.
+         *   If `flag` is not supplied, the default of `'a'` is used.
+         */
+        appendFile(path: PathLike, data: NjsStringLike | Buffer, options?: WriteFileOptions): Promise<void>;
+
+        /**
+         * Asynchronously creates a directory at the specified `path`.
+         *
+         * @since 0.4.2
+         * @param path A path to a file.
+         * @param options The file mode (or an object specifying the file mode). Defaults to `0o777`.
+         */
+        mkdir(path: PathLike, options?: { mode?: number } | number): Promise<void>;
+
+        /**
+         * Asynchronously reads the contents of a directory at the specified `path`.
+         *
+         * @since 0.4.2
+         * @param path A path to a file.
+         * @param options A string that specifies encoding or an object optionally specifying
+         *   the following keys:
+         *   - `encoding` - `'utf8'` (default) or `'buffer'` (since 0.4.4)
+         *   - `withFileTypes` - if set to `true`, the files array will contain `fs.Dirent` objects; defaults to `false`.
+         */
+        readdir(path: PathLike, options?: { encoding?: "utf8"; withFileTypes?: false; } | "utf8"): Promise<string[]>;
+        readdir(path: PathLike, options: { encoding: "buffer"; withFileTypes?: false; } | "buffer"): Promise<Buffer[]>;
+        readdir(path: PathLike, options: { encoding?: "utf8" | "buffer"; withFileTypes: true; }): Promise<Dirent[]>;
+
+        /**
+         * Asynchronously returns the contents of the file with provided `filename`.
+         * If an encoding is specified, a `string` is returned, otherwise, a `Buffer`.
+         *
+         * @param path A path to a file.
+         * @param options A string that specifies encoding or an object with the following optional keys:
+         *   - `encoding` - `'utf8'`, `'hex'`, `'base64'`, or `'base64url'` (the last three since 0.4.4).
+         *   - `flag` - file system flag, defaults to `r`.
+         */
+        readFile(path: PathLike): Promise<Buffer>;
+        readFile(path: PathLike, options?: { flag?: OpenMode; }): Promise<Buffer>;
+        readFile(path: PathLike, options: { encoding?: FileEncoding; flag?: OpenMode; } | FileEncoding): Promise<string>;
+
+        /**
+         * Asynchronously computes the canonical pathname by resolving `.`, `..` and symbolic links using
+         * `realpath(3)`.
+         *
+         * @since 0.3.9
+         * @param path A path to a file.
+         * @param options The encoding (or an object specifying the encoding), used as the encoding of the result.
+         */
+        realpath(path: PathLike, options?: { encoding?: "utf8" } | "utf8"): Promise<string>;
+        realpath(path: PathLike, options: { encoding: "buffer" } | "buffer"): Promise<Buffer>;
+
+        /**
+         * Asynchronously changes the name or location of a file from `oldPath` to `newPath`.
+         *
+         * @since 0.3.4
+         * @param oldPath A path to a file.
+         * @param newPath A path to a file.
+         */
+        rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
+
+        /**
+         * Asynchronously removes a directory at the specified `path`.
+         *
+         * @since 0.4.2
+         * @param path A path to a file.
+         */
+        rmdir(path: PathLike): Promise<void>;
+
+        /**
+         * Asynchronously creates the link called `path` pointing to `target` using `symlink(2)`.
+         * Relative targets are relative to the link’s parent directory.
+         *
+         * @since 0.3.9
+         * @param target A path to an existing file.
+         * @param path A path to the new symlink.
+         */
+        symlink(target: PathLike, path: PathLike): Promise<void>;
+
+        /**
+         * Asynchronously unlinks a file by `path`.
+         *
+         * @since 0.3.9
+         * @param path A path to a file.
+         */
+        unlink(path: PathLike): Promise<void>;
+
+        /**
+         * Asynchronously writes `data` to a file with provided `filename`. If the file does not
+         * exist, it will be created, if the file exists, it will be replaced.
+         *
+         * @since 0.4.4
+         * @param path A path to a file.
+         * @param data The data to write.
+         * @param options An object optionally specifying the file mode and flag.
+         *   If `mode` is not supplied, the default of `0o666` is used.
+         *   If `flag` is not supplied, the default of `'w'` is used.
+         */
+        writeFile(path: PathLike, data: NjsStringLike | Buffer, options?: WriteFileOptions): Promise<void>;
+    }
+
+    interface NjsFS {
+        /**
+         * Promissified versions of file system methods.
+         *
+         * @since 0.3.9
+         */
+        promises: Promises
+        /**
+         * File Access Constants
+         */
+        constants: Constants
+
+        /**
+         * Synchronously 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.
+         *
+         * @example
+         *   try {
+         *     fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK);
+         *     console.log('has access');
+         *   } catch (e) {
+         *     console.log('no access');
+         *   }
+         *
+         * @since 0.3.9
+         * @param path A path to a file or directory.
+         * @param mode An optional integer that specifies the accessibility checks to be performed.
+         *   Defaults to `fs.constants.F_OK`.
+         */
+        accessSync(path: PathLike, mode?: number): void;
+
+        /**
+         * Synchronously appends specified `data` to a file with provided `filename`.
+         * If the file does not exist, it will be created.
+         *
+         * @since 0.4.4
+         * @param path A path to a file.
+         * @param data The data to write.
+         * @param options An object optionally specifying the file mode and flag.
+         *   If `mode` is not supplied, the default of `0o666` is used.
+         *   If `flag` is not supplied, the default of `'a'` is used.
+         */
+        appendFileSync(path: PathLike, data: NjsStringLike | Buffer, options?: WriteFileOptions): void;
+
+        /**
+         * Synchronously creates a directory at the specified `path`.
+         *
+         * @since 0.4.2
+         * @param path A path to a file.
+         * @param options The file mode (or an object specifying the file mode). Defaults to `0o777`.
+         */
+        mkdirSync(path: PathLike, options?: { mode?: number } | number): void;
+
+        /**
+         * Synchronously reads the contents of a directory at the specified `path`.
+         *
+         * @since 0.4.2
+         * @param path A path to a file.
+         * @param options A string that specifies encoding or an object optionally specifying
+         *   the following keys:
+         *   - `encoding` - `'utf8'` (default) or `'buffer'` (since 0.4.4)
+         *   - `withFileTypes` - if set to `true`, the files array will contain `fs.Dirent` objects;
+         *     defaults to `false`.
+         */
+        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[];
+
+        /**
+         * Synchronously returns the contents of the file with provided `filename`.
+         * If an encoding is specified, a `string` is returned, otherwise, a `Buffer`.
+         *
+         * @example
+         *   import fs from 'fs'
+         *   var file = fs.readFileSync('/file/path.tar.gz')
+         *   var gzipped = file.slice(0,2).toString('hex') === '1f8b'; gzipped  // => true
+         *
+         * @param path A path to a file.
+         * @param options A string that specifies encoding or an object with the following optional keys:
+         *   - `encoding` - `'utf8'`, `'hex'`, `'base64'`, or `'base64url'` (the last three since 0.4.4).
+         *   - `flag` - file system flag, defaults to `r`.
+         */
+        readFileSync(path: PathLike): Buffer;
+        readFileSync(path: PathLike, options?: { flag?: OpenMode; }): Buffer;
+        readFileSync(path: PathLike, options: { encoding?: FileEncoding; flag?: OpenMode; } | FileEncoding): string;
+
+        /**
+         * Synchronously computes the canonical pathname by resolving `.`, `..` and symbolic links using
+         * `realpath(3)`.
+         *
+         * @since 0.3.9
+         * @param path A path to a file.
+         * @param options The encoding (or an object specifying the encoding), used as the encoding of the result.
+         */
+        realpathSync(path: PathLike, options?: { encoding?: "utf8" } | "utf8"): string;
+        realpathSync(path: PathLike, options: { encoding: "buffer" } | "buffer"): Buffer;
+
+        /**
+         * Synchronously changes the name or location of a file from `oldPath` to `newPath`.
+         *
+         * @example
+         *   import fs from 'fs'
+         *   var file = fs.renameSync('hello.txt', 'HelloWorld.txt')
+         *
+         * @since 0.3.4
+         * @param oldPath A path to a file.
+         * @param newPath A path to a file.
+         */
+        renameSync(oldPath: PathLike, newPath: PathLike): void;
+
+        /**
+         * Synchronously removes a directory at the specified `path`.
+         *
+         * @since 0.4.2
+         * @param path A path to a file.
+         */
+        rmdirSync(path: PathLike): void;
+
+        /**
+         * Synchronously creates the link called `path` pointing to `target` using `symlink(2)`.
+         * Relative targets are relative to the link’s parent directory.
+         *
+         * @since 0.3.9
+         * @param target A path to an existing file.
+         * @param path A path to the new symlink.
+         */
+        symlinkSync(target: PathLike, path: PathLike): void;
+
+        /**
+         * Synchronously unlinks a file by `path`.
+         *
+         * @since 0.3.9
+         * @param path A path to a file.
+         */
+        unlinkSync(path: PathLike): void;
+
+        /**
+         * Synchronously writes `data` to a file with provided `filename`. If the file does not exist,
+         * it will be created, if the file exists, it will be replaced.
+         *
+         * @example
+         *   import fs from 'fs'
+         *   fs.writeFileSync('hello.txt', 'Hello world')
+         *
+         * @since 0.4.4
+         * @param path A path to a file.
+         * @param data The data to write.
+         * @param options An object optionally specifying the file mode and flag.
+         *   If `mode` is not supplied, the default of `0o666` is used.
+         *   If `flag` is not supplied, the default of `'w'` is used.
+         */
+        writeFileSync(path: PathLike, data: NjsStringLike | Buffer, options?: WriteFileOptions): void;
+    }
+
+    const fs: NjsFS;
+
+    // It's exported like this because njs doesn't support named imports.
+    // TODO: Replace NjsFS with individual named exports as soon as njs supports named imports.
+    export default fs;
+}
diff -r 5eab7463f984 -r 6b84320e31d4 test/ts/test.ts
--- a/test/ts/test.ts	Sat Oct 17 01:38:31 2020 +0200
+++ b/test/ts/test.ts	Fri Oct 09 02:33:31 2020 +0200
@@ -1,4 +1,7 @@
 /// <reference path="../../build/ts/ngx_http_js_module.d.ts" />
+/// <reference path="../../build/ts/fs.d.ts" />
+
+import fs from 'fs';
 
 function http_module(r: NginxHTTPRequest) {
     var bs: NjsByteString;
@@ -61,6 +64,13 @@ function http_module(r: NginxHTTPRequest
 
 }
 
+function fs_module() {
+    var s:string;
+
+    s = fs.readFileSync('/path', 'utf8');
+    s = fs.readFileSync(Buffer.from('/path'), {encoding:'hex'});
+}
+
 function buffer(b: Buffer) {
     var s:string;
 


More information about the nginx-devel mailing list