From: Jakub Jirutka Date: Fri, 9 Oct 2020 00:33:31 +0000 (+0200) Subject: Added TypeScript description for fs module. X-Git-Url: http://www.kaiwu.me/postgresql/commit/?a=commitdiff_plain;h=993e7a8d0a801211bd4ffd4ebb74b1d5ceeb443d;p=njs.git Added TypeScript description for fs module. --- diff --git a/src/ts/fs.d.ts b/src/ts/fs.d.ts new file mode 100644 index 00000000..682cee49 --- /dev/null +++ b/src/ts/fs.d.ts @@ -0,0 +1,384 @@ +/// + +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; + + /** + * 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; + + /** + * 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; + + /** + * 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; + readdir(path: PathLike, options: { encoding: "buffer"; withFileTypes?: false; } | "buffer"): Promise; + readdir(path: PathLike, options: { encoding?: "utf8" | "buffer"; withFileTypes: true; }): Promise; + + /** + * 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; + readFile(path: PathLike, options?: { flag?: OpenMode; }): Promise; + readFile(path: PathLike, options: { encoding?: FileEncoding; flag?: OpenMode; } | FileEncoding): Promise; + + /** + * 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; + realpath(path: PathLike, options: { encoding: "buffer" } | "buffer"): Promise; + + /** + * 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; + + /** + * Asynchronously removes a directory at the specified `path`. + * + * @since 0.4.2 + * @param path A path to a file. + */ + rmdir(path: PathLike): Promise; + + /** + * 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; + + /** + * Asynchronously unlinks a file by `path`. + * + * @since 0.3.9 + * @param path A path to a file. + */ + unlink(path: PathLike): Promise; + + /** + * 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; + } + + 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 --git a/test/ts/test.ts b/test/ts/test.ts index 5caca7e0..43546e22 100644 --- a/test/ts/test.ts +++ b/test/ts/test.ts @@ -1,4 +1,7 @@ /// +/// + +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;