diff --git a/node_modules/.package-lock.json b/node_modules/.package-lock.json index e93e9e6..ae34f19 100644 --- a/node_modules/.package-lock.json +++ b/node_modules/.package-lock.json @@ -1,7 +1,7 @@ { "name": "setup-maven", "version": "1.0.0", - "lockfileVersion": 2, + "lockfileVersion": 3, "requires": true, "packages": { "node_modules/@actions/core": { @@ -185,9 +185,12 @@ } }, "node_modules/@types/node": { - "version": "16.11.64", - "resolved": "https://registry.npmjs.org/@types/node/-/node-16.11.64.tgz", - "integrity": "sha512-z5hPTlVFzNwtJ2LNozTpJcD1Cu44c4LNuzaq1mwxmiHWQh2ULdR6Vjwo1UGldzRpzL0yUEdZddnfqGW2G70z6Q==" + "version": "20.11.6", + "resolved": "https://registry.npmjs.org/@types/node/-/node-20.11.6.tgz", + "integrity": "sha512-+EOokTnksGVgip2PbYbr3xnR7kZigh4LbybAfBAw5BpnQ+FqBYUsvCEjYd70IXKlbohQ64mzEYmMtlWUY8q//Q==", + "dependencies": { + "undici-types": "~5.26.4" + } }, "node_modules/@types/normalize-package-data": { "version": "2.4.0", @@ -1171,6 +1174,11 @@ "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.13.4.tgz", "integrity": "sha512-BQFnUDuAQ4Yf/cYY5LNrK9NCJFKriaRbD9uR1fTeXnBeoa97W0i41qkZfGO9pSo8I5KzjAcSY2XYtdf0oKd7KQ==" }, + "node_modules/undici-types": { + "version": "5.26.5", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz", + "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==" + }, "node_modules/universal-user-agent": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-2.1.0.tgz", diff --git a/node_modules/@types/node/LICENSE b/node_modules/@types/node/LICENSE old mode 100755 new mode 100644 diff --git a/node_modules/@types/node/README.md b/node_modules/@types/node/README.md old mode 100755 new mode 100644 index 1a99d7a..daedb7d --- a/node_modules/@types/node/README.md +++ b/node_modules/@types/node/README.md @@ -2,15 +2,14 @@ > `npm install --save @types/node` # Summary -This package contains type definitions for Node.js (https://nodejs.org/). +This package contains type definitions for node (https://nodejs.org/). # Details -Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node/v16. +Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node. ### Additional Details - * Last updated: Mon, 03 Oct 2022 22:33:04 GMT - * Dependencies: none - * Global values: `AbortController`, `AbortSignal`, `__dirname`, `__filename`, `console`, `exports`, `gc`, `global`, `module`, `process`, `require` + * Last updated: Wed, 24 Jan 2024 06:08:24 GMT + * Dependencies: [undici-types](https://npmjs.com/package/undici-types) # Credits -These definitions were written by [Microsoft TypeScript](https://github.com/Microsoft), [DefinitelyTyped](https://github.com/DefinitelyTyped), [Alberto Schiabel](https://github.com/jkomyno), [Alvis HT Tang](https://github.com/alvis), [Andrew Makarov](https://github.com/r3nya), [Benjamin Toueg](https://github.com/btoueg), [Chigozirim C.](https://github.com/smac89), [David Junger](https://github.com/touffy), [Deividas Bakanas](https://github.com/DeividasBakanas), [Eugene Y. Q. Shen](https://github.com/eyqs), [Hannes Magnusson](https://github.com/Hannes-Magnusson-CK), [Huw](https://github.com/hoo29), [Kelvin Jin](https://github.com/kjin), [Klaus Meinhardt](https://github.com/ajafff), [Lishude](https://github.com/islishude), [Mariusz Wiktorczyk](https://github.com/mwiktorczyk), [Mohsen Azimi](https://github.com/mohsen1), [Nicolas Even](https://github.com/n-e), [Nikita Galkin](https://github.com/galkin), [Parambir Singh](https://github.com/parambirs), [Sebastian Silbermann](https://github.com/eps1lon), [Seth Westphal](https://github.com/westy92), [Simon Schick](https://github.com/SimonSchick), [Thomas den Hollander](https://github.com/ThomasdenH), [Wilco Bakker](https://github.com/WilcoBakker), [wwwy3y3](https://github.com/wwwy3y3), [Samuel Ainsworth](https://github.com/samuela), [Kyle Uehlein](https://github.com/kuehlein), [Thanik Bhongbhibhat](https://github.com/bhongy), [Marcin Kopacz](https://github.com/chyzwar), [Trivikram Kamat](https://github.com/trivikr), [Junxiao Shi](https://github.com/yoursunny), [Ilia Baryshnikov](https://github.com/qwelias), [ExE Boss](https://github.com/ExE-Boss), [Piotr Błażejewicz](https://github.com/peterblazejewicz), [Anna Henningsen](https://github.com/addaleax), [Victor Perin](https://github.com/victorperin), [Yongsheng Zhang](https://github.com/ZYSzys), [NodeJS Contributors](https://github.com/NodeJS), [Linus Unnebäck](https://github.com/LinusU), and [wafuwafu13](https://github.com/wafuwafu13). +These definitions were written by [Microsoft TypeScript](https://github.com/Microsoft), [Alberto Schiabel](https://github.com/jkomyno), [Alvis HT Tang](https://github.com/alvis), [Andrew Makarov](https://github.com/r3nya), [Benjamin Toueg](https://github.com/btoueg), [Chigozirim C.](https://github.com/smac89), [David Junger](https://github.com/touffy), [Deividas Bakanas](https://github.com/DeividasBakanas), [Eugene Y. Q. Shen](https://github.com/eyqs), [Hannes Magnusson](https://github.com/Hannes-Magnusson-CK), [Huw](https://github.com/hoo29), [Kelvin Jin](https://github.com/kjin), [Klaus Meinhardt](https://github.com/ajafff), [Lishude](https://github.com/islishude), [Mariusz Wiktorczyk](https://github.com/mwiktorczyk), [Mohsen Azimi](https://github.com/mohsen1), [Nicolas Even](https://github.com/n-e), [Nikita Galkin](https://github.com/galkin), [Parambir Singh](https://github.com/parambirs), [Sebastian Silbermann](https://github.com/eps1lon), [Thomas den Hollander](https://github.com/ThomasdenH), [Wilco Bakker](https://github.com/WilcoBakker), [wwwy3y3](https://github.com/wwwy3y3), [Samuel Ainsworth](https://github.com/samuela), [Kyle Uehlein](https://github.com/kuehlein), [Thanik Bhongbhibhat](https://github.com/bhongy), [Marcin Kopacz](https://github.com/chyzwar), [Trivikram Kamat](https://github.com/trivikr), [Junxiao Shi](https://github.com/yoursunny), [Ilia Baryshnikov](https://github.com/qwelias), [ExE Boss](https://github.com/ExE-Boss), [Piotr Błażejewicz](https://github.com/peterblazejewicz), [Anna Henningsen](https://github.com/addaleax), [Victor Perin](https://github.com/victorperin), [Yongsheng Zhang](https://github.com/ZYSzys), [NodeJS Contributors](https://github.com/NodeJS), [Linus Unnebäck](https://github.com/LinusU), [wafuwafu13](https://github.com/wafuwafu13), [Matteo Collina](https://github.com/mcollina), and [Dmitry Semigradsky](https://github.com/Semigradsky). diff --git a/node_modules/@types/node/assert.d.ts b/node_modules/@types/node/assert.d.ts old mode 100755 new mode 100644 index 9f916c1..cd82143 --- a/node_modules/@types/node/assert.d.ts +++ b/node_modules/@types/node/assert.d.ts @@ -1,9 +1,9 @@ /** - * The `assert` module provides a set of assertion functions for verifying + * The `node:assert` module provides a set of assertion functions for verifying * invariants. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/assert.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/assert.js) */ -declare module 'assert' { +declare module "assert" { /** * An alias of {@link ok}. * @since v0.5.9 @@ -12,15 +12,29 @@ declare module 'assert' { function assert(value: unknown, message?: string | Error): asserts value; namespace assert { /** - * Indicates the failure of an assertion. All errors thrown by the `assert` module - * will be instances of the `AssertionError` class. + * Indicates the failure of an assertion. All errors thrown by the `node:assert`module will be instances of the `AssertionError` class. */ class AssertionError extends Error { + /** + * Set to the `actual` argument for methods such as {@link assert.strictEqual()}. + */ actual: unknown; + /** + * Set to the `expected` argument for methods such as {@link assert.strictEqual()}. + */ expected: unknown; + /** + * Set to the passed in operator value. + */ operator: string; + /** + * Indicates if the message was auto-generated (`true`) or not. + */ generatedMessage: boolean; - code: 'ERR_ASSERTION'; + /** + * Value is always `ERR_ASSERTION` to show that the error is an assertion error. + */ + code: "ERR_ASSERTION"; constructor(options?: { /** If provided, the error message is set to this value. */ message?: string | undefined; @@ -31,14 +45,15 @@ declare module 'assert' { /** The `operator` property on the error instance. */ operator?: string | undefined; /** If provided, the generated stack trace omits frames before this function. */ - // tslint:disable-next-line:ban-types + // eslint-disable-next-line @typescript-eslint/ban-types stackStartFn?: Function | undefined; }); } /** - * This feature is currently experimental and behavior might still change. + * This feature is deprecated and will be removed in a future version. + * Please consider using alternatives such as the `mock` helper function. * @since v14.2.0, v12.19.0 - * @experimental + * @deprecated Deprecated */ class CallTracker { /** @@ -47,7 +62,7 @@ declare module 'assert' { * error. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * // Creates call tracker. * const tracker = new assert.CallTracker(); @@ -65,26 +80,44 @@ declare module 'assert' { */ calls(exact?: number): () => void; calls any>(fn?: Func, exact?: number): Func; + /** + * Example: + * + * ```js + * import assert from 'node:assert'; + * + * const tracker = new assert.CallTracker(); + * + * function func() {} + * const callsfunc = tracker.calls(func); + * callsfunc(1, 2, 3); + * + * assert.deepStrictEqual(tracker.getCalls(callsfunc), + * [{ thisArg: undefined, arguments: [1, 2, 3] }]); + * ``` + * @since v18.8.0, v16.18.0 + * @param fn + * @return An Array with all the calls to a tracked function. + */ + getCalls(fn: Function): CallTrackerCall[]; /** * The arrays contains information about the expected and actual number of calls of * the functions that have not been called the expected number of times. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * // Creates call tracker. * const tracker = new assert.CallTracker(); * * function func() {} * - * function foo() {} - * * // Returns a function that wraps func() that must be called exact times * // before tracker.verify(). * const callsfunc = tracker.calls(func, 2); * * // Returns an array containing information on callsfunc() - * tracker.report(); + * console.log(tracker.report()); * // [ * // { * // message: 'Expected the func function to be executed 2 time(s) but was @@ -97,15 +130,39 @@ declare module 'assert' { * // ] * ``` * @since v14.2.0, v12.19.0 - * @return of objects containing information about the wrapper functions returned by `calls`. + * @return An Array of objects containing information about the wrapper functions returned by `calls`. */ report(): CallTrackerReportInformation[]; + /** + * Reset calls of the call tracker. + * If a tracked function is passed as an argument, the calls will be reset for it. + * If no arguments are passed, all tracked functions will be reset. + * + * ```js + * import assert from 'node:assert'; + * + * const tracker = new assert.CallTracker(); + * + * function func() {} + * const callsfunc = tracker.calls(func); + * + * callsfunc(); + * // Tracker was called once + * assert.strictEqual(tracker.getCalls(callsfunc).length, 1); + * + * tracker.reset(callsfunc); + * assert.strictEqual(tracker.getCalls(callsfunc).length, 0); + * ``` + * @since v18.8.0, v16.18.0 + * @param fn a tracked function to reset. + */ + reset(fn?: Function): void; /** * Iterates through the list of functions passed to `tracker.calls()` and will throw an error for functions that * have not been called the expected number of times. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * // Creates call tracker. * const tracker = new assert.CallTracker(); @@ -125,6 +182,10 @@ declare module 'assert' { */ verify(): void; } + interface CallTrackerCall { + thisArg: object; + arguments: unknown[]; + } interface CallTrackerReportInformation { message: string; /** The actual number of times the function was called. */ @@ -136,14 +197,14 @@ declare module 'assert' { /** A stack trace of the function. */ stack: object; } - type AssertPredicate = RegExp | (new () => object) | ((thrown: unknown) => boolean) | object | Error; + type AssertPredicate = RegExp | (new() => object) | ((thrown: unknown) => boolean) | object | Error; /** * Throws an `AssertionError` with the provided error message or a default * error message. If the `message` parameter is an instance of an `Error` then * it will be thrown instead of the `AssertionError`. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.fail(); * // AssertionError [ERR_ASSERTION]: Failed @@ -167,8 +228,8 @@ declare module 'assert' { expected: unknown, message?: string | Error, operator?: string, - // tslint:disable-next-line:ban-types - stackStartFn?: Function + // eslint-disable-next-line @typescript-eslint/ban-types + stackStartFn?: Function, ): never; /** * Tests if `value` is truthy. It is equivalent to`assert.equal(!!value, true, message)`. @@ -181,7 +242,7 @@ declare module 'assert' { * thrown in a file! See below for further details. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.ok(true); * // OK @@ -216,7 +277,7 @@ declare module 'assert' { * ``` * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * // Using `assert()` works the same: * assert(0); @@ -237,11 +298,11 @@ declare module 'assert' { * > Stability: 3 - Legacy: Use {@link strictEqual} instead. * * Tests shallow, coercive equality between the `actual` and `expected` parameters - * using the [Abstract Equality Comparison](https://tc39.github.io/ecma262/#sec-abstract-equality-comparison) ( `==` ). `NaN` is special handled - * and treated as being identical in case both sides are `NaN`. + * using the [`==` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality). `NaN` is specially handled + * and treated as being identical if both sides are `NaN`. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * assert.equal(1, 1); * // OK, 1 == 1 @@ -270,12 +331,11 @@ declare module 'assert' { * * > Stability: 3 - Legacy: Use {@link notStrictEqual} instead. * - * Tests shallow, coercive inequality with the [Abstract Equality Comparison](https://tc39.github.io/ecma262/#sec-abstract-equality-comparison)(`!=` ). `NaN` is special handled and treated as - * being identical in case both - * sides are `NaN`. + * Tests shallow, coercive inequality with the [`!=` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Inequality). `NaN` is + * specially handled and treated as being identical if both sides are `NaN`. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * assert.notEqual(1, 2); * // OK @@ -322,24 +382,24 @@ declare module 'assert' { * Tests for any deep inequality. Opposite of {@link deepEqual}. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * const obj1 = { * a: { - * b: 1 - * } + * b: 1, + * }, * }; * const obj2 = { * a: { - * b: 2 - * } + * b: 2, + * }, * }; * const obj3 = { * a: { - * b: 1 - * } + * b: 1, + * }, * }; - * const obj4 = Object.create(obj1); + * const obj4 = { __proto__: obj1 }; * * assert.notDeepEqual(obj1, obj1); * // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } @@ -362,10 +422,10 @@ declare module 'assert' { function notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void; /** * Tests strict equality between the `actual` and `expected` parameters as - * determined by the [SameValue Comparison](https://tc39.github.io/ecma262/#sec-samevalue). + * determined by [`Object.is()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is). * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.strictEqual(1, 2); * // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal: @@ -400,10 +460,10 @@ declare module 'assert' { function strictEqual(actual: unknown, expected: T, message?: string | Error): asserts actual is T; /** * Tests strict inequality between the `actual` and `expected` parameters as - * determined by the [SameValue Comparison](https://tc39.github.io/ecma262/#sec-samevalue). + * determined by [`Object.is()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is). * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.notStrictEqual(1, 2); * // OK @@ -434,7 +494,7 @@ declare module 'assert' { * Tests for deep strict inequality. Opposite of {@link deepStrictEqual}. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.notDeepStrictEqual({ a: 1 }, { a: '1' }); * // OK @@ -465,14 +525,14 @@ declare module 'assert' { * Custom validation object/error instance: * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * const err = new TypeError('Wrong value'); * err.code = 404; * err.foo = 'bar'; * err.info = { * nested: true, - * baz: 'text' + * baz: 'text', * }; * err.reg = /abc/i; * @@ -485,16 +545,16 @@ declare module 'assert' { * message: 'Wrong value', * info: { * nested: true, - * baz: 'text' - * } + * baz: 'text', + * }, * // Only properties on the validation object will be tested for. * // Using nested objects requires all properties to be present. Otherwise * // the validation is going to fail. - * } + * }, * ); * * // Using regular expressions to validate error properties: - * throws( + * assert.throws( * () => { * throw err; * }, @@ -508,17 +568,17 @@ declare module 'assert' { * info: { * nested: true, * // It is not possible to use regular expressions for nested properties! - * baz: 'text' + * baz: 'text', * }, * // The `reg` property contains a regular expression and only if the * // validation object contains an identical regular expression, it is going * // to pass. - * reg: /abc/i - * } + * reg: /abc/i, + * }, * ); * * // Fails due to the different `message` and `name` properties: - * throws( + * assert.throws( * () => { * const otherErr = new Error('Not found'); * // Copy all enumerable properties from `err` to `otherErr`. @@ -529,20 +589,20 @@ declare module 'assert' { * }, * // The error's `message` and `name` properties will also be checked when using * // an error as validation object. - * err + * err, * ); * ``` * * Validate instanceof using constructor: * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.throws( * () => { * throw new Error('Wrong value'); * }, - * Error + * Error, * ); * ``` * @@ -552,13 +612,13 @@ declare module 'assert' { * therefore also include the error name. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.throws( * () => { * throw new Error('Wrong value'); * }, - * /^Error: Wrong value$/ + * /^Error: Wrong value$/, * ); * ``` * @@ -568,7 +628,7 @@ declare module 'assert' { * It will otherwise fail with an `AssertionError`. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.throws( * () => { @@ -584,7 +644,7 @@ declare module 'assert' { * // possible. * return true; * }, - * 'unexpected error' + * 'unexpected error', * ); * ``` * @@ -594,7 +654,7 @@ declare module 'assert' { * a string as the second argument gets considered: * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * function throwingFirst() { * throw new Error('First'); @@ -650,20 +710,20 @@ declare module 'assert' { * propagated back to the caller. * * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), - * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) or a validation + * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions), or a validation * function. See {@link throws} for more details. * * The following, for instance, will throw the `TypeError` because there is no * matching error type in the assertion: * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.doesNotThrow( * () => { * throw new TypeError('Wrong value'); * }, - * SyntaxError + * SyntaxError, * ); * ``` * @@ -671,27 +731,27 @@ declare module 'assert' { * 'Got unwanted exception...': * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.doesNotThrow( * () => { * throw new TypeError('Wrong value'); * }, - * TypeError + * TypeError, * ); * ``` * * If an `AssertionError` is thrown and a value is provided for the `message`parameter, the value of `message` will be appended to the `AssertionError` message: * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.doesNotThrow( * () => { * throw new TypeError('Wrong value'); * }, * /Wrong value/, - * 'Whoops' + * 'Whoops', * ); * // Throws: AssertionError: Got unwanted exception: Whoops * ``` @@ -705,7 +765,7 @@ declare module 'assert' { * from the error passed to `ifError()` including the potential new frames for`ifError()` itself. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.ifError(null); * // OK @@ -751,7 +811,7 @@ declare module 'assert' { * If specified, `message` will be the message provided by the `AssertionError` if the `asyncFn` fails to reject. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * await assert.rejects( * async () => { @@ -759,13 +819,13 @@ declare module 'assert' { * }, * { * name: 'TypeError', - * message: 'Wrong value' - * } + * message: 'Wrong value', + * }, * ); * ``` * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * await assert.rejects( * async () => { @@ -775,16 +835,16 @@ declare module 'assert' { * assert.strictEqual(err.name, 'TypeError'); * assert.strictEqual(err.message, 'Wrong value'); * return true; - * } + * }, * ); * ``` * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.rejects( * Promise.reject(new Error('Wrong value')), - * Error + * Error, * ).then(() => { * // ... * }); @@ -797,7 +857,11 @@ declare module 'assert' { * @since v10.0.0 */ function rejects(block: (() => Promise) | Promise, message?: string | Error): Promise; - function rejects(block: (() => Promise) | Promise, error: AssertPredicate, message?: string | Error): Promise; + function rejects( + block: (() => Promise) | Promise, + error: AssertPredicate, + message?: string | Error, + ): Promise; /** * Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately * calls the function and awaits the returned promise to complete. It will then @@ -814,24 +878,24 @@ declare module 'assert' { * error messages as expressive as possible. * * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), - * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) or a validation + * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions), or a validation * function. See {@link throws} for more details. * * Besides the async nature to await the completion behaves identically to {@link doesNotThrow}. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * await assert.doesNotReject( * async () => { * throw new TypeError('Wrong value'); * }, - * SyntaxError + * SyntaxError, * ); * ``` * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.doesNotReject(Promise.reject(new TypeError('Wrong value'))) * .then(() => { @@ -840,13 +904,20 @@ declare module 'assert' { * ``` * @since v10.0.0 */ - function doesNotReject(block: (() => Promise) | Promise, message?: string | Error): Promise; - function doesNotReject(block: (() => Promise) | Promise, error: AssertPredicate, message?: string | Error): Promise; + function doesNotReject( + block: (() => Promise) | Promise, + message?: string | Error, + ): Promise; + function doesNotReject( + block: (() => Promise) | Promise, + error: AssertPredicate, + message?: string | Error, + ): Promise; /** * Expects the `string` input to match the regular expression. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.match('I will fail', /pass/); * // AssertionError [ERR_ASSERTION]: The input did not match the regular ... @@ -869,7 +940,7 @@ declare module 'assert' { * Expects the `string` input not to match the regular expression. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.doesNotMatch('I will fail', /fail/); * // AssertionError [ERR_ASSERTION]: The input was expected to not match the ... @@ -888,25 +959,38 @@ declare module 'assert' { * @since v13.6.0, v12.16.0 */ function doesNotMatch(value: string, regExp: RegExp, message?: string | Error): void; - const strict: Omit & { - (value: unknown, message?: string | Error): asserts value; - equal: typeof strictEqual; - notEqual: typeof notStrictEqual; - deepEqual: typeof deepStrictEqual; - notDeepEqual: typeof notDeepStrictEqual; - // Mapped types and assertion functions are incompatible? - // TS2775: Assertions require every name in the call target - // to be declared with an explicit type annotation. - ok: typeof ok; - strictEqual: typeof strictEqual; - deepStrictEqual: typeof deepStrictEqual; - ifError: typeof ifError; - strict: typeof strict; - }; + const strict: + & Omit< + typeof assert, + | "equal" + | "notEqual" + | "deepEqual" + | "notDeepEqual" + | "ok" + | "strictEqual" + | "deepStrictEqual" + | "ifError" + | "strict" + > + & { + (value: unknown, message?: string | Error): asserts value; + equal: typeof strictEqual; + notEqual: typeof notStrictEqual; + deepEqual: typeof deepStrictEqual; + notDeepEqual: typeof notDeepStrictEqual; + // Mapped types and assertion functions are incompatible? + // TS2775: Assertions require every name in the call target + // to be declared with an explicit type annotation. + ok: typeof ok; + strictEqual: typeof strictEqual; + deepStrictEqual: typeof deepStrictEqual; + ifError: typeof ifError; + strict: typeof strict; + }; } export = assert; } -declare module 'node:assert' { - import assert = require('assert'); +declare module "node:assert" { + import assert = require("assert"); export = assert; } diff --git a/node_modules/@types/node/assert/strict.d.ts b/node_modules/@types/node/assert/strict.d.ts old mode 100755 new mode 100644 index b4319b9..f333913 --- a/node_modules/@types/node/assert/strict.d.ts +++ b/node_modules/@types/node/assert/strict.d.ts @@ -1,8 +1,8 @@ -declare module 'assert/strict' { - import { strict } from 'node:assert'; +declare module "assert/strict" { + import { strict } from "node:assert"; export = strict; } -declare module 'node:assert/strict' { - import { strict } from 'node:assert'; +declare module "node:assert/strict" { + import { strict } from "node:assert"; export = strict; } diff --git a/node_modules/@types/node/async_hooks.d.ts b/node_modules/@types/node/async_hooks.d.ts old mode 100755 new mode 100644 index ed294eb..0667a61 --- a/node_modules/@types/node/async_hooks.d.ts +++ b/node_modules/@types/node/async_hooks.d.ts @@ -1,19 +1,27 @@ /** - * The `async_hooks` module provides an API to track asynchronous resources. It - * can be accessed using: + * We strongly discourage the use of the `async_hooks` API. + * Other APIs that can cover most of its use cases include: + * + * * `AsyncLocalStorage` tracks async context + * * `process.getActiveResourcesInfo()` tracks active resources + * + * The `node:async_hooks` module provides an API to track asynchronous resources. + * It can be accessed using: * * ```js - * import async_hooks from 'async_hooks'; + * import async_hooks from 'node:async_hooks'; * ``` * @experimental - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/async_hooks.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/async_hooks.js) */ -declare module 'async_hooks' { +declare module "async_hooks" { /** * ```js - * import { executionAsyncId } from 'async_hooks'; + * import { executionAsyncId } from 'node:async_hooks'; + * import fs from 'node:fs'; * * console.log(executionAsyncId()); // 1 - bootstrap + * const path = '.'; * fs.open(path, 'r', (err, fd) => { * console.log(executionAsyncId()); // 6 - open() * }); @@ -51,8 +59,8 @@ declare module 'async_hooks' { * but having an object representing the top-level can be helpful. * * ```js - * import { open } from 'fs'; - * import { executionAsyncId, executionAsyncResource } from 'async_hooks'; + * import { open } from 'node:fs'; + * import { executionAsyncId, executionAsyncResource } from 'node:async_hooks'; * * console.log(executionAsyncId(), executionAsyncResource()); // 1 {} * open(new URL(import.meta.url), 'r', (err, fd) => { @@ -64,11 +72,11 @@ declare module 'async_hooks' { * use of a tracking `Map` to store the metadata: * * ```js - * import { createServer } from 'http'; + * import { createServer } from 'node:http'; * import { * executionAsyncId, * executionAsyncResource, - * createHook + * createHook, * } from 'async_hooks'; * const sym = Symbol('state'); // Private symbol to avoid pollution * @@ -78,7 +86,7 @@ declare module 'async_hooks' { * if (cr) { * resource[sym] = cr[sym]; * } - * } + * }, * }).enable(); * * const server = createServer((req, res) => { @@ -167,11 +175,11 @@ declare module 'async_hooks' { * specifics of all functions that can be passed to `callbacks` is in the `Hook Callbacks` section. * * ```js - * import { createHook } from 'async_hooks'; + * import { createHook } from 'node:async_hooks'; * * const asyncHook = createHook({ * init(asyncId, type, triggerAsyncId, resource) { }, - * destroy(asyncId) { } + * destroy(asyncId) { }, * }); * ``` * @@ -223,13 +231,13 @@ declare module 'async_hooks' { * The following is an overview of the `AsyncResource` API. * * ```js - * import { AsyncResource, executionAsyncId } from 'async_hooks'; + * import { AsyncResource, executionAsyncId } from 'node:async_hooks'; * * // AsyncResource() is meant to be extended. Instantiating a * // new AsyncResource() also triggers init. If triggerAsyncId is omitted then * // async_hook.executionAsyncId() is used. * const asyncResource = new AsyncResource( - * type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false } + * type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false }, * ); * * // Run a function in the execution context of the resource. This will @@ -263,9 +271,6 @@ declare module 'async_hooks' { constructor(type: string, triggerAsyncId?: number | AsyncResourceOptions); /** * Binds the given function to the current execution context. - * - * The returned function will have an `asyncResource` property referencing - * the `AsyncResource` to which the function is bound. * @since v14.8.0, v12.19.0 * @param fn The function to bind to the current execution context. * @param type An optional name to associate with the underlying `AsyncResource`. @@ -273,23 +278,14 @@ declare module 'async_hooks' { static bind any, ThisArg>( fn: Func, type?: string, - thisArg?: ThisArg - ): Func & { - asyncResource: AsyncResource; - }; + thisArg?: ThisArg, + ): Func; /** * Binds the given function to execute to this `AsyncResource`'s scope. - * - * The returned function will have an `asyncResource` property referencing - * the `AsyncResource` to which the function is bound. * @since v14.8.0, v12.19.0 * @param fn The function to bind to the current `AsyncResource`. */ - bind any>( - fn: Func - ): Func & { - asyncResource: AsyncResource; - }; + bind any>(fn: Func): Func; /** * Call the provided function with the provided arguments in the execution context * of the async resource. This will establish the context, trigger the AsyncHooks @@ -300,7 +296,11 @@ declare module 'async_hooks' { * @param thisArg The receiver to be used for the function call. * @param args Optional arguments to pass to the function. */ - runInAsyncScope(fn: (this: This, ...args: any[]) => Result, thisArg?: This, ...args: any[]): Result; + runInAsyncScope( + fn: (this: This, ...args: any[]) => Result, + thisArg?: This, + ...args: any[] + ): Result; /** * Call all `destroy` hooks. This should only ever be called once. An error will * be thrown if it is called more than once. This **must** be manually called. If @@ -314,7 +314,6 @@ declare module 'async_hooks' { */ asyncId(): number; /** - * * @return The same `triggerAsyncId` that is passed to the `AsyncResource` constructor. */ triggerAsyncId(): number; @@ -322,17 +321,17 @@ declare module 'async_hooks' { /** * This class creates stores that stay coherent through asynchronous operations. * - * While you can create your own implementation on top of the `async_hooks` module,`AsyncLocalStorage` should be preferred as it is a performant and memory safe - * implementation that involves significant optimizations that are non-obvious to - * implement. + * While you can create your own implementation on top of the `node:async_hooks`module, `AsyncLocalStorage` should be preferred as it is a performant and memory + * safe implementation that involves significant optimizations that are non-obvious + * to implement. * * The following example uses `AsyncLocalStorage` to build a simple logger * that assigns IDs to incoming HTTP requests and includes them in messages * logged within each request. * * ```js - * import http from 'http'; - * import { AsyncLocalStorage } from 'async_hooks'; + * import http from 'node:http'; + * import { AsyncLocalStorage } from 'node:async_hooks'; * * const asyncLocalStorage = new AsyncLocalStorage(); * @@ -364,10 +363,48 @@ declare module 'async_hooks' { * * Each instance of `AsyncLocalStorage` maintains an independent storage context. * Multiple instances can safely exist simultaneously without risk of interfering - * with each other data. + * with each other's data. * @since v13.10.0, v12.17.0 */ class AsyncLocalStorage { + /** + * Binds the given function to the current execution context. + * @since v19.8.0 + * @experimental + * @param fn The function to bind to the current execution context. + * @return A new function that calls `fn` within the captured execution context. + */ + static bind any>(fn: Func): Func; + /** + * Captures the current execution context and returns a function that accepts a + * function as an argument. Whenever the returned function is called, it + * calls the function passed to it within the captured context. + * + * ```js + * const asyncLocalStorage = new AsyncLocalStorage(); + * const runInAsyncScope = asyncLocalStorage.run(123, () => AsyncLocalStorage.snapshot()); + * const result = asyncLocalStorage.run(321, () => runInAsyncScope(() => asyncLocalStorage.getStore())); + * console.log(result); // returns 123 + * ``` + * + * AsyncLocalStorage.snapshot() can replace the use of AsyncResource for simple + * async context tracking purposes, for example: + * + * ```js + * class Foo { + * #runInAsyncScope = AsyncLocalStorage.snapshot(); + * + * get() { return this.#runInAsyncScope(() => asyncLocalStorage.getStore()); } + * } + * + * const foo = asyncLocalStorage.run(123, () => new Foo()); + * console.log(asyncLocalStorage.run(321, () => foo.get())); // returns 123 + * ``` + * @since v19.8.0 + * @experimental + * @return A new function with the signature `(fn: (...args) : R, ...args) : R`. + */ + static snapshot(): (fn: (...args: TArgs) => R, ...args: TArgs) => R; /** * Disables the instance of `AsyncLocalStorage`. All subsequent calls * to `asyncLocalStorage.getStore()` will return `undefined` until`asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()` is called again. @@ -395,8 +432,9 @@ declare module 'async_hooks' { getStore(): T | undefined; /** * Runs a function synchronously within a context and returns its - * return value. The store is not accessible outside of the callback function or - * the asynchronous operations created within the callback. + * return value. The store is not accessible outside of the callback function. + * The store is accessible to any asynchronous operations created within the + * callback. * * The optional `args` are passed to the callback function. * @@ -410,6 +448,9 @@ declare module 'async_hooks' { * try { * asyncLocalStorage.run(store, () => { * asyncLocalStorage.getStore(); // Returns the store object + * setTimeout(() => { + * asyncLocalStorage.getStore(); // Returns the store object + * }, 200); * throw new Error(); * }); * } catch (e) { @@ -419,6 +460,7 @@ declare module 'async_hooks' { * ``` * @since v13.10.0, v12.17.0 */ + run(store: T, callback: () => R): R; run(store: T, callback: (...args: TArgs) => R, ...args: TArgs): R; /** * Runs a function synchronously outside of a context and returns its @@ -492,6 +534,6 @@ declare module 'async_hooks' { enterWith(store: T): void; } } -declare module 'node:async_hooks' { - export * from 'async_hooks'; +declare module "node:async_hooks" { + export * from "async_hooks"; } diff --git a/node_modules/@types/node/buffer.d.ts b/node_modules/@types/node/buffer.d.ts old mode 100755 new mode 100644 index 1d9dd98..2fa2e74 --- a/node_modules/@types/node/buffer.d.ts +++ b/node_modules/@types/node/buffer.d.ts @@ -10,7 +10,7 @@ * recommended to explicitly reference it via an import or require statement. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Creates a zero-filled Buffer of length 10. * const buf1 = Buffer.alloc(10); @@ -41,11 +41,29 @@ * // Creates a Buffer containing the Latin-1 bytes [0x74, 0xe9, 0x73, 0x74]. * const buf7 = Buffer.from('tést', 'latin1'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/buffer.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/buffer.js) */ -declare module 'buffer' { - import { BinaryLike } from 'node:crypto'; - import { ReadableStream as WebReadableStream } from 'node:stream/web'; +declare module "buffer" { + import { BinaryLike } from "node:crypto"; + import { ReadableStream as WebReadableStream } from "node:stream/web"; + /** + * This function returns `true` if `input` contains only valid UTF-8-encoded data, + * including the case in which `input` is empty. + * + * Throws if the `input` is a detached array buffer. + * @since v19.4.0, v18.14.0 + * @param input The input to validate. + */ + export function isUtf8(input: Buffer | ArrayBuffer | NodeJS.TypedArray): boolean; + /** + * This function returns `true` if `input` contains only valid ASCII-encoded data, + * including the case in which `input` is empty. + * + * Throws if the `input` is a detached array buffer. + * @since v19.6.0, v18.15.0 + * @param input The input to validate. + */ + export function isAscii(input: Buffer | ArrayBuffer | NodeJS.TypedArray): boolean; export const INSPECT_MAX_BYTES: number; export const kMaxLength: number; export const kStringMaxLength: number; @@ -53,7 +71,16 @@ declare module 'buffer' { MAX_LENGTH: number; MAX_STRING_LENGTH: number; }; - export type TranscodeEncoding = 'ascii' | 'utf8' | 'utf16le' | 'ucs2' | 'latin1' | 'binary'; + export type TranscodeEncoding = + | "ascii" + | "utf8" + | "utf-8" + | "utf16le" + | "utf-16le" + | "ucs2" + | "ucs-2" + | "latin1" + | "binary"; /** * Re-encodes the given `Buffer` or `Uint8Array` instance from one character * encoding to another. Returns a new `Buffer` instance. @@ -67,7 +94,7 @@ declare module 'buffer' { * sequence cannot be adequately represented in the target encoding. For instance: * * ```js - * import { Buffer, transcode } from 'buffer'; + * import { Buffer, transcode } from 'node:buffer'; * * const newBuf = transcode(Buffer.from('€'), 'utf8', 'ascii'); * console.log(newBuf.toString('ascii')); @@ -84,7 +111,7 @@ declare module 'buffer' { export function transcode(source: Uint8Array, fromEnc: TranscodeEncoding, toEnc: TranscodeEncoding): Buffer; export const SlowBuffer: { /** @deprecated since v6.0.0, use `Buffer.allocUnsafeSlow()` */ - new (size: number): Buffer; + new(size: number): Buffer; prototype: Buffer; }; /** @@ -114,18 +141,17 @@ declare module 'buffer' { /** * A [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) encapsulates immutable, raw data that can be safely shared across * multiple worker threads. - * @since v15.7.0 - * @experimental + * @since v15.7.0, v14.18.0 */ export class Blob { /** * The total size of the `Blob` in bytes. - * @since v15.7.0 + * @since v15.7.0, v14.18.0 */ readonly size: number; /** * The content-type of the `Blob`. - * @since v15.7.0 + * @since v15.7.0, v14.18.0 */ readonly type: string; /** @@ -140,13 +166,13 @@ declare module 'buffer' { /** * Returns a promise that fulfills with an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) containing a copy of * the `Blob` data. - * @since v15.7.0 + * @since v15.7.0, v14.18.0 */ arrayBuffer(): Promise; /** * Creates and returns a new `Blob` containing a subset of this `Blob` objects * data. The original `Blob` is not altered. - * @since v15.7.0 + * @since v15.7.0, v14.18.0 * @param start The starting index. * @param end The ending index. * @param type The content-type for the new `Blob` @@ -155,25 +181,72 @@ declare module 'buffer' { /** * Returns a promise that fulfills with the contents of the `Blob` decoded as a * UTF-8 string. - * @since v15.7.0 + * @since v15.7.0, v14.18.0 */ text(): Promise; /** - * Returns a new (WHATWG) `ReadableStream` that allows the content of the `Blob` to be read. + * Returns a new `ReadableStream` that allows the content of the `Blob` to be read. * @since v16.7.0 */ stream(): WebReadableStream; } + export interface FileOptions { + /** + * One of either `'transparent'` or `'native'`. When set to `'native'`, line endings in string source parts will be + * converted to the platform native line-ending as specified by `require('node:os').EOL`. + */ + endings?: "native" | "transparent"; + /** The File content-type. */ + type?: string; + /** The last modified date of the file. `Default`: Date.now(). */ + lastModified?: number; + } + /** + * A [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) provides information about files. + * @since v19.2.0, v18.13.0 + */ + export class File extends Blob { + constructor(sources: Array, fileName: string, options?: FileOptions); + /** + * The name of the `File`. + * @since v19.2.0, v18.13.0 + */ + readonly name: string; + /** + * The last modified date of the `File`. + * @since v19.2.0, v18.13.0 + */ + readonly lastModified: number; + } export import atob = globalThis.atob; export import btoa = globalThis.btoa; + import { Blob as NodeBlob } from "buffer"; + // This conditional type will be the existing global Blob in a browser, or + // the copy below in a Node environment. + type __Blob = typeof globalThis extends { onmessage: any; Blob: any } ? {} : NodeBlob; global { + namespace NodeJS { + export { BufferEncoding }; + } // Buffer class - type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex'; + type BufferEncoding = + | "ascii" + | "utf8" + | "utf-8" + | "utf16le" + | "utf-16le" + | "ucs2" + | "ucs-2" + | "base64" + | "base64url" + | "latin1" + | "binary" + | "hex"; type WithImplicitCoercion = | T | { - valueOf(): T; - }; + valueOf(): T; + }; /** * Raw data is stored in instances of the Buffer class. * A Buffer is similar to an array of integers but corresponds to a raw memory allocation outside the V8 heap. A Buffer cannot be resized. @@ -187,68 +260,75 @@ declare module 'buffer' { * @param encoding encoding to use, optional. Default is 'utf8' * @deprecated since v10.0.0 - Use `Buffer.from(string[, encoding])` instead. */ - new (str: string, encoding?: BufferEncoding): Buffer; + new(str: string, encoding?: BufferEncoding): Buffer; /** * Allocates a new buffer of {size} octets. * * @param size count of octets to allocate. * @deprecated since v10.0.0 - Use `Buffer.alloc()` instead (also see `Buffer.allocUnsafe()`). */ - new (size: number): Buffer; + new(size: number): Buffer; /** * Allocates a new buffer containing the given {array} of octets. * * @param array The octets to store. * @deprecated since v10.0.0 - Use `Buffer.from(array)` instead. */ - new (array: Uint8Array): Buffer; + new(array: Uint8Array): Buffer; /** * Produces a Buffer backed by the same allocated memory as * the given {ArrayBuffer}/{SharedArrayBuffer}. * - * * @param arrayBuffer The ArrayBuffer with which to share memory. * @deprecated since v10.0.0 - Use `Buffer.from(arrayBuffer[, byteOffset[, length]])` instead. */ - new (arrayBuffer: ArrayBuffer | SharedArrayBuffer): Buffer; + new(arrayBuffer: ArrayBuffer | SharedArrayBuffer): Buffer; /** * Allocates a new buffer containing the given {array} of octets. * * @param array The octets to store. * @deprecated since v10.0.0 - Use `Buffer.from(array)` instead. */ - new (array: ReadonlyArray): Buffer; + new(array: readonly any[]): Buffer; /** * Copies the passed {buffer} data onto a new {Buffer} instance. * * @param buffer The buffer to copy. * @deprecated since v10.0.0 - Use `Buffer.from(buffer)` instead. */ - new (buffer: Buffer): Buffer; + new(buffer: Buffer): Buffer; /** * Allocates a new `Buffer` using an `array` of bytes in the range `0` – `255`. * Array entries outside that range will be truncated to fit into it. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'. * const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); * ``` * + * If `array` is an `Array`\-like object (that is, one with a `length` property of + * type `number`), it is treated as if it is an array, unless it is a `Buffer` or + * a `Uint8Array`. This means all other `TypedArray` variants get treated as an`Array`. To create a `Buffer` from the bytes backing a `TypedArray`, use `Buffer.copyBytesFrom()`. + * * A `TypeError` will be thrown if `array` is not an `Array` or another type * appropriate for `Buffer.from()` variants. * * `Buffer.from(array)` and `Buffer.from(string)` may also use the internal`Buffer` pool like `Buffer.allocUnsafe()` does. * @since v5.10.0 */ - from(arrayBuffer: WithImplicitCoercion, byteOffset?: number, length?: number): Buffer; + from( + arrayBuffer: WithImplicitCoercion, + byteOffset?: number, + length?: number, + ): Buffer; /** * Creates a new Buffer using the passed {data} * @param data data to create a new Buffer */ - from(data: Uint8Array | ReadonlyArray): Buffer; - from(data: WithImplicitCoercion | string>): Buffer; + from(data: Uint8Array | readonly number[]): Buffer; + from(data: WithImplicitCoercion): Buffer; /** * Creates a new Buffer containing the given JavaScript string {str}. * If provided, the {encoding} parameter identifies the character encoding. @@ -258,9 +338,9 @@ declare module 'buffer' { str: | WithImplicitCoercion | { - [Symbol.toPrimitive](hint: 'string'): string; - }, - encoding?: BufferEncoding + [Symbol.toPrimitive](hint: "string"): string; + }, + encoding?: BufferEncoding, ): Buffer; /** * Creates a new Buffer using the passed {data} @@ -271,7 +351,7 @@ declare module 'buffer' { * Returns `true` if `obj` is a `Buffer`, `false` otherwise. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * Buffer.isBuffer(Buffer.alloc(10)); // true * Buffer.isBuffer(Buffer.from('foo')); // true @@ -287,7 +367,7 @@ declare module 'buffer' { * or `false` otherwise. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * console.log(Buffer.isEncoding('utf8')); * // Prints: true @@ -316,7 +396,7 @@ declare module 'buffer' { * string. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const str = '\u00bd + \u00bc = \u00be'; * @@ -334,7 +414,10 @@ declare module 'buffer' { * @param [encoding='utf8'] If `string` is a string, this is its encoding. * @return The number of bytes contained within `string`. */ - byteLength(string: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer, encoding?: BufferEncoding): number; + byteLength( + string: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer, + encoding?: BufferEncoding, + ): number; /** * Returns a new `Buffer` which is the result of concatenating all the `Buffer`instances in the `list` together. * @@ -348,7 +431,7 @@ declare module 'buffer' { * truncated to `totalLength`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Create a single `Buffer` from a list of three `Buffer` instances. * @@ -373,12 +456,29 @@ declare module 'buffer' { * @param list List of `Buffer` or {@link Uint8Array} instances to concatenate. * @param totalLength Total length of the `Buffer` instances in `list` when concatenated. */ - concat(list: ReadonlyArray, totalLength?: number): Buffer; + concat(list: readonly Uint8Array[], totalLength?: number): Buffer; + /** + * Copies the underlying memory of `view` into a new `Buffer`. + * + * ```js + * const u16 = new Uint16Array([0, 0xffff]); + * const buf = Buffer.copyBytesFrom(u16, 1, 1); + * u16[1] = 0; + * console.log(buf.length); // 2 + * console.log(buf[0]); // 255 + * console.log(buf[1]); // 255 + * ``` + * @since v19.8.0 + * @param view The {TypedArray} to copy. + * @param [offset=': 0'] The starting offset within `view`. + * @param [length=view.length - offset] The number of elements from `view` to copy. + */ + copyBytesFrom(view: NodeJS.TypedArray, offset?: number, length?: number): Buffer; /** * Compares `buf1` to `buf2`, typically for the purpose of sorting arrays of`Buffer` instances. This is equivalent to calling `buf1.compare(buf2)`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from('1234'); * const buf2 = Buffer.from('0123'); @@ -391,12 +491,12 @@ declare module 'buffer' { * @since v0.11.13 * @return Either `-1`, `0`, or `1`, depending on the result of the comparison. See `compare` for details. */ - compare(buf1: Uint8Array, buf2: Uint8Array): number; + compare(buf1: Uint8Array, buf2: Uint8Array): -1 | 0 | 1; /** * Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the`Buffer` will be zero-filled. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.alloc(5); * @@ -404,12 +504,12 @@ declare module 'buffer' { * // Prints: * ``` * - * If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_INVALID_ARG_VALUE` is thrown. + * If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_OUT_OF_RANGE` is thrown. * * If `fill` is specified, the allocated `Buffer` will be initialized by calling `buf.fill(fill)`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.alloc(5, 'a'); * @@ -421,7 +521,7 @@ declare module 'buffer' { * initialized by calling `buf.fill(fill, encoding)`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64'); * @@ -439,15 +539,15 @@ declare module 'buffer' { * @param [fill=0] A value to pre-fill the new `Buffer` with. * @param [encoding='utf8'] If `fill` is a string, this is its encoding. */ - alloc(size: number, fill?: string | Buffer | number, encoding?: BufferEncoding): Buffer; + alloc(size: number, fill?: string | Uint8Array | number, encoding?: BufferEncoding): Buffer; /** - * Allocates a new `Buffer` of `size` bytes. If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_INVALID_ARG_VALUE` is thrown. + * Allocates a new `Buffer` of `size` bytes. If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_OUT_OF_RANGE` is thrown. * * The underlying memory for `Buffer` instances created in this way is _not_ - * _initialized_. The contents of the newly created `Buffer` are unknown and_may contain sensitive data_. Use `Buffer.alloc()` instead to initialize`Buffer` instances with zeroes. + * _initialized_. The contents of the newly created `Buffer` are unknown and _may contain sensitive data_. Use `Buffer.alloc()` instead to initialize`Buffer` instances with zeroes. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(10); * @@ -463,9 +563,8 @@ declare module 'buffer' { * A `TypeError` will be thrown if `size` is not a number. * * The `Buffer` module pre-allocates an internal `Buffer` instance of - * size `Buffer.poolSize` that is used as a pool for the fast allocation of new`Buffer` instances created using `Buffer.allocUnsafe()`,`Buffer.from(array)`, `Buffer.concat()`, and the - * deprecated`new Buffer(size)` constructor only when `size` is less than or equal - * to `Buffer.poolSize >> 1` (floor of `Buffer.poolSize` divided by two). + * size `Buffer.poolSize` that is used as a pool for the fast allocation of new`Buffer` instances created using `Buffer.allocUnsafe()`, `Buffer.from(array)`, + * and `Buffer.concat()` only when `size` is less than`Buffer.poolSize >>> 1` (floor of `Buffer.poolSize` divided by two). * * Use of this pre-allocated internal memory pool is a key difference between * calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)`. @@ -478,15 +577,15 @@ declare module 'buffer' { */ allocUnsafe(size: number): Buffer; /** - * Allocates a new `Buffer` of `size` bytes. If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_INVALID_ARG_VALUE` is thrown. A zero-length `Buffer` is created - * if `size` is 0. + * Allocates a new `Buffer` of `size` bytes. If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_OUT_OF_RANGE` is thrown. A zero-length `Buffer` is created if + * `size` is 0. * * The underlying memory for `Buffer` instances created in this way is _not_ - * _initialized_. The contents of the newly created `Buffer` are unknown and_may contain sensitive data_. Use `buf.fill(0)` to initialize + * _initialized_. The contents of the newly created `Buffer` are unknown and _may contain sensitive data_. Use `buf.fill(0)` to initialize * such `Buffer` instances with zeroes. * * When using `Buffer.allocUnsafe()` to allocate new `Buffer` instances, - * allocations under 4 KB are sliced from a single pre-allocated `Buffer`. This + * allocations under 4 KiB are sliced from a single pre-allocated `Buffer`. This * allows applications to avoid the garbage collection overhead of creating many * individually allocated `Buffer` instances. This approach improves both * performance and memory usage by eliminating the need to track and clean up as @@ -498,7 +597,7 @@ declare module 'buffer' { * then copying out the relevant bits. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Need to keep around a few small chunks of memory. * const store = []; @@ -536,7 +635,7 @@ declare module 'buffer' { * written. However, partially encoded characters will not be written. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.alloc(256); * @@ -572,7 +671,7 @@ declare module 'buffer' { * as {@link constants.MAX_STRING_LENGTH}. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.allocUnsafe(26); * @@ -609,7 +708,7 @@ declare module 'buffer' { * In particular, `Buffer.from(buf.toJSON())` works like `Buffer.from(buf)`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]); * const json = JSON.stringify(buf); @@ -629,14 +728,14 @@ declare module 'buffer' { * @since v0.9.2 */ toJSON(): { - type: 'Buffer'; + type: "Buffer"; data: number[]; }; /** * Returns `true` if both `buf` and `otherBuffer` have exactly the same bytes,`false` otherwise. Equivalent to `buf.compare(otherBuffer) === 0`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from('ABC'); * const buf2 = Buffer.from('414243', 'hex'); @@ -660,7 +759,7 @@ declare module 'buffer' { * * `-1` is returned if `target` should come _after_`buf` when sorted. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from('ABC'); * const buf2 = Buffer.from('BCD'); @@ -684,7 +783,7 @@ declare module 'buffer' { * The optional `targetStart`, `targetEnd`, `sourceStart`, and `sourceEnd`arguments can be used to limit the comparison to specific ranges within `target`and `buf` respectively. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9]); * const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4]); @@ -705,7 +804,13 @@ declare module 'buffer' { * @param [sourceStart=0] The offset within `buf` at which to begin comparison. * @param [sourceEnd=buf.length] The offset within `buf` at which to end comparison (not inclusive). */ - compare(target: Uint8Array, targetStart?: number, targetEnd?: number, sourceStart?: number, sourceEnd?: number): number; + compare( + target: Uint8Array, + targetStart?: number, + targetEnd?: number, + sourceStart?: number, + sourceEnd?: number, + ): -1 | 0 | 1; /** * Copies data from a region of `buf` to a region in `target`, even if the `target`memory region overlaps with `buf`. * @@ -714,7 +819,7 @@ declare module 'buffer' { * different function arguments. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Create two `Buffer` instances. * const buf1 = Buffer.allocUnsafe(26); @@ -735,7 +840,7 @@ declare module 'buffer' { * ``` * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Create a `Buffer` and copy data from one region to an overlapping region * // within the same `Buffer`. @@ -764,13 +869,11 @@ declare module 'buffer' { * Returns a new `Buffer` that references the same memory as the original, but * offset and cropped by the `start` and `end` indices. * - * This is the same behavior as `buf.subarray()`. - * * This method is not compatible with the `Uint8Array.prototype.slice()`, * which is a superclass of `Buffer`. To copy the slice, use`Uint8Array.prototype.slice()`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('buffer'); * @@ -781,8 +884,17 @@ declare module 'buffer' { * * console.log(buf.toString()); * // Prints: buffer + * + * // With buf.slice(), the original buffer is modified. + * const notReallyCopiedBuf = buf.slice(); + * notReallyCopiedBuf[0]++; + * console.log(notReallyCopiedBuf.toString()); + * // Prints: cuffer + * console.log(buf.toString()); + * // Also prints: cuffer (!) * ``` * @since v0.3.0 + * @deprecated Use `subarray` instead. * @param [start=0] Where the new `Buffer` will start. * @param [end=buf.length] Where the new `Buffer` will end (not inclusive). */ @@ -799,7 +911,7 @@ declare module 'buffer' { * Modifying the new `Buffer` slice will modify the memory in the original `Buffer`because the allocated memory of the two objects overlap. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Create a `Buffer` with the ASCII alphabet, take a slice, and modify one byte * // from the original `Buffer`. @@ -826,7 +938,7 @@ declare module 'buffer' { * end of `buf` rather than the beginning. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('buffer'); * @@ -853,7 +965,7 @@ declare module 'buffer' { * `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -874,7 +986,7 @@ declare module 'buffer' { * `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -895,7 +1007,7 @@ declare module 'buffer' { * This function is also available under the `writeBigUint64BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -919,7 +1031,7 @@ declare module 'buffer' { * Writes `value` to `buf` at the specified `offset` as little-endian * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -948,7 +1060,7 @@ declare module 'buffer' { * This function is also available under the `writeUintLE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(6); * @@ -976,7 +1088,7 @@ declare module 'buffer' { * This function is also available under the `writeUintBE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(6); * @@ -1002,7 +1114,7 @@ declare module 'buffer' { * when `value` is anything other than a signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(6); * @@ -1023,7 +1135,7 @@ declare module 'buffer' { * signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(6); * @@ -1045,7 +1157,7 @@ declare module 'buffer' { * This function is also available under the `readBigUint64BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]); * @@ -1067,7 +1179,7 @@ declare module 'buffer' { * This function is also available under the `readBigUint64LE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]); * @@ -1108,7 +1220,7 @@ declare module 'buffer' { * This function is also available under the `readUintLE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]); * @@ -1132,7 +1244,7 @@ declare module 'buffer' { * This function is also available under the `readUintBE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]); * @@ -1156,7 +1268,7 @@ declare module 'buffer' { * supporting up to 48 bits of accuracy. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]); * @@ -1173,7 +1285,7 @@ declare module 'buffer' { * supporting up to 48 bits of accuracy. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]); * @@ -1195,7 +1307,7 @@ declare module 'buffer' { * This function is also available under the `readUint8` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([1, -2]); * @@ -1221,7 +1333,7 @@ declare module 'buffer' { * This function is also available under the `readUint16LE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56]); * @@ -1247,7 +1359,7 @@ declare module 'buffer' { * This function is also available under the `readUint16BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56]); * @@ -1271,7 +1383,7 @@ declare module 'buffer' { * This function is also available under the `readUint32LE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]); * @@ -1295,7 +1407,7 @@ declare module 'buffer' { * This function is also available under the `readUint32BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]); * @@ -1317,7 +1429,7 @@ declare module 'buffer' { * Integers read from a `Buffer` are interpreted as two's complement signed values. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([-1, 5]); * @@ -1338,7 +1450,7 @@ declare module 'buffer' { * Integers read from a `Buffer` are interpreted as two's complement signed values. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0, 5]); * @@ -1357,7 +1469,7 @@ declare module 'buffer' { * Integers read from a `Buffer` are interpreted as two's complement signed values. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0, 5]); * @@ -1374,7 +1486,7 @@ declare module 'buffer' { * Integers read from a `Buffer` are interpreted as two's complement signed values. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0, 0, 0, 5]); * @@ -1393,7 +1505,7 @@ declare module 'buffer' { * Integers read from a `Buffer` are interpreted as two's complement signed values. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0, 0, 0, 5]); * @@ -1408,7 +1520,7 @@ declare module 'buffer' { * Reads a 32-bit, little-endian float from `buf` at the specified `offset`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([1, 2, 3, 4]); * @@ -1425,7 +1537,7 @@ declare module 'buffer' { * Reads a 32-bit, big-endian float from `buf` at the specified `offset`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([1, 2, 3, 4]); * @@ -1440,7 +1552,7 @@ declare module 'buffer' { * Reads a 64-bit, little-endian double from `buf` at the specified `offset`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]); * @@ -1457,7 +1569,7 @@ declare module 'buffer' { * Reads a 64-bit, big-endian double from `buf` at the specified `offset`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]); * @@ -1474,7 +1586,7 @@ declare module 'buffer' { * byte order _in-place_. Throws `ERR_INVALID_BUFFER_SIZE` if `buf.length` is not a multiple of 2. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); * @@ -1496,7 +1608,7 @@ declare module 'buffer' { * between UTF-16 little-endian and UTF-16 big-endian: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('This is little-endian UTF-16', 'utf16le'); * buf.swap16(); // Convert to big-endian UTF-16 text. @@ -1510,7 +1622,7 @@ declare module 'buffer' { * byte order _in-place_. Throws `ERR_INVALID_BUFFER_SIZE` if `buf.length` is not a multiple of 4. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); * @@ -1536,7 +1648,7 @@ declare module 'buffer' { * Throws `ERR_INVALID_BUFFER_SIZE` if `buf.length` is not a multiple of 8. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); * @@ -1565,7 +1677,7 @@ declare module 'buffer' { * This function is also available under the `writeUint8` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1595,7 +1707,7 @@ declare module 'buffer' { * This function is also available under the `writeUint16LE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1623,7 +1735,7 @@ declare module 'buffer' { * This function is also available under the `writeUint16BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1651,7 +1763,7 @@ declare module 'buffer' { * This function is also available under the `writeUint32LE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1678,7 +1790,7 @@ declare module 'buffer' { * This function is also available under the `writeUint32BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1706,7 +1818,7 @@ declare module 'buffer' { * `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(2); * @@ -1729,7 +1841,7 @@ declare module 'buffer' { * The `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(2); * @@ -1751,7 +1863,7 @@ declare module 'buffer' { * The `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(2); * @@ -1773,7 +1885,7 @@ declare module 'buffer' { * The `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1795,7 +1907,7 @@ declare module 'buffer' { * The `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1815,7 +1927,7 @@ declare module 'buffer' { * undefined when `value` is anything other than a JavaScript number. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1835,7 +1947,7 @@ declare module 'buffer' { * undefined when `value` is anything other than a JavaScript number. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1855,7 +1967,7 @@ declare module 'buffer' { * other than a JavaScript number. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -1875,7 +1987,7 @@ declare module 'buffer' { * other than a JavaScript number. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -1895,7 +2007,7 @@ declare module 'buffer' { * the entire `buf` will be filled: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Fill a `Buffer` with the ASCII character 'h'. * @@ -1903,6 +2015,12 @@ declare module 'buffer' { * * console.log(b.toString()); * // Prints: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh + * + * // Fill a buffer with empty string + * const c = Buffer.allocUnsafe(5).fill(''); + * + * console.log(c.fill('')); + * // Prints: * ``` * * `value` is coerced to a `uint32` value if it is not a string, `Buffer`, or @@ -1913,7 +2031,7 @@ declare module 'buffer' { * then only the bytes of that character that fit into `buf` are written: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Fill a `Buffer` with character that takes up two bytes in UTF-8. * @@ -1925,7 +2043,7 @@ declare module 'buffer' { * fill data remains, an exception is thrown: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(5); * @@ -1937,7 +2055,7 @@ declare module 'buffer' { * // Throws an exception. * ``` * @since v0.5.0 - * @param value The value with which to fill `buf`. + * @param value The value with which to fill `buf`. Empty value (string, Uint8Array, Buffer) is coerced to `0`. * @param [offset=0] Number of bytes to skip before starting to fill `buf`. * @param [end=buf.length] Where to stop filling `buf` (not inclusive). * @param [encoding='utf8'] The encoding for `value` if `value` is a string. @@ -1949,12 +2067,12 @@ declare module 'buffer' { * * * a string, `value` is interpreted according to the character encoding in`encoding`. * * a `Buffer` or [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array), `value` will be used in its entirety. - * To compare a partial `Buffer`, use `buf.slice()`. + * To compare a partial `Buffer`, use `buf.subarray`. * * a number, `value` will be interpreted as an unsigned 8-bit integer * value between `0` and `255`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('this is a buffer'); * @@ -1987,7 +2105,7 @@ declare module 'buffer' { * behavior matches [`String.prototype.indexOf()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf). * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const b = Buffer.from('abcdef'); * @@ -2018,7 +2136,7 @@ declare module 'buffer' { * rather than the first occurrence. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('this buffer is a buffer'); * @@ -2053,7 +2171,7 @@ declare module 'buffer' { * This behavior matches [`String.prototype.lastIndexOf()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/lastIndexOf). * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const b = Buffer.from('abcdef'); * @@ -2086,7 +2204,7 @@ declare module 'buffer' { * of `buf`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Log the entire contents of a `Buffer`. * @@ -2110,7 +2228,7 @@ declare module 'buffer' { * Equivalent to `buf.indexOf() !== -1`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('this is a buffer'); * @@ -2140,7 +2258,7 @@ declare module 'buffer' { * Creates and returns an [iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) of `buf` keys (indices). * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('buffer'); * @@ -2163,7 +2281,7 @@ declare module 'buffer' { * called automatically when a `Buffer` is used in a `for..of` statement. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('buffer'); * @@ -2205,8 +2323,8 @@ declare module 'buffer' { * **binary data and predate the introduction of typed arrays in JavaScript.** * **For code running using Node.js APIs, converting between base64-encoded strings** * **and binary data should be performed using `Buffer.from(str, 'base64')` and`buf.toString('base64')`.** - * @since v15.13.0 - * @deprecated Use `Buffer.from(data, 'base64')` instead. + * @since v15.13.0, v14.17.0 + * @legacy Use `Buffer.from(data, 'base64')` instead. * @param data The Base64-encoded input string. */ function atob(data: string): string; @@ -2221,13 +2339,24 @@ declare module 'buffer' { * **binary data and predate the introduction of typed arrays in JavaScript.** * **For code running using Node.js APIs, converting between base64-encoded strings** * **and binary data should be performed using `Buffer.from(str, 'base64')` and`buf.toString('base64')`.** - * @since v15.13.0 - * @deprecated Use `buf.toString('base64')` instead. + * @since v15.13.0, v14.17.0 + * @legacy Use `buf.toString('base64')` instead. * @param data An ASCII (Latin1) string. */ function btoa(data: string): string; + interface Blob extends __Blob {} + /** + * `Blob` class is a global reference for `require('node:buffer').Blob` + * https://nodejs.org/api/buffer.html#class-blob + * @since v18.0.0 + */ + var Blob: typeof globalThis extends { + onmessage: any; + Blob: infer T; + } ? T + : typeof NodeBlob; } } -declare module 'node:buffer' { - export * from 'buffer'; +declare module "node:buffer" { + export * from "buffer"; } diff --git a/node_modules/@types/node/child_process.d.ts b/node_modules/@types/node/child_process.d.ts old mode 100755 new mode 100644 index d383145..a97532b --- a/node_modules/@types/node/child_process.d.ts +++ b/node_modules/@types/node/child_process.d.ts @@ -1,10 +1,10 @@ /** - * The `child_process` module provides the ability to spawn subprocesses in + * The `node:child_process` module provides the ability to spawn subprocesses in * a manner that is similar, but not identical, to [`popen(3)`](http://man7.org/linux/man-pages/man3/popen.3.html). This capability * is primarily provided by the {@link spawn} function: * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const ls = spawn('ls', ['-lh', '/usr']); * * ls.stdout.on('data', (data) => { @@ -28,8 +28,11 @@ * identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }`option if the output will not be consumed. * * The command lookup is performed using the `options.env.PATH` environment - * variable if it is in the `options` object. Otherwise, `process.env.PATH` is - * used. + * variable if `env` is in the `options` object. Otherwise, `process.env.PATH` is + * used. If `options.env` is set without `PATH`, lookup on Unix is performed + * on a default search path search of `/usr/bin:/bin` (see your operating system's + * manual for execvpe/execvp), on Windows the current processes environment + * variable `PATH` is used. * * On Windows, environment variables are case-insensitive. Node.js * lexicographically sorts the `env` keys and uses the first one that @@ -41,8 +44,8 @@ * without blocking the Node.js event loop. The {@link spawnSync} function provides equivalent functionality in a synchronous manner that blocks * the event loop until the spawned process either exits or is terminated. * - * For convenience, the `child_process` module provides a handful of synchronous - * and asynchronous alternatives to {@link spawn} and {@link spawnSync}. Each of these alternatives are implemented on + * For convenience, the `node:child_process` module provides a handful of + * synchronous and asynchronous alternatives to {@link spawn} and {@link spawnSync}. Each of these alternatives are implemented on * top of {@link spawn} or {@link spawnSync}. * * * {@link exec}: spawns a shell and runs a command within that @@ -60,14 +63,14 @@ * For certain use cases, such as automating shell scripts, the `synchronous counterparts` may be more convenient. In many cases, however, * the synchronous methods can have significant impact on performance due to * stalling the event loop while spawned processes complete. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/child_process.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/child_process.js) */ -declare module 'child_process' { - import { ObjectEncodingOptions } from 'node:fs'; - import { EventEmitter, Abortable } from 'node:events'; - import * as net from 'node:net'; - import { Writable, Readable, Stream, Pipe } from 'node:stream'; - import { URL } from 'node:url'; +declare module "child_process" { + import { ObjectEncodingOptions } from "node:fs"; + import { Abortable, EventEmitter } from "node:events"; + import * as net from "node:net"; + import { Pipe, Readable, Stream, Writable } from "node:stream"; + import { URL } from "node:url"; type Serializable = string | object | number | boolean | bigint; type SendHandle = net.Socket | net.Server; /** @@ -91,8 +94,7 @@ declare module 'child_process' { * `subprocess.stdin` is an alias for `subprocess.stdio[0]`. Both properties will * refer to the same value. * - * The `subprocess.stdin` property can be `undefined` if the child process could - * not be successfully spawned. + * The `subprocess.stdin` property can be `null` or `undefined`if the child process could not be successfully spawned. * @since v0.1.90 */ stdin: Writable | null; @@ -106,7 +108,7 @@ declare module 'child_process' { * refer to the same value. * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * * const subprocess = spawn('ls'); * @@ -115,8 +117,7 @@ declare module 'child_process' { * }); * ``` * - * The `subprocess.stdout` property can be `null` if the child process could - * not be successfully spawned. + * The `subprocess.stdout` property can be `null` or `undefined`if the child process could not be successfully spawned. * @since v0.1.90 */ stdout: Readable | null; @@ -129,14 +130,13 @@ declare module 'child_process' { * `subprocess.stderr` is an alias for `subprocess.stdio[2]`. Both properties will * refer to the same value. * - * The `subprocess.stderr` property can be `null` if the child process could - * not be successfully spawned. + * The `subprocess.stderr` property can be `null` or `undefined`if the child process could not be successfully spawned. * @since v0.1.90 */ stderr: Readable | null; /** * The `subprocess.channel` property is a reference to the child's IPC channel. If - * no IPC channel currently exists, this property is `undefined`. + * no IPC channel exists, this property is `undefined`. * @since v7.1.0 */ readonly channel?: Pipe | null | undefined; @@ -151,16 +151,16 @@ declare module 'child_process' { * in the array are `null`. * * ```js - * const assert = require('assert'); - * const fs = require('fs'); - * const child_process = require('child_process'); + * const assert = require('node:assert'); + * const fs = require('node:fs'); + * const child_process = require('node:child_process'); * * const subprocess = child_process.spawn('ls', { * stdio: [ * 0, // Use parent's stdin for child. * 'pipe', // Pipe child's stdout to parent. * fs.openSync('err.out', 'w'), // Direct child's stderr to a file. - * ] + * ], * }); * * assert.strictEqual(subprocess.stdio[0], null); @@ -186,7 +186,7 @@ declare module 'child_process' { // stderr Readable | Writable | null | undefined, // extra - Readable | Writable | null | undefined // extra + Readable | Writable | null | undefined, // extra ]; /** * The `subprocess.killed` property indicates whether the child process @@ -201,7 +201,7 @@ declare module 'child_process' { * emitted. * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const grep = spawn('grep', ['ssh']); * * console.log(`Spawned child pid: ${grep.pid}`); @@ -248,7 +248,7 @@ declare module 'child_process' { * returns `true` if [`kill(2)`](http://man7.org/linux/man-pages/man2/kill.2.html) succeeds, and `false` otherwise. * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const grep = spawn('grep', ['ssh']); * * grep.on('close', (code, signal) => { @@ -281,7 +281,7 @@ declare module 'child_process' { * * ```js * 'use strict'; - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * * const subprocess = spawn( * 'sh', @@ -291,8 +291,8 @@ declare module 'child_process' { * console.log(process.pid, 'is alive') * }, 500);"`, * ], { - * stdio: ['inherit', 'inherit', 'inherit'] - * } + * stdio: ['inherit', 'inherit', 'inherit'], + * }, * ); * * setTimeout(() => { @@ -302,6 +302,11 @@ declare module 'child_process' { * @since v0.1.90 */ kill(signal?: NodeJS.Signals | number): boolean; + /** + * Calls {@link ChildProcess.kill} with `'SIGTERM'`. + * @since v20.5.0 + */ + [Symbol.dispose](): void; /** * When an IPC channel has been established between the parent and child ( * i.e. when using {@link fork}), the `subprocess.send()` method can @@ -314,7 +319,7 @@ declare module 'child_process' { * For example, in the parent script: * * ```js - * const cp = require('child_process'); + * const cp = require('node:child_process'); * const n = cp.fork(`${__dirname}/sub.js`); * * n.on('message', (m) => { @@ -368,10 +373,10 @@ declare module 'child_process' { * a TCP server object to the child process as illustrated in the example below: * * ```js - * const subprocess = require('child_process').fork('subprocess.js'); + * const subprocess = require('node:child_process').fork('subprocess.js'); * * // Open up the server object and send the handle. - * const server = require('net').createServer(); + * const server = require('node:net').createServer(); * server.on('connection', (socket) => { * socket.end('handled by parent'); * }); @@ -395,10 +400,9 @@ declare module 'child_process' { * Once the server is now shared between the parent and child, some connections * can be handled by the parent and some by the child. * - * While the example above uses a server created using the `net` module, `dgram`module servers use exactly the same workflow with the exceptions of listening on - * a `'message'` event instead of `'connection'` and using `server.bind()` instead - * of `server.listen()`. This is, however, currently only supported on Unix - * platforms. + * While the example above uses a server created using the `node:net` module,`node:dgram` module servers use exactly the same workflow with the exceptions of + * listening on a `'message'` event instead of `'connection'` and using`server.bind()` instead of `server.listen()`. This is, however, only + * supported on Unix platforms. * * #### Example: sending a socket object * @@ -407,13 +411,13 @@ declare module 'child_process' { * handle connections with "normal" or "special" priority: * * ```js - * const { fork } = require('child_process'); + * const { fork } = require('node:child_process'); * const normal = fork('subprocess.js', ['normal']); * const special = fork('subprocess.js', ['special']); * * // Open up the server and send sockets to child. Use pauseOnConnect to prevent * // the sockets from being read before they are sent to the child process. - * const server = require('net').createServer({ pauseOnConnect: true }); + * const server = require('node:net').createServer({ pauseOnConnect: true }); * server.on('connection', (socket) => { * * // If this is special priority... @@ -454,7 +458,12 @@ declare module 'child_process' { */ send(message: Serializable, callback?: (error: Error | null) => void): boolean; send(message: Serializable, sendHandle?: SendHandle, callback?: (error: Error | null) => void): boolean; - send(message: Serializable, sendHandle?: SendHandle, options?: MessageOptions, callback?: (error: Error | null) => void): boolean; + send( + message: Serializable, + sendHandle?: SendHandle, + options?: MessageOptions, + callback?: (error: Error | null) => void, + ): boolean; /** * Closes the IPC channel between parent and child, allowing the child to exit * gracefully once there are no other connections keeping it alive. After calling @@ -479,11 +488,11 @@ declare module 'child_process' { * the child and the parent. * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * * const subprocess = spawn(process.argv[0], ['child_program.js'], { * detached: true, - * stdio: 'ignore' + * stdio: 'ignore', * }); * * subprocess.unref(); @@ -497,11 +506,11 @@ declare module 'child_process' { * to wait for the child to exit before exiting itself. * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * * const subprocess = spawn(process.argv[0], ['child_program.js'], { * detached: true, - * stdio: 'ignore' + * stdio: 'ignore', * }); * * subprocess.unref(); @@ -520,47 +529,53 @@ declare module 'child_process' { * 6. spawn */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - addListener(event: 'disconnect', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - addListener(event: 'message', listener: (message: Serializable, sendHandle: SendHandle) => void): this; - addListener(event: 'spawn', listener: () => void): this; + addListener(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + addListener(event: "disconnect", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + addListener(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this; + addListener(event: "spawn", listener: () => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close', code: number | null, signal: NodeJS.Signals | null): boolean; - emit(event: 'disconnect'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'exit', code: number | null, signal: NodeJS.Signals | null): boolean; - emit(event: 'message', message: Serializable, sendHandle: SendHandle): boolean; - emit(event: 'spawn', listener: () => void): boolean; + emit(event: "close", code: number | null, signal: NodeJS.Signals | null): boolean; + emit(event: "disconnect"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "exit", code: number | null, signal: NodeJS.Signals | null): boolean; + emit(event: "message", message: Serializable, sendHandle: SendHandle): boolean; + emit(event: "spawn", listener: () => void): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - on(event: 'disconnect', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - on(event: 'message', listener: (message: Serializable, sendHandle: SendHandle) => void): this; - on(event: 'spawn', listener: () => void): this; + on(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + on(event: "disconnect", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + on(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this; + on(event: "spawn", listener: () => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - once(event: 'disconnect', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - once(event: 'message', listener: (message: Serializable, sendHandle: SendHandle) => void): this; - once(event: 'spawn', listener: () => void): this; + once(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + once(event: "disconnect", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + once(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this; + once(event: "spawn", listener: () => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - prependListener(event: 'disconnect', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - prependListener(event: 'message', listener: (message: Serializable, sendHandle: SendHandle) => void): this; - prependListener(event: 'spawn', listener: () => void): this; + prependListener(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + prependListener(event: "disconnect", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + prependListener(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this; + prependListener(event: "spawn", listener: () => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - prependOnceListener(event: 'disconnect', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - prependOnceListener(event: 'message', listener: (message: Serializable, sendHandle: SendHandle) => void): this; - prependOnceListener(event: 'spawn', listener: () => void): this; + prependOnceListener( + event: "close", + listener: (code: number | null, signal: NodeJS.Signals | null) => void, + ): this; + prependOnceListener(event: "disconnect", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener( + event: "exit", + listener: (code: number | null, signal: NodeJS.Signals | null) => void, + ): this; + prependOnceListener(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this; + prependOnceListener(event: "spawn", listener: () => void): this; } // return this object when stdio option is undefined or not specified interface ChildProcessWithoutNullStreams extends ChildProcess { @@ -574,11 +589,13 @@ declare module 'child_process' { // stderr Readable | Writable | null | undefined, // extra, no modification - Readable | Writable | null | undefined // extra, no modification + Readable | Writable | null | undefined, // extra, no modification ]; } // return this object when stdio option is a tuple of 3 - interface ChildProcessByStdio extends ChildProcess { + interface ChildProcessByStdio + extends ChildProcess + { stdin: I; stdout: O; stderr: E; @@ -588,15 +605,15 @@ declare module 'child_process' { E, Readable | Writable | null | undefined, // extra, no modification - Readable | Writable | null | undefined // extra, no modification + Readable | Writable | null | undefined, // extra, no modification ]; } interface MessageOptions { keepOpen?: boolean | undefined; } - type IOType = 'overlapped' | 'pipe' | 'ignore' | 'inherit'; - type StdioOptions = IOType | Array; - type SerializationType = 'json' | 'advanced'; + type IOType = "overlapped" | "pipe" | "ignore" | "inherit"; + type StdioOptions = IOType | Array; + type SerializationType = "json" | "advanced"; interface MessagingOptions extends Abortable { /** * Specify the kind of serialization used for sending messages between processes. @@ -621,7 +638,7 @@ declare module 'child_process' { } interface CommonOptions extends ProcessEnvOptions { /** - * @default true + * @default false */ windowsHide?: boolean | undefined; /** @@ -631,6 +648,15 @@ declare module 'child_process' { } interface CommonSpawnOptions extends CommonOptions, MessagingOptions, Abortable { argv0?: string | undefined; + /** + * Can be set to 'pipe', 'inherit', 'overlapped', or 'ignore', or an array of these strings. + * If passed as an array, the first element is used for `stdin`, the second for + * `stdout`, and the third for `stderr`. A fourth element can be used to + * specify the `stdio` behavior beyond the standard streams. See + * {@link ChildProcess.stdio} for more information. + * + * @default 'pipe' + */ stdio?: StdioOptions | undefined; shell?: boolean | string | undefined; windowsVerbatimArguments?: boolean | undefined; @@ -641,10 +667,14 @@ declare module 'child_process' { interface SpawnOptionsWithoutStdio extends SpawnOptions { stdio?: StdioPipeNamed | StdioPipe[] | undefined; } - type StdioNull = 'inherit' | 'ignore' | Stream; - type StdioPipeNamed = 'pipe' | 'overlapped'; + type StdioNull = "inherit" | "ignore" | Stream; + type StdioPipeNamed = "pipe" | "overlapped"; type StdioPipe = undefined | null | StdioPipeNamed; - interface SpawnOptionsWithStdioTuple extends SpawnOptions { + interface SpawnOptionsWithStdioTuple< + Stdin extends StdioNull | StdioPipe, + Stdout extends StdioNull | StdioPipe, + Stderr extends StdioNull | StdioPipe, + > extends SpawnOptions { stdio: [Stdin, Stdout, Stderr]; } /** @@ -660,7 +690,7 @@ declare module 'child_process' { * ```js * const defaults = { * cwd: undefined, - * env: process.env + * env: process.env, * }; * ``` * @@ -679,7 +709,7 @@ declare module 'child_process' { * exit code: * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const ls = spawn('ls', ['-lh', '/usr']); * * ls.stdout.on('data', (data) => { @@ -698,7 +728,7 @@ declare module 'child_process' { * Example: A very elaborate way to run `ps ax | grep ssh` * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const ps = spawn('ps', ['ax']); * const grep = spawn('grep', ['ssh']); * @@ -735,7 +765,7 @@ declare module 'child_process' { * Example of checking for failed `spawn`: * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const subprocess = spawn('bad_command'); * * subprocess.on('error', (err) => { @@ -746,14 +776,14 @@ declare module 'child_process' { * Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process * title while others (Windows, SunOS) will use `command`. * - * Node.js currently overwrites `argv[0]` with `process.execPath` on startup, so`process.argv[0]` in a Node.js child process will not match the `argv0`parameter passed to `spawn` from the parent, - * retrieve it with the`process.argv0` property instead. + * Node.js overwrites `argv[0]` with `process.execPath` on startup, so`process.argv[0]` in a Node.js child process will not match the `argv0`parameter passed to `spawn` from the parent. Retrieve + * it with the`process.argv0` property instead. * * If the `signal` option is enabled, calling `.abort()` on the corresponding`AbortController` is similar to calling `.kill()` on the child process except * the error passed to the callback will be an `AbortError`: * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const controller = new AbortController(); * const { signal } = controller; * const grep = spawn('grep', ['ssh'], { signal }); @@ -767,26 +797,86 @@ declare module 'child_process' { * @param args List of string arguments. */ function spawn(command: string, options?: SpawnOptionsWithoutStdio): ChildProcessWithoutNullStreams; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; function spawn(command: string, options: SpawnOptions): ChildProcess; // overloads of spawn with 'args' - function spawn(command: string, args?: ReadonlyArray, options?: SpawnOptionsWithoutStdio): ChildProcessWithoutNullStreams; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptions): ChildProcess; + function spawn( + command: string, + args?: readonly string[], + options?: SpawnOptionsWithoutStdio, + ): ChildProcessWithoutNullStreams; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn(command: string, args: readonly string[], options: SpawnOptions): ChildProcess; interface ExecOptions extends CommonOptions { shell?: string | undefined; signal?: AbortSignal | undefined; @@ -812,7 +902,7 @@ declare module 'child_process' { * need to be dealt with accordingly: * * ```js - * const { exec } = require('child_process'); + * const { exec } = require('node:child_process'); * * exec('"/path/to/test file/test.sh" arg1 arg2'); * // Double quotes are used so that the space in the path is not interpreted as @@ -838,7 +928,7 @@ declare module 'child_process' { * encoding, `Buffer` objects will be passed to the callback instead. * * ```js - * const { exec } = require('child_process'); + * const { exec } = require('node:child_process'); * exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => { * if (error) { * console.error(`exec error: ${error}`); @@ -863,8 +953,8 @@ declare module 'child_process' { * callback, but with two additional properties `stdout` and `stderr`. * * ```js - * const util = require('util'); - * const exec = util.promisify(require('child_process').exec); + * const util = require('node:util'); + * const exec = util.promisify(require('node:child_process').exec); * * async function lsExample() { * const { stdout, stderr } = await exec('ls'); @@ -878,11 +968,11 @@ declare module 'child_process' { * the error passed to the callback will be an `AbortError`: * * ```js - * const { exec } = require('child_process'); + * const { exec } = require('node:child_process'); * const controller = new AbortController(); * const { signal } = controller; * const child = exec('grep ssh', { signal }, (error) => { - * console.log(error); // an AbortError + * console.error(error); // an AbortError * }); * controller.abort(); * ``` @@ -890,14 +980,17 @@ declare module 'child_process' { * @param command The command to run, with space-separated arguments. * @param callback called with the output when process terminates. */ - function exec(command: string, callback?: (error: ExecException | null, stdout: string, stderr: string) => void): ChildProcess; + function exec( + command: string, + callback?: (error: ExecException | null, stdout: string, stderr: string) => void, + ): ChildProcess; // `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`. function exec( command: string, options: { - encoding: 'buffer' | null; + encoding: "buffer" | null; } & ExecOptions, - callback?: (error: ExecException | null, stdout: Buffer, stderr: Buffer) => void + callback?: (error: ExecException | null, stdout: Buffer, stderr: Buffer) => void, ): ChildProcess; // `options` with well known `encoding` means stdout/stderr are definitely `string`. function exec( @@ -905,7 +998,7 @@ declare module 'child_process' { options: { encoding: BufferEncoding; } & ExecOptions, - callback?: (error: ExecException | null, stdout: string, stderr: string) => void + callback?: (error: ExecException | null, stdout: string, stderr: string) => void, ): ChildProcess; // `options` with an `encoding` whose type is `string` means stdout/stderr could either be `Buffer` or `string`. // There is no guarantee the `encoding` is unknown as `string` is a superset of `BufferEncoding`. @@ -914,15 +1007,19 @@ declare module 'child_process' { options: { encoding: BufferEncoding; } & ExecOptions, - callback?: (error: ExecException | null, stdout: string | Buffer, stderr: string | Buffer) => void + callback?: (error: ExecException | null, stdout: string | Buffer, stderr: string | Buffer) => void, ): ChildProcess; // `options` without an `encoding` means stdout/stderr are definitely `string`. - function exec(command: string, options: ExecOptions, callback?: (error: ExecException | null, stdout: string, stderr: string) => void): ChildProcess; + function exec( + command: string, + options: ExecOptions, + callback?: (error: ExecException | null, stdout: string, stderr: string) => void, + ): ChildProcess; // fallback if nothing else matches. Worst case is always `string | Buffer`. function exec( command: string, options: (ObjectEncodingOptions & ExecOptions) | undefined | null, - callback?: (error: ExecException | null, stdout: string | Buffer, stderr: string | Buffer) => void + callback?: (error: ExecException | null, stdout: string | Buffer, stderr: string | Buffer) => void, ): ChildProcess; interface PromiseWithChild extends Promise { child: ChildProcess; @@ -935,8 +1032,8 @@ declare module 'child_process' { function __promisify__( command: string, options: { - encoding: 'buffer' | null; - } & ExecOptions + encoding: "buffer" | null; + } & ExecOptions, ): PromiseWithChild<{ stdout: Buffer; stderr: Buffer; @@ -945,21 +1042,21 @@ declare module 'child_process' { command: string, options: { encoding: BufferEncoding; - } & ExecOptions + } & ExecOptions, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( command: string, - options: ExecOptions + options: ExecOptions, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( command: string, - options?: (ObjectEncodingOptions & ExecOptions) | null + options?: (ObjectEncodingOptions & ExecOptions) | null, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; @@ -976,12 +1073,15 @@ declare module 'child_process' { encoding: BufferEncoding; } interface ExecFileOptionsWithBufferEncoding extends ExecFileOptions { - encoding: 'buffer' | null; + encoding: "buffer" | null; } interface ExecFileOptionsWithOtherEncoding extends ExecFileOptions { encoding: BufferEncoding; } - type ExecFileException = ExecException & NodeJS.ErrnoException; + type ExecFileException = + & Omit + & Omit + & { code?: string | number | undefined | null }; /** * The `child_process.execFile()` function is similar to {@link exec} except that it does not spawn a shell by default. Rather, the specified * executable `file` is spawned directly as a new process making it slightly more @@ -992,7 +1092,7 @@ declare module 'child_process' { * supported. * * ```js - * const { execFile } = require('child_process'); + * const { execFile } = require('node:child_process'); * const child = execFile('node', ['--version'], (error, stdout, stderr) => { * if (error) { * throw error; @@ -1015,8 +1115,8 @@ declare module 'child_process' { * callback, but with two additional properties `stdout` and `stderr`. * * ```js - * const util = require('util'); - * const execFile = util.promisify(require('child_process').execFile); + * const util = require('node:util'); + * const execFile = util.promisify(require('node:child_process').execFile); * async function getVersion() { * const { stdout } = await execFile('node', ['--version']); * console.log(stdout); @@ -1032,11 +1132,11 @@ declare module 'child_process' { * the error passed to the callback will be an `AbortError`: * * ```js - * const { execFile } = require('child_process'); + * const { execFile } = require('node:child_process'); * const controller = new AbortController(); * const { signal } = controller; * const child = execFile('node', ['--version'], { signal }, (error) => { - * console.log(error); // an AbortError + * console.error(error); // an AbortError * }); * controller.abort(); * ``` @@ -1046,56 +1146,92 @@ declare module 'child_process' { * @param callback Called with the output when process terminates. */ function execFile(file: string): ChildProcess; - function execFile(file: string, options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null): ChildProcess; - function execFile(file: string, args?: ReadonlyArray | null): ChildProcess; - function execFile(file: string, args: ReadonlyArray | undefined | null, options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null): ChildProcess; - // no `options` definitely means stdout/stderr are `string`. - function execFile(file: string, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void): ChildProcess; - function execFile(file: string, args: ReadonlyArray | undefined | null, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void): ChildProcess; - // `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`. - function execFile(file: string, options: ExecFileOptionsWithBufferEncoding, callback: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void): ChildProcess; function execFile( file: string, - args: ReadonlyArray | undefined | null, + options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, + ): ChildProcess; + function execFile(file: string, args?: readonly string[] | null): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, + ): ChildProcess; + // no `options` definitely means stdout/stderr are `string`. + function execFile( + file: string, + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + ): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + ): ChildProcess; + // `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`. + function execFile( + file: string, options: ExecFileOptionsWithBufferEncoding, - callback: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void + callback: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void, + ): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithBufferEncoding, + callback: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void, ): ChildProcess; // `options` with well known `encoding` means stdout/stderr are definitely `string`. - function execFile(file: string, options: ExecFileOptionsWithStringEncoding, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void): ChildProcess; function execFile( file: string, - args: ReadonlyArray | undefined | null, options: ExecFileOptionsWithStringEncoding, - callback: (error: ExecFileException | null, stdout: string, stderr: string) => void + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + ): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithStringEncoding, + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, ): ChildProcess; // `options` with an `encoding` whose type is `string` means stdout/stderr could either be `Buffer` or `string`. // There is no guarantee the `encoding` is unknown as `string` is a superset of `BufferEncoding`. - function execFile(file: string, options: ExecFileOptionsWithOtherEncoding, callback: (error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void): ChildProcess; function execFile( file: string, - args: ReadonlyArray | undefined | null, options: ExecFileOptionsWithOtherEncoding, - callback: (error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void + callback: (error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void, + ): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithOtherEncoding, + callback: (error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void, ): ChildProcess; // `options` without an `encoding` means stdout/stderr are definitely `string`. - function execFile(file: string, options: ExecFileOptions, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void): ChildProcess; function execFile( file: string, - args: ReadonlyArray | undefined | null, options: ExecFileOptions, - callback: (error: ExecFileException | null, stdout: string, stderr: string) => void + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + ): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + options: ExecFileOptions, + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, ): ChildProcess; // fallback if nothing else matches. Worst case is always `string | Buffer`. function execFile( file: string, options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, - callback: ((error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void) | undefined | null + callback: + | ((error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void) + | undefined + | null, ): ChildProcess; function execFile( file: string, - args: ReadonlyArray | undefined | null, + args: readonly string[] | undefined | null, options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, - callback: ((error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void) | undefined | null + callback: + | ((error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void) + | undefined + | null, ): ChildProcess; namespace execFile { function __promisify__(file: string): PromiseWithChild<{ @@ -1104,82 +1240,82 @@ declare module 'child_process' { }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null + args: readonly string[] | undefined | null, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( file: string, - options: ExecFileOptionsWithBufferEncoding + options: ExecFileOptionsWithBufferEncoding, ): PromiseWithChild<{ stdout: Buffer; stderr: Buffer; }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null, - options: ExecFileOptionsWithBufferEncoding + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithBufferEncoding, ): PromiseWithChild<{ stdout: Buffer; stderr: Buffer; }>; function __promisify__( file: string, - options: ExecFileOptionsWithStringEncoding + options: ExecFileOptionsWithStringEncoding, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null, - options: ExecFileOptionsWithStringEncoding + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithStringEncoding, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( file: string, - options: ExecFileOptionsWithOtherEncoding + options: ExecFileOptionsWithOtherEncoding, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null, - options: ExecFileOptionsWithOtherEncoding + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithOtherEncoding, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; }>; function __promisify__( file: string, - options: ExecFileOptions + options: ExecFileOptions, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null, - options: ExecFileOptions + args: readonly string[] | undefined | null, + options: ExecFileOptions, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( file: string, - options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null + options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null, - options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null + args: readonly string[] | undefined | null, + options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; @@ -1189,6 +1325,15 @@ declare module 'child_process' { execPath?: string | undefined; execArgv?: string[] | undefined; silent?: boolean | undefined; + /** + * Can be set to 'pipe', 'inherit', 'overlapped', or 'ignore', or an array of these strings. + * If passed as an array, the first element is used for `stdin`, the second for + * `stdout`, and the third for `stderr`. A fourth element can be used to + * specify the `stdio` behavior beyond the standard streams. See + * {@link ChildProcess.stdio} for more information. + * + * @default 'pipe' + */ stdio?: StdioOptions | undefined; detached?: boolean | undefined; windowsVerbatimArguments?: boolean | undefined; @@ -1228,7 +1373,7 @@ declare module 'child_process' { * console.log(`Hello from ${process.argv[2]}!`); * }, 1_000); * } else { - * const { fork } = require('child_process'); + * const { fork } = require('node:child_process'); * const controller = new AbortController(); * const { signal } = controller; * const child = fork(__filename, ['child'], { signal }); @@ -1243,17 +1388,17 @@ declare module 'child_process' { * @param args List of string arguments. */ function fork(modulePath: string, options?: ForkOptions): ChildProcess; - function fork(modulePath: string, args?: ReadonlyArray, options?: ForkOptions): ChildProcess; + function fork(modulePath: string, args?: readonly string[], options?: ForkOptions): ChildProcess; interface SpawnSyncOptions extends CommonSpawnOptions { input?: string | NodeJS.ArrayBufferView | undefined; maxBuffer?: number | undefined; - encoding?: BufferEncoding | 'buffer' | null | undefined; + encoding?: BufferEncoding | "buffer" | null | undefined; } interface SpawnSyncOptionsWithStringEncoding extends SpawnSyncOptions { encoding: BufferEncoding; } interface SpawnSyncOptionsWithBufferEncoding extends SpawnSyncOptions { - encoding?: 'buffer' | null | undefined; + encoding?: "buffer" | null | undefined; } interface SpawnSyncReturns { pid: number; @@ -1283,16 +1428,37 @@ declare module 'child_process' { function spawnSync(command: string, options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns; function spawnSync(command: string, options: SpawnSyncOptionsWithBufferEncoding): SpawnSyncReturns; function spawnSync(command: string, options?: SpawnSyncOptions): SpawnSyncReturns; - function spawnSync(command: string, args: ReadonlyArray): SpawnSyncReturns; - function spawnSync(command: string, args: ReadonlyArray, options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns; - function spawnSync(command: string, args: ReadonlyArray, options: SpawnSyncOptionsWithBufferEncoding): SpawnSyncReturns; - function spawnSync(command: string, args?: ReadonlyArray, options?: SpawnSyncOptions): SpawnSyncReturns; + function spawnSync(command: string, args: readonly string[]): SpawnSyncReturns; + function spawnSync( + command: string, + args: readonly string[], + options: SpawnSyncOptionsWithStringEncoding, + ): SpawnSyncReturns; + function spawnSync( + command: string, + args: readonly string[], + options: SpawnSyncOptionsWithBufferEncoding, + ): SpawnSyncReturns; + function spawnSync( + command: string, + args?: readonly string[], + options?: SpawnSyncOptions, + ): SpawnSyncReturns; interface CommonExecOptions extends CommonOptions { input?: string | NodeJS.ArrayBufferView | undefined; + /** + * Can be set to 'pipe', 'inherit, or 'ignore', or an array of these strings. + * If passed as an array, the first element is used for `stdin`, the second for + * `stdout`, and the third for `stderr`. A fourth element can be used to + * specify the `stdio` behavior beyond the standard streams. See + * {@link ChildProcess.stdio} for more information. + * + * @default 'pipe' + */ stdio?: StdioOptions | undefined; killSignal?: NodeJS.Signals | number | undefined; maxBuffer?: number | undefined; - encoding?: BufferEncoding | 'buffer' | null | undefined; + encoding?: BufferEncoding | "buffer" | null | undefined; } interface ExecSyncOptions extends CommonExecOptions { shell?: string | undefined; @@ -1301,7 +1467,7 @@ declare module 'child_process' { encoding: BufferEncoding; } interface ExecSyncOptionsWithBufferEncoding extends ExecSyncOptions { - encoding?: 'buffer' | null | undefined; + encoding?: "buffer" | null | undefined; } /** * The `child_process.execSync()` method is generally identical to {@link exec} with the exception that the method will not return @@ -1330,7 +1496,7 @@ declare module 'child_process' { encoding: BufferEncoding; } interface ExecFileSyncOptionsWithBufferEncoding extends ExecFileSyncOptions { - encoding?: 'buffer' | null; // specify `null`. + encoding?: "buffer" | null; // specify `null`. } /** * The `child_process.execFileSync()` method is generally identical to {@link execFile} with the exception that the method will not @@ -1356,11 +1522,19 @@ declare module 'child_process' { function execFileSync(file: string, options: ExecFileSyncOptionsWithStringEncoding): string; function execFileSync(file: string, options: ExecFileSyncOptionsWithBufferEncoding): Buffer; function execFileSync(file: string, options?: ExecFileSyncOptions): string | Buffer; - function execFileSync(file: string, args: ReadonlyArray): Buffer; - function execFileSync(file: string, args: ReadonlyArray, options: ExecFileSyncOptionsWithStringEncoding): string; - function execFileSync(file: string, args: ReadonlyArray, options: ExecFileSyncOptionsWithBufferEncoding): Buffer; - function execFileSync(file: string, args?: ReadonlyArray, options?: ExecFileSyncOptions): string | Buffer; + function execFileSync(file: string, args: readonly string[]): Buffer; + function execFileSync( + file: string, + args: readonly string[], + options: ExecFileSyncOptionsWithStringEncoding, + ): string; + function execFileSync( + file: string, + args: readonly string[], + options: ExecFileSyncOptionsWithBufferEncoding, + ): Buffer; + function execFileSync(file: string, args?: readonly string[], options?: ExecFileSyncOptions): string | Buffer; } -declare module 'node:child_process' { - export * from 'child_process'; +declare module "node:child_process" { + export * from "child_process"; } diff --git a/node_modules/@types/node/cluster.d.ts b/node_modules/@types/node/cluster.d.ts old mode 100755 new mode 100644 index 7f16141..39cd56a --- a/node_modules/@types/node/cluster.d.ts +++ b/node_modules/@types/node/cluster.d.ts @@ -1,18 +1,19 @@ /** - * A single instance of Node.js runs in a single thread. To take advantage of - * multi-core systems, the user will sometimes want to launch a cluster of Node.js - * processes to handle the load. + * Clusters of Node.js processes can be used to run multiple instances of Node.js + * that can distribute workloads among their application threads. When process + * isolation is not needed, use the `worker_threads` module instead, which + * allows running multiple application threads within a single Node.js instance. * * The cluster module allows easy creation of child processes that all share * server ports. * * ```js - * import cluster from 'cluster'; - * import http from 'http'; - * import { cpus } from 'os'; - * import process from 'process'; + * import cluster from 'node:cluster'; + * import http from 'node:http'; + * import { availableParallelism } from 'node:os'; + * import process from 'node:process'; * - * const numCPUs = cpus().length; + * const numCPUs = availableParallelism(); * * if (cluster.isPrimary) { * console.log(`Primary ${process.pid} is running`); @@ -49,12 +50,13 @@ * ``` * * On Windows, it is not yet possible to set up a named pipe server in a worker. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/cluster.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/cluster.js) */ -declare module 'cluster' { - import * as child from 'node:child_process'; - import EventEmitter = require('node:events'); - import * as net from 'node:net'; +declare module "cluster" { + import * as child from "node:child_process"; + import EventEmitter = require("node:events"); + import * as net from "node:net"; + type SerializationType = "json" | "advanced"; export interface ClusterSettings { execArgv?: string[] | undefined; // default: process.execArgv exec?: string | undefined; @@ -64,11 +66,14 @@ declare module 'cluster' { uid?: number | undefined; gid?: number | undefined; inspectPort?: number | (() => number) | undefined; + serialization?: SerializationType | undefined; + cwd?: string | undefined; + windowsHide?: boolean | undefined; } export interface Address { address: string; port: number; - addressType: number | 'udp4' | 'udp6'; // 4, 6, -1, "udp4", "udp6" + addressType: number | "udp4" | "udp6"; // 4, 6, -1, "udp4", "udp6" } /** * A `Worker` object contains all public information and method about a worker. @@ -99,9 +104,9 @@ declare module 'cluster' { /** * Send a message to a worker or primary, optionally with a handle. * - * In the primary this sends a message to a specific worker. It is identical to `ChildProcess.send()`. + * In the primary, this sends a message to a specific worker. It is identical to `ChildProcess.send()`. * - * In a worker this sends a message to the primary. It is identical to`process.send()`. + * In a worker, this sends a message to the primary. It is identical to`process.send()`. * * This example will echo back all messages from the primary: * @@ -120,22 +125,25 @@ declare module 'cluster' { * @param options The `options` argument, if present, is an object used to parameterize the sending of certain types of handles. `options` supports the following properties: */ send(message: child.Serializable, callback?: (error: Error | null) => void): boolean; - send(message: child.Serializable, sendHandle: child.SendHandle, callback?: (error: Error | null) => void): boolean; - send(message: child.Serializable, sendHandle: child.SendHandle, options?: child.MessageOptions, callback?: (error: Error | null) => void): boolean; + send( + message: child.Serializable, + sendHandle: child.SendHandle, + callback?: (error: Error | null) => void, + ): boolean; + send( + message: child.Serializable, + sendHandle: child.SendHandle, + options?: child.MessageOptions, + callback?: (error: Error | null) => void, + ): boolean; /** - * This function will kill the worker. In the primary, it does this - * by disconnecting the `worker.process`, and once disconnected, killing - * with `signal`. In the worker, it does it by disconnecting the channel, - * and then exiting with code `0`. + * This function will kill the worker. In the primary worker, it does this by + * disconnecting the `worker.process`, and once disconnected, killing with`signal`. In the worker, it does it by killing the process with `signal`. * - * Because `kill()` attempts to gracefully disconnect the worker process, it is - * susceptible to waiting indefinitely for the disconnect to complete. For example, - * if the worker enters an infinite loop, a graceful disconnect will never occur. - * If the graceful disconnect behavior is not needed, use `worker.process.kill()`. + * The `kill()` function kills the worker process without waiting for a graceful + * disconnect, it has the same behavior as `worker.process.kill()`. * - * Causes `.exitedAfterDisconnect` to be set. - * - * This method is aliased as `worker.destroy()` for backward compatibility. + * This method is aliased as `worker.destroy()` for backwards compatibility. * * In a worker, `process.kill()` exists, but it is not this function; * it is `kill()`. @@ -188,7 +196,7 @@ declare module 'cluster' { * }); * * } else if (cluster.isWorker) { - * const net = require('net'); + * const net = require('node:net'); * const server = net.createServer((socket) => { * // Connections never end * }); @@ -218,12 +226,12 @@ declare module 'cluster' { * because of exiting or being signaled). Otherwise, it returns `false`. * * ```js - * import cluster from 'cluster'; - * import http from 'http'; - * import { cpus } from 'os'; - * import process from 'process'; + * import cluster from 'node:cluster'; + * import http from 'node:http'; + * import { availableParallelism } from 'node:os'; + * import process from 'node:process'; * - * const numCPUs = cpus().length; + * const numCPUs = availableParallelism(); * * if (cluster.isPrimary) { * console.log(`Primary ${process.pid} is running`); @@ -253,7 +261,8 @@ declare module 'cluster' { */ isDead(): boolean; /** - * This property is `true` if the worker exited due to `.kill()` or`.disconnect()`. If the worker exited any other way, it is `false`. If the + * This property is `true` if the worker exited due to `.disconnect()`. + * If the worker exited any other way, it is `false`. If the * worker has not exited, it is `undefined`. * * The boolean `worker.exitedAfterDisconnect` allows distinguishing between @@ -283,47 +292,47 @@ declare module 'cluster' { * 6. online */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'disconnect', listener: () => void): this; - addListener(event: 'error', listener: (error: Error) => void): this; - addListener(event: 'exit', listener: (code: number, signal: string) => void): this; - addListener(event: 'listening', listener: (address: Address) => void): this; - addListener(event: 'message', listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - addListener(event: 'online', listener: () => void): this; + addListener(event: "disconnect", listener: () => void): this; + addListener(event: "error", listener: (error: Error) => void): this; + addListener(event: "exit", listener: (code: number, signal: string) => void): this; + addListener(event: "listening", listener: (address: Address) => void): this; + addListener(event: "message", listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + addListener(event: "online", listener: () => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'disconnect'): boolean; - emit(event: 'error', error: Error): boolean; - emit(event: 'exit', code: number, signal: string): boolean; - emit(event: 'listening', address: Address): boolean; - emit(event: 'message', message: any, handle: net.Socket | net.Server): boolean; - emit(event: 'online'): boolean; + emit(event: "disconnect"): boolean; + emit(event: "error", error: Error): boolean; + emit(event: "exit", code: number, signal: string): boolean; + emit(event: "listening", address: Address): boolean; + emit(event: "message", message: any, handle: net.Socket | net.Server): boolean; + emit(event: "online"): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'disconnect', listener: () => void): this; - on(event: 'error', listener: (error: Error) => void): this; - on(event: 'exit', listener: (code: number, signal: string) => void): this; - on(event: 'listening', listener: (address: Address) => void): this; - on(event: 'message', listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - on(event: 'online', listener: () => void): this; + on(event: "disconnect", listener: () => void): this; + on(event: "error", listener: (error: Error) => void): this; + on(event: "exit", listener: (code: number, signal: string) => void): this; + on(event: "listening", listener: (address: Address) => void): this; + on(event: "message", listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + on(event: "online", listener: () => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'disconnect', listener: () => void): this; - once(event: 'error', listener: (error: Error) => void): this; - once(event: 'exit', listener: (code: number, signal: string) => void): this; - once(event: 'listening', listener: (address: Address) => void): this; - once(event: 'message', listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - once(event: 'online', listener: () => void): this; + once(event: "disconnect", listener: () => void): this; + once(event: "error", listener: (error: Error) => void): this; + once(event: "exit", listener: (code: number, signal: string) => void): this; + once(event: "listening", listener: (address: Address) => void): this; + once(event: "message", listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + once(event: "online", listener: () => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'disconnect', listener: () => void): this; - prependListener(event: 'error', listener: (error: Error) => void): this; - prependListener(event: 'exit', listener: (code: number, signal: string) => void): this; - prependListener(event: 'listening', listener: (address: Address) => void): this; - prependListener(event: 'message', listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - prependListener(event: 'online', listener: () => void): this; + prependListener(event: "disconnect", listener: () => void): this; + prependListener(event: "error", listener: (error: Error) => void): this; + prependListener(event: "exit", listener: (code: number, signal: string) => void): this; + prependListener(event: "listening", listener: (address: Address) => void): this; + prependListener(event: "message", listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + prependListener(event: "online", listener: () => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'disconnect', listener: () => void): this; - prependOnceListener(event: 'error', listener: (error: Error) => void): this; - prependOnceListener(event: 'exit', listener: (code: number, signal: string) => void): this; - prependOnceListener(event: 'listening', listener: (address: Address) => void): this; - prependOnceListener(event: 'message', listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - prependOnceListener(event: 'online', listener: () => void): this; + prependOnceListener(event: "disconnect", listener: () => void): this; + prependOnceListener(event: "error", listener: (error: Error) => void): this; + prependOnceListener(event: "exit", listener: (code: number, signal: string) => void): this; + prependOnceListener(event: "listening", listener: (address: Address) => void): this; + prependOnceListener(event: "message", listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + prependOnceListener(event: "online", listener: () => void): this; } export interface Cluster extends EventEmitter { disconnect(callback?: () => void): void; @@ -355,60 +364,69 @@ declare module 'cluster' { * 7. setup */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'disconnect', listener: (worker: Worker) => void): this; - addListener(event: 'exit', listener: (worker: Worker, code: number, signal: string) => void): this; - addListener(event: 'fork', listener: (worker: Worker) => void): this; - addListener(event: 'listening', listener: (worker: Worker, address: Address) => void): this; - addListener(event: 'message', listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - addListener(event: 'online', listener: (worker: Worker) => void): this; - addListener(event: 'setup', listener: (settings: ClusterSettings) => void): this; + addListener(event: "disconnect", listener: (worker: Worker) => void): this; + addListener(event: "exit", listener: (worker: Worker, code: number, signal: string) => void): this; + addListener(event: "fork", listener: (worker: Worker) => void): this; + addListener(event: "listening", listener: (worker: Worker, address: Address) => void): this; + addListener( + event: "message", + listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void, + ): this; // the handle is a net.Socket or net.Server object, or undefined. + addListener(event: "online", listener: (worker: Worker) => void): this; + addListener(event: "setup", listener: (settings: ClusterSettings) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'disconnect', worker: Worker): boolean; - emit(event: 'exit', worker: Worker, code: number, signal: string): boolean; - emit(event: 'fork', worker: Worker): boolean; - emit(event: 'listening', worker: Worker, address: Address): boolean; - emit(event: 'message', worker: Worker, message: any, handle: net.Socket | net.Server): boolean; - emit(event: 'online', worker: Worker): boolean; - emit(event: 'setup', settings: ClusterSettings): boolean; + emit(event: "disconnect", worker: Worker): boolean; + emit(event: "exit", worker: Worker, code: number, signal: string): boolean; + emit(event: "fork", worker: Worker): boolean; + emit(event: "listening", worker: Worker, address: Address): boolean; + emit(event: "message", worker: Worker, message: any, handle: net.Socket | net.Server): boolean; + emit(event: "online", worker: Worker): boolean; + emit(event: "setup", settings: ClusterSettings): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'disconnect', listener: (worker: Worker) => void): this; - on(event: 'exit', listener: (worker: Worker, code: number, signal: string) => void): this; - on(event: 'fork', listener: (worker: Worker) => void): this; - on(event: 'listening', listener: (worker: Worker, address: Address) => void): this; - on(event: 'message', listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - on(event: 'online', listener: (worker: Worker) => void): this; - on(event: 'setup', listener: (settings: ClusterSettings) => void): this; + on(event: "disconnect", listener: (worker: Worker) => void): this; + on(event: "exit", listener: (worker: Worker, code: number, signal: string) => void): this; + on(event: "fork", listener: (worker: Worker) => void): this; + on(event: "listening", listener: (worker: Worker, address: Address) => void): this; + on(event: "message", listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + on(event: "online", listener: (worker: Worker) => void): this; + on(event: "setup", listener: (settings: ClusterSettings) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'disconnect', listener: (worker: Worker) => void): this; - once(event: 'exit', listener: (worker: Worker, code: number, signal: string) => void): this; - once(event: 'fork', listener: (worker: Worker) => void): this; - once(event: 'listening', listener: (worker: Worker, address: Address) => void): this; - once(event: 'message', listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - once(event: 'online', listener: (worker: Worker) => void): this; - once(event: 'setup', listener: (settings: ClusterSettings) => void): this; + once(event: "disconnect", listener: (worker: Worker) => void): this; + once(event: "exit", listener: (worker: Worker, code: number, signal: string) => void): this; + once(event: "fork", listener: (worker: Worker) => void): this; + once(event: "listening", listener: (worker: Worker, address: Address) => void): this; + once(event: "message", listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + once(event: "online", listener: (worker: Worker) => void): this; + once(event: "setup", listener: (settings: ClusterSettings) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'disconnect', listener: (worker: Worker) => void): this; - prependListener(event: 'exit', listener: (worker: Worker, code: number, signal: string) => void): this; - prependListener(event: 'fork', listener: (worker: Worker) => void): this; - prependListener(event: 'listening', listener: (worker: Worker, address: Address) => void): this; + prependListener(event: "disconnect", listener: (worker: Worker) => void): this; + prependListener(event: "exit", listener: (worker: Worker, code: number, signal: string) => void): this; + prependListener(event: "fork", listener: (worker: Worker) => void): this; + prependListener(event: "listening", listener: (worker: Worker, address: Address) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - prependListener(event: 'message', listener: (worker: Worker, message: any, handle?: net.Socket | net.Server) => void): this; - prependListener(event: 'online', listener: (worker: Worker) => void): this; - prependListener(event: 'setup', listener: (settings: ClusterSettings) => void): this; + prependListener( + event: "message", + listener: (worker: Worker, message: any, handle?: net.Socket | net.Server) => void, + ): this; + prependListener(event: "online", listener: (worker: Worker) => void): this; + prependListener(event: "setup", listener: (settings: ClusterSettings) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'disconnect', listener: (worker: Worker) => void): this; - prependOnceListener(event: 'exit', listener: (worker: Worker, code: number, signal: string) => void): this; - prependOnceListener(event: 'fork', listener: (worker: Worker) => void): this; - prependOnceListener(event: 'listening', listener: (worker: Worker, address: Address) => void): this; + prependOnceListener(event: "disconnect", listener: (worker: Worker) => void): this; + prependOnceListener(event: "exit", listener: (worker: Worker, code: number, signal: string) => void): this; + prependOnceListener(event: "fork", listener: (worker: Worker) => void): this; + prependOnceListener(event: "listening", listener: (worker: Worker, address: Address) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - prependOnceListener(event: 'message', listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; - prependOnceListener(event: 'online', listener: (worker: Worker) => void): this; - prependOnceListener(event: 'setup', listener: (settings: ClusterSettings) => void): this; + prependOnceListener( + event: "message", + listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void, + ): this; + prependOnceListener(event: "online", listener: (worker: Worker) => void): this; + prependOnceListener(event: "setup", listener: (settings: ClusterSettings) => void): this; } const cluster: Cluster; export default cluster; } -declare module 'node:cluster' { - export * from 'cluster'; - export { default as default } from 'cluster'; +declare module "node:cluster" { + export * from "cluster"; + export { default as default } from "cluster"; } diff --git a/node_modules/@types/node/console.d.ts b/node_modules/@types/node/console.d.ts old mode 100755 new mode 100644 index ede7a53..bcc3450 --- a/node_modules/@types/node/console.d.ts +++ b/node_modules/@types/node/console.d.ts @@ -1,11 +1,11 @@ /** - * The `console` module provides a simple debugging console that is similar to the - * JavaScript console mechanism provided by web browsers. + * The `node:console` module provides a simple debugging console that is similar to + * the JavaScript console mechanism provided by web browsers. * * The module exports two specific components: * - * * A `Console` class with methods such as `console.log()`, `console.error()` and`console.warn()` that can be used to write to any Node.js stream. - * * A global `console` instance configured to write to `process.stdout` and `process.stderr`. The global `console` can be used without calling`require('console')`. + * * A `Console` class with methods such as `console.log()`, `console.error()`, and`console.warn()` that can be used to write to any Node.js stream. + * * A global `console` instance configured to write to `process.stdout` and `process.stderr`. The global `console` can be used without calling`require('node:console')`. * * _**Warning**_: The global console object's methods are neither consistently * synchronous like the browser APIs they resemble, nor are they consistently @@ -53,14 +53,14 @@ * myConsole.warn(`Danger ${name}! Danger!`); * // Prints: Danger Will Robinson! Danger!, to err * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/console.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/console.js) */ -declare module 'console' { - import console = require('node:console'); +declare module "console" { + import console = require("node:console"); export = console; } -declare module 'node:console' { - import { InspectOptions } from 'node:util'; +declare module "node:console" { + import { InspectOptions } from "node:util"; global { // This needs to be global to avoid TS2403 in case lib.dom.d.ts is present in the same build interface Console { @@ -123,7 +123,7 @@ declare module 'node:console' { * > * ``` * @since v8.3.0 - * @param label The display label for the counter. + * @param [label='default'] The display label for the counter. */ count(label?: string): void; /** @@ -141,7 +141,7 @@ declare module 'node:console' { * > * ``` * @since v8.3.0 - * @param label The display label for the counter. + * @param [label='default'] The display label for the counter. */ countReset(label?: string): void; /** @@ -221,7 +221,7 @@ declare module 'node:console' { log(message?: any, ...optionalParams: any[]): void; /** * Try to construct a table with the columns of the properties of `tabularData`(or use `properties`) and rows of `tabularData` and log it. Falls back to just - * logging the argument if it can’t be parsed as tabular. + * logging the argument if it can't be parsed as tabular. * * ```js * // These can't be parsed as tabular data @@ -250,13 +250,14 @@ declare module 'node:console' { * @since v10.0.0 * @param properties Alternate properties for constructing the table. */ - table(tabularData: any, properties?: ReadonlyArray): void; + table(tabularData: any, properties?: readonly string[]): void; /** * Starts a timer that can be used to compute the duration of an operation. Timers * are identified by a unique `label`. Use the same `label` when calling {@link timeEnd} to stop the timer and output the elapsed time in * suitable time units to `stdout`. For example, if the elapsed * time is 3869ms, `console.timeEnd()` displays "3.869s". * @since v0.1.104 + * @param [label='default'] */ time(label?: string): void; /** @@ -264,12 +265,13 @@ declare module 'node:console' { * prints the result to `stdout`: * * ```js - * console.time('100-elements'); - * for (let i = 0; i < 100; i++) {} - * console.timeEnd('100-elements'); - * // prints 100-elements: 225.438ms + * console.time('bunch-of-stuff'); + * // Do a bunch of stuff. + * console.timeEnd('bunch-of-stuff'); + * // Prints: bunch-of-stuff: 225.438ms * ``` * @since v0.1.104 + * @param [label='default'] */ timeEnd(label?: string): void; /** @@ -285,6 +287,7 @@ declare module 'node:console' { * console.timeEnd('process'); * ``` * @since v10.7.0 + * @param [label='default'] */ timeLog(label?: string, ...data: any[]): void; /** @@ -392,7 +395,7 @@ declare module 'node:console' { stdout: NodeJS.WritableStream; stderr?: NodeJS.WritableStream | undefined; ignoreErrors?: boolean | undefined; - colorMode?: boolean | 'auto' | undefined; + colorMode?: boolean | "auto" | undefined; inspectOptions?: InspectOptions | undefined; /** * Set group indentation @@ -402,8 +405,8 @@ declare module 'node:console' { } interface ConsoleConstructor { prototype: Console; - new (stdout: NodeJS.WritableStream, stderr?: NodeJS.WritableStream, ignoreErrors?: boolean): Console; - new (options: ConsoleConstructorOptions): Console; + new(stdout: NodeJS.WritableStream, stderr?: NodeJS.WritableStream, ignoreErrors?: boolean): Console; + new(options: ConsoleConstructorOptions): Console; } } var console: Console; diff --git a/node_modules/@types/node/constants.d.ts b/node_modules/@types/node/constants.d.ts old mode 100755 new mode 100644 index 208020d..c3ac2b8 --- a/node_modules/@types/node/constants.d.ts +++ b/node_modules/@types/node/constants.d.ts @@ -1,18 +1,19 @@ /** @deprecated since v6.3.0 - use constants property exposed by the relevant module instead. */ -declare module 'constants' { - import { constants as osConstants, SignalConstants } from 'node:os'; - import { constants as cryptoConstants } from 'node:crypto'; - import { constants as fsConstants } from 'node:fs'; +declare module "constants" { + import { constants as osConstants, SignalConstants } from "node:os"; + import { constants as cryptoConstants } from "node:crypto"; + import { constants as fsConstants } from "node:fs"; - const exp: typeof osConstants.errno & - typeof osConstants.priority & - SignalConstants & - typeof cryptoConstants & - typeof fsConstants; + const exp: + & typeof osConstants.errno + & typeof osConstants.priority + & SignalConstants + & typeof cryptoConstants + & typeof fsConstants; export = exp; } -declare module 'node:constants' { - import constants = require('constants'); +declare module "node:constants" { + import constants = require("constants"); export = constants; } diff --git a/node_modules/@types/node/crypto.d.ts b/node_modules/@types/node/crypto.d.ts old mode 100755 new mode 100644 index 4f6dc9f..7509b76 --- a/node_modules/@types/node/crypto.d.ts +++ b/node_modules/@types/node/crypto.d.ts @@ -1,9 +1,10 @@ /** - * The `crypto` module provides cryptographic functionality that includes a set of - * wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify functions. + * The `node:crypto` module provides cryptographic functionality that includes a + * set of wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify + * functions. * * ```js - * const { createHmac } = await import('crypto'); + * const { createHmac } = await import('node:crypto'); * * const secret = 'abcdefg'; * const hash = createHmac('sha256', secret) @@ -13,12 +14,64 @@ * // Prints: * // c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/crypto.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/crypto.js) */ -declare module 'crypto' { - import * as stream from 'node:stream'; - import { PeerCertificate } from 'node:tls'; - interface Certificate { +declare module "crypto" { + import * as stream from "node:stream"; + import { PeerCertificate } from "node:tls"; + /** + * SPKAC is a Certificate Signing Request mechanism originally implemented by + * Netscape and was specified formally as part of HTML5's `keygen` element. + * + * `` is deprecated since [HTML 5.2](https://www.w3.org/TR/html52/changes.html#features-removed) and new projects + * should not use this element anymore. + * + * The `node:crypto` module provides the `Certificate` class for working with SPKAC + * data. The most common usage is handling output generated by the HTML5`` element. Node.js uses [OpenSSL's SPKAC + * implementation](https://www.openssl.org/docs/man3.0/man1/openssl-spkac.html) internally. + * @since v0.11.8 + */ + class Certificate { + /** + * ```js + * const { Certificate } = await import('node:crypto'); + * const spkac = getSpkacSomehow(); + * const challenge = Certificate.exportChallenge(spkac); + * console.log(challenge.toString('utf8')); + * // Prints: the challenge as a UTF8 string + * ``` + * @since v9.0.0 + * @param encoding The `encoding` of the `spkac` string. + * @return The challenge component of the `spkac` data structure, which includes a public key and a challenge. + */ + static exportChallenge(spkac: BinaryLike): Buffer; + /** + * ```js + * const { Certificate } = await import('node:crypto'); + * const spkac = getSpkacSomehow(); + * const publicKey = Certificate.exportPublicKey(spkac); + * console.log(publicKey); + * // Prints: the public key as + * ``` + * @since v9.0.0 + * @param encoding The `encoding` of the `spkac` string. + * @return The public key component of the `spkac` data structure, which includes a public key and a challenge. + */ + static exportPublicKey(spkac: BinaryLike, encoding?: string): Buffer; + /** + * ```js + * import { Buffer } from 'node:buffer'; + * const { Certificate } = await import('node:crypto'); + * + * const spkac = getSpkacSomehow(); + * console.log(Certificate.verifySpkac(Buffer.from(spkac))); + * // Prints: true or false + * ``` + * @since v9.0.0 + * @param encoding The `encoding` of the `spkac` string. + * @return `true` if the given `spkac` data structure is valid, `false` otherwise. + */ + static verifySpkac(spkac: NodeJS.ArrayBufferView): boolean; /** * @deprecated * @param spkac @@ -42,36 +95,13 @@ declare module 'crypto' { */ verifySpkac(spkac: NodeJS.ArrayBufferView): boolean; } - const Certificate: Certificate & { - /** @deprecated since v14.9.0 - Use static methods of `crypto.Certificate` instead. */ - new (): Certificate; - /** @deprecated since v14.9.0 - Use static methods of `crypto.Certificate` instead. */ - (): Certificate; - /** - * @param spkac - * @returns The challenge component of the `spkac` data structure, - * which includes a public key and a challenge. - */ - exportChallenge(spkac: BinaryLike): Buffer; - /** - * @param spkac - * @param encoding The encoding of the spkac string. - * @returns The public key component of the `spkac` data structure, - * which includes a public key and a challenge. - */ - exportPublicKey(spkac: BinaryLike, encoding?: string): Buffer; - /** - * @param spkac - * @returns `true` if the given `spkac` data structure is valid, - * `false` otherwise. - */ - verifySpkac(spkac: NodeJS.ArrayBufferView): boolean; - }; namespace constants { - // https://nodejs.org/dist/latest-v10.x/docs/api/crypto.html#crypto_crypto_constants + // https://nodejs.org/dist/latest-v20.x/docs/api/crypto.html#crypto-constants const OPENSSL_VERSION_NUMBER: number; /** Applies multiple bug workarounds within OpenSSL. See https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html for detail. */ const SSL_OP_ALL: number; + /** Instructs OpenSSL to allow a non-[EC]DHE-based key exchange mode for TLS v1.3 */ + const SSL_OP_ALLOW_NO_DHE_KEX: number; /** Allows legacy insecure renegotiation between OpenSSL and unpatched clients or servers. See https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html. */ const SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION: number; /** Attempts to use the server's preferences instead of the client's when selecting a cipher. See https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html. */ @@ -84,39 +114,33 @@ declare module 'crypto' { const SSL_OP_CRYPTOPRO_TLSEXT_BUG: number; /** Instructs OpenSSL to disable a SSL 3.0/TLS 1.0 vulnerability workaround added in OpenSSL 0.9.6d. */ const SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS: number; - /** Instructs OpenSSL to always use the tmp_rsa key when performing RSA operations. */ - const SSL_OP_EPHEMERAL_RSA: number; /** Allows initial connection to servers that do not support RI. */ const SSL_OP_LEGACY_SERVER_CONNECT: number; - const SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER: number; - const SSL_OP_MICROSOFT_SESS_ID_BUG: number; - /** Instructs OpenSSL to disable the workaround for a man-in-the-middle protocol-version vulnerability in the SSL 2.0 server implementation. */ - const SSL_OP_MSIE_SSLV2_RSA_PADDING: number; - const SSL_OP_NETSCAPE_CA_DN_BUG: number; - const SSL_OP_NETSCAPE_CHALLENGE_BUG: number; - const SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG: number; - const SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG: number; /** Instructs OpenSSL to disable support for SSL/TLS compression. */ const SSL_OP_NO_COMPRESSION: number; + /** Instructs OpenSSL to disable encrypt-then-MAC. */ + const SSL_OP_NO_ENCRYPT_THEN_MAC: number; const SSL_OP_NO_QUERY_MTU: number; + /** Instructs OpenSSL to disable renegotiation. */ + const SSL_OP_NO_RENEGOTIATION: number; /** Instructs OpenSSL to always start a new session when performing renegotiation. */ const SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION: number; + /** Instructs OpenSSL to turn off SSL v2 */ const SSL_OP_NO_SSLv2: number; + /** Instructs OpenSSL to turn off SSL v3 */ const SSL_OP_NO_SSLv3: number; + /** Instructs OpenSSL to disable use of RFC4507bis tickets. */ const SSL_OP_NO_TICKET: number; + /** Instructs OpenSSL to turn off TLS v1 */ const SSL_OP_NO_TLSv1: number; + /** Instructs OpenSSL to turn off TLS v1.1 */ const SSL_OP_NO_TLSv1_1: number; + /** Instructs OpenSSL to turn off TLS v1.2 */ const SSL_OP_NO_TLSv1_2: number; - const SSL_OP_PKCS1_CHECK_1: number; - const SSL_OP_PKCS1_CHECK_2: number; - /** Instructs OpenSSL to always create a new key when using temporary/ephemeral DH parameters. */ - const SSL_OP_SINGLE_DH_USE: number; - /** Instructs OpenSSL to always create a new key when using temporary/ephemeral ECDH parameters. */ - const SSL_OP_SINGLE_ECDH_USE: number; - const SSL_OP_SSLEAY_080_CLIENT_DH_BUG: number; - const SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG: number; - const SSL_OP_TLS_BLOCK_PADDING_BUG: number; - const SSL_OP_TLS_D5_BUG: number; + /** Instructs OpenSSL to turn off TLS v1.3 */ + const SSL_OP_NO_TLSv1_3: number; + /** Instructs OpenSSL server to prioritize ChaCha20-Poly1305 when the client does. This option has no effect if `SSL_OP_CIPHER_SERVER_PREFERENCE` is not enabled. */ + const SSL_OP_PRIORITIZE_CHACHA: number; /** Instructs OpenSSL to disable version rollback attack detection. */ const SSL_OP_TLS_ROLLBACK_BUG: number; const ENGINE_METHOD_RSA: number; @@ -134,7 +158,6 @@ declare module 'crypto' { const DH_CHECK_P_NOT_PRIME: number; const DH_UNABLE_TO_CHECK_GENERATOR: number; const DH_NOT_SUITABLE_GENERATOR: number; - const ALPN_ENABLED: number; const RSA_PKCS1_PADDING: number; const RSA_SSLV23_PADDING: number; const RSA_NO_PADDING: number; @@ -172,19 +195,19 @@ declare module 'crypto' { * * The `algorithm` is dependent on the available algorithms supported by the * version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc. - * On recent releases of OpenSSL, `openssl list -digest-algorithms`(`openssl list-message-digest-algorithms` for older versions of OpenSSL) will + * On recent releases of OpenSSL, `openssl list -digest-algorithms` will * display the available digest algorithms. * * Example: generating the sha256 sum of a file * * ```js * import { - * createReadStream - * } from 'fs'; - * import { argv } from 'process'; + * createReadStream, + * } from 'node:fs'; + * import { argv } from 'node:process'; * const { - * createHash - * } = await import('crypto'); + * createHash, + * } = await import('node:crypto'); * * const filename = argv[2]; * @@ -212,22 +235,24 @@ declare module 'crypto' { * * The `algorithm` is dependent on the available algorithms supported by the * version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc. - * On recent releases of OpenSSL, `openssl list -digest-algorithms`(`openssl list-message-digest-algorithms` for older versions of OpenSSL) will + * On recent releases of OpenSSL, `openssl list -digest-algorithms` will * display the available digest algorithms. * * The `key` is the HMAC key used to generate the cryptographic HMAC hash. If it is - * a `KeyObject`, its type must be `secret`. + * a `KeyObject`, its type must be `secret`. If it is a string, please consider `caveats when using strings as inputs to cryptographic APIs`. If it was + * obtained from a cryptographically secure source of entropy, such as {@link randomBytes} or {@link generateKey}, its length should not + * exceed the block size of `algorithm` (e.g., 512 bits for SHA-256). * * Example: generating the sha256 HMAC of a file * * ```js * import { - * createReadStream - * } from 'fs'; - * import { argv } from 'process'; + * createReadStream, + * } from 'node:fs'; + * import { argv } from 'node:process'; * const { - * createHmac - * } = await import('crypto'); + * createHmac, + * } = await import('node:crypto'); * * const filename = argv[2]; * @@ -250,11 +275,11 @@ declare module 'crypto' { */ function createHmac(algorithm: string, key: BinaryLike | KeyObject, options?: stream.TransformOptions): Hmac; // https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings - type BinaryToTextEncoding = 'base64' | 'base64url' | 'hex'; - type CharacterEncoding = 'utf8' | 'utf-8' | 'utf16le' | 'latin1'; - type LegacyCharacterEncoding = 'ascii' | 'binary' | 'ucs2' | 'ucs-2'; + type BinaryToTextEncoding = "base64" | "base64url" | "hex" | "binary"; + type CharacterEncoding = "utf8" | "utf-8" | "utf16le" | "utf-16le" | "latin1"; + type LegacyCharacterEncoding = "ascii" | "binary" | "ucs2" | "ucs-2"; type Encoding = BinaryToTextEncoding | CharacterEncoding | LegacyCharacterEncoding; - type ECDHKeyFormat = 'compressed' | 'uncompressed' | 'hybrid'; + type ECDHKeyFormat = "compressed" | "uncompressed" | "hybrid"; /** * The `Hash` class is a utility for creating hash digests of data. It can be * used in one of two ways: @@ -270,8 +295,8 @@ declare module 'crypto' { * * ```js * const { - * createHash - * } = await import('crypto'); + * createHash, + * } = await import('node:crypto'); * * const hash = createHash('sha256'); * @@ -293,9 +318,9 @@ declare module 'crypto' { * Example: Using `Hash` and piped streams: * * ```js - * import { createReadStream } from 'fs'; - * import { stdout } from 'process'; - * const { createHash } = await import('crypto'); + * import { createReadStream } from 'node:fs'; + * import { stdout } from 'node:process'; + * const { createHash } = await import('node:crypto'); * * const hash = createHash('sha256'); * @@ -307,8 +332,8 @@ declare module 'crypto' { * * ```js * const { - * createHash - * } = await import('crypto'); + * createHash, + * } = await import('node:crypto'); * * const hash = createHash('sha256'); * @@ -335,8 +360,8 @@ declare module 'crypto' { * ```js * // Calculate a rolling hash. * const { - * createHash - * } = await import('crypto'); + * createHash, + * } = await import('node:crypto'); * * const hash = createHash('sha256'); * @@ -354,7 +379,7 @@ declare module 'crypto' { * @since v13.1.0 * @param options `stream.transform` options */ - copy(options?: stream.TransformOptions): Hash; + copy(options?: HashOptions): Hash; /** * Updates the hash content with the given `data`, the encoding of which * is given in `inputEncoding`. @@ -395,8 +420,8 @@ declare module 'crypto' { * * ```js * const { - * createHmac - * } = await import('crypto'); + * createHmac, + * } = await import('node:crypto'); * * const hmac = createHmac('sha256', 'a secret'); * @@ -418,11 +443,11 @@ declare module 'crypto' { * Example: Using `Hmac` and piped streams: * * ```js - * import { createReadStream } from 'fs'; - * import { stdout } from 'process'; + * import { createReadStream } from 'node:fs'; + * import { stdout } from 'node:process'; * const { - * createHmac - * } = await import('crypto'); + * createHmac, + * } = await import('node:crypto'); * * const hmac = createHmac('sha256', 'a secret'); * @@ -434,8 +459,8 @@ declare module 'crypto' { * * ```js * const { - * createHmac - * } = await import('crypto'); + * createHmac, + * } = await import('node:crypto'); * * const hmac = createHmac('sha256', 'a secret'); * @@ -473,15 +498,15 @@ declare module 'crypto' { digest(): Buffer; digest(encoding: BinaryToTextEncoding): string; } - type KeyObjectType = 'secret' | 'public' | 'private'; + type KeyObjectType = "secret" | "public" | "private"; interface KeyExportOptions { - type: 'pkcs1' | 'spki' | 'pkcs8' | 'sec1'; + type: "pkcs1" | "spki" | "pkcs8" | "sec1"; format: T; cipher?: string | undefined; passphrase?: string | Buffer | undefined; } interface JwkKeyExportOptions { - format: 'jwk'; + format: "jwk"; } interface JsonWebKey { crv?: string | undefined; @@ -548,13 +573,13 @@ declare module 'crypto' { * Example: Converting a `CryptoKey` instance to a `KeyObject`: * * ```js - * const { webcrypto, KeyObject } = await import('crypto'); - * const { subtle } = webcrypto; + * const { KeyObject } = await import('node:crypto'); + * const { subtle } = globalThis.crypto; * * const key = await subtle.generateKey({ * name: 'HMAC', * hash: 'SHA-256', - * length: 256 + * length: 256, * }, true, ['sign', 'verify']); * * const keyObject = KeyObject.from(key); @@ -625,9 +650,16 @@ declare module 'crypto' { * PKCS#1 and SEC1 encryption. * @since v11.6.0 */ - export(options: KeyExportOptions<'pem'>): string | Buffer; - export(options?: KeyExportOptions<'der'>): Buffer; + export(options: KeyExportOptions<"pem">): string | Buffer; + export(options?: KeyExportOptions<"der">): Buffer; export(options?: JwkKeyExportOptions): JsonWebKey; + /** + * Returns `true` or `false` depending on whether the keys have exactly the same + * type, value, and parameters. This method is not [constant time](https://en.wikipedia.org/wiki/Timing_attack). + * @since v17.7.0, v16.15.0 + * @param otherKeyObject A `KeyObject` with which to compare `keyObject`. + */ + equals(otherKeyObject: KeyObject): boolean; /** * For secret keys, this property represents the size of the key in bytes. This * property is `undefined` for asymmetric keys. @@ -641,9 +673,9 @@ declare module 'crypto' { */ type: KeyObjectType; } - type CipherCCMTypes = 'aes-128-ccm' | 'aes-192-ccm' | 'aes-256-ccm' | 'chacha20-poly1305'; - type CipherGCMTypes = 'aes-128-gcm' | 'aes-192-gcm' | 'aes-256-gcm'; - type CipherOCBTypes = 'aes-128-ocb' | 'aes-192-ocb' | 'aes-256-ocb'; + type CipherCCMTypes = "aes-128-ccm" | "aes-192-ccm" | "aes-256-ccm" | "chacha20-poly1305"; + type CipherGCMTypes = "aes-128-gcm" | "aes-192-gcm" | "aes-256-gcm"; + type CipherOCBTypes = "aes-128-ocb" | "aes-192-ocb" | "aes-256-ocb"; type BinaryLike = string | NodeJS.ArrayBufferView; type CipherKey = BinaryLike | KeyObject; interface CipherCCMOptions extends stream.TransformOptions { @@ -659,25 +691,30 @@ declare module 'crypto' { * Creates and returns a `Cipher` object that uses the given `algorithm` and`password`. * * The `options` argument controls stream behavior and is optional except when a - * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the + * cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the * authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication * tag that will be returned by `getAuthTag()` and defaults to 16 bytes. + * For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes. * * The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On - * recent OpenSSL releases, `openssl list -cipher-algorithms`(`openssl list-cipher-algorithms` for older versions of OpenSSL) will + * recent OpenSSL releases, `openssl list -cipher-algorithms` will * display the available cipher algorithms. * * The `password` is used to derive the cipher key and initialization vector (IV). * The value must be either a `'latin1'` encoded string, a `Buffer`, a`TypedArray`, or a `DataView`. * + * **This function is semantically insecure for all** + * **supported ciphers and fatally flawed for ciphers in counter mode (such as CTR,** + * **GCM, or CCM).** + * * The implementation of `crypto.createCipher()` derives keys using the OpenSSL - * function [`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) with the digest algorithm set to MD5, one + * function [`EVP_BytesToKey`](https://www.openssl.org/docs/man3.0/man3/EVP_BytesToKey.html) with the digest algorithm set to MD5, one * iteration, and no salt. The lack of salt allows dictionary attacks as the same * password always creates the same key. The low iteration count and * non-cryptographically secure hash algorithm allow passwords to be tested very * rapidly. * - * In line with OpenSSL's recommendation to use a more modern algorithm instead of [`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) it is recommended that + * In line with OpenSSL's recommendation to use a more modern algorithm instead of [`EVP_BytesToKey`](https://www.openssl.org/docs/man3.0/man3/EVP_BytesToKey.html) it is recommended that * developers derive a key and IV on * their own using {@link scrypt} and to use {@link createCipheriv} to create the `Cipher` object. Users should not use ciphers with counter mode * (e.g. CTR, GCM, or CCM) in `crypto.createCipher()`. A warning is emitted when @@ -697,12 +734,13 @@ declare module 'crypto' { * initialization vector (`iv`). * * The `options` argument controls stream behavior and is optional except when a - * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the + * cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the * authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication * tag that will be returned by `getAuthTag()` and defaults to 16 bytes. + * For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes. * * The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On - * recent OpenSSL releases, `openssl list -cipher-algorithms`(`openssl list-cipher-algorithms` for older versions of OpenSSL) will + * recent OpenSSL releases, `openssl list -cipher-algorithms` will * display the available cipher algorithms. * * The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded @@ -721,10 +759,30 @@ declare module 'crypto' { * @since v0.1.94 * @param options `stream.transform` options */ - function createCipheriv(algorithm: CipherCCMTypes, key: CipherKey, iv: BinaryLike, options: CipherCCMOptions): CipherCCM; - function createCipheriv(algorithm: CipherOCBTypes, key: CipherKey, iv: BinaryLike, options: CipherOCBOptions): CipherOCB; - function createCipheriv(algorithm: CipherGCMTypes, key: CipherKey, iv: BinaryLike, options?: CipherGCMOptions): CipherGCM; - function createCipheriv(algorithm: string, key: CipherKey, iv: BinaryLike | null, options?: stream.TransformOptions): Cipher; + function createCipheriv( + algorithm: CipherCCMTypes, + key: CipherKey, + iv: BinaryLike, + options: CipherCCMOptions, + ): CipherCCM; + function createCipheriv( + algorithm: CipherOCBTypes, + key: CipherKey, + iv: BinaryLike, + options: CipherOCBOptions, + ): CipherOCB; + function createCipheriv( + algorithm: CipherGCMTypes, + key: CipherKey, + iv: BinaryLike, + options?: CipherGCMOptions, + ): CipherGCM; + function createCipheriv( + algorithm: string, + key: CipherKey, + iv: BinaryLike | null, + options?: stream.TransformOptions, + ): Cipher; /** * Instances of the `Cipher` class are used to encrypt data. The class can be * used in one of two ways: @@ -744,8 +802,8 @@ declare module 'crypto' { * const { * scrypt, * randomFill, - * createCipheriv - * } = await import('crypto'); + * createCipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -779,17 +837,17 @@ declare module 'crypto' { * import { * createReadStream, * createWriteStream, - * } from 'fs'; + * } from 'node:fs'; * * import { - * pipeline - * } from 'stream'; + * pipeline, + * } from 'node:stream'; * * const { * scrypt, * randomFill, - * createCipheriv - * } = await import('crypto'); + * createCipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -820,8 +878,8 @@ declare module 'crypto' { * const { * scrypt, * randomFill, - * createCipheriv - * } = await import('crypto'); + * createCipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -896,7 +954,7 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options: { plaintextLength: number; - } + }, ): this; getAuthTag(): Buffer; } @@ -905,7 +963,7 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options?: { plaintextLength: number; - } + }, ): this; getAuthTag(): Buffer; } @@ -914,7 +972,7 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options?: { plaintextLength: number; - } + }, ): this; getAuthTag(): Buffer; } @@ -922,17 +980,22 @@ declare module 'crypto' { * Creates and returns a `Decipher` object that uses the given `algorithm` and`password` (key). * * The `options` argument controls stream behavior and is optional except when a - * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the + * cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the * authentication tag in bytes, see `CCM mode`. + * For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes. + * + * **This function is semantically insecure for all** + * **supported ciphers and fatally flawed for ciphers in counter mode (such as CTR,** + * **GCM, or CCM).** * * The implementation of `crypto.createDecipher()` derives keys using the OpenSSL - * function [`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) with the digest algorithm set to MD5, one + * function [`EVP_BytesToKey`](https://www.openssl.org/docs/man3.0/man3/EVP_BytesToKey.html) with the digest algorithm set to MD5, one * iteration, and no salt. The lack of salt allows dictionary attacks as the same * password always creates the same key. The low iteration count and * non-cryptographically secure hash algorithm allow passwords to be tested very * rapidly. * - * In line with OpenSSL's recommendation to use a more modern algorithm instead of [`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) it is recommended that + * In line with OpenSSL's recommendation to use a more modern algorithm instead of [`EVP_BytesToKey`](https://www.openssl.org/docs/man3.0/man3/EVP_BytesToKey.html) it is recommended that * developers derive a key and IV on * their own using {@link scrypt} and to use {@link createDecipheriv} to create the `Decipher` object. * @since v0.1.94 @@ -948,12 +1011,13 @@ declare module 'crypto' { * Creates and returns a `Decipher` object that uses the given `algorithm`, `key`and initialization vector (`iv`). * * The `options` argument controls stream behavior and is optional except when a - * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the + * cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the * authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to restrict accepted authentication tags * to those with the specified length. + * For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes. * * The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On - * recent OpenSSL releases, `openssl list -cipher-algorithms`(`openssl list-cipher-algorithms` for older versions of OpenSSL) will + * recent OpenSSL releases, `openssl list -cipher-algorithms` will * display the available cipher algorithms. * * The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded @@ -972,10 +1036,30 @@ declare module 'crypto' { * @since v0.1.94 * @param options `stream.transform` options */ - function createDecipheriv(algorithm: CipherCCMTypes, key: CipherKey, iv: BinaryLike, options: CipherCCMOptions): DecipherCCM; - function createDecipheriv(algorithm: CipherOCBTypes, key: CipherKey, iv: BinaryLike, options: CipherOCBOptions): DecipherOCB; - function createDecipheriv(algorithm: CipherGCMTypes, key: CipherKey, iv: BinaryLike, options?: CipherGCMOptions): DecipherGCM; - function createDecipheriv(algorithm: string, key: CipherKey, iv: BinaryLike | null, options?: stream.TransformOptions): Decipher; + function createDecipheriv( + algorithm: CipherCCMTypes, + key: CipherKey, + iv: BinaryLike, + options: CipherCCMOptions, + ): DecipherCCM; + function createDecipheriv( + algorithm: CipherOCBTypes, + key: CipherKey, + iv: BinaryLike, + options: CipherOCBOptions, + ): DecipherOCB; + function createDecipheriv( + algorithm: CipherGCMTypes, + key: CipherKey, + iv: BinaryLike, + options?: CipherGCMOptions, + ): DecipherGCM; + function createDecipheriv( + algorithm: string, + key: CipherKey, + iv: BinaryLike | null, + options?: stream.TransformOptions, + ): Decipher; /** * Instances of the `Decipher` class are used to decrypt data. The class can be * used in one of two ways: @@ -992,11 +1076,11 @@ declare module 'crypto' { * Example: Using `Decipher` objects as streams: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * const { * scryptSync, - * createDecipheriv - * } = await import('crypto'); + * createDecipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -1011,6 +1095,7 @@ declare module 'crypto' { * * let decrypted = ''; * decipher.on('readable', () => { + * let chunk; * while (null !== (chunk = decipher.read())) { * decrypted += chunk.toString('utf8'); * } @@ -1033,12 +1118,12 @@ declare module 'crypto' { * import { * createReadStream, * createWriteStream, - * } from 'fs'; - * import { Buffer } from 'buffer'; + * } from 'node:fs'; + * import { Buffer } from 'node:buffer'; * const { * scryptSync, - * createDecipheriv - * } = await import('crypto'); + * createDecipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -1058,11 +1143,11 @@ declare module 'crypto' { * Example: Using the `decipher.update()` and `decipher.final()` methods: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * const { * scryptSync, - * createDecipheriv - * } = await import('crypto'); + * createDecipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -1133,7 +1218,7 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options: { plaintextLength: number; - } + }, ): this; } interface DecipherGCM extends Decipher { @@ -1142,7 +1227,7 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options?: { plaintextLength: number; - } + }, ): this; } interface DecipherOCB extends Decipher { @@ -1151,66 +1236,74 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options?: { plaintextLength: number; - } + }, ): this; } interface PrivateKeyInput { key: string | Buffer; format?: KeyFormat | undefined; - type?: 'pkcs1' | 'pkcs8' | 'sec1' | undefined; + type?: "pkcs1" | "pkcs8" | "sec1" | undefined; passphrase?: string | Buffer | undefined; + encoding?: string | undefined; } interface PublicKeyInput { key: string | Buffer; format?: KeyFormat | undefined; - type?: 'pkcs1' | 'spki' | undefined; + type?: "pkcs1" | "spki" | undefined; + encoding?: string | undefined; } /** * Asynchronously generates a new random secret key of the given `length`. The`type` will determine which validations will be performed on the `length`. * * ```js * const { - * generateKey - * } = await import('crypto'); + * generateKey, + * } = await import('node:crypto'); * - * generateKey('hmac', { length: 64 }, (err, key) => { + * generateKey('hmac', { length: 512 }, (err, key) => { * if (err) throw err; * console.log(key.export().toString('hex')); // 46e..........620 * }); * ``` + * + * The size of a generated HMAC key should not exceed the block size of the + * underlying hash function. See {@link createHmac} for more information. * @since v15.0.0 * @param type The intended use of the generated secret key. Currently accepted values are `'hmac'` and `'aes'`. */ function generateKey( - type: 'hmac' | 'aes', + type: "hmac" | "aes", options: { length: number; }, - callback: (err: Error | null, key: KeyObject) => void + callback: (err: Error | null, key: KeyObject) => void, ): void; /** * Synchronously generates a new random secret key of the given `length`. The`type` will determine which validations will be performed on the `length`. * * ```js * const { - * generateKeySync - * } = await import('crypto'); + * generateKeySync, + * } = await import('node:crypto'); * - * const key = generateKeySync('hmac', { length: 64 }); + * const key = generateKeySync('hmac', { length: 512 }); * console.log(key.export().toString('hex')); // e89..........41e * ``` + * + * The size of a generated HMAC key should not exceed the block size of the + * underlying hash function. See {@link createHmac} for more information. * @since v15.0.0 * @param type The intended use of the generated secret key. Currently accepted values are `'hmac'` and `'aes'`. */ function generateKeySync( - type: 'hmac' | 'aes', + type: "hmac" | "aes", options: { length: number; - } + }, ): KeyObject; interface JsonWebKeyInput { key: JsonWebKey; - format: 'jwk'; + format: "jwk"; } /** * Creates and returns a new key object containing a private key. If `key` is a @@ -1257,10 +1350,10 @@ declare module 'crypto' { * @param options `stream.Writable` options */ function createSign(algorithm: string, options?: stream.WritableOptions): Sign; - type DSAEncoding = 'der' | 'ieee-p1363'; + type DSAEncoding = "der" | "ieee-p1363"; interface SigningOptions { /** - * @See crypto.constants.RSA_PKCS1_PADDING + * @see crypto.constants.RSA_PKCS1_PADDING */ padding?: number | undefined; saltLength?: number | undefined; @@ -1274,6 +1367,7 @@ declare module 'crypto' { interface VerifyKeyObjectInput extends SigningOptions { key: KeyObject; } + interface VerifyJsonWebKeyInput extends JsonWebKeyInput, SigningOptions {} type KeyLike = string | Buffer | KeyObject; /** * The `Sign` class is a utility for generating signatures. It can be used in one @@ -1293,11 +1387,11 @@ declare module 'crypto' { * const { * generateKeyPairSync, * createSign, - * createVerify - * } = await import('crypto'); + * createVerify, + * } = await import('node:crypto'); * * const { privateKey, publicKey } = generateKeyPairSync('ec', { - * namedCurve: 'sect239k1' + * namedCurve: 'sect239k1', * }); * * const sign = createSign('SHA256'); @@ -1318,8 +1412,8 @@ declare module 'crypto' { * const { * generateKeyPairSync, * createSign, - * createVerify - * } = await import('crypto'); + * createVerify, + * } = await import('node:crypto'); * * const { privateKey, publicKey } = generateKeyPairSync('rsa', { * modulusLength: 2048, @@ -1365,7 +1459,10 @@ declare module 'crypto' { * @since v0.1.92 */ sign(privateKey: KeyLike | SignKeyObjectInput | SignPrivateKeyInput): Buffer; - sign(privateKey: KeyLike | SignKeyObjectInput | SignPrivateKeyInput, outputFormat: BinaryToTextEncoding): string; + sign( + privateKey: KeyLike | SignKeyObjectInput | SignPrivateKeyInput, + outputFormat: BinaryToTextEncoding, + ): string; } /** * Creates and returns a `Verify` object that uses the given algorithm. @@ -1428,8 +1525,15 @@ declare module 'crypto' { * be passed instead of a public key. * @since v0.1.92 */ - verify(object: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, signature: NodeJS.ArrayBufferView): boolean; - verify(object: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, signature: string, signature_format?: BinaryToTextEncoding): boolean; + verify( + object: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput | VerifyJsonWebKeyInput, + signature: NodeJS.ArrayBufferView, + ): boolean; + verify( + object: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput | VerifyJsonWebKeyInput, + signature: string, + signature_format?: BinaryToTextEncoding, + ): boolean; } /** * Creates a `DiffieHellman` key exchange object using the supplied `prime` and an @@ -1447,11 +1551,27 @@ declare module 'crypto' { * @param [generator=2] * @param generatorEncoding The `encoding` of the `generator` string. */ - function createDiffieHellman(primeLength: number, generator?: number | NodeJS.ArrayBufferView): DiffieHellman; - function createDiffieHellman(prime: NodeJS.ArrayBufferView): DiffieHellman; - function createDiffieHellman(prime: string, primeEncoding: BinaryToTextEncoding): DiffieHellman; - function createDiffieHellman(prime: string, primeEncoding: BinaryToTextEncoding, generator: number | NodeJS.ArrayBufferView): DiffieHellman; - function createDiffieHellman(prime: string, primeEncoding: BinaryToTextEncoding, generator: string, generatorEncoding: BinaryToTextEncoding): DiffieHellman; + function createDiffieHellman(primeLength: number, generator?: number): DiffieHellman; + function createDiffieHellman( + prime: ArrayBuffer | NodeJS.ArrayBufferView, + generator?: number | ArrayBuffer | NodeJS.ArrayBufferView, + ): DiffieHellman; + function createDiffieHellman( + prime: ArrayBuffer | NodeJS.ArrayBufferView, + generator: string, + generatorEncoding: BinaryToTextEncoding, + ): DiffieHellman; + function createDiffieHellman( + prime: string, + primeEncoding: BinaryToTextEncoding, + generator?: number | ArrayBuffer | NodeJS.ArrayBufferView, + ): DiffieHellman; + function createDiffieHellman( + prime: string, + primeEncoding: BinaryToTextEncoding, + generator: string, + generatorEncoding: BinaryToTextEncoding, + ): DiffieHellman; /** * The `DiffieHellman` class is a utility for creating Diffie-Hellman key * exchanges. @@ -1459,11 +1579,11 @@ declare module 'crypto' { * Instances of the `DiffieHellman` class can be created using the {@link createDiffieHellman} function. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * const { - * createDiffieHellman - * } = await import('crypto'); + * createDiffieHellman, + * } = await import('node:crypto'); * * // Generate Alice's keys... * const alice = createDiffieHellman(2048); @@ -1485,10 +1605,15 @@ declare module 'crypto' { class DiffieHellman { private constructor(); /** - * Generates private and public Diffie-Hellman key values, and returns + * Generates private and public Diffie-Hellman key values unless they have been + * generated or computed already, and returns * the public key in the specified `encoding`. This key should be * transferred to the other party. * If `encoding` is provided a string is returned; otherwise a `Buffer` is returned. + * + * This function is a thin wrapper around [`DH_generate_key()`](https://www.openssl.org/docs/man3.0/man3/DH_generate_key.html). In particular, + * once a private key has been generated or set, calling this function only updates + * the public key but does not generate a new private key. * @since v0.5.0 * @param encoding The `encoding` of the return value. */ @@ -1509,8 +1634,16 @@ declare module 'crypto' { */ computeSecret(otherPublicKey: NodeJS.ArrayBufferView, inputEncoding?: null, outputEncoding?: null): Buffer; computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding, outputEncoding?: null): Buffer; - computeSecret(otherPublicKey: NodeJS.ArrayBufferView, inputEncoding: null, outputEncoding: BinaryToTextEncoding): string; - computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding, outputEncoding: BinaryToTextEncoding): string; + computeSecret( + otherPublicKey: NodeJS.ArrayBufferView, + inputEncoding: null, + outputEncoding: BinaryToTextEncoding, + ): string; + computeSecret( + otherPublicKey: string, + inputEncoding: BinaryToTextEncoding, + outputEncoding: BinaryToTextEncoding, + ): string; /** * Returns the Diffie-Hellman prime in the specified `encoding`. * If `encoding` is provided a string is @@ -1560,6 +1693,9 @@ declare module 'crypto' { * Sets the Diffie-Hellman private key. If the `encoding` argument is provided,`privateKey` is expected * to be a string. If no `encoding` is provided, `privateKey` is expected * to be a `Buffer`, `TypedArray`, or `DataView`. + * + * This function does not automatically compute the associated public key. Either `diffieHellman.setPublicKey()` or `diffieHellman.generateKeys()` can be + * used to manually provide the public key or to automatically derive it. * @since v0.5.0 * @param encoding The `encoding` of the `privateKey` string. */ @@ -1569,7 +1705,7 @@ declare module 'crypto' { * A bit field containing any warnings and/or errors resulting from a check * performed during initialization of the `DiffieHellman` object. * - * The following values are valid for this property (as defined in `constants`module): + * The following values are valid for this property (as defined in `node:constants` module): * * * `DH_CHECK_P_NOT_SAFE_PRIME` * * `DH_CHECK_P_NOT_PRIME` @@ -1608,12 +1744,12 @@ declare module 'crypto' { (name: string): DiffieHellmanGroup; readonly prototype: DiffieHellmanGroup; } - type DiffieHellmanGroup = Omit; + type DiffieHellmanGroup = Omit; /** * Creates a predefined `DiffieHellmanGroup` key exchange object. The - * supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in [RFC 2412](https://www.rfc-editor.org/rfc/rfc2412.txt), but see `Caveats`) and `'modp14'`, `'modp15'`,`'modp16'`, `'modp17'`, - * `'modp18'` (defined in [RFC 3526](https://www.rfc-editor.org/rfc/rfc3526.txt)). The - * returned object mimics the interface of objects created by {@link createDiffieHellman}, but will not allow changing + * supported groups are listed in the documentation for `DiffieHellmanGroup`. + * + * The returned object mimics the interface of objects created by {@link createDiffieHellman}, but will not allow changing * the keys (with `diffieHellman.setPublicKey()`, for example). The * advantage of using this method is that the parties do not have to * generate nor exchange a group modulus beforehand, saving both processor @@ -1623,8 +1759,8 @@ declare module 'crypto' { * * ```js * const { - * getDiffieHellman - * } = await import('crypto'); + * getDiffieHellman, + * } = await import('node:crypto'); * const alice = getDiffieHellman('modp14'); * const bob = getDiffieHellman('modp14'); * @@ -1654,9 +1790,6 @@ declare module 'crypto' { * otherwise `err` will be `null`. By default, the successfully generated`derivedKey` will be passed to the callback as a `Buffer`. An error will be * thrown if any of the input arguments specify invalid values or types. * - * If `digest` is `null`, `'sha1'` will be used. This behavior is deprecated, - * please specify a `digest` explicitly. - * * The `iterations` argument must be a number set as high as possible. The * higher the number of iterations, the more secure the derived key will be, * but will take a longer amount of time to complete. @@ -1668,8 +1801,8 @@ declare module 'crypto' { * * ```js * const { - * pbkdf2 - * } = await import('crypto'); + * pbkdf2, + * } = await import('node:crypto'); * * pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => { * if (err) throw err; @@ -1677,25 +1810,20 @@ declare module 'crypto' { * }); * ``` * - * The `crypto.DEFAULT_ENCODING` property can be used to change the way the`derivedKey` is passed to the callback. This property, however, has been - * deprecated and use should be avoided. - * - * ```js - * import crypto from 'crypto'; - * crypto.DEFAULT_ENCODING = 'hex'; - * crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => { - * if (err) throw err; - * console.log(derivedKey); // '3745e48...aa39b34' - * }); - * ``` - * * An array of supported digest functions can be retrieved using {@link getHashes}. * * This API uses libuv's threadpool, which can have surprising and * negative performance implications for some applications; see the `UV_THREADPOOL_SIZE` documentation for more information. * @since v0.5.5 */ - function pbkdf2(password: BinaryLike, salt: BinaryLike, iterations: number, keylen: number, digest: string, callback: (err: Error | null, derivedKey: Buffer) => void): void; + function pbkdf2( + password: BinaryLike, + salt: BinaryLike, + iterations: number, + keylen: number, + digest: string, + callback: (err: Error | null, derivedKey: Buffer) => void, + ): void; /** * Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2) * implementation. A selected HMAC digest algorithm specified by `digest` is @@ -1704,9 +1832,6 @@ declare module 'crypto' { * If an error occurs an `Error` will be thrown, otherwise the derived key will be * returned as a `Buffer`. * - * If `digest` is `null`, `'sha1'` will be used. This behavior is deprecated, - * please specify a `digest` explicitly. - * * The `iterations` argument must be a number set as high as possible. The * higher the number of iterations, the more secure the derived key will be, * but will take a longer amount of time to complete. @@ -1718,27 +1843,23 @@ declare module 'crypto' { * * ```js * const { - * pbkdf2Sync - * } = await import('crypto'); + * pbkdf2Sync, + * } = await import('node:crypto'); * * const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512'); * console.log(key.toString('hex')); // '3745e48...08d59ae' * ``` * - * The `crypto.DEFAULT_ENCODING` property may be used to change the way the`derivedKey` is returned. This property, however, is deprecated and use - * should be avoided. - * - * ```js - * import crypto from 'crypto'; - * crypto.DEFAULT_ENCODING = 'hex'; - * const key = crypto.pbkdf2Sync('secret', 'salt', 100000, 512, 'sha512'); - * console.log(key); // '3745e48...aa39b34' - * ``` - * * An array of supported digest functions can be retrieved using {@link getHashes}. * @since v0.9.3 */ - function pbkdf2Sync(password: BinaryLike, salt: BinaryLike, iterations: number, keylen: number, digest: string): Buffer; + function pbkdf2Sync( + password: BinaryLike, + salt: BinaryLike, + iterations: number, + keylen: number, + digest: string, + ): Buffer; /** * Generates cryptographically strong pseudorandom data. The `size` argument * is a number indicating the number of bytes to generate. @@ -1750,8 +1871,8 @@ declare module 'crypto' { * ```js * // Asynchronous * const { - * randomBytes - * } = await import('crypto'); + * randomBytes, + * } = await import('node:crypto'); * * randomBytes(256, (err, buf) => { * if (err) throw err; @@ -1766,8 +1887,8 @@ declare module 'crypto' { * ```js * // Synchronous * const { - * randomBytes - * } = await import('crypto'); + * randomBytes, + * } = await import('node:crypto'); * * const buf = randomBytes(256); * console.log( @@ -1808,8 +1929,8 @@ declare module 'crypto' { * ```js * // Asynchronous * const { - * randomInt - * } = await import('crypto'); + * randomInt, + * } = await import('node:crypto'); * * randomInt(3, (err, n) => { * if (err) throw err; @@ -1820,8 +1941,8 @@ declare module 'crypto' { * ```js * // Synchronous * const { - * randomInt - * } = await import('crypto'); + * randomInt, + * } = await import('node:crypto'); * * const n = randomInt(3); * console.log(`Random number chosen from (0, 1, 2): ${n}`); @@ -1830,8 +1951,8 @@ declare module 'crypto' { * ```js * // With `min` argument * const { - * randomInt - * } = await import('crypto'); + * randomInt, + * } = await import('node:crypto'); * * const n = randomInt(1, 7); * console.log(`The dice rolled: ${n}`); @@ -1849,8 +1970,8 @@ declare module 'crypto' { * Synchronous version of {@link randomFill}. * * ```js - * import { Buffer } from 'buffer'; - * const { randomFillSync } = await import('crypto'); + * import { Buffer } from 'node:buffer'; + * const { randomFillSync } = await import('node:crypto'); * * const buf = Buffer.alloc(10); * console.log(randomFillSync(buf).toString('hex')); @@ -1866,8 +1987,8 @@ declare module 'crypto' { * Any `ArrayBuffer`, `TypedArray` or `DataView` instance may be passed as`buffer`. * * ```js - * import { Buffer } from 'buffer'; - * const { randomFillSync } = await import('crypto'); + * import { Buffer } from 'node:buffer'; + * const { randomFillSync } = await import('node:crypto'); * * const a = new Uint32Array(10); * console.log(Buffer.from(randomFillSync(a).buffer, @@ -1895,8 +2016,8 @@ declare module 'crypto' { * If the `callback` function is not provided, an error will be thrown. * * ```js - * import { Buffer } from 'buffer'; - * const { randomFill } = await import('crypto'); + * import { Buffer } from 'node:buffer'; + * const { randomFill } = await import('node:crypto'); * * const buf = Buffer.alloc(10); * randomFill(buf, (err, buf) => { @@ -1925,8 +2046,8 @@ declare module 'crypto' { * distribution and have no meaningful lower or upper bounds. * * ```js - * import { Buffer } from 'buffer'; - * const { randomFill } = await import('crypto'); + * import { Buffer } from 'node:buffer'; + * const { randomFill } = await import('node:crypto'); * * const a = new Uint32Array(10); * randomFill(a, (err, buf) => { @@ -1962,9 +2083,21 @@ declare module 'crypto' { * @param [size=buffer.length - offset] * @param callback `function(err, buf) {}`. */ - function randomFill(buffer: T, callback: (err: Error | null, buf: T) => void): void; - function randomFill(buffer: T, offset: number, callback: (err: Error | null, buf: T) => void): void; - function randomFill(buffer: T, offset: number, size: number, callback: (err: Error | null, buf: T) => void): void; + function randomFill( + buffer: T, + callback: (err: Error | null, buf: T) => void, + ): void; + function randomFill( + buffer: T, + offset: number, + callback: (err: Error | null, buf: T) => void, + ): void; + function randomFill( + buffer: T, + offset: number, + size: number, + callback: (err: Error | null, buf: T) => void, + ): void; interface ScryptOptions { cost?: number | undefined; blockSize?: number | undefined; @@ -1992,8 +2125,8 @@ declare module 'crypto' { * * ```js * const { - * scrypt - * } = await import('crypto'); + * scrypt, + * } = await import('node:crypto'); * * // Using the factory defaults. * scrypt('password', 'salt', 64, (err, derivedKey) => { @@ -2008,8 +2141,19 @@ declare module 'crypto' { * ``` * @since v10.5.0 */ - function scrypt(password: BinaryLike, salt: BinaryLike, keylen: number, callback: (err: Error | null, derivedKey: Buffer) => void): void; - function scrypt(password: BinaryLike, salt: BinaryLike, keylen: number, options: ScryptOptions, callback: (err: Error | null, derivedKey: Buffer) => void): void; + function scrypt( + password: BinaryLike, + salt: BinaryLike, + keylen: number, + callback: (err: Error | null, derivedKey: Buffer) => void, + ): void; + function scrypt( + password: BinaryLike, + salt: BinaryLike, + keylen: number, + options: ScryptOptions, + callback: (err: Error | null, derivedKey: Buffer) => void, + ): void; /** * Provides a synchronous [scrypt](https://en.wikipedia.org/wiki/Scrypt) implementation. Scrypt is a password-based * key derivation function that is designed to be expensive computationally and @@ -2028,8 +2172,8 @@ declare module 'crypto' { * * ```js * const { - * scryptSync - * } = await import('crypto'); + * scryptSync, + * } = await import('node:crypto'); * // Using the factory defaults. * * const key1 = scryptSync('password', 'salt', 64); @@ -2100,8 +2244,8 @@ declare module 'crypto' { /** * ```js * const { - * getCiphers - * } = await import('crypto'); + * getCiphers, + * } = await import('node:crypto'); * * console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...] * ``` @@ -2112,8 +2256,8 @@ declare module 'crypto' { /** * ```js * const { - * getCurves - * } = await import('crypto'); + * getCurves, + * } = await import('node:crypto'); * * console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...] * ``` @@ -2127,7 +2271,8 @@ declare module 'crypto' { */ function getFips(): 1 | 0; /** - * Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build. Throws an error if FIPS mode is not available. + * Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build. + * Throws an error if FIPS mode is not available. * @since v10.0.0 * @param bool `true` to enable FIPS mode. */ @@ -2135,8 +2280,8 @@ declare module 'crypto' { /** * ```js * const { - * getHashes - * } = await import('crypto'); + * getHashes, + * } = await import('node:crypto'); * * console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...] * ``` @@ -2151,11 +2296,11 @@ declare module 'crypto' { * Instances of the `ECDH` class can be created using the {@link createECDH} function. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * const { - * createECDH - * } = await import('crypto'); + * createECDH, + * } = await import('node:crypto'); * * // Generate Alice's keys... * const alice = createECDH('secp521r1'); @@ -2196,8 +2341,8 @@ declare module 'crypto' { * ```js * const { * createECDH, - * ECDH - * } = await import('crypto'); + * ECDH, + * } = await import('node:crypto'); * * const ecdh = createECDH('secp256k1'); * ecdh.generateKeys(); @@ -2222,8 +2367,8 @@ declare module 'crypto' { key: BinaryLike, curve: string, inputEncoding?: BinaryToTextEncoding, - outputEncoding?: 'latin1' | 'hex' | 'base64' | 'base64url', - format?: 'uncompressed' | 'compressed' | 'hybrid' + outputEncoding?: "latin1" | "hex" | "base64" | "base64url", + format?: "uncompressed" | "compressed" | "hybrid", ): Buffer | string; /** * Generates private and public EC Diffie-Hellman key values, and returns @@ -2259,7 +2404,11 @@ declare module 'crypto' { computeSecret(otherPublicKey: NodeJS.ArrayBufferView): Buffer; computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding): Buffer; computeSecret(otherPublicKey: NodeJS.ArrayBufferView, outputEncoding: BinaryToTextEncoding): string; - computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding, outputEncoding: BinaryToTextEncoding): string; + computeSecret( + otherPublicKey: string, + inputEncoding: BinaryToTextEncoding, + outputEncoding: BinaryToTextEncoding, + ): string; /** * If `encoding` is specified, a string is returned; otherwise a `Buffer` is * returned. @@ -2279,7 +2428,7 @@ declare module 'crypto' { * @param [format='uncompressed'] * @return The EC Diffie-Hellman public key in the specified `encoding` and `format`. */ - getPublicKey(): Buffer; + getPublicKey(encoding?: null, format?: ECDHKeyFormat): Buffer; getPublicKey(encoding: BinaryToTextEncoding, format?: ECDHKeyFormat): string; /** * Sets the EC Diffie-Hellman private key. @@ -2304,28 +2453,33 @@ declare module 'crypto' { */ function createECDH(curveName: string): ECDH; /** - * This function is based on a constant-time algorithm. - * Returns true if `a` is equal to `b`, without leaking timing information that + * This function compares the underlying bytes that represent the given`ArrayBuffer`, `TypedArray`, or `DataView` instances using a constant-time + * algorithm. + * + * This function does not leak timing information that * would allow an attacker to guess one of the values. This is suitable for * comparing HMAC digests or secret values like authentication cookies or [capability urls](https://www.w3.org/TR/capability-urls/). * * `a` and `b` must both be `Buffer`s, `TypedArray`s, or `DataView`s, and they - * must have the same byte length. + * must have the same byte length. An error is thrown if `a` and `b` have + * different byte lengths. * * If at least one of `a` and `b` is a `TypedArray` with more than one byte per * entry, such as `Uint16Array`, the result will be computed using the platform * byte order. * + * **When both of the inputs are `Float32Array`s or`Float64Array`s, this function might return unexpected results due to IEEE 754** + * **encoding of floating-point numbers. In particular, neither `x === y` nor`Object.is(x, y)` implies that the byte representations of two floating-point** + * **numbers `x` and `y` are equal.** + * * Use of `crypto.timingSafeEqual` does not guarantee that the _surrounding_ code * is timing-safe. Care should be taken to ensure that the surrounding code does * not introduce timing vulnerabilities. * @since v6.6.0 */ function timingSafeEqual(a: NodeJS.ArrayBufferView, b: NodeJS.ArrayBufferView): boolean; - /** @deprecated since v10.0.0 */ - const DEFAULT_ENCODING: BufferEncoding; - type KeyType = 'rsa' | 'rsa-pss' | 'dsa' | 'ec' | 'ed25519' | 'ed448' | 'x25519' | 'x448'; - type KeyFormat = 'pem' | 'der'; + type KeyType = "rsa" | "rsa-pss" | "dsa" | "ec" | "ed25519" | "ed448" | "x25519" | "x448"; + type KeyFormat = "pem" | "der" | "jwk"; interface BasePrivateKeyEncodingOptions { format: T; cipher?: string | undefined; @@ -2344,6 +2498,10 @@ declare module 'crypto' { * Name of the curve to use */ namedCurve: string; + /** + * Must be `'named'` or `'explicit'`. Default: `'named'`. + */ + paramEncoding?: "explicit" | "named" | undefined; } interface RSAKeyPairKeyObjectOptions { /** @@ -2400,11 +2558,11 @@ declare module 'crypto' { */ publicExponent?: number | undefined; publicKeyEncoding: { - type: 'pkcs1' | 'spki'; + type: "pkcs1" | "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs1' | 'pkcs8'; + type: "pkcs1" | "pkcs8"; }; } interface RSAPSSKeyPairOptions { @@ -2430,11 +2588,11 @@ declare module 'crypto' { */ saltLength?: string; publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } interface DSAKeyPairOptions { @@ -2447,60 +2605,56 @@ declare module 'crypto' { */ divisorLength: number; publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } - interface ECKeyPairOptions { - /** - * Name of the curve to use. - */ - namedCurve: string; + interface ECKeyPairOptions extends ECKeyPairKeyObjectOptions { publicKeyEncoding: { - type: 'pkcs1' | 'spki'; + type: "pkcs1" | "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'sec1' | 'pkcs8'; + type: "sec1" | "pkcs8"; }; } interface ED25519KeyPairOptions { publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } interface ED448KeyPairOptions { publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } interface X25519KeyPairOptions { publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } interface X448KeyPairOptions { publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } interface KeyPairSyncResult { @@ -2521,8 +2675,8 @@ declare module 'crypto' { * * ```js * const { - * generateKeyPairSync - * } = await import('crypto'); + * generateKeyPairSync, + * } = await import('node:crypto'); * * const { * publicKey, @@ -2531,14 +2685,14 @@ declare module 'crypto' { * modulusLength: 4096, * publicKeyEncoding: { * type: 'spki', - * format: 'pem' + * format: 'pem', * }, * privateKeyEncoding: { * type: 'pkcs8', * format: 'pem', * cipher: 'aes-256-cbc', - * passphrase: 'top secret' - * } + * passphrase: 'top secret', + * }, * }); * ``` * @@ -2548,46 +2702,142 @@ declare module 'crypto' { * @since v10.12.0 * @param type Must be `'rsa'`, `'rsa-pss'`, `'dsa'`, `'ec'`, `'ed25519'`, `'ed448'`, `'x25519'`, `'x448'`, or `'dh'`. */ - function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa', options: RSAKeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa-pss', options: RSAPSSKeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'dsa', options: DSAKeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ec', options: ECKeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed25519', options?: ED25519KeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed448', options?: ED448KeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x25519', options?: X25519KeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x448', options?: X448KeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "rsa", + options: RSAKeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa", + options: RSAKeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa", + options: RSAKeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa", + options: RSAKeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "rsa", options: RSAKeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "rsa-pss", options: RSAPSSKeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "dsa", + options: DSAKeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "dsa", + options: DSAKeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "dsa", + options: DSAKeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "dsa", + options: DSAKeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "dsa", options: DSAKeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "ec", + options: ECKeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ec", + options: ECKeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ec", + options: ECKeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ec", + options: ECKeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "ec", options: ECKeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed25519", + options: ED25519KeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed25519", + options: ED25519KeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "ed25519", options?: ED25519KeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "ed448", + options: ED448KeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed448", + options: ED448KeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed448", + options: ED448KeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed448", + options: ED448KeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "ed448", options?: ED448KeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "x25519", + options: X25519KeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x25519", + options: X25519KeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x25519", + options: X25519KeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x25519", + options: X25519KeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "x25519", options?: X25519KeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "x448", + options: X448KeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x448", + options: X448KeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x448", + options: X448KeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x448", + options: X448KeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "x448", options?: X448KeyPairKeyObjectOptions): KeyPairKeyObjectResult; /** * Generates a new asymmetric key pair of the given `type`. RSA, RSA-PSS, DSA, EC, * Ed25519, Ed448, X25519, X448, and DH are currently supported. @@ -2600,21 +2850,21 @@ declare module 'crypto' { * * ```js * const { - * generateKeyPair - * } = await import('crypto'); + * generateKeyPair, + * } = await import('node:crypto'); * * generateKeyPair('rsa', { * modulusLength: 4096, * publicKeyEncoding: { * type: 'spki', - * format: 'pem' + * format: 'pem', * }, * privateKeyEncoding: { * type: 'pkcs8', * format: 'pem', * cipher: 'aes-256-cbc', - * passphrase: 'top secret' - * } + * passphrase: 'top secret', + * }, * }, (err, publicKey, privateKey) => { * // Handle errors and use the generated key pair. * }); @@ -2627,279 +2877,448 @@ declare module 'crypto' { * @since v10.12.0 * @param type Must be `'rsa'`, `'rsa-pss'`, `'dsa'`, `'ec'`, `'ed25519'`, `'ed448'`, `'x25519'`, `'x448'`, or `'dh'`. */ - function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'rsa', options: RSAKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'rsa-pss', options: RSAPSSKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'dsa', options: DSAKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ec', options: ECKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ed25519', options: ED25519KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ed448', options: ED448KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'x25519', options: X25519KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'x448', options: X448KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; + function generateKeyPair( + type: "rsa", + options: RSAKeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "rsa", + options: RSAKeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "rsa", + options: RSAKeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "rsa", + options: RSAKeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "rsa", + options: RSAKeyPairKeyObjectOptions, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "rsa-pss", + options: RSAPSSKeyPairKeyObjectOptions, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "dsa", + options: DSAKeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "dsa", + options: DSAKeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "dsa", + options: DSAKeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "dsa", + options: DSAKeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "dsa", + options: DSAKeyPairKeyObjectOptions, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "ec", + options: ECKeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ec", + options: ECKeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ec", + options: ECKeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ec", + options: ECKeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ec", + options: ECKeyPairKeyObjectOptions, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ed25519", + options: ED25519KeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ed25519", + options: ED25519KeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ed25519", + options: ED25519KeyPairKeyObjectOptions | undefined, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "ed448", + options: ED448KeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ed448", + options: ED448KeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ed448", + options: ED448KeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ed448", + options: ED448KeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ed448", + options: ED448KeyPairKeyObjectOptions | undefined, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "x25519", + options: X25519KeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "x25519", + options: X25519KeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "x25519", + options: X25519KeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "x25519", + options: X25519KeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "x25519", + options: X25519KeyPairKeyObjectOptions | undefined, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "x448", + options: X448KeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "x448", + options: X448KeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "x448", + options: X448KeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "x448", + options: X448KeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "x448", + options: X448KeyPairKeyObjectOptions | undefined, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; namespace generateKeyPair { function __promisify__( - type: 'rsa', - options: RSAKeyPairOptions<'pem', 'pem'> + type: "rsa", + options: RSAKeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'rsa', - options: RSAKeyPairOptions<'pem', 'der'> + type: "rsa", + options: RSAKeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'rsa', - options: RSAKeyPairOptions<'der', 'pem'> + type: "rsa", + options: RSAKeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'rsa', - options: RSAKeyPairOptions<'der', 'der'> + type: "rsa", + options: RSAKeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'rsa', options: RSAKeyPairKeyObjectOptions): Promise; + function __promisify__(type: "rsa", options: RSAKeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'rsa-pss', - options: RSAPSSKeyPairOptions<'pem', 'pem'> + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'rsa-pss', - options: RSAPSSKeyPairOptions<'pem', 'der'> + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'rsa-pss', - options: RSAPSSKeyPairOptions<'der', 'pem'> + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'rsa-pss', - options: RSAPSSKeyPairOptions<'der', 'der'> + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'rsa-pss', options: RSAPSSKeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'dsa', - options: DSAKeyPairOptions<'pem', 'pem'> + type: "rsa-pss", + options: RSAPSSKeyPairKeyObjectOptions, + ): Promise; + function __promisify__( + type: "dsa", + options: DSAKeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'dsa', - options: DSAKeyPairOptions<'pem', 'der'> + type: "dsa", + options: DSAKeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'dsa', - options: DSAKeyPairOptions<'der', 'pem'> + type: "dsa", + options: DSAKeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'dsa', - options: DSAKeyPairOptions<'der', 'der'> + type: "dsa", + options: DSAKeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'dsa', options: DSAKeyPairKeyObjectOptions): Promise; + function __promisify__(type: "dsa", options: DSAKeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'ec', - options: ECKeyPairOptions<'pem', 'pem'> + type: "ec", + options: ECKeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'ec', - options: ECKeyPairOptions<'pem', 'der'> + type: "ec", + options: ECKeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'ec', - options: ECKeyPairOptions<'der', 'pem'> + type: "ec", + options: ECKeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'ec', - options: ECKeyPairOptions<'der', 'der'> + type: "ec", + options: ECKeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'ec', options: ECKeyPairKeyObjectOptions): Promise; + function __promisify__(type: "ec", options: ECKeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'ed25519', - options: ED25519KeyPairOptions<'pem', 'pem'> + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'ed25519', - options: ED25519KeyPairOptions<'pem', 'der'> + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'ed25519', - options: ED25519KeyPairOptions<'der', 'pem'> + type: "ed25519", + options: ED25519KeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'ed25519', - options: ED25519KeyPairOptions<'der', 'der'> + type: "ed25519", + options: ED25519KeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'ed25519', options?: ED25519KeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'ed448', - options: ED448KeyPairOptions<'pem', 'pem'> + type: "ed25519", + options?: ED25519KeyPairKeyObjectOptions, + ): Promise; + function __promisify__( + type: "ed448", + options: ED448KeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'ed448', - options: ED448KeyPairOptions<'pem', 'der'> + type: "ed448", + options: ED448KeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'ed448', - options: ED448KeyPairOptions<'der', 'pem'> + type: "ed448", + options: ED448KeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'ed448', - options: ED448KeyPairOptions<'der', 'der'> + type: "ed448", + options: ED448KeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'ed448', options?: ED448KeyPairKeyObjectOptions): Promise; + function __promisify__(type: "ed448", options?: ED448KeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'x25519', - options: X25519KeyPairOptions<'pem', 'pem'> + type: "x25519", + options: X25519KeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'x25519', - options: X25519KeyPairOptions<'pem', 'der'> + type: "x25519", + options: X25519KeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'x25519', - options: X25519KeyPairOptions<'der', 'pem'> + type: "x25519", + options: X25519KeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'x25519', - options: X25519KeyPairOptions<'der', 'der'> + type: "x25519", + options: X25519KeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'x25519', options?: X25519KeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'x448', - options: X448KeyPairOptions<'pem', 'pem'> + type: "x25519", + options?: X25519KeyPairKeyObjectOptions, + ): Promise; + function __promisify__( + type: "x448", + options: X448KeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'x448', - options: X448KeyPairOptions<'pem', 'der'> + type: "x448", + options: X448KeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'x448', - options: X448KeyPairOptions<'der', 'pem'> + type: "x448", + options: X448KeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'x448', - options: X448KeyPairOptions<'der', 'der'> + type: "x448", + options: X448KeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'x448', options?: X448KeyPairKeyObjectOptions): Promise; + function __promisify__(type: "x448", options?: X448KeyPairKeyObjectOptions): Promise; } /** * Calculates and returns the signature for `data` using the given private key and @@ -2913,12 +3332,16 @@ declare module 'crypto' { * If the `callback` function is provided this function uses libuv's threadpool. * @since v12.0.0 */ - function sign(algorithm: string | null | undefined, data: NodeJS.ArrayBufferView, key: KeyLike | SignKeyObjectInput | SignPrivateKeyInput): Buffer; function sign( algorithm: string | null | undefined, data: NodeJS.ArrayBufferView, key: KeyLike | SignKeyObjectInput | SignPrivateKeyInput, - callback: (error: Error | null, data: Buffer) => void + ): Buffer; + function sign( + algorithm: string | null | undefined, + data: NodeJS.ArrayBufferView, + key: KeyLike | SignKeyObjectInput | SignPrivateKeyInput, + callback: (error: Error | null, data: Buffer) => void, ): void; /** * Verifies the given signature for `data` using the given key and algorithm. If`algorithm` is `null` or `undefined`, then the algorithm is dependent upon the @@ -2936,13 +3359,18 @@ declare module 'crypto' { * If the `callback` function is provided this function uses libuv's threadpool. * @since v12.0.0 */ - function verify(algorithm: string | null | undefined, data: NodeJS.ArrayBufferView, key: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, signature: NodeJS.ArrayBufferView): boolean; function verify( algorithm: string | null | undefined, data: NodeJS.ArrayBufferView, - key: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, + key: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput | VerifyJsonWebKeyInput, signature: NodeJS.ArrayBufferView, - callback: (error: Error | null, result: boolean) => void + ): boolean; + function verify( + algorithm: string | null | undefined, + data: NodeJS.ArrayBufferView, + key: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput | VerifyJsonWebKeyInput, + signature: NodeJS.ArrayBufferView, + callback: (error: Error | null, result: boolean) => void, ): void; /** * Computes the Diffie-Hellman secret based on a `privateKey` and a `publicKey`. @@ -2950,7 +3378,7 @@ declare module 'crypto' { * @since v13.9.0, v12.17.0 */ function diffieHellman(options: { privateKey: KeyObject; publicKey: KeyObject }): Buffer; - type CipherMode = 'cbc' | 'ccm' | 'cfb' | 'ctr' | 'ecb' | 'gcm' | 'ocb' | 'ofb' | 'stream' | 'wrap' | 'xts'; + type CipherMode = "cbc" | "ccm" | "cfb" | "ctr" | "ecb" | "gcm" | "ocb" | "ofb" | "stream" | "wrap" | "xts"; interface CipherInfoOptions { /** * A test key length. @@ -3010,10 +3438,10 @@ declare module 'crypto' { * of the input arguments specify invalid values or types. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * const { - * hkdf - * } = await import('crypto'); + * hkdf, + * } = await import('node:crypto'); * * hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => { * if (err) throw err; @@ -3022,13 +3450,20 @@ declare module 'crypto' { * ``` * @since v15.0.0 * @param digest The digest algorithm to use. - * @param ikm The input keying material. It must be at least one byte in length. + * @param ikm The input keying material. Must be provided but can be zero-length. * @param salt The salt value. Must be provided but can be zero-length. * @param info Additional info value. Must be provided but can be zero-length, and cannot be more than 1024 bytes. * @param keylen The length of the key to generate. Must be greater than 0. The maximum allowable value is `255` times the number of bytes produced by the selected digest function (e.g. `sha512` * generates 64-byte hashes, making the maximum HKDF output 16320 bytes). */ - function hkdf(digest: string, irm: BinaryLike | KeyObject, salt: BinaryLike, info: BinaryLike, keylen: number, callback: (err: Error | null, derivedKey: ArrayBuffer) => void): void; + function hkdf( + digest: string, + irm: BinaryLike | KeyObject, + salt: BinaryLike, + info: BinaryLike, + keylen: number, + callback: (err: Error | null, derivedKey: ArrayBuffer) => void, + ): void; /** * Provides a synchronous HKDF key derivation function as defined in RFC 5869\. The * given `ikm`, `salt` and `info` are used with the `digest` to derive a key of`keylen` bytes. @@ -3039,23 +3474,29 @@ declare module 'crypto' { * types, or if the derived key cannot be generated. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * const { - * hkdfSync - * } = await import('crypto'); + * hkdfSync, + * } = await import('node:crypto'); * * const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64); * console.log(Buffer.from(derivedKey).toString('hex')); // '24156e2...5391653' * ``` * @since v15.0.0 * @param digest The digest algorithm to use. - * @param ikm The input keying material. It must be at least one byte in length. + * @param ikm The input keying material. Must be provided but can be zero-length. * @param salt The salt value. Must be provided but can be zero-length. * @param info Additional info value. Must be provided but can be zero-length, and cannot be more than 1024 bytes. * @param keylen The length of the key to generate. Must be greater than 0. The maximum allowable value is `255` times the number of bytes produced by the selected digest function (e.g. `sha512` * generates 64-byte hashes, making the maximum HKDF output 16320 bytes). */ - function hkdfSync(digest: string, ikm: BinaryLike | KeyObject, salt: BinaryLike, info: BinaryLike, keylen: number): ArrayBuffer; + function hkdfSync( + digest: string, + ikm: BinaryLike | KeyObject, + salt: BinaryLike, + info: BinaryLike, + keylen: number, + ): ArrayBuffer; interface SecureHeapUsage { /** * The total allocated secure heap size as specified using the `--secure-heap=n` command-line flag. @@ -3089,40 +3530,41 @@ declare module 'crypto' { */ disableEntropyCache?: boolean | undefined; } + type UUID = `${string}-${string}-${string}-${string}-${string}`; /** * Generates a random [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122.txt) version 4 UUID. The UUID is generated using a * cryptographic pseudorandom number generator. - * @since v15.6.0 + * @since v15.6.0, v14.17.0 */ - function randomUUID(options?: RandomUUIDOptions): string; + function randomUUID(options?: RandomUUIDOptions): UUID; interface X509CheckOptions { /** * @default 'always' */ - subject: 'always' | 'never'; + subject?: "always" | "default" | "never"; /** * @default true */ - wildcards: boolean; + wildcards?: boolean; /** * @default true */ - partialWildcards: boolean; + partialWildcards?: boolean; /** * @default false */ - multiLabelWildcards: boolean; + multiLabelWildcards?: boolean; /** * @default false */ - singleLabelSubdomains: boolean; + singleLabelSubdomains?: boolean; } /** * Encapsulates an X509 certificate and provides read-only access to * its information. * * ```js - * const { X509Certificate } = await import('crypto'); + * const { X509Certificate } = await import('node:crypto'); * * const x509 = new X509Certificate('{... pem encoded cert ...}'); * @@ -3132,12 +3574,16 @@ declare module 'crypto' { */ class X509Certificate { /** - * Will be \`true\` if this is a Certificate Authority (ca) certificate. + * Will be \`true\` if this is a Certificate Authority (CA) certificate. * @since v15.6.0 */ readonly ca: boolean; /** * The SHA-1 fingerprint of this certificate. + * + * Because SHA-1 is cryptographically broken and because the security of SHA-1 is + * significantly worse than that of algorithms that are commonly used to sign + * certificates, consider using `x509.fingerprint256` instead. * @since v15.6.0 */ readonly fingerprint: string; @@ -3148,23 +3594,53 @@ declare module 'crypto' { readonly fingerprint256: string; /** * The SHA-512 fingerprint of this certificate. - * @since v16.14.0 + * + * Because computing the SHA-256 fingerprint is usually faster and because it is + * only half the size of the SHA-512 fingerprint, `x509.fingerprint256` may be + * a better choice. While SHA-512 presumably provides a higher level of security in + * general, the security of SHA-256 matches that of most algorithms that are + * commonly used to sign certificates. + * @since v17.2.0, v16.14.0 */ - readonly fingerprint512: string; + readonly fingerprint512: string; /** * The complete subject of this certificate. * @since v15.6.0 */ readonly subject: string; /** - * The subject alternative name specified for this certificate or `undefined` - * if not available. + * The subject alternative name specified for this certificate. + * + * This is a comma-separated list of subject alternative names. Each entry begins + * with a string identifying the kind of the subject alternative name followed by + * a colon and the value associated with the entry. + * + * Earlier versions of Node.js incorrectly assumed that it is safe to split this + * property at the two-character sequence `', '` (see [CVE-2021-44532](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44532)). However, + * both malicious and legitimate certificates can contain subject alternative names + * that include this sequence when represented as a string. + * + * After the prefix denoting the type of the entry, the remainder of each entry + * might be enclosed in quotes to indicate that the value is a JSON string literal. + * For backward compatibility, Node.js only uses JSON string literals within this + * property when necessary to avoid ambiguity. Third-party code should be prepared + * to handle both possible entry formats. * @since v15.6.0 */ readonly subjectAltName: string | undefined; /** - * The information access content of this certificate or `undefined` if not - * available. + * A textual representation of the certificate's authority information access + * extension. + * + * This is a line feed separated list of access descriptions. Each line begins with + * the access method and the kind of the access location, followed by a colon and + * the value associated with the access location. + * + * After the prefix denoting the access method and the kind of the access location, + * the remainder of each line might be enclosed in quotes to indicate that the + * value is a JSON string literal. For backward compatibility, Node.js only uses + * JSON string literals within this property when necessary to avoid ambiguity. + * Third-party code should be prepared to handle both possible entry formats. * @since v15.6.0 */ readonly infoAccess: string | undefined; @@ -3196,6 +3672,10 @@ declare module 'crypto' { readonly raw: Buffer; /** * The serial number of this certificate. + * + * Serial numbers are assigned by certificate authorities and do not uniquely + * identify certificates. Consider using `x509.fingerprint256` as a unique + * identifier instead. * @since v15.6.0 */ readonly serialNumber: string; @@ -3212,18 +3692,50 @@ declare module 'crypto' { constructor(buffer: BinaryLike); /** * Checks whether the certificate matches the given email address. + * + * If the `'subject'` option is undefined or set to `'default'`, the certificate + * subject is only considered if the subject alternative name extension either does + * not exist or does not contain any email addresses. + * + * If the `'subject'` option is set to `'always'` and if the subject alternative + * name extension either does not exist or does not contain a matching email + * address, the certificate subject is considered. + * + * If the `'subject'` option is set to `'never'`, the certificate subject is never + * considered, even if the certificate contains no subject alternative names. * @since v15.6.0 * @return Returns `email` if the certificate matches, `undefined` if it does not. */ - checkEmail(email: string, options?: Pick): string | undefined; + checkEmail(email: string, options?: Pick): string | undefined; /** * Checks whether the certificate matches the given host name. + * + * If the certificate matches the given host name, the matching subject name is + * returned. The returned name might be an exact match (e.g., `foo.example.com`) + * or it might contain wildcards (e.g., `*.example.com`). Because host name + * comparisons are case-insensitive, the returned subject name might also differ + * from the given `name` in capitalization. + * + * If the `'subject'` option is undefined or set to `'default'`, the certificate + * subject is only considered if the subject alternative name extension either does + * not exist or does not contain any DNS names. This behavior is consistent with [RFC 2818](https://www.rfc-editor.org/rfc/rfc2818.txt) ("HTTP Over TLS"). + * + * If the `'subject'` option is set to `'always'` and if the subject alternative + * name extension either does not exist or does not contain a matching DNS name, + * the certificate subject is considered. + * + * If the `'subject'` option is set to `'never'`, the certificate subject is never + * considered, even if the certificate contains no subject alternative names. * @since v15.6.0 - * @return Returns `name` if the certificate matches, `undefined` if it does not. + * @return Returns a subject name that matches `name`, or `undefined` if no subject name matches `name`. */ checkHost(name: string, options?: X509CheckOptions): string | undefined; /** * Checks whether the certificate matches the given IP address (IPv4 or IPv6). + * + * Only [RFC 5280](https://www.rfc-editor.org/rfc/rfc5280.txt) `iPAddress` subject alternative names are considered, and they + * must match the given `ip` address exactly. Other subject alternative names as + * well as the subject field of the certificate are ignored. * @since v15.6.0 * @return Returns `ip` if the certificate matches, `undefined` if it does not. */ @@ -3308,9 +3820,21 @@ declare module 'crypto' { * @param size The size (in bits) of the prime to generate. */ function generatePrime(size: number, callback: (err: Error | null, prime: ArrayBuffer) => void): void; - function generatePrime(size: number, options: GeneratePrimeOptionsBigInt, callback: (err: Error | null, prime: bigint) => void): void; - function generatePrime(size: number, options: GeneratePrimeOptionsArrayBuffer, callback: (err: Error | null, prime: ArrayBuffer) => void): void; - function generatePrime(size: number, options: GeneratePrimeOptions, callback: (err: Error | null, prime: ArrayBuffer | bigint) => void): void; + function generatePrime( + size: number, + options: GeneratePrimeOptionsBigInt, + callback: (err: Error | null, prime: bigint) => void, + ): void; + function generatePrime( + size: number, + options: GeneratePrimeOptionsArrayBuffer, + callback: (err: Error | null, prime: ArrayBuffer) => void, + ): void; + function generatePrime( + size: number, + options: GeneratePrimeOptions, + callback: (err: Error | null, prime: ArrayBuffer | bigint) => void, + ): void; /** * Generates a pseudorandom prime of `size` bits. * @@ -3345,7 +3869,7 @@ declare module 'crypto' { interface CheckPrimeOptions { /** * The number of Miller-Rabin probabilistic primality iterations to perform. - * When the value is 0 (zero), a number of checks is used that yields a false positive rate of at most 2-64 for random input. + * When the value is 0 (zero), a number of checks is used that yields a false positive rate of at most `2**-64` for random input. * Care must be used when selecting a number of checks. * Refer to the OpenSSL documentation for the BN_is_prime_ex function nchecks options for more details. * @@ -3359,7 +3883,11 @@ declare module 'crypto' { * @param candidate A possible prime encoded as a sequence of big endian octets of arbitrary length. */ function checkPrime(value: LargeNumberLike, callback: (err: Error | null, result: boolean) => void): void; - function checkPrime(value: LargeNumberLike, options: CheckPrimeOptions, callback: (err: Error | null, result: boolean) => void): void; + function checkPrime( + value: LargeNumberLike, + options: CheckPrimeOptions, + callback: (err: Error | null, result: boolean) => void, + ): void; /** * Checks the primality of the `candidate`. * @since v15.8.0 @@ -3372,30 +3900,36 @@ declare module 'crypto' { * * `engine` could be either an id or a path to the engine's shared library. * - * The optional `flags` argument uses `ENGINE_METHOD_ALL` by default. - * The `flags` is a bit field taking one of or a mix of the following flags (defined in `crypto.constants`): + * The optional `flags` argument uses `ENGINE_METHOD_ALL` by default. The `flags`is a bit field taking one of or a mix of the following flags (defined in`crypto.constants`): * - * - `crypto.constants.ENGINE_METHOD_RSA` - * - `crypto.constants.ENGINE_METHOD_DSA` - * - `crypto.constants.ENGINE_METHOD_DH` - * - `crypto.constants.ENGINE_METHOD_RAND` - * - `crypto.constants.ENGINE_METHOD_EC` - * - `crypto.constants.ENGINE_METHOD_CIPHERS` - * - `crypto.constants.ENGINE_METHOD_DIGESTS` - * - `crypto.constants.ENGINE_METHOD_PKEY_METHS` - * - `crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS` - * - `crypto.constants.ENGINE_METHOD_ALL` - * - `crypto.constants.ENGINE_METHOD_NONE` - * - * The flags below are deprecated in OpenSSL-1.1.0. - * - * - `crypto.constants.ENGINE_METHOD_ECDH` - * - `crypto.constants.ENGINE_METHOD_ECDSA` - * - `crypto.constants.ENGINE_METHOD_STORE` + * * `crypto.constants.ENGINE_METHOD_RSA` + * * `crypto.constants.ENGINE_METHOD_DSA` + * * `crypto.constants.ENGINE_METHOD_DH` + * * `crypto.constants.ENGINE_METHOD_RAND` + * * `crypto.constants.ENGINE_METHOD_EC` + * * `crypto.constants.ENGINE_METHOD_CIPHERS` + * * `crypto.constants.ENGINE_METHOD_DIGESTS` + * * `crypto.constants.ENGINE_METHOD_PKEY_METHS` + * * `crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS` + * * `crypto.constants.ENGINE_METHOD_ALL` + * * `crypto.constants.ENGINE_METHOD_NONE` * @since v0.11.11 - * @param [flags=crypto.constants.ENGINE_METHOD_ALL] + * @param flags */ function setEngine(engine: string, flags?: number): void; + /** + * A convenient alias for {@link webcrypto.getRandomValues}. This + * implementation is not compliant with the Web Crypto spec, to write + * web-compatible code use {@link webcrypto.getRandomValues} instead. + * @since v17.4.0 + * @return Returns `typedArray`. + */ + function getRandomValues(typedArray: T): T; + /** + * A convenient alias for `crypto.webcrypto.subtle`. + * @since v17.4.0 + */ + const subtle: webcrypto.SubtleCrypto; /** * An implementation of the Web Crypto API standard. * @@ -3405,9 +3939,17 @@ declare module 'crypto' { const webcrypto: webcrypto.Crypto; namespace webcrypto { type BufferSource = ArrayBufferView | ArrayBuffer; - type KeyFormat = 'jwk' | 'pkcs8' | 'raw' | 'spki'; - type KeyType = 'private' | 'public' | 'secret'; - type KeyUsage = 'decrypt' | 'deriveBits' | 'deriveKey' | 'encrypt' | 'sign' | 'unwrapKey' | 'verify' | 'wrapKey'; + type KeyFormat = "jwk" | "pkcs8" | "raw" | "spki"; + type KeyType = "private" | "public" | "secret"; + type KeyUsage = + | "decrypt" + | "deriveBits" + | "deriveKey" + | "encrypt" + | "sign" + | "unwrapKey" + | "verify" + | "wrapKey"; type AlgorithmIdentifier = Algorithm | string; type HashAlgorithmIdentifier = AlgorithmIdentifier; type NamedCurve = string; @@ -3553,7 +4095,7 @@ declare module 'crypto' { * The UUID is generated using a cryptographic pseudorandom number generator. * @since v16.7.0 */ - randomUUID(): string; + randomUUID(): UUID; CryptoKey: CryptoKeyConstructor; } // This constructor throws ILLEGAL_CONSTRUCTOR so it should not be newable. @@ -3561,7 +4103,7 @@ declare module 'crypto' { /** Illegal constructor */ (_: { readonly _: unique symbol }): never; // Allows instanceof to work but not be callable by the user. readonly length: 0; - readonly name: 'CryptoKey'; + readonly name: "CryptoKey"; readonly prototype: CryptoKey; } /** @@ -3634,21 +4176,34 @@ declare module 'crypto' { * - `'AES-GCM'` * @since v15.0.0 */ - decrypt(algorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, key: CryptoKey, data: BufferSource): Promise; + decrypt( + algorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, + key: CryptoKey, + data: BufferSource, + ): Promise; /** * Using the method and parameters specified in `algorithm` and the keying material provided by `baseKey`, * `subtle.deriveBits()` attempts to generate `length` bits. - * The Node.js implementation requires that `length` is a multiple of `8`. + * The Node.js implementation requires that when `length` is a number it must be multiple of `8`. + * When `length` is `null` the maximum number of bits for a given algorithm is generated. This is allowed + * for the `'ECDH'`, `'X25519'`, and `'X448'` algorithms. * If successful, the returned promise will be resolved with an `` containing the generated data. * * The algorithms currently supported include: * * - `'ECDH'` + * - `'X25519'` + * - `'X448'` * - `'HKDF'` * - `'PBKDF2'` * @since v15.0.0 */ - deriveBits(algorithm: AlgorithmIdentifier | EcdhKeyDeriveParams | HkdfParams | Pbkdf2Params, baseKey: CryptoKey, length: number): Promise; + deriveBits(algorithm: EcdhKeyDeriveParams, baseKey: CryptoKey, length: number | null): Promise; + deriveBits( + algorithm: AlgorithmIdentifier | HkdfParams | Pbkdf2Params, + baseKey: CryptoKey, + length: number, + ): Promise; /** * Using the method and parameters specified in `algorithm`, and the keying material provided by `baseKey`, * `subtle.deriveKey()` attempts to generate a new ` based on the method and parameters in `derivedKeyAlgorithm`. @@ -3659,6 +4214,8 @@ declare module 'crypto' { * The algorithms currently supported include: * * - `'ECDH'` + * - `'X25519'` + * - `'X448'` * - `'HKDF'` * - `'PBKDF2'` * @param keyUsages See {@link https://nodejs.org/docs/latest/api/webcrypto.html#cryptokeyusages Key usages}. @@ -3667,9 +4224,14 @@ declare module 'crypto' { deriveKey( algorithm: AlgorithmIdentifier | EcdhKeyDeriveParams | HkdfParams | Pbkdf2Params, baseKey: CryptoKey, - derivedKeyAlgorithm: AlgorithmIdentifier | AesDerivedKeyParams | HmacImportParams | HkdfParams | Pbkdf2Params, + derivedKeyAlgorithm: + | AlgorithmIdentifier + | AesDerivedKeyParams + | HmacImportParams + | HkdfParams + | Pbkdf2Params, extractable: boolean, - keyUsages: ReadonlyArray + keyUsages: readonly KeyUsage[], ): Promise; /** * Using the method identified by `algorithm`, `subtle.digest()` attempts to generate a digest of `data`. @@ -3699,7 +4261,11 @@ declare module 'crypto' { * - `'AES-GCM'` * @since v15.0.0 */ - encrypt(algorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, key: CryptoKey, data: BufferSource): Promise; + encrypt( + algorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, + key: CryptoKey, + data: BufferSource, + ): Promise; /** * Exports the given key into the specified format, if supported. * @@ -3714,8 +4280,8 @@ declare module 'crypto' { * @returns `` containing ``. * @since v15.0.0 */ - exportKey(format: 'jwk', key: CryptoKey): Promise; - exportKey(format: Exclude, key: CryptoKey): Promise; + exportKey(format: "jwk", key: CryptoKey): Promise; + exportKey(format: Exclude, key: CryptoKey): Promise; /** * Using the method and parameters provided in `algorithm`, * `subtle.generateKey()` attempts to generate new keying material. @@ -3727,7 +4293,11 @@ declare module 'crypto' { * - `'RSA-PSS'` * - `'RSA-OAEP'` * - `'ECDSA'` + * - `'Ed25519'` + * - `'Ed448'` * - `'ECDH'` + * - `'X25519'` + * - `'X448'` * The `` (secret key) generating algorithms supported include: * * - `'HMAC'` @@ -3738,9 +4308,21 @@ declare module 'crypto' { * @param keyUsages See {@link https://nodejs.org/docs/latest/api/webcrypto.html#cryptokeyusages Key usages}. * @since v15.0.0 */ - generateKey(algorithm: RsaHashedKeyGenParams | EcKeyGenParams, extractable: boolean, keyUsages: ReadonlyArray): Promise; - generateKey(algorithm: AesKeyGenParams | HmacKeyGenParams | Pbkdf2Params, extractable: boolean, keyUsages: ReadonlyArray): Promise; - generateKey(algorithm: AlgorithmIdentifier, extractable: boolean, keyUsages: KeyUsage[]): Promise; + generateKey( + algorithm: RsaHashedKeyGenParams | EcKeyGenParams, + extractable: boolean, + keyUsages: readonly KeyUsage[], + ): Promise; + generateKey( + algorithm: AesKeyGenParams | HmacKeyGenParams | Pbkdf2Params, + extractable: boolean, + keyUsages: readonly KeyUsage[], + ): Promise; + generateKey( + algorithm: AlgorithmIdentifier, + extractable: boolean, + keyUsages: KeyUsage[], + ): Promise; /** * The `subtle.importKey()` method attempts to interpret the provided `keyData` as the given `format` * to create a `` instance using the provided `algorithm`, `extractable`, and `keyUsages` arguments. @@ -3752,18 +4334,28 @@ declare module 'crypto' { * @since v15.0.0 */ importKey( - format: 'jwk', + format: "jwk", keyData: JsonWebKey, - algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm, + algorithm: + | AlgorithmIdentifier + | RsaHashedImportParams + | EcKeyImportParams + | HmacImportParams + | AesKeyAlgorithm, extractable: boolean, - keyUsages: ReadonlyArray + keyUsages: readonly KeyUsage[], ): Promise; importKey( - format: Exclude, + format: Exclude, keyData: BufferSource, - algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm, + algorithm: + | AlgorithmIdentifier + | RsaHashedImportParams + | EcKeyImportParams + | HmacImportParams + | AesKeyAlgorithm, extractable: boolean, - keyUsages: KeyUsage[] + keyUsages: KeyUsage[], ): Promise; /** * Using the method and parameters given by `algorithm` and the keying material provided by `key`, @@ -3775,10 +4367,16 @@ declare module 'crypto' { * - `'RSASSA-PKCS1-v1_5'` * - `'RSA-PSS'` * - `'ECDSA'` + * - `'Ed25519'` + * - `'Ed448'` * - `'HMAC'` * @since v15.0.0 */ - sign(algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams | Ed448Params, key: CryptoKey, data: BufferSource): Promise; + sign( + algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams | Ed448Params, + key: CryptoKey, + data: BufferSource, + ): Promise; /** * In cryptography, "wrapping a key" refers to exporting and then encrypting the keying material. * The `subtle.unwrapKey()` method attempts to decrypt a wrapped key and create a `` instance. @@ -3800,7 +4398,11 @@ declare module 'crypto' { * - `'RSA-PSS'` * - `'RSA-OAEP'` * - `'ECDSA'` + * - `'Ed25519'` + * - `'Ed448'` * - `'ECDH'` + * - `'X25519'` + * - `'X448'` * - `'HMAC'` * - `'AES-CTR'` * - `'AES-CBC'` @@ -3815,9 +4417,14 @@ declare module 'crypto' { wrappedKey: BufferSource, unwrappingKey: CryptoKey, unwrapAlgorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, - unwrappedKeyAlgorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm, + unwrappedKeyAlgorithm: + | AlgorithmIdentifier + | RsaHashedImportParams + | EcKeyImportParams + | HmacImportParams + | AesKeyAlgorithm, extractable: boolean, - keyUsages: KeyUsage[] + keyUsages: KeyUsage[], ): Promise; /** * Using the method and parameters given in `algorithm` and the keying material provided by `key`, @@ -3829,10 +4436,17 @@ declare module 'crypto' { * - `'RSASSA-PKCS1-v1_5'` * - `'RSA-PSS'` * - `'ECDSA'` + * - `'Ed25519'` + * - `'Ed448'` * - `'HMAC'` * @since v15.0.0 */ - verify(algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams | Ed448Params, key: CryptoKey, signature: BufferSource, data: BufferSource): Promise; + verify( + algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams | Ed448Params, + key: CryptoKey, + signature: BufferSource, + data: BufferSource, + ): Promise; /** * In cryptography, "wrapping a key" refers to exporting and then encrypting the keying material. * The `subtle.wrapKey()` method exports the keying material into the format identified by `format`, @@ -3851,10 +4465,15 @@ declare module 'crypto' { * @param format Must be one of `'raw'`, `'pkcs8'`, `'spki'`, or `'jwk'`. * @since v15.0.0 */ - wrapKey(format: KeyFormat, key: CryptoKey, wrappingKey: CryptoKey, wrapAlgorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams): Promise; + wrapKey( + format: KeyFormat, + key: CryptoKey, + wrappingKey: CryptoKey, + wrapAlgorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, + ): Promise; } } } -declare module 'node:crypto' { - export * from 'crypto'; +declare module "node:crypto" { + export * from "crypto"; } diff --git a/node_modules/@types/node/dgram.d.ts b/node_modules/@types/node/dgram.d.ts old mode 100755 new mode 100644 index d7b9ee2..0b86ae7 --- a/node_modules/@types/node/dgram.d.ts +++ b/node_modules/@types/node/dgram.d.ts @@ -1,13 +1,13 @@ /** - * The `dgram` module provides an implementation of UDP datagram sockets. + * The `node:dgram` module provides an implementation of UDP datagram sockets. * * ```js - * import dgram from 'dgram'; + * import dgram from 'node:dgram'; * * const server = dgram.createSocket('udp4'); * * server.on('error', (err) => { - * console.log(`server error:\n${err.stack}`); + * console.error(`server error:\n${err.stack}`); * server.close(); * }); * @@ -23,15 +23,15 @@ * server.bind(41234); * // Prints: server listening 0.0.0.0:41234 * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/dgram.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/dgram.js) */ -declare module 'dgram' { - import { AddressInfo } from 'node:net'; - import * as dns from 'node:dns'; - import { EventEmitter, Abortable } from 'node:events'; +declare module "dgram" { + import { AddressInfo } from "node:net"; + import * as dns from "node:dns"; + import { Abortable, EventEmitter } from "node:events"; interface RemoteInfo { address: string; - family: 'IPv4' | 'IPv6'; + family: "IPv4" | "IPv6"; port: number; size: number; } @@ -41,7 +41,7 @@ declare module 'dgram' { exclusive?: boolean | undefined; fd?: number | undefined; } - type SocketType = 'udp4' | 'udp6'; + type SocketType = "udp4" | "udp6"; interface SocketOptions extends Abortable { type: SocketType; reuseAddr?: boolean | undefined; @@ -51,7 +51,13 @@ declare module 'dgram' { ipv6Only?: boolean | undefined; recvBufferSize?: number | undefined; sendBufferSize?: number | undefined; - lookup?: ((hostname: string, options: dns.LookupOneOptions, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void) => void) | undefined; + lookup?: + | (( + hostname: string, + options: dns.LookupOneOptions, + callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, + ) => void) + | undefined; } /** * Creates a `dgram.Socket` object. Once the socket is created, calling `socket.bind()` will instruct the socket to begin listening for datagram @@ -98,8 +104,8 @@ declare module 'dgram' { * When sharing a UDP socket across multiple `cluster` workers, the`socket.addMembership()` function must be called only once or an`EADDRINUSE` error will occur: * * ```js - * import cluster from 'cluster'; - * import dgram from 'dgram'; + * import cluster from 'node:cluster'; + * import dgram from 'node:dgram'; * * if (cluster.isPrimary) { * cluster.fork(); // Works ok. @@ -116,7 +122,7 @@ declare module 'dgram' { addMembership(multicastAddress: string, multicastInterface?: string): void; /** * Returns an object containing the address information for a socket. - * For UDP sockets, this object will contain `address`, `family` and `port`properties. + * For UDP sockets, this object will contain `address`, `family`, and `port`properties. * * This method throws `EBADF` if called on an unbound socket. * @since v0.1.99 @@ -142,12 +148,12 @@ declare module 'dgram' { * Example of a UDP server listening on port 41234: * * ```js - * import dgram from 'dgram'; + * import dgram from 'node:dgram'; * * const server = dgram.createSocket('udp4'); * * server.on('error', (err) => { - * console.log(`server error:\n${err.stack}`); + * console.error(`server error:\n${err.stack}`); * server.close(); * }); * @@ -221,6 +227,16 @@ declare module 'dgram' { * @return the `SO_SNDBUF` socket send buffer size in bytes. */ getSendBufferSize(): number; + /** + * @since v18.8.0, v16.19.0 + * @return Number of bytes queued for sending. + */ + getSendQueueSize(): number; + /** + * @since v18.8.0, v16.19.0 + * @return Number of send requests currently in the queue awaiting to be processed. + */ + getSendQueueCount(): number; /** * By default, binding a socket will cause it to block the Node.js process from * exiting as long as the socket is open. The `socket.unref()` method can be used @@ -260,7 +276,7 @@ declare module 'dgram' { * * The `address` argument is a string. If the value of `address` is a host name, * DNS will be used to resolve the address of the host. If `address` is not - * provided or otherwise falsy, `'127.0.0.1'` (for `udp4` sockets) or `'::1'`(for `udp6` sockets) will be used by default. + * provided or otherwise nullish, `'127.0.0.1'` (for `udp4` sockets) or `'::1'`(for `udp6` sockets) will be used by default. * * If the socket has not been previously bound with a call to `bind`, the socket * is assigned a random port number and is bound to the "all interfaces" address @@ -284,8 +300,8 @@ declare module 'dgram' { * Example of sending a UDP packet to a port on `localhost`; * * ```js - * import dgram from 'dgram'; - * import { Buffer } from 'buffer'; + * import dgram from 'node:dgram'; + * import { Buffer } from 'node:buffer'; * * const message = Buffer.from('Some bytes'); * const client = dgram.createSocket('udp4'); @@ -297,8 +313,8 @@ declare module 'dgram' { * Example of sending a UDP packet composed of multiple buffers to a port on`127.0.0.1`; * * ```js - * import dgram from 'dgram'; - * import { Buffer } from 'buffer'; + * import dgram from 'node:dgram'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from('Some '); * const buf2 = Buffer.from('bytes'); @@ -316,8 +332,8 @@ declare module 'dgram' { * Example of sending a UDP packet using a socket connected to a port on`localhost`: * * ```js - * import dgram from 'dgram'; - * import { Buffer } from 'buffer'; + * import dgram from 'node:dgram'; + * import { Buffer } from 'node:buffer'; * * const message = Buffer.from('Some bytes'); * const client = dgram.createSocket('udp4'); @@ -335,12 +351,42 @@ declare module 'dgram' { * @param address Destination host name or IP address. * @param callback Called when the message has been sent. */ - send(msg: string | Uint8Array | ReadonlyArray, port?: number, address?: string, callback?: (error: Error | null, bytes: number) => void): void; - send(msg: string | Uint8Array | ReadonlyArray, port?: number, callback?: (error: Error | null, bytes: number) => void): void; - send(msg: string | Uint8Array | ReadonlyArray, callback?: (error: Error | null, bytes: number) => void): void; - send(msg: string | Uint8Array, offset: number, length: number, port?: number, address?: string, callback?: (error: Error | null, bytes: number) => void): void; - send(msg: string | Uint8Array, offset: number, length: number, port?: number, callback?: (error: Error | null, bytes: number) => void): void; - send(msg: string | Uint8Array, offset: number, length: number, callback?: (error: Error | null, bytes: number) => void): void; + send( + msg: string | Uint8Array | readonly any[], + port?: number, + address?: string, + callback?: (error: Error | null, bytes: number) => void, + ): void; + send( + msg: string | Uint8Array | readonly any[], + port?: number, + callback?: (error: Error | null, bytes: number) => void, + ): void; + send( + msg: string | Uint8Array | readonly any[], + callback?: (error: Error | null, bytes: number) => void, + ): void; + send( + msg: string | Uint8Array, + offset: number, + length: number, + port?: number, + address?: string, + callback?: (error: Error | null, bytes: number) => void, + ): void; + send( + msg: string | Uint8Array, + offset: number, + length: number, + port?: number, + callback?: (error: Error | null, bytes: number) => void, + ): void; + send( + msg: string | Uint8Array, + offset: number, + length: number, + callback?: (error: Error | null, bytes: number) => void, + ): void; /** * Sets or clears the `SO_BROADCAST` socket option. When set to `true`, UDP * packets may be sent to a local interface's broadcast address. @@ -451,7 +497,7 @@ declare module 'dgram' { * TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. * Changing TTL values is typically done for network probes or when multicasting. * - * The `ttl` argument may be between between 1 and 255\. The default on most systems + * The `ttl` argument may be between 1 and 255\. The default on most systems * is 64. * * This method throws `EBADF` if called on an unbound socket. @@ -465,7 +511,7 @@ declare module 'dgram' { * process active, allowing the process to exit even if the socket is still * listening. * - * Calling `socket.unref()` multiple times will have no addition effect. + * Calling `socket.unref()` multiple times will have no additional effect. * * The `socket.unref()` method returns a reference to the socket so calls can be * chained. @@ -503,43 +549,48 @@ declare module 'dgram' { * 5. message */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'connect', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'listening', listener: () => void): this; - addListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "connect", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "listening", listener: () => void): this; + addListener(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close'): boolean; - emit(event: 'connect'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'listening'): boolean; - emit(event: 'message', msg: Buffer, rinfo: RemoteInfo): boolean; + emit(event: "close"): boolean; + emit(event: "connect"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "listening"): boolean; + emit(event: "message", msg: Buffer, rinfo: RemoteInfo): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'connect', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'listening', listener: () => void): this; - on(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + on(event: "close", listener: () => void): this; + on(event: "connect", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "listening", listener: () => void): this; + on(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'connect', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'listening', listener: () => void): this; - once(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + once(event: "close", listener: () => void): this; + once(event: "connect", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "listening", listener: () => void): this; + once(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'connect', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'listening', listener: () => void): this; - prependListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "connect", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "listening", listener: () => void): this; + prependListener(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'connect', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'listening', listener: () => void): this; - prependOnceListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "connect", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "listening", listener: () => void): this; + prependOnceListener(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + /** + * Calls `socket.close()` and returns a promise that fulfills when the socket has closed. + * @since v20.5.0 + */ + [Symbol.asyncDispose](): Promise; } } -declare module 'node:dgram' { - export * from 'dgram'; +declare module "node:dgram" { + export * from "dgram"; } diff --git a/node_modules/@types/node/diagnostics_channel.d.ts b/node_modules/@types/node/diagnostics_channel.d.ts old mode 100755 new mode 100644 index cb2429e..cd4bd71 --- a/node_modules/@types/node/diagnostics_channel.d.ts +++ b/node_modules/@types/node/diagnostics_channel.d.ts @@ -1,11 +1,11 @@ /** - * The `diagnostics_channel` module provides an API to create named channels + * The `node:diagnostics_channel` module provides an API to create named channels * to report arbitrary message data for diagnostics purposes. * * It can be accessed using: * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * ``` * * It is intended that a module writer wanting to report diagnostics messages @@ -19,10 +19,11 @@ * channels are used along with the shape of the message data. Channel names * should generally include the module name to avoid collisions with data from * other modules. - * @experimental - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/diagnostics_channel.js) + * @since v15.1.0, v14.17.0 + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/diagnostics_channel.js) */ -declare module 'diagnostics_channel' { +declare module "diagnostics_channel" { + import { AsyncLocalStorage } from "node:async_hooks"; /** * Check if there are active subscribers to the named channel. This is helpful if * the message you want to send might be expensive to prepare. @@ -31,7 +32,7 @@ declare module 'diagnostics_channel' { * performance-sensitive code. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * if (diagnostics_channel.hasSubscribers('my-channel')) { * // There are subscribers, prepare and publish message @@ -41,14 +42,14 @@ declare module 'diagnostics_channel' { * @param name The channel name * @return If there are active subscribers */ - function hasSubscribers(name: string): boolean; + function hasSubscribers(name: string | symbol): boolean; /** - * This is the primary entry-point for anyone wanting to interact with a named + * This is the primary entry-point for anyone wanting to publish to a named * channel. It produces a channel object which is optimized to reduce overhead at * publish time as much as possible. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * const channel = diagnostics_channel.channel('my-channel'); * ``` @@ -56,19 +57,86 @@ declare module 'diagnostics_channel' { * @param name The channel name * @return The named channel object */ - function channel(name: string): Channel; - type ChannelListener = (message: unknown, name: string) => void; + function channel(name: string | symbol): Channel; + type ChannelListener = (message: unknown, name: string | symbol) => void; + /** + * Register a message handler to subscribe to this channel. This message handler + * will be run synchronously whenever a message is published to the channel. Any + * errors thrown in the message handler will trigger an `'uncaughtException'`. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * diagnostics_channel.subscribe('my-channel', (message, name) => { + * // Received data + * }); + * ``` + * @since v18.7.0, v16.17.0 + * @param name The channel name + * @param onMessage The handler to receive channel messages + */ + function subscribe(name: string | symbol, onMessage: ChannelListener): void; + /** + * Remove a message handler previously registered to this channel with {@link subscribe}. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * function onMessage(message, name) { + * // Received data + * } + * + * diagnostics_channel.subscribe('my-channel', onMessage); + * + * diagnostics_channel.unsubscribe('my-channel', onMessage); + * ``` + * @since v18.7.0, v16.17.0 + * @param name The channel name + * @param onMessage The previous subscribed handler to remove + * @return `true` if the handler was found, `false` otherwise. + */ + function unsubscribe(name: string | symbol, onMessage: ChannelListener): boolean; + /** + * Creates a `TracingChannel` wrapper for the given `TracingChannel Channels`. If a name is given, the corresponding tracing + * channels will be created in the form of `tracing:${name}:${eventType}` where`eventType` corresponds to the types of `TracingChannel Channels`. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channelsByName = diagnostics_channel.tracingChannel('my-channel'); + * + * // or... + * + * const channelsByCollection = diagnostics_channel.tracingChannel({ + * start: diagnostics_channel.channel('tracing:my-channel:start'), + * end: diagnostics_channel.channel('tracing:my-channel:end'), + * asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'), + * asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'), + * error: diagnostics_channel.channel('tracing:my-channel:error'), + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param nameOrChannels Channel name or object containing all the `TracingChannel Channels` + * @return Collection of channels to trace with + */ + function tracingChannel< + StoreType = unknown, + ContextType extends object = StoreType extends object ? StoreType : object, + >( + nameOrChannels: string | TracingChannelCollection, + ): TracingChannel; /** * The class `Channel` represents an individual named channel within the data - * pipeline. It is use to track subscribers and to publish messages when there + * pipeline. It is used to track subscribers and to publish messages when there * are subscribers present. It exists as a separate object to avoid channel * lookups at publish time, enabling very fast publish speeds and allowing * for heavy use while incurring very minimal cost. Channels are created with {@link channel}, constructing a channel directly * with `new Channel(name)` is not supported. * @since v15.1.0, v14.17.0 */ - class Channel { - readonly name: string; + class Channel { + readonly name: string | symbol; /** * Check if there are active subscribers to this channel. This is helpful if * the message you want to send might be expensive to prepare. @@ -77,7 +145,7 @@ declare module 'diagnostics_channel' { * performance-sensitive code. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * const channel = diagnostics_channel.channel('my-channel'); * @@ -88,19 +156,18 @@ declare module 'diagnostics_channel' { * @since v15.1.0, v14.17.0 */ readonly hasSubscribers: boolean; - private constructor(name: string); + private constructor(name: string | symbol); /** - * Publish a message to any subscribers to the channel. This will - * trigger message handlers synchronously so they will execute within - * the same context. + * Publish a message to any subscribers to the channel. This will trigger + * message handlers synchronously so they will execute within the same context. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * const channel = diagnostics_channel.channel('my-channel'); * * channel.publish({ - * some: 'message' + * some: 'message', * }); * ``` * @since v15.1.0, v14.17.0 @@ -113,7 +180,7 @@ declare module 'diagnostics_channel' { * errors thrown in the message handler will trigger an `'uncaughtException'`. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * const channel = diagnostics_channel.channel('my-channel'); * @@ -122,6 +189,7 @@ declare module 'diagnostics_channel' { * }); * ``` * @since v15.1.0, v14.17.0 + * @deprecated Since v18.7.0,v16.17.0 - Use {@link subscribe(name, onMessage)} * @param onMessage The handler to receive channel messages */ subscribe(onMessage: ChannelListener): void; @@ -129,7 +197,7 @@ declare module 'diagnostics_channel' { * Remove a message handler previously registered to this channel with `channel.subscribe(onMessage)`. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * const channel = diagnostics_channel.channel('my-channel'); * @@ -142,11 +210,336 @@ declare module 'diagnostics_channel' { * channel.unsubscribe(onMessage); * ``` * @since v15.1.0, v14.17.0 + * @deprecated Since v18.7.0,v16.17.0 - Use {@link unsubscribe(name, onMessage)} * @param onMessage The previous subscribed handler to remove + * @return `true` if the handler was found, `false` otherwise. */ unsubscribe(onMessage: ChannelListener): void; + /** + * When `channel.runStores(context, ...)` is called, the given context data + * will be applied to any store bound to the channel. If the store has already been + * bound the previous `transform` function will be replaced with the new one. + * The `transform` function may be omitted to set the given context data as the + * context directly. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * import { AsyncLocalStorage } from 'node:async_hooks'; + * + * const store = new AsyncLocalStorage(); + * + * const channel = diagnostics_channel.channel('my-channel'); + * + * channel.bindStore(store, (data) => { + * return { data }; + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param store The store to which to bind the context data + * @param transform Transform context data before setting the store context + */ + bindStore(store: AsyncLocalStorage, transform?: (context: ContextType) => StoreType): void; + /** + * Remove a message handler previously registered to this channel with `channel.bindStore(store)`. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * import { AsyncLocalStorage } from 'node:async_hooks'; + * + * const store = new AsyncLocalStorage(); + * + * const channel = diagnostics_channel.channel('my-channel'); + * + * channel.bindStore(store); + * channel.unbindStore(store); + * ``` + * @since v19.9.0 + * @experimental + * @param store The store to unbind from the channel. + * @return `true` if the store was found, `false` otherwise. + */ + unbindStore(store: any): void; + /** + * Applies the given data to any AsyncLocalStorage instances bound to the channel + * for the duration of the given function, then publishes to the channel within + * the scope of that data is applied to the stores. + * + * If a transform function was given to `channel.bindStore(store)` it will be + * applied to transform the message data before it becomes the context value for + * the store. The prior storage context is accessible from within the transform + * function in cases where context linking is required. + * + * The context applied to the store should be accessible in any async code which + * continues from execution which began during the given function, however + * there are some situations in which `context loss` may occur. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * import { AsyncLocalStorage } from 'node:async_hooks'; + * + * const store = new AsyncLocalStorage(); + * + * const channel = diagnostics_channel.channel('my-channel'); + * + * channel.bindStore(store, (message) => { + * const parent = store.getStore(); + * return new Span(message, parent); + * }); + * channel.runStores({ some: 'message' }, () => { + * store.getStore(); // Span({ some: 'message' }) + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param context Message to send to subscribers and bind to stores + * @param fn Handler to run within the entered storage context + * @param thisArg The receiver to be used for the function call. + * @param args Optional arguments to pass to the function. + */ + runStores(): void; + } + interface TracingChannelSubscribers { + start: (message: ContextType) => void; + end: ( + message: ContextType & { + error?: unknown; + result?: unknown; + }, + ) => void; + asyncStart: ( + message: ContextType & { + error?: unknown; + result?: unknown; + }, + ) => void; + asyncEnd: ( + message: ContextType & { + error?: unknown; + result?: unknown; + }, + ) => void; + error: ( + message: ContextType & { + error: unknown; + }, + ) => void; + } + interface TracingChannelCollection { + start: Channel; + end: Channel; + asyncStart: Channel; + asyncEnd: Channel; + error: Channel; + } + /** + * The class `TracingChannel` is a collection of `TracingChannel Channels` which + * together express a single traceable action. It is used to formalize and + * simplify the process of producing events for tracing application flow.{@link tracingChannel} is used to construct a`TracingChannel`. As with `Channel` it is recommended to create and reuse a + * single `TracingChannel` at the top-level of the file rather than creating them + * dynamically. + * @since v19.9.0 + * @experimental + */ + class TracingChannel implements TracingChannelCollection { + start: Channel; + end: Channel; + asyncStart: Channel; + asyncEnd: Channel; + error: Channel; + /** + * Helper to subscribe a collection of functions to the corresponding channels. + * This is the same as calling `channel.subscribe(onMessage)` on each channel + * individually. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * channels.subscribe({ + * start(message) { + * // Handle start message + * }, + * end(message) { + * // Handle end message + * }, + * asyncStart(message) { + * // Handle asyncStart message + * }, + * asyncEnd(message) { + * // Handle asyncEnd message + * }, + * error(message) { + * // Handle error message + * }, + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param subscribers Set of `TracingChannel Channels` subscribers + */ + subscribe(subscribers: TracingChannelSubscribers): void; + /** + * Helper to unsubscribe a collection of functions from the corresponding channels. + * This is the same as calling `channel.unsubscribe(onMessage)` on each channel + * individually. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * channels.unsubscribe({ + * start(message) { + * // Handle start message + * }, + * end(message) { + * // Handle end message + * }, + * asyncStart(message) { + * // Handle asyncStart message + * }, + * asyncEnd(message) { + * // Handle asyncEnd message + * }, + * error(message) { + * // Handle error message + * }, + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param subscribers Set of `TracingChannel Channels` subscribers + * @return `true` if all handlers were successfully unsubscribed, and `false` otherwise. + */ + unsubscribe(subscribers: TracingChannelSubscribers): void; + /** + * Trace a synchronous function call. This will always produce a `start event` and `end event` around the execution and may produce an `error event` if the given function throws an error. + * This will run the given function using `channel.runStores(context, ...)` on the `start` channel which ensures all + * events should have any bound stores set to match this trace context. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * channels.traceSync(() => { + * // Do something + * }, { + * some: 'thing', + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param fn Function to wrap a trace around + * @param context Shared object to correlate events through + * @param thisArg The receiver to be used for the function call + * @param args Optional arguments to pass to the function + * @return The return value of the given function + */ + traceSync( + fn: (this: ThisArg, ...args: Args) => any, + context?: ContextType, + thisArg?: ThisArg, + ...args: Args + ): void; + /** + * Trace a promise-returning function call. This will always produce a `start event` and `end event` around the synchronous portion of the + * function execution, and will produce an `asyncStart event` and `asyncEnd event` when a promise continuation is reached. It may also + * produce an `error event` if the given function throws an error or the + * returned promise rejects. This will run the given function using `channel.runStores(context, ...)` on the `start` channel which ensures all + * events should have any bound stores set to match this trace context. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * channels.tracePromise(async () => { + * // Do something + * }, { + * some: 'thing', + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param fn Promise-returning function to wrap a trace around + * @param context Shared object to correlate trace events through + * @param thisArg The receiver to be used for the function call + * @param args Optional arguments to pass to the function + * @return Chained from promise returned by the given function + */ + tracePromise( + fn: (this: ThisArg, ...args: Args) => Promise, + context?: ContextType, + thisArg?: ThisArg, + ...args: Args + ): void; + /** + * Trace a callback-receiving function call. This will always produce a `start event` and `end event` around the synchronous portion of the + * function execution, and will produce a `asyncStart event` and `asyncEnd event` around the callback execution. It may also produce an `error event` if the given function throws an error or + * the returned + * promise rejects. This will run the given function using `channel.runStores(context, ...)` on the `start` channel which ensures all + * events should have any bound stores set to match this trace context. + * + * The `position` will be -1 by default to indicate the final argument should + * be used as the callback. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * channels.traceCallback((arg1, callback) => { + * // Do something + * callback(null, 'result'); + * }, 1, { + * some: 'thing', + * }, thisArg, arg1, callback); + * ``` + * + * The callback will also be run with `channel.runStores(context, ...)` which + * enables context loss recovery in some cases. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * import { AsyncLocalStorage } from 'node:async_hooks'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * const myStore = new AsyncLocalStorage(); + * + * // The start channel sets the initial store data to something + * // and stores that store data value on the trace context object + * channels.start.bindStore(myStore, (data) => { + * const span = new Span(data); + * data.span = span; + * return span; + * }); + * + * // Then asyncStart can restore from that data it stored previously + * channels.asyncStart.bindStore(myStore, (data) => { + * return data.span; + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param fn callback using function to wrap a trace around + * @param position Zero-indexed argument position of expected callback + * @param context Shared object to correlate trace events through + * @param thisArg The receiver to be used for the function call + * @param args Optional arguments to pass to the function + * @return The return value of the given function + */ + traceCallback any>( + fn: Fn, + position: number | undefined, + context: ContextType | undefined, + thisArg: any, + ...args: Parameters + ): void; } } -declare module 'node:diagnostics_channel' { - export * from 'diagnostics_channel'; +declare module "node:diagnostics_channel" { + export * from "diagnostics_channel"; } diff --git a/node_modules/@types/node/dns.d.ts b/node_modules/@types/node/dns.d.ts old mode 100755 new mode 100644 index 78776f4..380cf7d --- a/node_modules/@types/node/dns.d.ts +++ b/node_modules/@types/node/dns.d.ts @@ -1,5 +1,5 @@ /** - * The `dns` module enables name resolution. For example, use it to look up IP + * The `node:dns` module enables name resolution. For example, use it to look up IP * addresses of host names. * * Although named for the [Domain Name System (DNS)](https://en.wikipedia.org/wiki/Domain_Name_System), it does not always use the @@ -9,7 +9,7 @@ * system do, use {@link lookup}. * * ```js - * const dns = require('dns'); + * const dns = require('node:dns'); * * dns.lookup('example.org', (err, address, family) => { * console.log('address: %j family: IPv%s', address, family); @@ -17,13 +17,13 @@ * // address: "93.184.216.34" family: IPv4 * ``` * - * All other functions in the `dns` module connect to an actual DNS server to + * All other functions in the `node:dns` module connect to an actual DNS server to * perform name resolution. They will always use the network to perform DNS * queries. These functions do not use the same set of configuration files used by {@link lookup} (e.g. `/etc/hosts`). Use these functions to always perform * DNS queries, bypassing other name-resolution facilities. * * ```js - * const dns = require('dns'); + * const dns = require('node:dns'); * * dns.resolve4('archive.org', (err, addresses) => { * if (err) throw err; @@ -42,10 +42,10 @@ * ``` * * See the `Implementation considerations section` for more information. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/dns.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/dns.js) */ -declare module 'dns' { - import * as dnsPromises from 'node:dns/promises'; +declare module "dns" { + import * as dnsPromises from "node:dns/promises"; // Supported getaddrinfo flags. export const ADDRCONFIG: number; export const V4MAPPED: number; @@ -58,6 +58,9 @@ declare module 'dns' { family?: number | undefined; hints?: number | undefined; all?: boolean | undefined; + /** + * @default true + */ verbatim?: boolean | undefined; } export interface LookupOneOptions extends LookupOptions { @@ -73,8 +76,8 @@ declare module 'dns' { /** * Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or * AAAA (IPv6) record. All `option` properties are optional. If `options` is an - * integer, then it must be `4` or `6` – if `options` is not provided, then IPv4 - * and IPv6 addresses are both returned if found. + * integer, then it must be `4` or `6` – if `options` is `0` or not provided, then + * IPv4 and IPv6 addresses are both returned if found. * * With the `all` option set to `true`, the arguments for `callback` change to`(err, addresses)`, with `addresses` being an array of objects with the * properties `address` and `family`. @@ -86,14 +89,14 @@ declare module 'dns' { * * `dns.lookup()` does not necessarily have anything to do with the DNS protocol. * The implementation uses an operating system facility that can associate names - * with addresses, and vice versa. This implementation can have subtle but + * with addresses and vice versa. This implementation can have subtle but * important consequences on the behavior of any Node.js program. Please take some * time to consult the `Implementation considerations section` before using`dns.lookup()`. * * Example usage: * * ```js - * const dns = require('dns'); + * const dns = require('node:dns'); * const options = { * family: 6, * hints: dns.ADDRCONFIG | dns.V4MAPPED, @@ -112,11 +115,30 @@ declare module 'dns' { * If this method is invoked as its `util.promisify()` ed version, and `all`is not set to `true`, it returns a `Promise` for an `Object` with `address` and`family` properties. * @since v0.1.90 */ - export function lookup(hostname: string, family: number, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void): void; - export function lookup(hostname: string, options: LookupOneOptions, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void): void; - export function lookup(hostname: string, options: LookupAllOptions, callback: (err: NodeJS.ErrnoException | null, addresses: LookupAddress[]) => void): void; - export function lookup(hostname: string, options: LookupOptions, callback: (err: NodeJS.ErrnoException | null, address: string | LookupAddress[], family: number) => void): void; - export function lookup(hostname: string, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void): void; + export function lookup( + hostname: string, + family: number, + callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, + ): void; + export function lookup( + hostname: string, + options: LookupOneOptions, + callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, + ): void; + export function lookup( + hostname: string, + options: LookupAllOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: LookupAddress[]) => void, + ): void; + export function lookup( + hostname: string, + options: LookupOptions, + callback: (err: NodeJS.ErrnoException | null, address: string | LookupAddress[], family: number) => void, + ): void; + export function lookup( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, + ): void; export namespace lookup { function __promisify__(hostname: string, options: LookupAllOptions): Promise; function __promisify__(hostname: string, options?: LookupOneOptions | number): Promise; @@ -132,7 +154,7 @@ declare module 'dns' { * On an error, `err` is an `Error` object, where `err.code` is the error code. * * ```js - * const dns = require('dns'); + * const dns = require('node:dns'); * dns.lookupService('127.0.0.1', 22, (err, hostname, service) => { * console.log(hostname, service); * // Prints: localhost ssh @@ -142,11 +164,15 @@ declare module 'dns' { * If this method is invoked as its `util.promisify()` ed version, it returns a`Promise` for an `Object` with `hostname` and `service` properties. * @since v0.11.14 */ - export function lookupService(address: string, port: number, callback: (err: NodeJS.ErrnoException | null, hostname: string, service: string) => void): void; + export function lookupService( + address: string, + port: number, + callback: (err: NodeJS.ErrnoException | null, hostname: string, service: string) => void, + ): void; export namespace lookupService { function __promisify__( address: string, - port: number + port: number, ): Promise<{ hostname: string; service: string; @@ -165,13 +191,13 @@ declare module 'dns' { /** @deprecated Use `AnyARecord` or `AnyAaaaRecord` instead. */ export type AnyRecordWithTtl = AnyARecord | AnyAaaaRecord; export interface AnyARecord extends RecordWithTtl { - type: 'A'; + type: "A"; } export interface AnyAaaaRecord extends RecordWithTtl { - type: 'AAAA'; + type: "AAAA"; } export interface CaaRecord { - critial: number; + critical: number; issue?: string | undefined; issuewild?: string | undefined; iodef?: string | undefined; @@ -183,7 +209,7 @@ declare module 'dns' { exchange: string; } export interface AnyMxRecord extends MxRecord { - type: 'MX'; + type: "MX"; } export interface NaptrRecord { flags: string; @@ -194,7 +220,7 @@ declare module 'dns' { preference: number; } export interface AnyNaptrRecord extends NaptrRecord { - type: 'NAPTR'; + type: "NAPTR"; } export interface SoaRecord { nsname: string; @@ -206,7 +232,7 @@ declare module 'dns' { minttl: number; } export interface AnySoaRecord extends SoaRecord { - type: 'SOA'; + type: "SOA"; } export interface SrvRecord { priority: number; @@ -215,25 +241,35 @@ declare module 'dns' { name: string; } export interface AnySrvRecord extends SrvRecord { - type: 'SRV'; + type: "SRV"; } export interface AnyTxtRecord { - type: 'TXT'; + type: "TXT"; entries: string[]; } export interface AnyNsRecord { - type: 'NS'; + type: "NS"; value: string; } export interface AnyPtrRecord { - type: 'PTR'; + type: "PTR"; value: string; } export interface AnyCnameRecord { - type: 'CNAME'; + type: "CNAME"; value: string; } - export type AnyRecord = AnyARecord | AnyAaaaRecord | AnyCnameRecord | AnyMxRecord | AnyNaptrRecord | AnyNsRecord | AnyPtrRecord | AnySoaRecord | AnySrvRecord | AnyTxtRecord; + export type AnyRecord = + | AnyARecord + | AnyAaaaRecord + | AnyCnameRecord + | AnyMxRecord + | AnyNaptrRecord + | AnyNsRecord + | AnyPtrRecord + | AnySoaRecord + | AnySrvRecord + | AnyTxtRecord; /** * Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array * of the resource records. The `callback` function has arguments`(err, records)`. When successful, `records` will be an array of resource @@ -246,32 +282,85 @@ declare module 'dns' { * @param hostname Host name to resolve. * @param [rrtype='A'] Resource record type. */ - export function resolve(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'A', callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'AAAA', callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'ANY', callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void): void; - export function resolve(hostname: string, rrtype: 'CNAME', callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'MX', callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void): void; - export function resolve(hostname: string, rrtype: 'NAPTR', callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void): void; - export function resolve(hostname: string, rrtype: 'NS', callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'PTR', callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'SOA', callback: (err: NodeJS.ErrnoException | null, addresses: SoaRecord) => void): void; - export function resolve(hostname: string, rrtype: 'SRV', callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void): void; - export function resolve(hostname: string, rrtype: 'TXT', callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void): void; + export function resolve( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "A", + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "AAAA", + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "ANY", + callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "CNAME", + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "MX", + callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "NAPTR", + callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "NS", + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "PTR", + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "SOA", + callback: (err: NodeJS.ErrnoException | null, addresses: SoaRecord) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "SRV", + callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "TXT", + callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void, + ): void; export function resolve( hostname: string, rrtype: string, - callback: (err: NodeJS.ErrnoException | null, addresses: string[] | MxRecord[] | NaptrRecord[] | SoaRecord | SrvRecord[] | string[][] | AnyRecord[]) => void + callback: ( + err: NodeJS.ErrnoException | null, + addresses: string[] | MxRecord[] | NaptrRecord[] | SoaRecord | SrvRecord[] | string[][] | AnyRecord[], + ) => void, ): void; export namespace resolve { - function __promisify__(hostname: string, rrtype?: 'A' | 'AAAA' | 'CNAME' | 'NS' | 'PTR'): Promise; - function __promisify__(hostname: string, rrtype: 'ANY'): Promise; - function __promisify__(hostname: string, rrtype: 'MX'): Promise; - function __promisify__(hostname: string, rrtype: 'NAPTR'): Promise; - function __promisify__(hostname: string, rrtype: 'SOA'): Promise; - function __promisify__(hostname: string, rrtype: 'SRV'): Promise; - function __promisify__(hostname: string, rrtype: 'TXT'): Promise; - function __promisify__(hostname: string, rrtype: string): Promise; + function __promisify__(hostname: string, rrtype?: "A" | "AAAA" | "CNAME" | "NS" | "PTR"): Promise; + function __promisify__(hostname: string, rrtype: "ANY"): Promise; + function __promisify__(hostname: string, rrtype: "MX"): Promise; + function __promisify__(hostname: string, rrtype: "NAPTR"): Promise; + function __promisify__(hostname: string, rrtype: "SOA"): Promise; + function __promisify__(hostname: string, rrtype: "SRV"): Promise; + function __promisify__(hostname: string, rrtype: "TXT"): Promise; + function __promisify__( + hostname: string, + rrtype: string, + ): Promise; } /** * Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the`hostname`. The `addresses` argument passed to the `callback` function @@ -279,23 +368,45 @@ declare module 'dns' { * @since v0.1.16 * @param hostname Host name to resolve. */ - export function resolve4(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve4(hostname: string, options: ResolveWithTtlOptions, callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void): void; - export function resolve4(hostname: string, options: ResolveOptions, callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void): void; + export function resolve4( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve4( + hostname: string, + options: ResolveWithTtlOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void, + ): void; + export function resolve4( + hostname: string, + options: ResolveOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void, + ): void; export namespace resolve4 { function __promisify__(hostname: string): Promise; function __promisify__(hostname: string, options: ResolveWithTtlOptions): Promise; function __promisify__(hostname: string, options?: ResolveOptions): Promise; } /** - * Uses the DNS protocol to resolve a IPv6 addresses (`AAAA` records) for the`hostname`. The `addresses` argument passed to the `callback` function + * Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the`hostname`. The `addresses` argument passed to the `callback` function * will contain an array of IPv6 addresses. * @since v0.1.16 * @param hostname Host name to resolve. */ - export function resolve6(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve6(hostname: string, options: ResolveWithTtlOptions, callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void): void; - export function resolve6(hostname: string, options: ResolveOptions, callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void): void; + export function resolve6( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve6( + hostname: string, + options: ResolveWithTtlOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void, + ): void; + export function resolve6( + hostname: string, + options: ResolveOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void, + ): void; export namespace resolve6 { function __promisify__(hostname: string): Promise; function __promisify__(hostname: string, options: ResolveWithTtlOptions): Promise; @@ -306,7 +417,10 @@ declare module 'dns' { * will contain an array of canonical name records available for the `hostname`(e.g. `['bar.example.com']`). * @since v0.3.2 */ - export function resolveCname(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; + export function resolveCname( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; export namespace resolveCname { function __promisify__(hostname: string): Promise; } @@ -314,9 +428,12 @@ declare module 'dns' { * Uses the DNS protocol to resolve `CAA` records for the `hostname`. The`addresses` argument passed to the `callback` function * will contain an array of certification authority authorization records * available for the `hostname` (e.g. `[{critical: 0, iodef: 'mailto:pki@example.com'}, {critical: 128, issue: 'pki.example.com'}]`). - * @since v15.0.0 + * @since v15.0.0, v14.17.0 */ - export function resolveCaa(hostname: string, callback: (err: NodeJS.ErrnoException | null, records: CaaRecord[]) => void): void; + export function resolveCaa( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, records: CaaRecord[]) => void, + ): void; export namespace resolveCaa { function __promisify__(hostname: string): Promise; } @@ -325,12 +442,15 @@ declare module 'dns' { * contain an array of objects containing both a `priority` and `exchange`property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`). * @since v0.1.27 */ - export function resolveMx(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void): void; + export function resolveMx( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void, + ): void; export namespace resolveMx { function __promisify__(hostname: string): Promise; } /** - * Uses the DNS protocol to resolve regular expression based records (`NAPTR`records) for the `hostname`. The `addresses` argument passed to the `callback`function will contain an array of + * Uses the DNS protocol to resolve regular expression-based records (`NAPTR`records) for the `hostname`. The `addresses` argument passed to the `callback`function will contain an array of * objects with the following properties: * * * `flags` @@ -352,7 +472,10 @@ declare module 'dns' { * ``` * @since v0.9.12 */ - export function resolveNaptr(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void): void; + export function resolveNaptr( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void, + ): void; export namespace resolveNaptr { function __promisify__(hostname: string): Promise; } @@ -361,7 +484,10 @@ declare module 'dns' { * contain an array of name server records available for `hostname`(e.g. `['ns1.example.com', 'ns2.example.com']`). * @since v0.1.90 */ - export function resolveNs(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; + export function resolveNs( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; export namespace resolveNs { function __promisify__(hostname: string): Promise; } @@ -370,7 +496,10 @@ declare module 'dns' { * be an array of strings containing the reply records. * @since v6.0.0 */ - export function resolvePtr(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; + export function resolvePtr( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; export namespace resolvePtr { function __promisify__(hostname: string): Promise; } @@ -400,7 +529,10 @@ declare module 'dns' { * ``` * @since v0.11.10 */ - export function resolveSoa(hostname: string, callback: (err: NodeJS.ErrnoException | null, address: SoaRecord) => void): void; + export function resolveSoa( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, address: SoaRecord) => void, + ): void; export namespace resolveSoa { function __promisify__(hostname: string): Promise; } @@ -423,7 +555,10 @@ declare module 'dns' { * ``` * @since v0.1.27 */ - export function resolveSrv(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void): void; + export function resolveSrv( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void, + ): void; export namespace resolveSrv { function __promisify__(hostname: string): Promise; } @@ -434,7 +569,10 @@ declare module 'dns' { * treated separately. * @since v0.1.27 */ - export function resolveTxt(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void): void; + export function resolveTxt( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void, + ): void; export namespace resolveTxt { function __promisify__(hostname: string): Promise; } @@ -468,7 +606,10 @@ declare module 'dns' { * DNS server operators may choose not to respond to `ANY`queries. It may be better to call individual methods like {@link resolve4},{@link resolveMx}, and so on. For more details, see [RFC * 8482](https://tools.ietf.org/html/rfc8482). */ - export function resolveAny(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void): void; + export function resolveAny( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void, + ): void; export namespace resolveAny { function __promisify__(hostname: string): Promise; } @@ -480,7 +621,18 @@ declare module 'dns' { * one of the `DNS error codes`. * @since v0.1.16 */ - export function reverse(ip: string, callback: (err: NodeJS.ErrnoException | null, hostnames: string[]) => void): void; + export function reverse( + ip: string, + callback: (err: NodeJS.ErrnoException | null, hostnames: string[]) => void, + ): void; + /** + * Get the default value for `verbatim` in {@link lookup} and `dnsPromises.lookup()`. The value could be: + * + * * `ipv4first`: for `verbatim` defaulting to `false`. + * * `verbatim`: for `verbatim` defaulting to `true`. + * @since v20.1.0 + */ + export function getDefaultResultOrder(): "ipv4first" | "verbatim"; /** * Sets the IP address and port of servers to be used when performing DNS * resolution. The `servers` argument is an array of [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6) formatted @@ -509,7 +661,7 @@ declare module 'dns' { * @since v0.11.3 * @param servers array of `RFC 5952` formatted addresses */ - export function setServers(servers: ReadonlyArray): void; + export function setServers(servers: readonly string[]): void; /** * Returns an array of IP address strings, formatted according to [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6), * that are currently configured for DNS resolution. A string will include a port @@ -527,16 +679,18 @@ declare module 'dns' { */ export function getServers(): string[]; /** - * Set the default value of `verbatim` in {@link lookup}. The value could be: - * - `ipv4first`: sets default `verbatim` `false`. - * - `verbatim`: sets default `verbatim` `true`. + * Set the default value of `verbatim` in {@link lookup} and `dnsPromises.lookup()`. The value could be: * - * The default is `ipv4first` and {@link setDefaultResultOrder} have higher priority than `--dns-result-order`. - * When using worker threads, {@link setDefaultResultOrder} from the main thread won't affect the default dns orders in workers. - * @since v14.18.0 - * @param order must be 'ipv4first' or 'verbatim'. + * * `ipv4first`: sets default `verbatim` `false`. + * * `verbatim`: sets default `verbatim` `true`. + * + * The default is `verbatim` and {@link setDefaultResultOrder} have higher + * priority than `--dns-result-order`. When using `worker threads`,{@link setDefaultResultOrder} from the main thread won't affect the default + * dns orders in workers. + * @since v16.4.0, v14.18.0 + * @param order must be `'ipv4first'` or `'verbatim'`. */ - export function setDefaultResultOrder(order: 'ipv4first' | 'verbatim'): void; + export function setDefaultResultOrder(order: "ipv4first" | "verbatim"): void; // Error codes export const NODATA: string; export const FORMERR: string; @@ -577,7 +731,7 @@ declare module 'dns' { * other resolvers: * * ```js - * const { Resolver } = require('dns'); + * const { Resolver } = require('node:dns'); * const resolver = new Resolver(); * resolver.setServers(['4.4.4.4']); * @@ -587,7 +741,7 @@ declare module 'dns' { * }); * ``` * - * The following methods from the `dns` module are available: + * The following methods from the `node:dns` module are available: * * * `resolver.getServers()` * * `resolver.resolve()` @@ -620,6 +774,7 @@ declare module 'dns' { resolve4: typeof resolve4; resolve6: typeof resolve6; resolveAny: typeof resolveAny; + resolveCaa: typeof resolveCaa; resolveCname: typeof resolveCname; resolveMx: typeof resolveMx; resolveNaptr: typeof resolveNaptr; @@ -634,13 +789,13 @@ declare module 'dns' { * This allows programs to specify outbound interfaces when used on multi-homed * systems. * - * If a v4 or v6 address is not specified, it is set to the default, and the + * If a v4 or v6 address is not specified, it is set to the default and the * operating system will choose a local address automatically. * * The resolver will use the v4 local address when making requests to IPv4 DNS * servers, and the v6 local address when making requests to IPv6 DNS servers. * The `rrtype` of resolution requests has no impact on the local address used. - * @since v15.1.0 + * @since v15.1.0, v14.17.0 * @param [ipv4='0.0.0.0'] A string representation of an IPv4 address. * @param [ipv6='::0'] A string representation of an IPv6 address. */ @@ -649,6 +804,6 @@ declare module 'dns' { } export { dnsPromises as promises }; } -declare module 'node:dns' { - export * from 'dns'; +declare module "node:dns" { + export * from "dns"; } diff --git a/node_modules/@types/node/dns/promises.d.ts b/node_modules/@types/node/dns/promises.d.ts old mode 100755 new mode 100644 index a236b5a..ef9b222 --- a/node_modules/@types/node/dns/promises.d.ts +++ b/node_modules/@types/node/dns/promises.d.ts @@ -1,26 +1,26 @@ /** * The `dns.promises` API provides an alternative set of asynchronous DNS methods * that return `Promise` objects rather than using callbacks. The API is accessible - * via `require('dns').promises` or `require('dns/promises')`. + * via `require('node:dns').promises` or `require('node:dns/promises')`. * @since v10.6.0 */ -declare module 'dns/promises' { +declare module "dns/promises" { import { - LookupAddress, - LookupOneOptions, - LookupAllOptions, - LookupOptions, AnyRecord, CaaRecord, + LookupAddress, + LookupAllOptions, + LookupOneOptions, + LookupOptions, MxRecord, NaptrRecord, - SoaRecord, - SrvRecord, - ResolveWithTtlOptions, RecordWithTtl, ResolveOptions, ResolverOptions, - } from 'node:dns'; + ResolveWithTtlOptions, + SoaRecord, + SrvRecord, + } from "node:dns"; /** * Returns an array of IP address strings, formatted according to [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6), * that are currently configured for DNS resolution. A string will include a port @@ -52,7 +52,7 @@ declare module 'dns/promises' { * * `dnsPromises.lookup()` does not necessarily have anything to do with the DNS * protocol. The implementation uses an operating system facility that can - * associate names with addresses, and vice versa. This implementation can have + * associate names with addresses and vice versa. This implementation can have * subtle but important consequences on the behavior of any Node.js program. Please * take some time to consult the `Implementation considerations section` before * using `dnsPromises.lookup()`. @@ -60,7 +60,7 @@ declare module 'dns/promises' { * Example usage: * * ```js - * const dns = require('dns'); + * const dns = require('node:dns'); * const dnsPromises = dns.promises; * const options = { * family: 6, @@ -96,7 +96,7 @@ declare module 'dns/promises' { * On error, the `Promise` is rejected with an `Error` object, where `err.code`is the error code. * * ```js - * const dnsPromises = require('dns').promises; + * const dnsPromises = require('node:dns').promises; * dnsPromises.lookupService('127.0.0.1', 22).then((result) => { * console.log(result.hostname, result.service); * // Prints: localhost ssh @@ -106,7 +106,7 @@ declare module 'dns/promises' { */ function lookupService( address: string, - port: number + port: number, ): Promise<{ hostname: string; service: string; @@ -125,19 +125,22 @@ declare module 'dns/promises' { * @param [rrtype='A'] Resource record type. */ function resolve(hostname: string): Promise; - function resolve(hostname: string, rrtype: 'A'): Promise; - function resolve(hostname: string, rrtype: 'AAAA'): Promise; - function resolve(hostname: string, rrtype: 'ANY'): Promise; - function resolve(hostname: string, rrtype: 'CAA'): Promise; - function resolve(hostname: string, rrtype: 'CNAME'): Promise; - function resolve(hostname: string, rrtype: 'MX'): Promise; - function resolve(hostname: string, rrtype: 'NAPTR'): Promise; - function resolve(hostname: string, rrtype: 'NS'): Promise; - function resolve(hostname: string, rrtype: 'PTR'): Promise; - function resolve(hostname: string, rrtype: 'SOA'): Promise; - function resolve(hostname: string, rrtype: 'SRV'): Promise; - function resolve(hostname: string, rrtype: 'TXT'): Promise; - function resolve(hostname: string, rrtype: string): Promise; + function resolve(hostname: string, rrtype: "A"): Promise; + function resolve(hostname: string, rrtype: "AAAA"): Promise; + function resolve(hostname: string, rrtype: "ANY"): Promise; + function resolve(hostname: string, rrtype: "CAA"): Promise; + function resolve(hostname: string, rrtype: "CNAME"): Promise; + function resolve(hostname: string, rrtype: "MX"): Promise; + function resolve(hostname: string, rrtype: "NAPTR"): Promise; + function resolve(hostname: string, rrtype: "NS"): Promise; + function resolve(hostname: string, rrtype: "PTR"): Promise; + function resolve(hostname: string, rrtype: "SOA"): Promise; + function resolve(hostname: string, rrtype: "SRV"): Promise; + function resolve(hostname: string, rrtype: "TXT"): Promise; + function resolve( + hostname: string, + rrtype: string, + ): Promise; /** * Uses the DNS protocol to resolve IPv4 addresses (`A` records) for the`hostname`. On success, the `Promise` is resolved with an array of IPv4 * addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`). @@ -189,7 +192,7 @@ declare module 'dns/promises' { * Uses the DNS protocol to resolve `CAA` records for the `hostname`. On success, * the `Promise` is resolved with an array of objects containing available * certification authority authorization records available for the `hostname`(e.g. `[{critical: 0, iodef: 'mailto:pki@example.com'},{critical: 128, issue: 'pki.example.com'}]`). - * @since v15.0.0 + * @since v15.0.0, v14.17.0 */ function resolveCaa(hostname: string): Promise; /** @@ -206,7 +209,7 @@ declare module 'dns/promises' { */ function resolveMx(hostname: string): Promise; /** - * Uses the DNS protocol to resolve regular expression based records (`NAPTR`records) for the `hostname`. On success, the `Promise` is resolved with an array + * Uses the DNS protocol to resolve regular expression-based records (`NAPTR`records) for the `hostname`. On success, the `Promise` is resolved with an array * of objects with the following properties: * * * `flags` @@ -304,6 +307,14 @@ declare module 'dns/promises' { * @since v10.6.0 */ function reverse(ip: string): Promise; + /** + * Get the default value for `verbatim` in {@link lookup} and `dnsPromises.lookup()`. The value could be: + * + * * `ipv4first`: for `verbatim` defaulting to `false`. + * * `verbatim`: for `verbatim` defaulting to `true`. + * @since v20.1.0 + */ + function getDefaultResultOrder(): "ipv4first" | "verbatim"; /** * Sets the IP address and port of servers to be used when performing DNS * resolution. The `servers` argument is an array of [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6) formatted @@ -330,18 +341,63 @@ declare module 'dns/promises' { * @since v10.6.0 * @param servers array of `RFC 5952` formatted addresses */ - function setServers(servers: ReadonlyArray): void; + function setServers(servers: readonly string[]): void; /** - * Set the default value of `verbatim` in {@link lookup}. The value could be: - * - `ipv4first`: sets default `verbatim` `false`. - * - `verbatim`: sets default `verbatim` `true`. + * Set the default value of `verbatim` in `dns.lookup()` and `dnsPromises.lookup()`. The value could be: * - * The default is `ipv4first` and {@link setDefaultResultOrder} have higher priority than `--dns-result-order`. - * When using worker threads, {@link setDefaultResultOrder} from the main thread won't affect the default dns orders in workers. - * @since v14.18.0 - * @param order must be 'ipv4first' or 'verbatim'. + * * `ipv4first`: sets default `verbatim` `false`. + * * `verbatim`: sets default `verbatim` `true`. + * + * The default is `verbatim` and `dnsPromises.setDefaultResultOrder()` have + * higher priority than `--dns-result-order`. When using `worker threads`,`dnsPromises.setDefaultResultOrder()` from the main thread won't affect the + * default dns orders in workers. + * @since v16.4.0, v14.18.0 + * @param order must be `'ipv4first'` or `'verbatim'`. + */ + function setDefaultResultOrder(order: "ipv4first" | "verbatim"): void; + /** + * An independent resolver for DNS requests. + * + * Creating a new resolver uses the default server settings. Setting + * the servers used for a resolver using `resolver.setServers()` does not affect + * other resolvers: + * + * ```js + * const { Resolver } = require('node:dns').promises; + * const resolver = new Resolver(); + * resolver.setServers(['4.4.4.4']); + * + * // This request will use the server at 4.4.4.4, independent of global settings. + * resolver.resolve4('example.org').then((addresses) => { + * // ... + * }); + * + * // Alternatively, the same code can be written using async-await style. + * (async function() { + * const addresses = await resolver.resolve4('example.org'); + * })(); + * ``` + * + * The following methods from the `dnsPromises` API are available: + * + * * `resolver.getServers()` + * * `resolver.resolve()` + * * `resolver.resolve4()` + * * `resolver.resolve6()` + * * `resolver.resolveAny()` + * * `resolver.resolveCaa()` + * * `resolver.resolveCname()` + * * `resolver.resolveMx()` + * * `resolver.resolveNaptr()` + * * `resolver.resolveNs()` + * * `resolver.resolvePtr()` + * * `resolver.resolveSoa()` + * * `resolver.resolveSrv()` + * * `resolver.resolveTxt()` + * * `resolver.reverse()` + * * `resolver.setServers()` + * @since v10.6.0 */ - function setDefaultResultOrder(order: 'ipv4first' | 'verbatim'): void; class Resolver { constructor(options?: ResolverOptions); cancel(): void; @@ -350,6 +406,7 @@ declare module 'dns/promises' { resolve4: typeof resolve4; resolve6: typeof resolve6; resolveAny: typeof resolveAny; + resolveCaa: typeof resolveCaa; resolveCname: typeof resolveCname; resolveMx: typeof resolveMx; resolveNaptr: typeof resolveNaptr; @@ -363,6 +420,6 @@ declare module 'dns/promises' { setServers: typeof setServers; } } -declare module 'node:dns/promises' { - export * from 'dns/promises'; +declare module "node:dns/promises" { + export * from "dns/promises"; } diff --git a/node_modules/@types/node/dom-events.d.ts b/node_modules/@types/node/dom-events.d.ts new file mode 100644 index 0000000..147a7b6 --- /dev/null +++ b/node_modules/@types/node/dom-events.d.ts @@ -0,0 +1,122 @@ +export {}; // Don't export anything! + +//// DOM-like Events +// NB: The Event / EventTarget / EventListener implementations below were copied +// from lib.dom.d.ts, then edited to reflect Node's documentation at +// https://nodejs.org/api/events.html#class-eventtarget. +// Please read that link to understand important implementation differences. + +// This conditional type will be the existing global Event in a browser, or +// the copy below in a Node environment. +type __Event = typeof globalThis extends { onmessage: any; Event: any } ? {} + : { + /** This is not used in Node.js and is provided purely for completeness. */ + readonly bubbles: boolean; + /** Alias for event.stopPropagation(). This is not used in Node.js and is provided purely for completeness. */ + cancelBubble: () => void; + /** True if the event was created with the cancelable option */ + readonly cancelable: boolean; + /** This is not used in Node.js and is provided purely for completeness. */ + readonly composed: boolean; + /** Returns an array containing the current EventTarget as the only entry or empty if the event is not being dispatched. This is not used in Node.js and is provided purely for completeness. */ + composedPath(): [EventTarget?]; + /** Alias for event.target. */ + readonly currentTarget: EventTarget | null; + /** Is true if cancelable is true and event.preventDefault() has been called. */ + readonly defaultPrevented: boolean; + /** This is not used in Node.js and is provided purely for completeness. */ + readonly eventPhase: 0 | 2; + /** The `AbortSignal` "abort" event is emitted with `isTrusted` set to `true`. The value is `false` in all other cases. */ + readonly isTrusted: boolean; + /** Sets the `defaultPrevented` property to `true` if `cancelable` is `true`. */ + preventDefault(): void; + /** This is not used in Node.js and is provided purely for completeness. */ + returnValue: boolean; + /** Alias for event.target. */ + readonly srcElement: EventTarget | null; + /** Stops the invocation of event listeners after the current one completes. */ + stopImmediatePropagation(): void; + /** This is not used in Node.js and is provided purely for completeness. */ + stopPropagation(): void; + /** The `EventTarget` dispatching the event */ + readonly target: EventTarget | null; + /** The millisecond timestamp when the Event object was created. */ + readonly timeStamp: number; + /** Returns the type of event, e.g. "click", "hashchange", or "submit". */ + readonly type: string; + }; + +// See comment above explaining conditional type +type __EventTarget = typeof globalThis extends { onmessage: any; EventTarget: any } ? {} + : { + /** + * Adds a new handler for the `type` event. Any given `listener` is added only once per `type` and per `capture` option value. + * + * If the `once` option is true, the `listener` is removed after the next time a `type` event is dispatched. + * + * The `capture` option is not used by Node.js in any functional way other than tracking registered event listeners per the `EventTarget` specification. + * Specifically, the `capture` option is used as part of the key when registering a `listener`. + * Any individual `listener` may be added once with `capture = false`, and once with `capture = true`. + */ + addEventListener( + type: string, + listener: EventListener | EventListenerObject, + options?: AddEventListenerOptions | boolean, + ): void; + /** Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. */ + dispatchEvent(event: Event): boolean; + /** Removes the event listener in target's event listener list with the same type, callback, and options. */ + removeEventListener( + type: string, + listener: EventListener | EventListenerObject, + options?: EventListenerOptions | boolean, + ): void; + }; + +interface EventInit { + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; +} + +interface EventListenerOptions { + /** Not directly used by Node.js. Added for API completeness. Default: `false`. */ + capture?: boolean; +} + +interface AddEventListenerOptions extends EventListenerOptions { + /** When `true`, the listener is automatically removed when it is first invoked. Default: `false`. */ + once?: boolean; + /** When `true`, serves as a hint that the listener will not call the `Event` object's `preventDefault()` method. Default: false. */ + passive?: boolean; +} + +interface EventListener { + (evt: Event): void; +} + +interface EventListenerObject { + handleEvent(object: Event): void; +} + +import {} from "events"; // Make this an ambient declaration +declare global { + /** An event which takes place in the DOM. */ + interface Event extends __Event {} + var Event: typeof globalThis extends { onmessage: any; Event: infer T } ? T + : { + prototype: __Event; + new(type: string, eventInitDict?: EventInit): __Event; + }; + + /** + * EventTarget is a DOM interface implemented by objects that can + * receive events and may have listeners for them. + */ + interface EventTarget extends __EventTarget {} + var EventTarget: typeof globalThis extends { onmessage: any; EventTarget: infer T } ? T + : { + prototype: __EventTarget; + new(): __EventTarget; + }; +} diff --git a/node_modules/@types/node/domain.d.ts b/node_modules/@types/node/domain.d.ts old mode 100755 new mode 100644 index a3ce7ee..72f17bd --- a/node_modules/@types/node/domain.d.ts +++ b/node_modules/@types/node/domain.d.ts @@ -12,10 +12,10 @@ * will be notified, rather than losing the context of the error in the`process.on('uncaughtException')` handler, or causing the program to * exit immediately with an error code. * @deprecated Since v1.4.2 - Deprecated - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/domain.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/domain.js) */ -declare module 'domain' { - import EventEmitter = require('node:events'); +declare module "domain" { + import EventEmitter = require("node:events"); /** * The `Domain` class encapsulates the functionality of routing errors and * uncaught exceptions to the active `Domain` object. @@ -56,15 +56,15 @@ declare module 'domain' { exit(): void; /** * Run the supplied function in the context of the domain, implicitly - * binding all event emitters, timers, and lowlevel requests that are + * binding all event emitters, timers, and low-level requests that are * created in that context. Optionally, arguments can be passed to * the function. * * This is the most basic way to use a domain. * * ```js - * const domain = require('domain'); - * const fs = require('fs'); + * const domain = require('node:domain'); + * const fs = require('node:fs'); * const d = domain.create(); * d.on('error', (er) => { * console.error('Caught error!', er); @@ -165,6 +165,6 @@ declare module 'domain' { } function create(): Domain; } -declare module 'node:domain' { - export * from 'domain'; +declare module "node:domain" { + export * from "domain"; } diff --git a/node_modules/@types/node/events.d.ts b/node_modules/@types/node/events.d.ts old mode 100755 new mode 100644 index 631841a..6ed47c5 --- a/node_modules/@types/node/events.d.ts +++ b/node_modules/@types/node/events.d.ts @@ -22,7 +22,7 @@ * the `eventEmitter.emit()` method is used to trigger the event. * * ```js - * const EventEmitter = require('events'); + * import { EventEmitter } from 'node:events'; * * class MyEmitter extends EventEmitter {} * @@ -32,25 +32,61 @@ * }); * myEmitter.emit('event'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/events.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/events.js) */ -declare module 'events' { +declare module "events" { + import { AsyncResource, AsyncResourceOptions } from "node:async_hooks"; + // NOTE: This class is in the docs but is **not actually exported** by Node. + // If https://github.com/nodejs/node/issues/39903 gets resolved and Node + // actually starts exporting the class, uncomment below. + // import { EventListener, EventListenerObject } from '__dom-events'; + // /** The NodeEventTarget is a Node.js-specific extension to EventTarget that emulates a subset of the EventEmitter API. */ + // interface NodeEventTarget extends EventTarget { + // /** + // * Node.js-specific extension to the `EventTarget` class that emulates the equivalent `EventEmitter` API. + // * The only difference between `addListener()` and `addEventListener()` is that addListener() will return a reference to the EventTarget. + // */ + // addListener(type: string, listener: EventListener | EventListenerObject, options?: { once: boolean }): this; + // /** Node.js-specific extension to the `EventTarget` class that returns an array of event `type` names for which event listeners are registered. */ + // eventNames(): string[]; + // /** Node.js-specific extension to the `EventTarget` class that returns the number of event listeners registered for the `type`. */ + // listenerCount(type: string): number; + // /** Node.js-specific alias for `eventTarget.removeListener()`. */ + // off(type: string, listener: EventListener | EventListenerObject): this; + // /** Node.js-specific alias for `eventTarget.addListener()`. */ + // on(type: string, listener: EventListener | EventListenerObject, options?: { once: boolean }): this; + // /** Node.js-specific extension to the `EventTarget` class that adds a `once` listener for the given event `type`. This is equivalent to calling `on` with the `once` option set to `true`. */ + // once(type: string, listener: EventListener | EventListenerObject): this; + // /** + // * Node.js-specific extension to the `EventTarget` class. + // * If `type` is specified, removes all registered listeners for `type`, + // * otherwise removes all registered listeners. + // */ + // removeAllListeners(type: string): this; + // /** + // * Node.js-specific extension to the `EventTarget` class that removes the listener for the given `type`. + // * The only difference between `removeListener()` and `removeEventListener()` is that `removeListener()` will return a reference to the `EventTarget`. + // */ + // removeListener(type: string, listener: EventListener | EventListenerObject): this; + // } interface EventEmitterOptions { /** * Enables automatic capturing of promise rejection. */ captureRejections?: boolean | undefined; } - interface NodeEventTarget { + // Any EventTarget with a Node-style `once` function + interface _NodeEventTarget { once(eventName: string | symbol, listener: (...args: any[]) => void): this; } - interface DOMEventTarget { + // Any EventTarget with a DOM-style `addEventListener` + interface _DOMEventTarget { addEventListener( eventName: string, listener: (...args: any[]) => void, opts?: { once: boolean; - } + }, ): any; } interface StaticEventEmitterOptions { @@ -58,10 +94,10 @@ declare module 'events' { } interface EventEmitter extends NodeJS.EventEmitter {} /** - * The `EventEmitter` class is defined and exposed by the `events` module: + * The `EventEmitter` class is defined and exposed by the `node:events` module: * * ```js - * const EventEmitter = require('events'); + * import { EventEmitter } from 'node:events'; * ``` * * All `EventEmitter`s emit the event `'newListener'` when new listeners are @@ -72,6 +108,9 @@ declare module 'events' { */ class EventEmitter { constructor(options?: EventEmitterOptions); + + [EventEmitter.captureRejectionSymbol]?(error: Error, event: string, ...args: any[]): void; + /** * Creates a `Promise` that is fulfilled when the `EventEmitter` emits the given * event or that is rejected if the `EventEmitter` emits `'error'` while waiting. @@ -82,31 +121,28 @@ declare module 'events' { * semantics and does not listen to the `'error'` event. * * ```js - * const { once, EventEmitter } = require('events'); + * import { once, EventEmitter } from 'node:events'; + * import process from 'node:process'; * - * async function run() { - * const ee = new EventEmitter(); + * const ee = new EventEmitter(); * - * process.nextTick(() => { - * ee.emit('myevent', 42); - * }); + * process.nextTick(() => { + * ee.emit('myevent', 42); + * }); * - * const [value] = await once(ee, 'myevent'); - * console.log(value); + * const [value] = await once(ee, 'myevent'); + * console.log(value); * - * const err = new Error('kaboom'); - * process.nextTick(() => { - * ee.emit('error', err); - * }); + * const err = new Error('kaboom'); + * process.nextTick(() => { + * ee.emit('error', err); + * }); * - * try { - * await once(ee, 'myevent'); - * } catch (err) { - * console.log('error happened', err); - * } + * try { + * await once(ee, 'myevent'); + * } catch (err) { + * console.error('error happened', err); * } - * - * run(); * ``` * * The special handling of the `'error'` event is only used when `events.once()`is used to wait for another event. If `events.once()` is used to wait for the @@ -114,13 +150,13 @@ declare module 'events' { * special handling: * * ```js - * const { EventEmitter, once } = require('events'); + * import { EventEmitter, once } from 'node:events'; * * const ee = new EventEmitter(); * * once(ee, 'error') * .then(([err]) => console.log('ok', err.message)) - * .catch((err) => console.log('error', err.message)); + * .catch((err) => console.error('error', err.message)); * * ee.emit('error', new Error('boom')); * @@ -130,7 +166,7 @@ declare module 'events' { * An `AbortSignal` can be used to cancel waiting for the event: * * ```js - * const { EventEmitter, once } = require('events'); + * import { EventEmitter, once } from 'node:events'; * * const ee = new EventEmitter(); * const ac = new AbortController(); @@ -154,29 +190,32 @@ declare module 'events' { * ``` * @since v11.13.0, v10.16.0 */ - static once(emitter: NodeEventTarget, eventName: string | symbol, options?: StaticEventEmitterOptions): Promise; - static once(emitter: DOMEventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise; + static once( + emitter: _NodeEventTarget, + eventName: string | symbol, + options?: StaticEventEmitterOptions, + ): Promise; + static once(emitter: _DOMEventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise; /** * ```js - * const { on, EventEmitter } = require('events'); + * import { on, EventEmitter } from 'node:events'; + * import process from 'node:process'; * - * (async () => { - * const ee = new EventEmitter(); + * const ee = new EventEmitter(); * - * // Emit later on - * process.nextTick(() => { - * ee.emit('foo', 'bar'); - * ee.emit('foo', 42); - * }); + * // Emit later on + * process.nextTick(() => { + * ee.emit('foo', 'bar'); + * ee.emit('foo', 42); + * }); * - * for await (const event of on(ee, 'foo')) { - * // The execution of this inner block is synchronous and it - * // processes one event at a time (even with await). Do not use - * // if concurrent execution is required. - * console.log(event); // prints ['bar'] [42] - * } - * // Unreachable here - * })(); + * for await (const event of on(ee, 'foo')) { + * // The execution of this inner block is synchronous and it + * // processes one event at a time (even with await). Do not use + * // if concurrent execution is required. + * console.log(event); // prints ['bar'] [42] + * } + * // Unreachable here * ``` * * Returns an `AsyncIterator` that iterates `eventName` events. It will throw @@ -187,7 +226,9 @@ declare module 'events' { * An `AbortSignal` can be used to cancel waiting on events: * * ```js - * const { on, EventEmitter } = require('events'); + * import { on, EventEmitter } from 'node:events'; + * import process from 'node:process'; + * * const ac = new AbortController(); * * (async () => { @@ -214,12 +255,17 @@ declare module 'events' { * @param eventName The name of the event being listened for * @return that iterates `eventName` events emitted by the `emitter` */ - static on(emitter: NodeJS.EventEmitter, eventName: string, options?: StaticEventEmitterOptions): AsyncIterableIterator; + static on( + emitter: NodeJS.EventEmitter, + eventName: string, + options?: StaticEventEmitterOptions, + ): AsyncIterableIterator; /** * A class method that returns the number of listeners for the given `eventName`registered on the given `emitter`. * * ```js - * const { EventEmitter, listenerCount } = require('events'); + * import { EventEmitter, listenerCount } from 'node:events'; + * * const myEmitter = new EventEmitter(); * myEmitter.on('event', () => {}); * myEmitter.on('event', () => {}); @@ -242,30 +288,56 @@ declare module 'events' { * event target. This is useful for debugging and diagnostic purposes. * * ```js - * const { getEventListeners, EventEmitter } = require('events'); + * import { getEventListeners, EventEmitter } from 'node:events'; * * { * const ee = new EventEmitter(); * const listener = () => console.log('Events are fun'); * ee.on('foo', listener); - * getEventListeners(ee, 'foo'); // [listener] + * console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ] * } * { * const et = new EventTarget(); * const listener = () => console.log('Events are fun'); * et.addEventListener('foo', listener); - * getEventListeners(et, 'foo'); // [listener] + * console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ] * } * ``` - * @since v15.2.0 + * @since v15.2.0, v14.17.0 */ - static getEventListeners(emitter: DOMEventTarget | NodeJS.EventEmitter, name: string | symbol): Function[]; + static getEventListeners(emitter: _DOMEventTarget | NodeJS.EventEmitter, name: string | symbol): Function[]; + /** + * Returns the currently set max amount of listeners. + * + * For `EventEmitter`s this behaves exactly the same as calling `.getMaxListeners` on + * the emitter. + * + * For `EventTarget`s this is the only way to get the max event listeners for the + * event target. If the number of event handlers on a single EventTarget exceeds + * the max set, the EventTarget will print a warning. + * + * ```js + * import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events'; + * + * { + * const ee = new EventEmitter(); + * console.log(getMaxListeners(ee)); // 10 + * setMaxListeners(11, ee); + * console.log(getMaxListeners(ee)); // 11 + * } + * { + * const et = new EventTarget(); + * console.log(getMaxListeners(et)); // 10 + * setMaxListeners(11, et); + * console.log(getMaxListeners(et)); // 11 + * } + * ``` + * @since v19.9.0 + */ + static getMaxListeners(emitter: _DOMEventTarget | NodeJS.EventEmitter): number; /** * ```js - * const { - * setMaxListeners, - * EventEmitter - * } = require('events'); + * import { setMaxListeners, EventEmitter } from 'node:events'; * * const target = new EventTarget(); * const emitter = new EventEmitter(); @@ -277,26 +349,103 @@ declare module 'events' { * @param eventsTargets Zero or more {EventTarget} or {EventEmitter} instances. If none are specified, `n` is set as the default max for all newly created {EventTarget} and {EventEmitter} * objects. */ - static setMaxListeners(n?: number, ...eventTargets: Array): void; + static setMaxListeners(n?: number, ...eventTargets: Array<_DOMEventTarget | NodeJS.EventEmitter>): void; /** - * This symbol shall be used to install a listener for only monitoring `'error'` - * events. Listeners installed using this symbol are called before the regular - * `'error'` listeners are called. + * Listens once to the `abort` event on the provided `signal`. * - * Installing a listener using this symbol does not change the behavior once an - * `'error'` event is emitted, therefore the process will still crash if no + * Listening to the `abort` event on abort signals is unsafe and may + * lead to resource leaks since another third party with the signal can + * call `e.stopImmediatePropagation()`. Unfortunately Node.js cannot change + * this since it would violate the web standard. Additionally, the original + * API makes it easy to forget to remove listeners. + * + * This API allows safely using `AbortSignal`s in Node.js APIs by solving these + * two issues by listening to the event such that `stopImmediatePropagation` does + * not prevent the listener from running. + * + * Returns a disposable so that it may be unsubscribed from more easily. + * + * ```js + * import { addAbortListener } from 'node:events'; + * + * function example(signal) { + * let disposable; + * try { + * signal.addEventListener('abort', (e) => e.stopImmediatePropagation()); + * disposable = addAbortListener(signal, (e) => { + * // Do something when signal is aborted. + * }); + * } finally { + * disposable?.[Symbol.dispose](); + * } + * } + * ``` + * @since v20.5.0 + * @experimental + * @return Disposable that removes the `abort` listener. + */ + static addAbortListener(signal: AbortSignal, resource: (event: Event) => void): Disposable; + /** + * This symbol shall be used to install a listener for only monitoring `'error'`events. Listeners installed using this symbol are called before the regular`'error'` listeners are called. + * + * Installing a listener using this symbol does not change the behavior once an`'error'` event is emitted. Therefore, the process will still crash if no * regular `'error'` listener is installed. + * @since v13.6.0, v12.17.0 */ static readonly errorMonitor: unique symbol; + /** + * Value: `Symbol.for('nodejs.rejection')` + * + * See how to write a custom `rejection handler`. + * @since v13.4.0, v12.16.0 + */ static readonly captureRejectionSymbol: unique symbol; /** - * Sets or gets the default captureRejection value for all emitters. + * Value: [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) + * + * Change the default `captureRejections` option on all new `EventEmitter` objects. + * @since v13.4.0, v12.16.0 */ - // TODO: These should be described using static getter/setter pairs: static captureRejections: boolean; + /** + * By default, a maximum of `10` listeners can be registered for any single + * event. This limit can be changed for individual `EventEmitter` instances + * using the `emitter.setMaxListeners(n)` method. To change the default + * for _all_`EventEmitter` instances, the `events.defaultMaxListeners`property can be used. If this value is not a positive number, a `RangeError`is thrown. + * + * Take caution when setting the `events.defaultMaxListeners` because the + * change affects _all_`EventEmitter` instances, including those created before + * the change is made. However, calling `emitter.setMaxListeners(n)` still has + * precedence over `events.defaultMaxListeners`. + * + * This is not a hard limit. The `EventEmitter` instance will allow + * more listeners to be added but will output a trace warning to stderr indicating + * that a "possible EventEmitter memory leak" has been detected. For any single`EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()`methods can be used to + * temporarily avoid this warning: + * + * ```js + * import { EventEmitter } from 'node:events'; + * const emitter = new EventEmitter(); + * emitter.setMaxListeners(emitter.getMaxListeners() + 1); + * emitter.once('event', () => { + * // do stuff + * emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0)); + * }); + * ``` + * + * The `--trace-warnings` command-line flag can be used to display the + * stack trace for such warnings. + * + * The emitted warning can be inspected with `process.on('warning')` and will + * have the additional `emitter`, `type`, and `count` properties, referring to + * the event emitter instance, the event's name and the number of attached + * listeners, respectively. + * Its `name` property is set to `'MaxListenersExceededWarning'`. + * @since v0.11.2 + */ static defaultMaxListeners: number; } - import internal = require('node:events'); + import internal = require("node:events"); namespace EventEmitter { // Should just be `export { EventEmitter }`, but that doesn't work in TypeScript 3.4 export { internal as EventEmitter }; @@ -306,10 +455,89 @@ declare module 'events' { */ signal?: AbortSignal | undefined; } + + export interface EventEmitterReferencingAsyncResource extends AsyncResource { + readonly eventEmitter: EventEmitterAsyncResource; + } + + export interface EventEmitterAsyncResourceOptions extends AsyncResourceOptions, EventEmitterOptions { + /** + * The type of async event, this is required when instantiating `EventEmitterAsyncResource` + * directly rather than as a child class. + * @default new.target.name if instantiated as a child class. + */ + name?: string; + } + + /** + * Integrates `EventEmitter` with `AsyncResource` for `EventEmitter`s that + * require manual async tracking. Specifically, all events emitted by instances + * of `events.EventEmitterAsyncResource` will run within its `async context`. + * + * ```js + * import { EventEmitterAsyncResource, EventEmitter } from 'node:events'; + * import { notStrictEqual, strictEqual } from 'node:assert'; + * import { executionAsyncId, triggerAsyncId } from 'node:async_hooks'; + * + * // Async tracking tooling will identify this as 'Q'. + * const ee1 = new EventEmitterAsyncResource({ name: 'Q' }); + * + * // 'foo' listeners will run in the EventEmitters async context. + * ee1.on('foo', () => { + * strictEqual(executionAsyncId(), ee1.asyncId); + * strictEqual(triggerAsyncId(), ee1.triggerAsyncId); + * }); + * + * const ee2 = new EventEmitter(); + * + * // 'foo' listeners on ordinary EventEmitters that do not track async + * // context, however, run in the same async context as the emit(). + * ee2.on('foo', () => { + * notStrictEqual(executionAsyncId(), ee2.asyncId); + * notStrictEqual(triggerAsyncId(), ee2.triggerAsyncId); + * }); + * + * Promise.resolve().then(() => { + * ee1.emit('foo'); + * ee2.emit('foo'); + * }); + * ``` + * + * The `EventEmitterAsyncResource` class has the same methods and takes the + * same options as `EventEmitter` and `AsyncResource` themselves. + * @since v17.4.0, v16.14.0 + */ + export class EventEmitterAsyncResource extends EventEmitter { + /** + * @param options Only optional in child class. + */ + constructor(options?: EventEmitterAsyncResourceOptions); + /** + * Call all `destroy` hooks. This should only ever be called once. An error will + * be thrown if it is called more than once. This **must** be manually called. If + * the resource is left to be collected by the GC then the `destroy` hooks will + * never be called. + */ + emitDestroy(): void; + /** + * The unique `asyncId` assigned to the resource. + */ + readonly asyncId: number; + /** + * The same triggerAsyncId that is passed to the AsyncResource constructor. + */ + readonly triggerAsyncId: number; + /** + * The returned `AsyncResource` object has an additional `eventEmitter` property + * that provides a reference to this `EventEmitterAsyncResource`. + */ + readonly asyncResource: EventEmitterReferencingAsyncResource; + } } global { namespace NodeJS { interface EventEmitter { + [EventEmitter.captureRejectionSymbol]?(error: Error, event: string, ...args: any[]): void; /** * Alias for `emitter.on(eventName, listener)`. * @since v0.1.26 @@ -333,6 +561,7 @@ declare module 'events' { * event listener to the beginning of the listeners array. * * ```js + * import { EventEmitter } from 'node:events'; * const myEE = new EventEmitter(); * myEE.on('foo', () => console.log('a')); * myEE.prependListener('foo', () => console.log('b')); @@ -362,6 +591,7 @@ declare module 'events' { * event listener to the beginning of the listeners array. * * ```js + * import { EventEmitter } from 'node:events'; * const myEE = new EventEmitter(); * myEE.once('foo', () => console.log('a')); * myEE.prependOnceListener('foo', () => console.log('b')); @@ -393,10 +623,12 @@ declare module 'events' { * called multiple times to remove each instance. * * Once an event is emitted, all listeners attached to it at the - * time of emitting are called in order. This implies that any`removeListener()` or `removeAllListeners()` calls _after_ emitting and_before_ the last listener finishes execution will - * not remove them from`emit()` in progress. Subsequent events behave as expected. + * time of emitting are called in order. This implies that any`removeListener()` or `removeAllListeners()` calls _after_ emitting and _before_ the last listener finishes execution + * will not remove them from`emit()` in progress. Subsequent events behave as expected. * * ```js + * import { EventEmitter } from 'node:events'; + * class MyEmitter extends EventEmitter {} * const myEmitter = new MyEmitter(); * * const callbackA = () => { @@ -437,6 +669,7 @@ declare module 'events' { * recently added instance. In the example the `once('ping')`listener is removed: * * ```js + * import { EventEmitter } from 'node:events'; * const ee = new EventEmitter(); * * function pong() { @@ -505,6 +738,7 @@ declare module 'events' { * including any wrappers (such as those created by `.once()`). * * ```js + * import { EventEmitter } from 'node:events'; * const emitter = new EventEmitter(); * emitter.once('log', () => console.log('log once')); * @@ -537,7 +771,7 @@ declare module 'events' { * Returns `true` if the event had listeners, `false` otherwise. * * ```js - * const EventEmitter = require('events'); + * import { EventEmitter } from 'node:events'; * const myEmitter = new EventEmitter(); * * // First listener @@ -572,11 +806,14 @@ declare module 'events' { */ emit(eventName: string | symbol, ...args: any[]): boolean; /** - * Returns the number of listeners listening to the event named `eventName`. + * Returns the number of listeners listening for the event named `eventName`. + * If `listener` is provided, it will return how many times the listener is found + * in the list of the listeners of the event. * @since v3.2.0 * @param eventName The name of the event being listened for + * @param listener The event handler function */ - listenerCount(eventName: string | symbol): number; + listenerCount(eventName: string | symbol, listener?: Function): number; /** * Adds the `listener` function to the _beginning_ of the listeners array for the * event named `eventName`. No checks are made to see if the `listener` has @@ -596,7 +833,7 @@ declare module 'events' { */ prependListener(eventName: string | symbol, listener: (...args: any[]) => void): this; /** - * Adds a **one-time**`listener` function for the event named `eventName` to the_beginning_ of the listeners array. The next time `eventName` is triggered, this + * Adds a **one-time**`listener` function for the event named `eventName` to the _beginning_ of the listeners array. The next time `eventName` is triggered, this * listener is removed, and then invoked. * * ```js @@ -616,7 +853,8 @@ declare module 'events' { * listeners. The values in the array are strings or `Symbol`s. * * ```js - * const EventEmitter = require('events'); + * import { EventEmitter } from 'node:events'; + * * const myEE = new EventEmitter(); * myEE.on('foo', () => {}); * myEE.on('bar', () => {}); @@ -635,7 +873,7 @@ declare module 'events' { } export = EventEmitter; } -declare module 'node:events' { - import events = require('events'); +declare module "node:events" { + import events = require("events"); export = events; } diff --git a/node_modules/@types/node/fs.d.ts b/node_modules/@types/node/fs.d.ts old mode 100755 new mode 100644 index a7b46c0..5cbca12 --- a/node_modules/@types/node/fs.d.ts +++ b/node_modules/@types/node/fs.d.ts @@ -1,28 +1,28 @@ /** - * The `fs` module enables interacting with the file system in a + * The `node:fs` module enables interacting with the file system in a * way modeled on standard POSIX functions. * * To use the promise-based APIs: * * ```js - * import * as fs from 'fs/promises'; + * import * as fs from 'node:fs/promises'; * ``` * * To use the callback and sync APIs: * * ```js - * import * as fs from 'fs'; + * import * as fs from 'node:fs'; * ``` * * All file system operations have synchronous, callback, and promise-based * forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM). - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/fs.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/fs.js) */ -declare module 'fs' { - import * as stream from 'node:stream'; - import { Abortable, EventEmitter } from 'node:events'; - import { URL } from 'node:url'; - import * as promises from 'node:fs/promises'; +declare module "fs" { + import * as stream from "node:stream"; + import { Abortable, EventEmitter } from "node:events"; + import { URL } from "node:url"; + import * as promises from "node:fs/promises"; export { promises }; /** * Valid types for path values in "fs". @@ -32,10 +32,10 @@ declare module 'fs' { export type TimeLike = string | number | Date; export type NoParamCallback = (err: NodeJS.ErrnoException | null) => void; export type BufferEncodingOption = - | 'buffer' + | "buffer" | { - encoding: 'buffer'; - }; + encoding: "buffer"; + }; export interface ObjectEncodingOptions { encoding?: BufferEncoding | null | undefined; } @@ -73,7 +73,7 @@ declare module 'fs' { /** * A `fs.Stats` object provides information about a file. * - * Objects returned from {@link stat}, {@link lstat} and {@link fstat} and + * Objects returned from {@link stat}, {@link lstat}, {@link fstat}, and * their synchronous counterparts are of this type. * If `bigint` in the `options` passed to those methods is true, the numeric values * will be `bigint` instead of `number`, and the object will contain additional @@ -131,6 +131,62 @@ declare module 'fs' { * @since v0.1.21 */ export class Stats {} + export interface StatsFsBase { + /** Type of file system. */ + type: T; + /** Optimal transfer block size. */ + bsize: T; + /** Total data blocks in file system. */ + blocks: T; + /** Free blocks in file system. */ + bfree: T; + /** Available blocks for unprivileged users */ + bavail: T; + /** Total file nodes in file system. */ + files: T; + /** Free file nodes in file system. */ + ffree: T; + } + export interface StatsFs extends StatsFsBase {} + /** + * Provides information about a mounted file system. + * + * Objects returned from {@link statfs} and its synchronous counterpart are of + * this type. If `bigint` in the `options` passed to those methods is `true`, the + * numeric values will be `bigint` instead of `number`. + * + * ```console + * StatFs { + * type: 1397114950, + * bsize: 4096, + * blocks: 121938943, + * bfree: 61058895, + * bavail: 61058895, + * files: 999, + * ffree: 1000000 + * } + * ``` + * + * `bigint` version: + * + * ```console + * StatFs { + * type: 1397114950n, + * bsize: 4096n, + * blocks: 121938943n, + * bfree: 61058895n, + * bavail: 61058895n, + * files: 999n, + * ffree: 1000000n + * } + * ``` + * @since v19.6.0, v18.15.0 + */ + export class StatsFs {} + export interface BigIntStatsFs extends StatsFsBase {} + export interface StatFsOptions { + bigint?: boolean | undefined; + } /** * A representation of a directory entry, which can be a file or a subdirectory * within the directory, as returned by reading from an `fs.Dir`. The @@ -184,6 +240,11 @@ declare module 'fs' { * @since v10.10.0 */ name: string; + /** + * The base path that this `fs.Dirent` object refers to. + * @since v20.1.0 + */ + path: string; } /** * A class representing a directory stream. @@ -191,7 +252,7 @@ declare module 'fs' { * Created by {@link opendir}, {@link opendirSync}, or `fsPromises.opendir()`. * * ```js - * import { opendir } from 'fs/promises'; + * import { opendir } from 'node:fs/promises'; * * try { * const dir = await opendir('./'); @@ -220,7 +281,7 @@ declare module 'fs' { * Asynchronously close the directory's underlying resource handle. * Subsequent reads will result in errors. * - * A promise is returned that will be resolved after the resource has been + * A promise is returned that will be fulfilled after the resource has been * closed. * @since v12.12.0 */ @@ -235,7 +296,7 @@ declare module 'fs' { /** * Asynchronously read the next directory entry via [`readdir(3)`](http://man7.org/linux/man-pages/man3/readdir.3.html) as an `fs.Dirent`. * - * A promise is returned that will be resolved with an `fs.Dirent`, or `null`if there are no more directory entries to read. + * A promise is returned that will be fulfilled with an `fs.Dirent`, or `null`if there are no more directory entries to read. * * Directory entries returned by this function are in no particular order as * provided by the operating system's underlying directory mechanisms. @@ -268,18 +329,22 @@ declare module 'fs' { */ export interface StatWatcher extends EventEmitter { /** + * When called, requests that the Node.js event loop _not_ exit so long as the `fs.StatWatcher` is active. Calling `watcher.ref()` multiple times will have + * no effect. + * + * By default, all `fs.StatWatcher` objects are "ref'ed", making it normally + * unnecessary to call `watcher.ref()` unless `watcher.unref()` had been + * called previously. * @since v14.3.0, v12.20.0 - * When called, requests that the Node.js event loop not exit so long as the `fs.StatWatcher` is active. - * Calling `watcher.ref()` multiple times will have no effect. - * By default, all `fs.StatWatcher`` objects are "ref'ed", making it normally unnecessary to call `watcher.ref()` - * unless `watcher.unref()` had been called previously. */ ref(): this; /** + * When called, the active `fs.StatWatcher` object will not require the Node.js + * event loop to remain active. If there is no other activity keeping the + * event loop running, the process may exit before the `fs.StatWatcher` object's + * callback is invoked. Calling `watcher.unref()` multiple times will have + * no effect. * @since v14.3.0, v12.20.0 - * When called, the active `fs.StatWatcher`` object will not require the Node.js event loop to remain active. - * If there is no other activity keeping the event loop running, the process may exit before the `fs.StatWatcher`` object's callback is invoked. - * `Calling watcher.unref()` multiple times will have no effect. */ unref(): this; } @@ -289,31 +354,51 @@ declare module 'fs' { * @since v0.5.8 */ close(): void; + /** + * When called, requests that the Node.js event loop _not_ exit so long as the `fs.FSWatcher` is active. Calling `watcher.ref()` multiple times will have + * no effect. + * + * By default, all `fs.FSWatcher` objects are "ref'ed", making it normally + * unnecessary to call `watcher.ref()` unless `watcher.unref()` had been + * called previously. + * @since v14.3.0, v12.20.0 + */ + ref(): this; + /** + * When called, the active `fs.FSWatcher` object will not require the Node.js + * event loop to remain active. If there is no other activity keeping the + * event loop running, the process may exit before the `fs.FSWatcher` object's + * callback is invoked. Calling `watcher.unref()` multiple times will have + * no effect. + * @since v14.3.0, v12.20.0 + */ + unref(): this; /** * events.EventEmitter * 1. change - * 2. error + * 2. close + * 3. error */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'change', listener: (eventType: string, filename: string | Buffer) => void): this; - addListener(event: 'error', listener: (error: Error) => void): this; - addListener(event: 'close', listener: () => void): this; + addListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "error", listener: (error: Error) => void): this; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'change', listener: (eventType: string, filename: string | Buffer) => void): this; - on(event: 'error', listener: (error: Error) => void): this; - on(event: 'close', listener: () => void): this; + on(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; + on(event: "close", listener: () => void): this; + on(event: "error", listener: (error: Error) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'change', listener: (eventType: string, filename: string | Buffer) => void): this; - once(event: 'error', listener: (error: Error) => void): this; - once(event: 'close', listener: () => void): this; + once(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; + once(event: "close", listener: () => void): this; + once(event: "error", listener: (error: Error) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'change', listener: (eventType: string, filename: string | Buffer) => void): this; - prependListener(event: 'error', listener: (error: Error) => void): this; - prependListener(event: 'close', listener: () => void): this; + prependListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "error", listener: (error: Error) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'change', listener: (eventType: string, filename: string | Buffer) => void): this; - prependOnceListener(event: 'error', listener: (error: Error) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; + prependOnceListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "error", listener: (error: Error) => void): this; } /** * Instances of `fs.ReadStream` are created and returned using the {@link createReadStream} function. @@ -345,55 +430,55 @@ declare module 'fs' { * 2. close * 3. ready */ - addListener(event: 'close', listener: () => void): this; - addListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - addListener(event: 'end', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'open', listener: (fd: number) => void): this; - addListener(event: 'pause', listener: () => void): this; - addListener(event: 'readable', listener: () => void): this; - addListener(event: 'ready', listener: () => void): this; - addListener(event: 'resume', listener: () => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: Buffer | string) => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "open", listener: (fd: number) => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "readable", listener: () => void): this; + addListener(event: "ready", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'data', listener: (chunk: Buffer | string) => void): this; - on(event: 'end', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'open', listener: (fd: number) => void): this; - on(event: 'pause', listener: () => void): this; - on(event: 'readable', listener: () => void): this; - on(event: 'ready', listener: () => void): this; - on(event: 'resume', listener: () => void): this; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: Buffer | string) => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "open", listener: (fd: number) => void): this; + on(event: "pause", listener: () => void): this; + on(event: "readable", listener: () => void): this; + on(event: "ready", listener: () => void): this; + on(event: "resume", listener: () => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'data', listener: (chunk: Buffer | string) => void): this; - once(event: 'end', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'open', listener: (fd: number) => void): this; - once(event: 'pause', listener: () => void): this; - once(event: 'readable', listener: () => void): this; - once(event: 'ready', listener: () => void): this; - once(event: 'resume', listener: () => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: Buffer | string) => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "open", listener: (fd: number) => void): this; + once(event: "pause", listener: () => void): this; + once(event: "readable", listener: () => void): this; + once(event: "ready", listener: () => void): this; + once(event: "resume", listener: () => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependListener(event: 'end', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'open', listener: (fd: number) => void): this; - prependListener(event: 'pause', listener: () => void): this; - prependListener(event: 'readable', listener: () => void): this; - prependListener(event: 'ready', listener: () => void): this; - prependListener(event: 'resume', listener: () => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "open", listener: (fd: number) => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "readable", listener: () => void): this; + prependListener(event: "ready", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependOnceListener(event: 'end', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'open', listener: (fd: number) => void): this; - prependOnceListener(event: 'pause', listener: () => void): this; - prependOnceListener(event: 'readable', listener: () => void): this; - prependOnceListener(event: 'ready', listener: () => void): this; - prependOnceListener(event: 'resume', listener: () => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "open", listener: (fd: number) => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "readable", listener: () => void): this; + prependOnceListener(event: "ready", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } /** @@ -434,50 +519,50 @@ declare module 'fs' { * 2. close * 3. ready */ - addListener(event: 'close', listener: () => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'finish', listener: () => void): this; - addListener(event: 'open', listener: (fd: number) => void): this; - addListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - addListener(event: 'ready', listener: () => void): this; - addListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "open", listener: (fd: number) => void): this; + addListener(event: "pipe", listener: (src: stream.Readable) => void): this; + addListener(event: "ready", listener: () => void): this; + addListener(event: "unpipe", listener: (src: stream.Readable) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'finish', listener: () => void): this; - on(event: 'open', listener: (fd: number) => void): this; - on(event: 'pipe', listener: (src: stream.Readable) => void): this; - on(event: 'ready', listener: () => void): this; - on(event: 'unpipe', listener: (src: stream.Readable) => void): this; + on(event: "close", listener: () => void): this; + on(event: "drain", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "open", listener: (fd: number) => void): this; + on(event: "pipe", listener: (src: stream.Readable) => void): this; + on(event: "ready", listener: () => void): this; + on(event: "unpipe", listener: (src: stream.Readable) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'finish', listener: () => void): this; - once(event: 'open', listener: (fd: number) => void): this; - once(event: 'pipe', listener: (src: stream.Readable) => void): this; - once(event: 'ready', listener: () => void): this; - once(event: 'unpipe', listener: (src: stream.Readable) => void): this; + once(event: "close", listener: () => void): this; + once(event: "drain", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "open", listener: (fd: number) => void): this; + once(event: "pipe", listener: (src: stream.Readable) => void): this; + once(event: "ready", listener: () => void): this; + once(event: "unpipe", listener: (src: stream.Readable) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'finish', listener: () => void): this; - prependListener(event: 'open', listener: (fd: number) => void): this; - prependListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependListener(event: 'ready', listener: () => void): this; - prependListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "open", listener: (fd: number) => void): this; + prependListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependListener(event: "ready", listener: () => void): this; + prependListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'finish', listener: () => void): this; - prependOnceListener(event: 'open', listener: (fd: number) => void): this; - prependOnceListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependOnceListener(event: 'ready', listener: () => void): this; - prependOnceListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "open", listener: (fd: number) => void): this; + prependOnceListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "ready", listener: () => void): this; + prependOnceListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } /** @@ -490,7 +575,7 @@ declare module 'fs' { * See also: [`rename(2)`](http://man7.org/linux/man-pages/man2/rename.2.html). * * ```js - * import { rename } from 'fs'; + * import { rename } from 'node:fs'; * * rename('oldFile.txt', 'newFile.txt', (err) => { * if (err) throw err; @@ -523,7 +608,7 @@ declare module 'fs' { * first argument. In this case, `fs.ftruncate()` is called. * * ```js - * import { truncate } from 'fs'; + * import { truncate } from 'node:fs'; * // Assuming that 'path/file.txt' is a regular file. * truncate('path/file.txt', (err) => { * if (err) throw err; @@ -575,7 +660,7 @@ declare module 'fs' { * file: * * ```js - * import { open, close, ftruncate } from 'fs'; + * import { open, close, ftruncate } from 'node:fs'; * * function closeFd(fd) { * close(fd, (err) => { @@ -732,7 +817,7 @@ declare module 'fs' { * See the POSIX [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html) documentation for more detail. * * ```js - * import { chmod } from 'fs'; + * import { chmod } from 'node:fs'; * * chmod('my_file.txt', 0o775, (err) => { * if (err) throw err; @@ -814,7 +899,10 @@ declare module 'fs' { * * In case of an error, the `err.code` will be one of `Common System Errors`. * - * Using `fs.stat()` to check for the existence of a file before calling`fs.open()`, `fs.readFile()` or `fs.writeFile()` is not recommended. + * {@link stat} follows symbolic links. Use {@link lstat} to look at the + * links themselves. + * + * Using `fs.stat()` to check for the existence of a file before calling`fs.open()`, `fs.readFile()`, or `fs.writeFile()` is not recommended. * Instead, user code should open/read/write the file directly and handle the * error raised if the file is not available. * @@ -831,7 +919,7 @@ declare module 'fs' { * The next program will check for the stats of the given paths: * * ```js - * import { stat } from 'fs'; + * import { stat } from 'node:fs'; * * const pathsToCheck = ['./txtDir', './txtDir/file.txt']; * @@ -896,19 +984,23 @@ declare module 'fs' { path: PathLike, options: | (StatOptions & { - bigint?: false | undefined; - }) + bigint?: false | undefined; + }) | undefined, - callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void + callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void, ): void; export function stat( path: PathLike, options: StatOptions & { bigint: true; }, - callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void + callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void, + ): void; + export function stat( + path: PathLike, + options: StatOptions | undefined, + callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void, ): void; - export function stat(path: PathLike, options: StatOptions | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void): void; export namespace stat { /** * Asynchronous stat(2) - Get file status. @@ -918,13 +1010,13 @@ declare module 'fs' { path: PathLike, options?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; function __promisify__( path: PathLike, options: StatOptions & { bigint: true; - } + }, ): Promise; function __promisify__(path: PathLike, options?: StatOptions): Promise; } @@ -935,33 +1027,33 @@ declare module 'fs' { options?: StatSyncOptions & { bigint?: false | undefined; throwIfNoEntry: false; - } + }, ): Stats | undefined; ( path: PathLike, options: StatSyncOptions & { bigint: true; throwIfNoEntry: false; - } + }, ): BigIntStats | undefined; ( path: PathLike, options?: StatSyncOptions & { bigint?: false | undefined; - } + }, ): Stats; ( path: PathLike, options: StatSyncOptions & { bigint: true; - } + }, ): BigIntStats; ( path: PathLike, options: StatSyncOptions & { bigint: boolean; throwIfNoEntry?: false | undefined; - } + }, ): Stats | BigIntStats; (path: PathLike, options?: StatSyncOptions): Stats | BigIntStats | undefined; } @@ -981,19 +1073,23 @@ declare module 'fs' { fd: number, options: | (StatOptions & { - bigint?: false | undefined; - }) + bigint?: false | undefined; + }) | undefined, - callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void + callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void, ): void; export function fstat( fd: number, options: StatOptions & { bigint: true; }, - callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void + callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void, + ): void; + export function fstat( + fd: number, + options: StatOptions | undefined, + callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void, ): void; - export function fstat(fd: number, options: StatOptions | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void): void; export namespace fstat { /** * Asynchronous fstat(2) - Get file status. @@ -1003,34 +1099,35 @@ declare module 'fs' { fd: number, options?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; function __promisify__( fd: number, options: StatOptions & { bigint: true; - } + }, ): Promise; function __promisify__(fd: number, options?: StatOptions): Promise; } /** - * Synchronous fstat(2) - Get file status. - * @param fd A file descriptor. + * Retrieves the `fs.Stats` for the file descriptor. + * + * See the POSIX [`fstat(2)`](http://man7.org/linux/man-pages/man2/fstat.2.html) documentation for more detail. + * @since v0.1.95 */ export function fstatSync( fd: number, options?: StatOptions & { bigint?: false | undefined; - } + }, ): Stats; export function fstatSync( fd: number, options: StatOptions & { bigint: true; - } + }, ): BigIntStats; export function fstatSync(fd: number, options?: StatOptions): Stats | BigIntStats; - /** * Retrieves the `fs.Stats` for the symbolic link referred to by the path. * The callback gets two arguments `(err, stats)` where `stats` is a `fs.Stats` object. `lstat()` is identical to `stat()`, except that if `path` is a symbolic @@ -1044,19 +1141,23 @@ declare module 'fs' { path: PathLike, options: | (StatOptions & { - bigint?: false | undefined; - }) + bigint?: false | undefined; + }) | undefined, - callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void + callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void, ): void; export function lstat( path: PathLike, options: StatOptions & { bigint: true; }, - callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void + callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void, + ): void; + export function lstat( + path: PathLike, + options: StatOptions | undefined, + callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void, ): void; - export function lstat(path: PathLike, options: StatOptions | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void): void; export namespace lstat { /** * Asynchronous lstat(2) - Get file status. Does not dereference symbolic links. @@ -1066,16 +1167,86 @@ declare module 'fs' { path: PathLike, options?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; function __promisify__( path: PathLike, options: StatOptions & { bigint: true; - } + }, ): Promise; function __promisify__(path: PathLike, options?: StatOptions): Promise; } + /** + * Asynchronous [`statfs(2)`](http://man7.org/linux/man-pages/man2/statfs.2.html). Returns information about the mounted file system which + * contains `path`. The callback gets two arguments `(err, stats)` where `stats`is an `fs.StatFs` object. + * + * In case of an error, the `err.code` will be one of `Common System Errors`. + * @since v19.6.0, v18.15.0 + * @param path A path to an existing file or directory on the file system to be queried. + */ + export function statfs(path: PathLike, callback: (err: NodeJS.ErrnoException | null, stats: StatsFs) => void): void; + export function statfs( + path: PathLike, + options: + | (StatFsOptions & { + bigint?: false | undefined; + }) + | undefined, + callback: (err: NodeJS.ErrnoException | null, stats: StatsFs) => void, + ): void; + export function statfs( + path: PathLike, + options: StatFsOptions & { + bigint: true; + }, + callback: (err: NodeJS.ErrnoException | null, stats: BigIntStatsFs) => void, + ): void; + export function statfs( + path: PathLike, + options: StatFsOptions | undefined, + callback: (err: NodeJS.ErrnoException | null, stats: StatsFs | BigIntStatsFs) => void, + ): void; + export namespace statfs { + /** + * Asynchronous statfs(2) - Returns information about the mounted file system which contains path. The callback gets two arguments (err, stats) where stats is an object. + * @param path A path to an existing file or directory on the file system to be queried. + */ + function __promisify__( + path: PathLike, + options?: StatFsOptions & { + bigint?: false | undefined; + }, + ): Promise; + function __promisify__( + path: PathLike, + options: StatFsOptions & { + bigint: true; + }, + ): Promise; + function __promisify__(path: PathLike, options?: StatFsOptions): Promise; + } + /** + * Synchronous [`statfs(2)`](http://man7.org/linux/man-pages/man2/statfs.2.html). Returns information about the mounted file system which + * contains `path`. + * + * In case of an error, the `err.code` will be one of `Common System Errors`. + * @since v19.6.0, v18.15.0 + * @param path A path to an existing file or directory on the file system to be queried. + */ + export function statfsSync( + path: PathLike, + options?: StatFsOptions & { + bigint?: false | undefined; + }, + ): StatsFs; + export function statfsSync( + path: PathLike, + options: StatFsOptions & { + bigint: true; + }, + ): BigIntStatsFs; + export function statfsSync(path: PathLike, options?: StatFsOptions): StatsFs | BigIntStatsFs; /** * Synchronous lstat(2) - Get file status. Does not dereference symbolic links. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -1109,30 +1280,37 @@ declare module 'fs' { * * The `type` argument is only available on Windows and ignored on other platforms. * It can be set to `'dir'`, `'file'`, or `'junction'`. If the `type` argument is - * not set, Node.js will autodetect `target` type and use `'file'` or `'dir'`. If - * the `target` does not exist, `'file'` will be used. Windows junction points - * require the destination path to be absolute. When using `'junction'`, the`target` argument will automatically be normalized to absolute path. + * not a string, Node.js will autodetect `target` type and use `'file'` or `'dir'`. + * If the `target` does not exist, `'file'` will be used. Windows junction points + * require the destination path to be absolute. When using `'junction'`, the`target` argument will automatically be normalized to absolute path. Junction + * points on NTFS volumes can only point to directories. * - * Relative targets are relative to the link’s parent directory. + * Relative targets are relative to the link's parent directory. * * ```js - * import { symlink } from 'fs'; + * import { symlink } from 'node:fs'; * - * symlink('./mew', './example/mewtwo', callback); + * symlink('./mew', './mewtwo', callback); * ``` * - * The above example creates a symbolic link `mewtwo` in the `example` which points - * to `mew` in the same directory: + * The above example creates a symbolic link `mewtwo` which points to `mew` in the + * same directory: * * ```bash - * $ tree example/ - * example/ + * $ tree . + * . * ├── mew * └── mewtwo -> ./mew * ``` * @since v0.1.31 + * @param [type='null'] */ - export function symlink(target: PathLike, path: PathLike, type: symlink.Type | undefined | null, callback: NoParamCallback): void; + export function symlink( + target: PathLike, + path: PathLike, + type: symlink.Type | undefined | null, + callback: NoParamCallback, + ): void; /** * Asynchronous symlink(2) - Create a new symbolic link to an existing file. * @param target A path to an existing file. If a URL is provided, it must use the `file:` protocol. @@ -1148,7 +1326,7 @@ declare module 'fs' { * When using `'junction'`, the `target` argument will automatically be normalized to an absolute path. */ function __promisify__(target: PathLike, path: PathLike, type?: string | null): Promise; - type Type = 'dir' | 'file' | 'junction'; + type Type = "dir" | "file" | "junction"; } /** * Returns `undefined`. @@ -1156,6 +1334,7 @@ declare module 'fs' { * For detailed information, see the documentation of the asynchronous version of * this API: {@link symlink}. * @since v0.1.31 + * @param [type='null'] */ export function symlinkSync(target: PathLike, path: PathLike, type?: symlink.Type | null): void; /** @@ -1170,24 +1349,39 @@ declare module 'fs' { * the link path returned will be passed as a `Buffer` object. * @since v0.1.31 */ - export function readlink(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, linkString: string) => void): void; + export function readlink( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, linkString: string) => void, + ): void; /** * Asynchronous readlink(2) - read value of a symbolic link. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - export function readlink(path: PathLike, options: BufferEncodingOption, callback: (err: NodeJS.ErrnoException | null, linkString: Buffer) => void): void; + export function readlink( + path: PathLike, + options: BufferEncodingOption, + callback: (err: NodeJS.ErrnoException | null, linkString: Buffer) => void, + ): void; /** * Asynchronous readlink(2) - read value of a symbolic link. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - export function readlink(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, linkString: string | Buffer) => void): void; + export function readlink( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, linkString: string | Buffer) => void, + ): void; /** * Asynchronous readlink(2) - read value of a symbolic link. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ - export function readlink(path: PathLike, callback: (err: NodeJS.ErrnoException | null, linkString: string) => void): void; + export function readlink( + path: PathLike, + callback: (err: NodeJS.ErrnoException | null, linkString: string) => void, + ): void; export namespace readlink { /** * Asynchronous readlink(2) - read value of a symbolic link. @@ -1233,7 +1427,7 @@ declare module 'fs' { */ export function readlinkSync(path: PathLike, options?: EncodingOption): string | Buffer; /** - * Asynchronously computes the canonical pathname by resolving `.`, `..` and + * Asynchronously computes the canonical pathname by resolving `.`, `..`, and * symbolic links. * * A canonical pathname is not necessarily unique. Hard links and bind mounts can @@ -1258,24 +1452,39 @@ declare module 'fs' { * dependent name for that object. * @since v0.1.31 */ - export function realpath(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void): void; + export function realpath( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void, + ): void; /** * Asynchronous realpath(3) - return the canonicalized absolute pathname. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - export function realpath(path: PathLike, options: BufferEncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: Buffer) => void): void; + export function realpath( + path: PathLike, + options: BufferEncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: Buffer) => void, + ): void; /** * Asynchronous realpath(3) - return the canonicalized absolute pathname. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - export function realpath(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | Buffer) => void): void; + export function realpath( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | Buffer) => void, + ): void; /** * Asynchronous realpath(3) - return the canonicalized absolute pathname. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ - export function realpath(path: PathLike, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void): void; + export function realpath( + path: PathLike, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void, + ): void; export namespace realpath { /** * Asynchronous realpath(3) - return the canonicalized absolute pathname. @@ -1312,10 +1521,25 @@ declare module 'fs' { * this restriction. * @since v9.2.0 */ - function native(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void): void; - function native(path: PathLike, options: BufferEncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: Buffer) => void): void; - function native(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | Buffer) => void): void; - function native(path: PathLike, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void): void; + function native( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void, + ): void; + function native( + path: PathLike, + options: BufferEncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: Buffer) => void, + ): void; + function native( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | Buffer) => void, + ): void; + function native( + path: PathLike, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void, + ): void; } /** * Returns the resolved pathname. @@ -1347,7 +1571,7 @@ declare module 'fs' { * possible exception are given to the completion callback. * * ```js - * import { unlink } from 'fs'; + * import { unlink } from 'node:fs'; * // Assuming that 'path/file.txt' is a regular file. * unlink('path/file.txt', (err) => { * if (err) throw err; @@ -1390,7 +1614,7 @@ declare module 'fs' { * Use `fs.rm(path, { recursive: true, force: true })` instead. * * If `true`, perform a recursive directory removal. In - * recursive mode soperations are retried on failure. + * recursive mode, operations are retried on failure. * @default false */ recursive?: boolean | undefined; @@ -1494,18 +1718,19 @@ declare module 'fs' { * * The callback is given a possible exception and, if `recursive` is `true`, the * first directory path created, `(err[, path])`.`path` can still be `undefined` when `recursive` is `true`, if no directory was - * created. + * created (for instance, if it was previously created). * * The optional `options` argument can be an integer specifying `mode` (permission * and sticky bits), or an object with a `mode` property and a `recursive`property indicating whether parent directories should be created. Calling`fs.mkdir()` when `path` is a directory that * exists results in an error only - * when `recursive` is false. + * when `recursive` is false. If `recursive` is false and the directory exists, + * an `EEXIST` error occurs. * * ```js - * import { mkdir } from 'fs'; + * import { mkdir } from 'node:fs'; * - * // Creates /tmp/a/apple, regardless of whether `/tmp` and /tmp/a exist. - * mkdir('/tmp/a/apple', { recursive: true }, (err) => { + * // Create ./tmp/a/apple, regardless of whether ./tmp and ./tmp/a exist. + * mkdir('./tmp/a/apple', { recursive: true }, (err) => { * if (err) throw err; * }); * ``` @@ -1514,7 +1739,7 @@ declare module 'fs' { * result in an error: * * ```js - * import { mkdir } from 'fs'; + * import { mkdir } from 'node:fs'; * * mkdir('/', { recursive: true }, (err) => { * // => [Error: EPERM: operation not permitted, mkdir 'C:\'] @@ -1529,7 +1754,7 @@ declare module 'fs' { options: MakeDirectoryOptions & { recursive: true; }, - callback: (err: NodeJS.ErrnoException | null, path?: string) => void + callback: (err: NodeJS.ErrnoException | null, path?: string) => void, ): void; /** * Asynchronous mkdir(2) - create a directory. @@ -1542,11 +1767,11 @@ declare module 'fs' { options: | Mode | (MakeDirectoryOptions & { - recursive?: false | undefined; - }) + recursive?: false | undefined; + }) | null | undefined, - callback: NoParamCallback + callback: NoParamCallback, ): void; /** * Asynchronous mkdir(2) - create a directory. @@ -1554,7 +1779,11 @@ declare module 'fs' { * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`. */ - export function mkdir(path: PathLike, options: Mode | MakeDirectoryOptions | null | undefined, callback: (err: NodeJS.ErrnoException | null, path?: string) => void): void; + export function mkdir( + path: PathLike, + options: Mode | MakeDirectoryOptions | null | undefined, + callback: (err: NodeJS.ErrnoException | null, path?: string) => void, + ): void; /** * Asynchronous mkdir(2) - create a directory with a mode of `0o777`. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -1571,7 +1800,7 @@ declare module 'fs' { path: PathLike, options: MakeDirectoryOptions & { recursive: true; - } + }, ): Promise; /** * Asynchronous mkdir(2) - create a directory. @@ -1584,9 +1813,9 @@ declare module 'fs' { options?: | Mode | (MakeDirectoryOptions & { - recursive?: false | undefined; - }) - | null + recursive?: false | undefined; + }) + | null, ): Promise; /** * Asynchronous mkdir(2) - create a directory. @@ -1594,7 +1823,10 @@ declare module 'fs' { * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`. */ - function __promisify__(path: PathLike, options?: Mode | MakeDirectoryOptions | null): Promise; + function __promisify__( + path: PathLike, + options?: Mode | MakeDirectoryOptions | null, + ): Promise; } /** * Synchronously creates a directory. Returns `undefined`, or if `recursive` is`true`, the first directory path created. @@ -1607,7 +1839,7 @@ declare module 'fs' { path: PathLike, options: MakeDirectoryOptions & { recursive: true; - } + }, ): string | undefined; /** * Synchronous mkdir(2) - create a directory. @@ -1620,9 +1852,9 @@ declare module 'fs' { options?: | Mode | (MakeDirectoryOptions & { - recursive?: false | undefined; - }) - | null + recursive?: false | undefined; + }) + | null, ): void; /** * Synchronous mkdir(2) - create a directory. @@ -1646,9 +1878,11 @@ declare module 'fs' { * object with an `encoding` property specifying the character encoding to use. * * ```js - * import { mkdtemp } from 'fs'; + * import { mkdtemp } from 'node:fs'; + * import { join } from 'node:path'; + * import { tmpdir } from 'node:os'; * - * mkdtemp(path.join(os.tmpdir(), 'foo-'), (err, directory) => { + * mkdtemp(join(tmpdir(), 'foo-'), (err, directory) => { * if (err) throw err; * console.log(directory); * // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2 @@ -1658,11 +1892,11 @@ declare module 'fs' { * The `fs.mkdtemp()` method will append the six randomly selected characters * directly to the `prefix` string. For instance, given a directory `/tmp`, if the * intention is to create a temporary directory _within_`/tmp`, the `prefix`must end with a trailing platform-specific path separator - * (`require('path').sep`). + * (`require('node:path').sep`). * * ```js - * import { tmpdir } from 'os'; - * import { mkdtemp } from 'fs'; + * import { tmpdir } from 'node:os'; + * import { mkdtemp } from 'node:fs'; * * // The parent directory for the new temporary directory * const tmpDir = tmpdir(); @@ -1677,7 +1911,7 @@ declare module 'fs' { * }); * * // This method is *CORRECT*: - * import { sep } from 'path'; + * import { sep } from 'node:path'; * mkdtemp(`${tmpDir}${sep}`, (err, directory) => { * if (err) throw err; * console.log(directory); @@ -1688,7 +1922,11 @@ declare module 'fs' { * ``` * @since v5.10.0 */ - export function mkdtemp(prefix: string, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, folder: string) => void): void; + export function mkdtemp( + prefix: string, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, folder: string) => void, + ): void; /** * Asynchronously creates a unique temporary directory. * Generates six random characters to be appended behind a required prefix to create a unique temporary directory. @@ -1697,23 +1935,30 @@ declare module 'fs' { export function mkdtemp( prefix: string, options: - | 'buffer' + | "buffer" | { - encoding: 'buffer'; - }, - callback: (err: NodeJS.ErrnoException | null, folder: Buffer) => void + encoding: "buffer"; + }, + callback: (err: NodeJS.ErrnoException | null, folder: Buffer) => void, ): void; /** * Asynchronously creates a unique temporary directory. * Generates six random characters to be appended behind a required prefix to create a unique temporary directory. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - export function mkdtemp(prefix: string, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, folder: string | Buffer) => void): void; + export function mkdtemp( + prefix: string, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, folder: string | Buffer) => void, + ): void; /** * Asynchronously creates a unique temporary directory. * Generates six random characters to be appended behind a required prefix to create a unique temporary directory. */ - export function mkdtemp(prefix: string, callback: (err: NodeJS.ErrnoException | null, folder: string) => void): void; + export function mkdtemp( + prefix: string, + callback: (err: NodeJS.ErrnoException | null, folder: string) => void, + ): void; export namespace mkdtemp { /** * Asynchronously creates a unique temporary directory. @@ -1774,13 +2019,14 @@ declare module 'fs' { path: PathLike, options: | { - encoding: BufferEncoding | null; - withFileTypes?: false | undefined; - } + encoding: BufferEncoding | null; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } | BufferEncoding | undefined | null, - callback: (err: NodeJS.ErrnoException | null, files: string[]) => void + callback: (err: NodeJS.ErrnoException | null, files: string[]) => void, ): void; /** * Asynchronous readdir(3) - read a directory. @@ -1791,11 +2037,12 @@ declare module 'fs' { path: PathLike, options: | { - encoding: 'buffer'; - withFileTypes?: false | undefined; - } - | 'buffer', - callback: (err: NodeJS.ErrnoException | null, files: Buffer[]) => void + encoding: "buffer"; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } + | "buffer", + callback: (err: NodeJS.ErrnoException | null, files: Buffer[]) => void, ): void; /** * Asynchronous readdir(3) - read a directory. @@ -1806,18 +2053,22 @@ declare module 'fs' { path: PathLike, options: | (ObjectEncodingOptions & { - withFileTypes?: false | undefined; - }) + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }) | BufferEncoding | undefined | null, - callback: (err: NodeJS.ErrnoException | null, files: string[] | Buffer[]) => void + callback: (err: NodeJS.ErrnoException | null, files: string[] | Buffer[]) => void, ): void; /** * Asynchronous readdir(3) - read a directory. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ - export function readdir(path: PathLike, callback: (err: NodeJS.ErrnoException | null, files: string[]) => void): void; + export function readdir( + path: PathLike, + callback: (err: NodeJS.ErrnoException | null, files: string[]) => void, + ): void; /** * Asynchronous readdir(3) - read a directory. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -1827,8 +2078,9 @@ declare module 'fs' { path: PathLike, options: ObjectEncodingOptions & { withFileTypes: true; + recursive?: boolean | undefined; }, - callback: (err: NodeJS.ErrnoException | null, files: Dirent[]) => void + callback: (err: NodeJS.ErrnoException | null, files: Dirent[]) => void, ): void; export namespace readdir { /** @@ -1840,11 +2092,12 @@ declare module 'fs' { path: PathLike, options?: | { - encoding: BufferEncoding | null; - withFileTypes?: false | undefined; - } + encoding: BufferEncoding | null; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } | BufferEncoding - | null + | null, ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -1854,11 +2107,12 @@ declare module 'fs' { function __promisify__( path: PathLike, options: - | 'buffer' + | "buffer" | { - encoding: 'buffer'; - withFileTypes?: false | undefined; - } + encoding: "buffer"; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }, ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -1869,10 +2123,11 @@ declare module 'fs' { path: PathLike, options?: | (ObjectEncodingOptions & { - withFileTypes?: false | undefined; - }) + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }) | BufferEncoding - | null + | null, ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -1883,7 +2138,8 @@ declare module 'fs' { path: PathLike, options: ObjectEncodingOptions & { withFileTypes: true; - } + recursive?: boolean | undefined; + }, ): Promise; } /** @@ -1903,11 +2159,12 @@ declare module 'fs' { path: PathLike, options?: | { - encoding: BufferEncoding | null; - withFileTypes?: false | undefined; - } + encoding: BufferEncoding | null; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } | BufferEncoding - | null + | null, ): string[]; /** * Synchronous readdir(3) - read a directory. @@ -1918,10 +2175,11 @@ declare module 'fs' { path: PathLike, options: | { - encoding: 'buffer'; - withFileTypes?: false | undefined; - } - | 'buffer' + encoding: "buffer"; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } + | "buffer", ): Buffer[]; /** * Synchronous readdir(3) - read a directory. @@ -1932,10 +2190,11 @@ declare module 'fs' { path: PathLike, options?: | (ObjectEncodingOptions & { - withFileTypes?: false | undefined; - }) + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }) | BufferEncoding - | null + | null, ): string[] | Buffer[]; /** * Synchronous readdir(3) - read a directory. @@ -1946,7 +2205,8 @@ declare module 'fs' { path: PathLike, options: ObjectEncodingOptions & { withFileTypes: true; - } + recursive?: boolean | undefined; + }, ): Dirent[]; /** * Closes the file descriptor. No arguments other than a possible exception are @@ -1993,13 +2253,22 @@ declare module 'fs' { * @param [flags='r'] See `support of file system `flags``. * @param [mode=0o666] */ - export function open(path: PathLike, flags: OpenMode | undefined, mode: Mode | undefined | null, callback: (err: NodeJS.ErrnoException | null, fd: number) => void): void; + export function open( + path: PathLike, + flags: OpenMode | undefined, + mode: Mode | undefined | null, + callback: (err: NodeJS.ErrnoException | null, fd: number) => void, + ): void; /** * Asynchronous open(2) - open and possibly create a file. If the file is created, its mode will be `0o666`. - * @param [flags='r'] See `support of file system `flags``. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. + * @param [flags='r'] See `support of file system `flags``. */ - export function open(path: PathLike, flags: OpenMode | undefined, callback: (err: NodeJS.ErrnoException | null, fd: number) => void): void; + export function open( + path: PathLike, + flags: OpenMode | undefined, + callback: (err: NodeJS.ErrnoException | null, fd: number) => void, + ): void; /** * Asynchronous open(2) - open and possibly create a file. If the file is created, its mode will be `0o666`. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -2029,7 +2298,7 @@ declare module 'fs' { * The `atime` and `mtime` arguments follow these rules: * * * Values can be either numbers representing Unix epoch time in seconds,`Date`s, or a numeric string like `'123456789.0'`. - * * If the value can not be converted to a number, or is `NaN`, `Infinity` or`-Infinity`, an `Error` will be thrown. + * * If the value can not be converted to a number, or is `NaN`, `Infinity`, or`-Infinity`, an `Error` will be thrown. * @since v0.4.2 */ export function utimes(path: PathLike, atime: TimeLike, mtime: TimeLike, callback: NoParamCallback): void; @@ -2093,8 +2362,7 @@ declare module 'fs' { */ export function fsyncSync(fd: number): void; /** - * Write `buffer` to the file specified by `fd`. If `buffer` is a normal object, it - * must have an own `toString` function property. + * Write `buffer` to the file specified by `fd`. * * `offset` determines the part of the buffer to be written, and `length` is * an integer specifying the number of bytes to write. @@ -2116,6 +2384,9 @@ declare module 'fs' { * The kernel ignores the position argument and always appends the data to * the end of the file. * @since v0.0.2 + * @param [offset=0] + * @param [length=buffer.byteLength - offset] + * @param [position='null'] */ export function write( fd: number, @@ -2123,7 +2394,7 @@ declare module 'fs' { offset: number | undefined | null, length: number | undefined | null, position: number | undefined | null, - callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void + callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void, ): void; /** * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor. @@ -2136,7 +2407,7 @@ declare module 'fs' { buffer: TBuffer, offset: number | undefined | null, length: number | undefined | null, - callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void + callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void, ): void; /** * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor. @@ -2147,13 +2418,17 @@ declare module 'fs' { fd: number, buffer: TBuffer, offset: number | undefined | null, - callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void + callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void, ): void; /** * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor. * @param fd A file descriptor. */ - export function write(fd: number, buffer: TBuffer, callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void): void; + export function write( + fd: number, + buffer: TBuffer, + callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void, + ): void; /** * Asynchronously writes `string` to the file referenced by the supplied file descriptor. * @param fd A file descriptor. @@ -2166,7 +2441,7 @@ declare module 'fs' { string: string, position: number | undefined | null, encoding: BufferEncoding | undefined | null, - callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void + callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void, ): void; /** * Asynchronously writes `string` to the file referenced by the supplied file descriptor. @@ -2174,13 +2449,22 @@ declare module 'fs' { * @param string A string to write. * @param position The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position. */ - export function write(fd: number, string: string, position: number | undefined | null, callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void): void; + export function write( + fd: number, + string: string, + position: number | undefined | null, + callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void, + ): void; /** * Asynchronously writes `string` to the file referenced by the supplied file descriptor. * @param fd A file descriptor. * @param string A string to write. */ - export function write(fd: number, string: string, callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void): void; + export function write( + fd: number, + string: string, + callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void, + ): void; export namespace write { /** * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor. @@ -2194,7 +2478,7 @@ declare module 'fs' { buffer?: TBuffer, offset?: number, length?: number, - position?: number | null + position?: number | null, ): Promise<{ bytesWritten: number; buffer: TBuffer; @@ -2210,21 +2494,28 @@ declare module 'fs' { fd: number, string: string, position?: number | null, - encoding?: BufferEncoding | null + encoding?: BufferEncoding | null, ): Promise<{ bytesWritten: number; buffer: string; }>; } /** - * If `buffer` is a plain object, it must have an own (not inherited) `toString`function property. - * * For detailed information, see the documentation of the asynchronous version of * this API: {@link write}. * @since v0.1.21 + * @param [offset=0] + * @param [length=buffer.byteLength - offset] + * @param [position='null'] * @return The number of bytes written. */ - export function writeSync(fd: number, buffer: NodeJS.ArrayBufferView, offset?: number | null, length?: number | null, position?: number | null): number; + export function writeSync( + fd: number, + buffer: NodeJS.ArrayBufferView, + offset?: number | null, + length?: number | null, + position?: number | null, + ): number; /** * Synchronously writes `string` to the file referenced by the supplied file descriptor, returning the number of bytes written. * @param fd A file descriptor. @@ -2232,8 +2523,30 @@ declare module 'fs' { * @param position The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position. * @param encoding The expected string encoding. */ - export function writeSync(fd: number, string: string, position?: number | null, encoding?: BufferEncoding | null): number; + export function writeSync( + fd: number, + string: string, + position?: number | null, + encoding?: BufferEncoding | null, + ): number; export type ReadPosition = number | bigint; + export interface ReadSyncOptions { + /** + * @default 0 + */ + offset?: number | undefined; + /** + * @default `length of buffer` + */ + length?: number | undefined; + /** + * @default null + */ + position?: ReadPosition | null | undefined; + } + export interface ReadAsyncOptions extends ReadSyncOptions { + buffer?: TBuffer; + } /** * Read data from the file specified by `fd`. * @@ -2257,7 +2570,25 @@ declare module 'fs' { offset: number, length: number, position: ReadPosition | null, - callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void + callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void, + ): void; + /** + * Similar to the above `fs.read` function, this version takes an optional `options` object. + * If not otherwise specified in an `options` object, + * `buffer` defaults to `Buffer.alloc(16384)`, + * `offset` defaults to `0`, + * `length` defaults to `buffer.byteLength`, `- offset` as of Node 17.6.0 + * `position` defaults to `null` + * @since v12.17.0, 13.11.0 + */ + export function read( + fd: number, + options: ReadAsyncOptions, + callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void, + ): void; + export function read( + fd: number, + callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: NodeJS.ArrayBufferView) => void, ): void; export namespace read { /** @@ -2272,25 +2603,22 @@ declare module 'fs' { buffer: TBuffer, offset: number, length: number, - position: number | null + position: number | null, ): Promise<{ bytesRead: number; buffer: TBuffer; }>; - } - export interface ReadSyncOptions { - /** - * @default 0 - */ - offset?: number | undefined; - /** - * @default `length of buffer` - */ - length?: number | undefined; - /** - * @default null - */ - position?: ReadPosition | null | undefined; + function __promisify__( + fd: number, + options: ReadAsyncOptions, + ): Promise<{ + bytesRead: number; + buffer: TBuffer; + }>; + function __promisify__(fd: number): Promise<{ + bytesRead: number; + buffer: NodeJS.ArrayBufferView; + }>; } /** * Returns the number of `bytesRead`. @@ -2298,8 +2626,15 @@ declare module 'fs' { * For detailed information, see the documentation of the asynchronous version of * this API: {@link read}. * @since v0.1.21 + * @param [position='null'] */ - export function readSync(fd: number, buffer: NodeJS.ArrayBufferView, offset: number, length: number, position: ReadPosition | null): number; + export function readSync( + fd: number, + buffer: NodeJS.ArrayBufferView, + offset: number, + length: number, + position: ReadPosition | null, + ): number; /** * Similar to the above `fs.readSync` function, this version takes an optional `options` object. * If no `options` object is specified, it will default with the above values. @@ -2309,7 +2644,7 @@ declare module 'fs' { * Asynchronously reads the entire contents of a file. * * ```js - * import { readFile } from 'fs'; + * import { readFile } from 'node:fs'; * * readFile('/etc/passwd', (err, data) => { * if (err) throw err; @@ -2325,7 +2660,7 @@ declare module 'fs' { * If `options` is a string, then it specifies the encoding: * * ```js - * import { readFile } from 'fs'; + * import { readFile } from 'node:fs'; * * readFile('/etc/passwd', 'utf8', callback); * ``` @@ -2335,7 +2670,7 @@ declare module 'fs' { * will be returned. * * ```js - * import { readFile } from 'fs'; + * import { readFile } from 'node:fs'; * * // macOS, Linux, and Windows * readFile('', (err, data) => { @@ -2352,7 +2687,7 @@ declare module 'fs' { * request is aborted the callback is called with an `AbortError`: * * ```js - * import { readFile } from 'fs'; + * import { readFile } from 'node:fs'; * * const controller = new AbortController(); * const signal = controller.signal; @@ -2375,12 +2710,12 @@ declare module 'fs' { path: PathOrFileDescriptor, options: | ({ - encoding?: null | undefined; - flag?: string | undefined; - } & Abortable) + encoding?: null | undefined; + flag?: string | undefined; + } & Abortable) | undefined | null, - callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void + callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void, ): void; /** * Asynchronously reads the entire contents of a file. @@ -2393,11 +2728,11 @@ declare module 'fs' { path: PathOrFileDescriptor, options: | ({ - encoding: BufferEncoding; - flag?: string | undefined; - } & Abortable) + encoding: BufferEncoding; + flag?: string | undefined; + } & Abortable) | BufferEncoding, - callback: (err: NodeJS.ErrnoException | null, data: string) => void + callback: (err: NodeJS.ErrnoException | null, data: string) => void, ): void; /** * Asynchronously reads the entire contents of a file. @@ -2410,19 +2745,22 @@ declare module 'fs' { path: PathOrFileDescriptor, options: | (ObjectEncodingOptions & { - flag?: string | undefined; - } & Abortable) + flag?: string | undefined; + } & Abortable) | BufferEncoding | undefined | null, - callback: (err: NodeJS.ErrnoException | null, data: string | Buffer) => void + callback: (err: NodeJS.ErrnoException | null, data: string | Buffer) => void, ): void; /** * Asynchronously reads the entire contents of a file. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * If a file descriptor is provided, the underlying file will _not_ be closed automatically. */ - export function readFile(path: PathOrFileDescriptor, callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void): void; + export function readFile( + path: PathOrFileDescriptor, + callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void, + ): void; export namespace readFile { /** * Asynchronously reads the entire contents of a file. @@ -2436,7 +2774,7 @@ declare module 'fs' { options?: { encoding?: null | undefined; flag?: string | undefined; - } | null + } | null, ): Promise; /** * Asynchronously reads the entire contents of a file. @@ -2450,10 +2788,10 @@ declare module 'fs' { path: PathOrFileDescriptor, options: | { - encoding: BufferEncoding; - flag?: string | undefined; - } - | BufferEncoding + encoding: BufferEncoding; + flag?: string | undefined; + } + | BufferEncoding, ): Promise; /** * Asynchronously reads the entire contents of a file. @@ -2467,10 +2805,10 @@ declare module 'fs' { path: PathOrFileDescriptor, options?: | (ObjectEncodingOptions & { - flag?: string | undefined; - }) + flag?: string | undefined; + }) | BufferEncoding - | null + | null, ): Promise; } /** @@ -2485,7 +2823,7 @@ declare module 'fs' { * Similar to {@link readFile}, when the path is a directory, the behavior of`fs.readFileSync()` is platform-specific. * * ```js - * import { readFileSync } from 'fs'; + * import { readFileSync } from 'node:fs'; * * // macOS, Linux, and Windows * readFileSync(''); @@ -2502,7 +2840,7 @@ declare module 'fs' { options?: { encoding?: null | undefined; flag?: string | undefined; - } | null + } | null, ): Buffer; /** * Synchronously reads the entire contents of a file. @@ -2515,10 +2853,10 @@ declare module 'fs' { path: PathOrFileDescriptor, options: | { - encoding: BufferEncoding; - flag?: string | undefined; - } - | BufferEncoding + encoding: BufferEncoding; + flag?: string | undefined; + } + | BufferEncoding, ): string; /** * Synchronously reads the entire contents of a file. @@ -2531,17 +2869,21 @@ declare module 'fs' { path: PathOrFileDescriptor, options?: | (ObjectEncodingOptions & { - flag?: string | undefined; - }) + flag?: string | undefined; + }) | BufferEncoding - | null + | null, ): string | Buffer; export type WriteFileOptions = - | (ObjectEncodingOptions & - Abortable & { - mode?: Mode | undefined; - flag?: string | undefined; - }) + | ( + & ObjectEncodingOptions + & Abortable + & { + mode?: Mode | undefined; + flag?: string | undefined; + flush?: boolean | undefined; + } + ) | BufferEncoding | null; /** @@ -2555,11 +2897,9 @@ declare module 'fs' { * * The `mode` option only affects the newly created file. See {@link open} for more details. * - * If `data` is a plain object, it must have an own (not inherited) `toString`function property. - * * ```js - * import { writeFile } from 'fs'; - * import { Buffer } from 'buffer'; + * import { writeFile } from 'node:fs'; + * import { Buffer } from 'node:buffer'; * * const data = new Uint8Array(Buffer.from('Hello Node.js')); * writeFile('message.txt', data, (err) => { @@ -2571,7 +2911,7 @@ declare module 'fs' { * If `options` is a string, then it specifies the encoding: * * ```js - * import { writeFile } from 'fs'; + * import { writeFile } from 'node:fs'; * * writeFile('message.txt', 'Hello Node.js', 'utf8', callback); * ``` @@ -2589,8 +2929,8 @@ declare module 'fs' { * to be written. * * ```js - * import { writeFile } from 'fs'; - * import { Buffer } from 'buffer'; + * import { writeFile } from 'node:fs'; + * import { Buffer } from 'node:buffer'; * * const controller = new AbortController(); * const { signal } = controller; @@ -2607,14 +2947,23 @@ declare module 'fs' { * @since v0.1.29 * @param file filename or file descriptor */ - export function writeFile(file: PathOrFileDescriptor, data: string | NodeJS.ArrayBufferView, options: WriteFileOptions, callback: NoParamCallback): void; + export function writeFile( + file: PathOrFileDescriptor, + data: string | NodeJS.ArrayBufferView, + options: WriteFileOptions, + callback: NoParamCallback, + ): void; /** * Asynchronously writes data to a file, replacing the file if it already exists. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * If a file descriptor is provided, the underlying file will _not_ be closed automatically. * @param data The data to write. If something other than a Buffer or Uint8Array is provided, the value is coerced to a string. */ - export function writeFile(path: PathOrFileDescriptor, data: string | NodeJS.ArrayBufferView, callback: NoParamCallback): void; + export function writeFile( + path: PathOrFileDescriptor, + data: string | NodeJS.ArrayBufferView, + callback: NoParamCallback, + ): void; export namespace writeFile { /** * Asynchronously writes data to a file, replacing the file if it already exists. @@ -2628,13 +2977,15 @@ declare module 'fs' { * If `mode` is a string, it is parsed as an octal integer. * If `flag` is not supplied, the default of `'w'` is used. */ - function __promisify__(path: PathOrFileDescriptor, data: string | NodeJS.ArrayBufferView, options?: WriteFileOptions): Promise; + function __promisify__( + path: PathOrFileDescriptor, + data: string | NodeJS.ArrayBufferView, + options?: WriteFileOptions, + ): Promise; } /** * Returns `undefined`. * - * If `data` is a plain object, it must have an own (not inherited) `toString`function property. - * * The `mode` option only affects the newly created file. See {@link open} for more details. * * For detailed information, see the documentation of the asynchronous version of @@ -2642,7 +2993,11 @@ declare module 'fs' { * @since v0.1.29 * @param file filename or file descriptor */ - export function writeFileSync(file: PathOrFileDescriptor, data: string | NodeJS.ArrayBufferView, options?: WriteFileOptions): void; + export function writeFileSync( + file: PathOrFileDescriptor, + data: string | NodeJS.ArrayBufferView, + options?: WriteFileOptions, + ): void; /** * Asynchronously append data to a file, creating the file if it does not yet * exist. `data` can be a string or a `Buffer`. @@ -2650,7 +3005,7 @@ declare module 'fs' { * The `mode` option only affects the newly created file. See {@link open} for more details. * * ```js - * import { appendFile } from 'fs'; + * import { appendFile } from 'node:fs'; * * appendFile('message.txt', 'data to append', (err) => { * if (err) throw err; @@ -2661,7 +3016,7 @@ declare module 'fs' { * If `options` is a string, then it specifies the encoding: * * ```js - * import { appendFile } from 'fs'; + * import { appendFile } from 'node:fs'; * * appendFile('message.txt', 'data to append', 'utf8', callback); * ``` @@ -2671,7 +3026,7 @@ declare module 'fs' { * not be closed automatically. * * ```js - * import { open, close, appendFile } from 'fs'; + * import { open, close, appendFile } from 'node:fs'; * * function closeFd(fd) { * close(fd, (err) => { @@ -2696,7 +3051,12 @@ declare module 'fs' { * @since v0.6.7 * @param path filename or file descriptor */ - export function appendFile(path: PathOrFileDescriptor, data: string | Uint8Array, options: WriteFileOptions, callback: NoParamCallback): void; + export function appendFile( + path: PathOrFileDescriptor, + data: string | Uint8Array, + options: WriteFileOptions, + callback: NoParamCallback, + ): void; /** * Asynchronously append data to a file, creating the file if it does not exist. * @param file A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -2717,7 +3077,11 @@ declare module 'fs' { * If `mode` is a string, it is parsed as an octal integer. * If `flag` is not supplied, the default of `'a'` is used. */ - function __promisify__(file: PathOrFileDescriptor, data: string | Uint8Array, options?: WriteFileOptions): Promise; + function __promisify__( + file: PathOrFileDescriptor, + data: string | Uint8Array, + options?: WriteFileOptions, + ): Promise; } /** * Synchronously append data to a file, creating the file if it does not yet @@ -2726,7 +3090,7 @@ declare module 'fs' { * The `mode` option only affects the newly created file. See {@link open} for more details. * * ```js - * import { appendFileSync } from 'fs'; + * import { appendFileSync } from 'node:fs'; * * try { * appendFileSync('message.txt', 'data to append'); @@ -2739,7 +3103,7 @@ declare module 'fs' { * If `options` is a string, then it specifies the encoding: * * ```js - * import { appendFileSync } from 'fs'; + * import { appendFileSync } from 'node:fs'; * * appendFileSync('message.txt', 'data to append', 'utf8'); * ``` @@ -2749,7 +3113,7 @@ declare module 'fs' { * not be closed automatically. * * ```js - * import { openSync, closeSync, appendFileSync } from 'fs'; + * import { openSync, closeSync, appendFileSync } from 'node:fs'; * * let fd; * @@ -2766,7 +3130,11 @@ declare module 'fs' { * @since v0.6.7 * @param path filename or file descriptor */ - export function appendFileSync(path: PathOrFileDescriptor, data: string | Uint8Array, options?: WriteFileOptions): void; + export function appendFileSync( + path: PathOrFileDescriptor, + data: string | Uint8Array, + options?: WriteFileOptions, + ): void; /** * Watch for changes on `filename`. The callback `listener` will be called each * time the file is accessed. @@ -2818,29 +3186,75 @@ declare module 'fs' { persistent?: boolean | undefined; interval?: number | undefined; } + /** + * Watch for changes on `filename`. The callback `listener` will be called each + * time the file is accessed. + * + * The `options` argument may be omitted. If provided, it should be an object. The`options` object may contain a boolean named `persistent` that indicates + * whether the process should continue to run as long as files are being watched. + * The `options` object may specify an `interval` property indicating how often the + * target should be polled in milliseconds. + * + * The `listener` gets two arguments the current stat object and the previous + * stat object: + * + * ```js + * import { watchFile } from 'node:fs'; + * + * watchFile('message.text', (curr, prev) => { + * console.log(`the current mtime is: ${curr.mtime}`); + * console.log(`the previous mtime was: ${prev.mtime}`); + * }); + * ``` + * + * These stat objects are instances of `fs.Stat`. If the `bigint` option is `true`, + * the numeric values in these objects are specified as `BigInt`s. + * + * To be notified when the file was modified, not just accessed, it is necessary + * to compare `curr.mtimeMs` and `prev.mtimeMs`. + * + * When an `fs.watchFile` operation results in an `ENOENT` error, it + * will invoke the listener once, with all the fields zeroed (or, for dates, the + * Unix Epoch). If the file is created later on, the listener will be called + * again, with the latest stat objects. This is a change in functionality since + * v0.10. + * + * Using {@link watch} is more efficient than `fs.watchFile` and`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and`fs.unwatchFile` when possible. + * + * When a file being watched by `fs.watchFile()` disappears and reappears, + * then the contents of `previous` in the second callback event (the file's + * reappearance) will be the same as the contents of `previous` in the first + * callback event (its disappearance). + * + * This happens when: + * + * * the file is deleted, followed by a restore + * * the file is renamed and then renamed a second time back to its original name + * @since v0.1.31 + */ export function watchFile( filename: PathLike, options: | (WatchFileOptions & { - bigint?: false | undefined; - }) + bigint?: false | undefined; + }) | undefined, - listener: (curr: Stats, prev: Stats) => void + listener: StatsListener, ): StatWatcher; export function watchFile( filename: PathLike, options: | (WatchFileOptions & { - bigint: true; - }) + bigint: true; + }) | undefined, - listener: (curr: BigIntStats, prev: BigIntStats) => void + listener: BigIntStatsListener, ): StatWatcher; /** * Watch for changes on `filename`. The callback `listener` will be called each time the file is accessed. * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol. */ - export function watchFile(filename: PathLike, listener: (curr: Stats, prev: Stats) => void): StatWatcher; + export function watchFile(filename: PathLike, listener: StatsListener): StatWatcher; /** * Stop watching for changes on `filename`. If `listener` is specified, only that * particular listener is removed. Otherwise, _all_ listeners are removed, @@ -2853,14 +3267,17 @@ declare module 'fs' { * @since v0.1.31 * @param listener Optional, a listener previously attached using `fs.watchFile()` */ - export function unwatchFile(filename: PathLike, listener?: (curr: Stats, prev: Stats) => void): void; + export function unwatchFile(filename: PathLike, listener?: StatsListener): void; + export function unwatchFile(filename: PathLike, listener?: BigIntStatsListener): void; export interface WatchOptions extends Abortable { - encoding?: BufferEncoding | 'buffer' | undefined; + encoding?: BufferEncoding | "buffer" | undefined; persistent?: boolean | undefined; recursive?: boolean | undefined; } - export type WatchEventType = 'rename' | 'change'; - export type WatchListener = (event: WatchEventType, filename: T) => void; + export type WatchEventType = "rename" | "change"; + export type WatchListener = (event: WatchEventType, filename: T | null) => void; + export type StatsListener = (curr: Stats, prev: Stats) => void; + export type BigIntStatsListener = (curr: BigIntStats, prev: BigIntStats) => void; /** * Watch for changes on `filename`, where `filename` is either a file or a * directory. @@ -2885,10 +3302,10 @@ declare module 'fs' { filename: PathLike, options: | (WatchOptions & { - encoding: 'buffer'; - }) - | 'buffer', - listener?: WatchListener + encoding: "buffer"; + }) + | "buffer", + listener?: WatchListener, ): FSWatcher; /** * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`. @@ -2898,7 +3315,11 @@ declare module 'fs' { * If `persistent` is not supplied, the default of `true` is used. * If `recursive` is not supplied, the default of `false` is used. */ - export function watch(filename: PathLike, options?: WatchOptions | BufferEncoding | null, listener?: WatchListener): FSWatcher; + export function watch( + filename: PathLike, + options?: WatchOptions | BufferEncoding | null, + listener?: WatchListener, + ): FSWatcher; /** * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`. * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol. @@ -2907,7 +3328,11 @@ declare module 'fs' { * If `persistent` is not supplied, the default of `true` is used. * If `recursive` is not supplied, the default of `false` is used. */ - export function watch(filename: PathLike, options: WatchOptions | string, listener?: WatchListener): FSWatcher; + export function watch( + filename: PathLike, + options: WatchOptions | string, + listener?: WatchListener, + ): FSWatcher; /** * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`. * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol. @@ -2918,7 +3343,7 @@ declare module 'fs' { * Then call the `callback` argument with either true or false: * * ```js - * import { exists } from 'fs'; + * import { exists } from 'node:fs'; * * exists('/etc/passwd', (e) => { * console.log(e ? 'it exists' : 'no passwd!'); @@ -2930,7 +3355,7 @@ declare module 'fs' { * has only one boolean parameter. This is one reason `fs.access()` is recommended * instead of `fs.exists()`. * - * Using `fs.exists()` to check for the existence of a file before calling`fs.open()`, `fs.readFile()` or `fs.writeFile()` is not recommended. Doing + * Using `fs.exists()` to check for the existence of a file before calling`fs.open()`, `fs.readFile()`, or `fs.writeFile()` is not recommended. Doing * so introduces a race condition, since other processes may change the file's * state between the two calls. Instead, user code should open/read/write the * file directly and handle the error raised if the file does not exist. @@ -2938,7 +3363,7 @@ declare module 'fs' { * **write (NOT RECOMMENDED)** * * ```js - * import { exists, open, close } from 'fs'; + * import { exists, open, close } from 'node:fs'; * * exists('myfile', (e) => { * if (e) { @@ -2962,7 +3387,7 @@ declare module 'fs' { * **write (RECOMMENDED)** * * ```js - * import { open, close } from 'fs'; + * import { open, close } from 'node:fs'; * open('myfile', 'wx', (err, fd) => { * if (err) { * if (err.code === 'EEXIST') { @@ -2986,7 +3411,7 @@ declare module 'fs' { * **read (NOT RECOMMENDED)** * * ```js - * import { open, close, exists } from 'fs'; + * import { open, close, exists } from 'node:fs'; * * exists('myfile', (e) => { * if (e) { @@ -3010,7 +3435,7 @@ declare module 'fs' { * **read (RECOMMENDED)** * * ```js - * import { open, close } from 'fs'; + * import { open, close } from 'node:fs'; * * open('myfile', 'r', (err, fd) => { * if (err) { @@ -3036,7 +3461,7 @@ declare module 'fs' { * file; the "recommended" examples are better because they use the file directly * and handle the error, if any. * - * In general, check for the existence of a file only if the file won’t be + * In general, check for the existence of a file only if the file won't be * used directly, for example when its existence is a signal from another * process. * @since v0.0.2 @@ -3061,7 +3486,7 @@ declare module 'fs' { * Node.js callbacks. `fs.existsSync()` does not use a callback. * * ```js - * import { existsSync } from 'fs'; + * import { existsSync } from 'node:fs'; * * if (existsSync('/etc/passwd')) * console.log('The path exists.'); @@ -3186,16 +3611,16 @@ declare module 'fs' { /** * Tests a user's permissions for the file or directory specified by `path`. * The `mode` argument is an optional integer that specifies the accessibility - * checks to be performed. Check `File access constants` for possible values - * of `mode`. It is possible to create a mask consisting of the bitwise OR of - * two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). + * checks to be performed. `mode` should be either the value `fs.constants.F_OK`or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`,`fs.constants.W_OK`, and `fs.constants.X_OK` + * (e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for + * possible values of `mode`. * * The final argument, `callback`, is a callback function that is invoked with * a possible error argument. If any of the accessibility checks fail, the error * argument will be an `Error` object. The following examples check if`package.json` exists, and if it is readable or writable. * * ```js - * import { access, constants } from 'fs'; + * import { access, constants } from 'node:fs'; * * const file = 'package.json'; * @@ -3214,18 +3639,13 @@ declare module 'fs' { * console.log(`${file} ${err ? 'is not writable' : 'is writable'}`); * }); * - * // Check if the file exists in the current directory, and if it is writable. - * access(file, constants.F_OK | constants.W_OK, (err) => { - * if (err) { - * console.error( - * `${file} ${err.code === 'ENOENT' ? 'does not exist' : 'is read-only'}`); - * } else { - * console.log(`${file} exists, and it is writable`); - * } + * // Check if the file is readable and writable. + * access(file, constants.R_OK | constants.W_OK, (err) => { + * console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`); * }); * ``` * - * Do not use `fs.access()` to check for the accessibility of a file before calling`fs.open()`, `fs.readFile()` or `fs.writeFile()`. Doing + * Do not use `fs.access()` to check for the accessibility of a file before calling`fs.open()`, `fs.readFile()`, or `fs.writeFile()`. Doing * so introduces a race condition, since other processes may change the file's * state between the two calls. Instead, user code should open/read/write the * file directly and handle the error raised if the file is not accessible. @@ -3233,7 +3653,7 @@ declare module 'fs' { * **write (NOT RECOMMENDED)** * * ```js - * import { access, open, close } from 'fs'; + * import { access, open, close } from 'node:fs'; * * access('myfile', (err) => { * if (!err) { @@ -3258,7 +3678,7 @@ declare module 'fs' { * **write (RECOMMENDED)** * * ```js - * import { open, close } from 'fs'; + * import { open, close } from 'node:fs'; * * open('myfile', 'wx', (err, fd) => { * if (err) { @@ -3283,7 +3703,7 @@ declare module 'fs' { * **read (NOT RECOMMENDED)** * * ```js - * import { access, open, close } from 'fs'; + * import { access, open, close } from 'node:fs'; * access('myfile', (err) => { * if (err) { * if (err.code === 'ENOENT') { @@ -3311,7 +3731,7 @@ declare module 'fs' { * **read (RECOMMENDED)** * * ```js - * import { open, close } from 'fs'; + * import { open, close } from 'node:fs'; * * open('myfile', 'r', (err, fd) => { * if (err) { @@ -3365,16 +3785,15 @@ declare module 'fs' { /** * Synchronously tests a user's permissions for the file or directory specified * by `path`. The `mode` argument is an optional integer that specifies the - * accessibility checks to be performed. Check `File access constants` for - * possible values of `mode`. It is possible to create a mask consisting of - * the bitwise OR of two or more values - * (e.g. `fs.constants.W_OK | fs.constants.R_OK`). + * accessibility checks to be performed. `mode` should be either the value`fs.constants.F_OK` or a mask consisting of the bitwise OR of any of`fs.constants.R_OK`, `fs.constants.W_OK`, and + * `fs.constants.X_OK` (e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for + * possible values of `mode`. * * If any of the accessibility checks fail, an `Error` will be thrown. Otherwise, * the method will return `undefined`. * * ```js - * import { accessSync, constants } from 'fs'; + * import { accessSync, constants } from 'node:fs'; * * try { * accessSync('etc/passwd', constants.R_OK | constants.W_OK); @@ -3393,19 +3812,33 @@ declare module 'fs' { fd?: number | promises.FileHandle | undefined; mode?: number | undefined; autoClose?: boolean | undefined; - /** - * @default false - */ emitClose?: boolean | undefined; start?: number | undefined; + signal?: AbortSignal | null | undefined; highWaterMark?: number | undefined; } + interface FSImplementation { + open?: (...args: any[]) => any; + close?: (...args: any[]) => any; + } + interface CreateReadStreamFSImplementation extends FSImplementation { + read: (...args: any[]) => any; + } + interface CreateWriteStreamFSImplementation extends FSImplementation { + write: (...args: any[]) => any; + writev?: (...args: any[]) => any; + } interface ReadStreamOptions extends StreamOptions { + fs?: CreateReadStreamFSImplementation | null | undefined; end?: number | undefined; } + interface WriteStreamOptions extends StreamOptions { + fs?: CreateWriteStreamFSImplementation | null | undefined; + flush?: boolean | undefined; + } /** - * Unlike the 16 kb default `highWaterMark` for a `stream.Readable`, the stream - * returned by this method has a default `highWaterMark` of 64 kb. + * Unlike the 16 KiB default `highWaterMark` for a `stream.Readable`, the stream + * returned by this method has a default `highWaterMark` of 64 KiB. * * `options` can include `start` and `end` values to read a range of bytes from * the file instead of the entire file. Both `start` and `end` are inclusive and @@ -3431,7 +3864,7 @@ declare module 'fs' { * also required. * * ```js - * import { createReadStream } from 'fs'; + * import { createReadStream } from 'node:fs'; * * // Create a stream from some character device. * const stream = createReadStream('/dev/input/event0'); @@ -3459,7 +3892,7 @@ declare module 'fs' { * An example to read the last 10 bytes of a file which is 100 bytes long: * * ```js - * import { createReadStream } from 'fs'; + * import { createReadStream } from 'node:fs'; * * createReadStream('sample.txt', { start: 90, end: 99 }); * ``` @@ -3471,9 +3904,9 @@ declare module 'fs' { /** * `options` may also include a `start` option to allow writing data at some * position past the beginning of the file, allowed values are in the - * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than replacing - * it may require the `flags` option to be set to `r+` rather than the default `w`. - * The `encoding` can be any one of those accepted by `Buffer`. + * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than + * replacing it may require the `flags` option to be set to `r+` rather than the + * default `w`. The `encoding` can be any one of those accepted by `Buffer`. * * If `autoClose` is set to true (default behavior) on `'error'` or `'finish'`the file descriptor will be closed automatically. If `autoClose` is false, * then the file descriptor won't be closed, even if there's an error. @@ -3483,7 +3916,7 @@ declare module 'fs' { * By default, the stream will emit a `'close'` event after it has been * destroyed. Set the `emitClose` option to `false` to change this behavior. * - * By providing the `fs` option it is possible to override the corresponding `fs`implementations for `open`, `write`, `writev` and `close`. Overriding `write()`without `writev()` can reduce + * By providing the `fs` option it is possible to override the corresponding `fs`implementations for `open`, `write`, `writev`, and `close`. Overriding `write()`without `writev()` can reduce * performance as some optimizations (`_writev()`) * will be disabled. When providing the `fs` option, overrides for at least one of`write` and `writev` are required. If no `fd` option is supplied, an override * for `open` is also required. If `autoClose` is `true`, an override for `close`is also required. @@ -3495,7 +3928,7 @@ declare module 'fs' { * If `options` is a string, then it specifies the encoding. * @since v0.1.31 */ - export function createWriteStream(path: PathLike, options?: BufferEncoding | StreamOptions): WriteStream; + export function createWriteStream(path: PathLike, options?: BufferEncoding | WriteStreamOptions): WriteStream; /** * Forces all currently queued I/O operations associated with the file to the * operating system's synchronized I/O completion state. Refer to the POSIX [`fdatasync(2)`](http://man7.org/linux/man-pages/man2/fdatasync.2.html) documentation for details. No arguments other @@ -3538,7 +3971,7 @@ declare module 'fs' { * copy-on-write, then the operation will fail. * * ```js - * import { copyFile, constants } from 'fs'; + * import { copyFile, constants } from 'node:fs'; * * function callback(err) { * if (err) throw err; @@ -3581,7 +4014,7 @@ declare module 'fs' { * copy-on-write, then the operation will fail. * * ```js - * import { copyFileSync, constants } from 'fs'; + * import { copyFileSync, constants } from 'node:fs'; * * // destination.txt will be created or overwritten by default. * copyFileSync('source.txt', 'destination.txt'); @@ -3614,28 +4047,38 @@ declare module 'fs' { * The kernel ignores the position argument and always appends the data to * the end of the file. * @since v12.9.0 + * @param [position='null'] */ - export function writev(fd: number, buffers: ReadonlyArray, cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void): void; export function writev( fd: number, - buffers: ReadonlyArray, + buffers: readonly NodeJS.ArrayBufferView[], + cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void, + ): void; + export function writev( + fd: number, + buffers: readonly NodeJS.ArrayBufferView[], position: number, - cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void + cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void, ): void; export interface WriteVResult { bytesWritten: number; buffers: NodeJS.ArrayBufferView[]; } export namespace writev { - function __promisify__(fd: number, buffers: ReadonlyArray, position?: number): Promise; + function __promisify__( + fd: number, + buffers: readonly NodeJS.ArrayBufferView[], + position?: number, + ): Promise; } /** * For detailed information, see the documentation of the asynchronous version of * this API: {@link writev}. * @since v12.9.0 + * @param [position='null'] * @return The number of bytes written. */ - export function writevSync(fd: number, buffers: ReadonlyArray, position?: number): number; + export function writevSync(fd: number, buffers: readonly NodeJS.ArrayBufferView[], position?: number): number; /** * Read from a file specified by `fd` and write to an array of `ArrayBufferView`s * using `readv()`. @@ -3649,29 +4092,72 @@ declare module 'fs' { * If this method is invoked as its `util.promisify()` ed version, it returns * a promise for an `Object` with `bytesRead` and `buffers` properties. * @since v13.13.0, v12.17.0 + * @param [position='null'] */ - export function readv(fd: number, buffers: ReadonlyArray, cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void): void; export function readv( fd: number, - buffers: ReadonlyArray, + buffers: readonly NodeJS.ArrayBufferView[], + cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void, + ): void; + export function readv( + fd: number, + buffers: readonly NodeJS.ArrayBufferView[], position: number, - cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void + cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void, ): void; export interface ReadVResult { bytesRead: number; buffers: NodeJS.ArrayBufferView[]; } export namespace readv { - function __promisify__(fd: number, buffers: ReadonlyArray, position?: number): Promise; + function __promisify__( + fd: number, + buffers: readonly NodeJS.ArrayBufferView[], + position?: number, + ): Promise; } /** * For detailed information, see the documentation of the asynchronous version of * this API: {@link readv}. * @since v13.13.0, v12.17.0 + * @param [position='null'] * @return The number of bytes read. */ - export function readvSync(fd: number, buffers: ReadonlyArray, position?: number): number; + export function readvSync(fd: number, buffers: readonly NodeJS.ArrayBufferView[], position?: number): number; + + export interface OpenAsBlobOptions { + /** + * An optional mime type for the blob. + * + * @default 'undefined' + */ + type?: string | undefined; + } + + /** + * Returns a `Blob` whose data is backed by the given file. + * + * The file must not be modified after the `Blob` is created. Any modifications + * will cause reading the `Blob` data to fail with a `DOMException` error. + * Synchronous stat operations on the file when the `Blob` is created, and before + * each read in order to detect whether the file data has been modified on disk. + * + * ```js + * import { openAsBlob } from 'node:fs'; + * + * const blob = await openAsBlob('the.file.txt'); + * const ab = await blob.arrayBuffer(); + * blob.stream(); + * ``` + * @since v19.8.0 + * @experimental + */ + export function openAsBlob(path: PathLike, options?: OpenAsBlobOptions): Promise; + export interface OpenDirOptions { + /** + * @default 'utf8' + */ encoding?: BufferEncoding | undefined; /** * Number of directory entries that are buffered @@ -3680,6 +4166,10 @@ declare module 'fs' { * @default 32 */ bufferSize?: number | undefined; + /** + * @default false + */ + recursive?: boolean; } /** * Synchronously open a directory. See [`opendir(3)`](http://man7.org/linux/man-pages/man3/opendir.3.html). @@ -3704,7 +4194,11 @@ declare module 'fs' { * @since v12.12.0 */ export function opendir(path: PathLike, cb: (err: NodeJS.ErrnoException | null, dir: Dir) => void): void; - export function opendir(path: PathLike, options: OpenDirOptions, cb: (err: NodeJS.ErrnoException | null, dir: Dir) => void): void; + export function opendir( + path: PathLike, + options: OpenDirOptions, + cb: (err: NodeJS.ErrnoException | null, dir: Dir) => void, + ): void; export namespace opendir { function __promisify__(path: PathLike, options?: OpenDirOptions): Promise; } @@ -3742,6 +4236,10 @@ declare module 'fs' { * @default true */ force?: boolean; + /** + * Modifiers for copy operation. See `mode` flag of {@link copyFileSync()} + */ + mode?: number; /** * When `true` timestamps from `src` will * be preserved. @@ -3753,6 +4251,11 @@ declare module 'fs' { * @default false */ recursive?: boolean; + /** + * When true, path resolution for symlinks will be skipped + * @default false + */ + verbatimSymlinks?: boolean; } export interface CopyOptions extends CopyOptionsBase { /** @@ -3779,8 +4282,17 @@ declare module 'fs' { * @param src source path to copy. * @param dest destination path to copy to. */ - export function cp(source: string | URL, destination: string | URL, callback: (err: NodeJS.ErrnoException | null) => void): void; - export function cp(source: string | URL, destination: string | URL, opts: CopyOptions, callback: (err: NodeJS.ErrnoException | null) => void): void; + export function cp( + source: string | URL, + destination: string | URL, + callback: (err: NodeJS.ErrnoException | null) => void, + ): void; + export function cp( + source: string | URL, + destination: string | URL, + opts: CopyOptions, + callback: (err: NodeJS.ErrnoException | null) => void, + ): void; /** * Synchronously copies the entire directory structure from `src` to `dest`, * including subdirectories and files. @@ -3794,6 +4306,6 @@ declare module 'fs' { */ export function cpSync(source: string | URL, destination: string | URL, opts?: CopySyncOptions): void; } -declare module 'node:fs' { - export * from 'fs'; +declare module "node:fs" { + export * from "fs"; } diff --git a/node_modules/@types/node/fs/promises.d.ts b/node_modules/@types/node/fs/promises.d.ts old mode 100755 new mode 100644 index c1667d8..88a9fc3 --- a/node_modules/@types/node/fs/promises.d.ts +++ b/node_modules/@types/node/fs/promises.d.ts @@ -8,11 +8,13 @@ * concurrent modifications on the same file or data corruption may occur. * @since v10.0.0 */ -declare module 'fs/promises' { - import { Abortable } from 'node:events'; - import { Stream } from 'node:stream'; +declare module "fs/promises" { + import { Abortable } from "node:events"; + import { Stream } from "node:stream"; + import { ReadableStream } from "node:stream/web"; import { BigIntStats, + BigIntStatsFs, BufferEncodingOption, constants as fsConstants, CopyOptions, @@ -28,26 +30,30 @@ declare module 'fs/promises' { ReadVResult, RmDirOptions, RmOptions, + StatFsOptions, StatOptions, Stats, + StatsFs, + TimeLike, WatchEventType, WatchOptions, WriteStream, WriteVResult, - } from 'node:fs'; + } from "node:fs"; + import { Interface as ReadlineInterface } from "node:readline"; interface FileChangeInfo { eventType: WatchEventType; - filename: T; + filename: T | null; } interface FlagAndOpenMode { mode?: Mode | undefined; flag?: OpenMode | undefined; } - interface FileReadResult { + interface FileReadResult { bytesRead: number; buffer: T; } - interface FileReadOptions { + interface FileReadOptions { /** * @default `Buffer.alloc(0xffff)` */ @@ -75,6 +81,15 @@ declare module 'fs/promises' { autoClose?: boolean | undefined; emitClose?: boolean | undefined; start?: number | undefined; + highWaterMark?: number | undefined; + flush?: boolean | undefined; + } + interface ReadableWebStreamOptions { + /** + * Whether to open a normal or a `'bytes'` stream. + * @since v20.0.0 + */ + type?: "bytes" | undefined; } // TODO: Add `EventEmitter` close interface FileHandle { @@ -91,7 +106,13 @@ declare module 'fs/promises' { * @since v10.0.0 * @return Fulfills with `undefined` upon success. */ - appendFile(data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null): Promise; + appendFile( + data: string | Uint8Array, + options?: + | (ObjectEncodingOptions & FlagAndOpenMode & { flush?: boolean | undefined }) + | BufferEncoding + | null, + ): Promise; /** * Changes the ownership of the file. A wrapper for [`chown(2)`](http://man7.org/linux/man-pages/man2/chown.2.html). * @since v10.0.0 @@ -108,8 +129,8 @@ declare module 'fs/promises' { */ chmod(mode: Mode): Promise; /** - * Unlike the 16 kb default `highWaterMark` for a `stream.Readable`, the stream - * returned by this method has a default `highWaterMark` of 64 kb. + * Unlike the 16 KiB default `highWaterMark` for a `stream.Readable`, the stream + * returned by this method has a default `highWaterMark` of 64 KiB. * * `options` can include `start` and `end` values to read a range of bytes from * the file instead of the entire file. Both `start` and `end` are inclusive and @@ -127,7 +148,7 @@ declare module 'fs/promises' { * destroyed. Set the `emitClose` option to `false` to change this behavior. * * ```js - * import { open } from 'fs/promises'; + * import { open } from 'node:fs/promises'; * * const fd = await open('/dev/input/event0'); * // Create a stream from some character device. @@ -153,7 +174,7 @@ declare module 'fs/promises' { * An example to read the last 10 bytes of a file which is 100 bytes long: * * ```js - * import { open } from 'fs/promises'; + * import { open } from 'node:fs/promises'; * * const fd = await open('sample.txt'); * fd.createReadStream({ start: 90, end: 99 }); @@ -164,9 +185,9 @@ declare module 'fs/promises' { /** * `options` may also include a `start` option to allow writing data at some * position past the beginning of the file, allowed values are in the - * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than replacing - * it may require the `flags` `open` option to be set to `r+` rather than the - * default `r`. The `encoding` can be any one of those accepted by `Buffer`. + * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than + * replacing it may require the `flags` `open` option to be set to `r+` rather than + * the default `r`. The `encoding` can be any one of those accepted by `Buffer`. * * If `autoClose` is set to true (default behavior) on `'error'` or `'finish'`the file descriptor will be closed automatically. If `autoClose` is false, * then the file descriptor won't be closed, even if there's an error. @@ -192,7 +213,7 @@ declare module 'fs/promises' { * device. The specific implementation is operating system and device specific. * Refer to the POSIX [`fsync(2)`](http://man7.org/linux/man-pages/man2/fsync.2.html) documentation for more detail. * @since v10.0.0 - * @return Fufills with `undefined` upon success. + * @return Fulfills with `undefined` upon success. */ sync(): Promise; /** @@ -208,8 +229,38 @@ declare module 'fs/promises' { * integer, the current file position will remain unchanged. * @return Fulfills upon success with an object with two properties: */ - read(buffer: T, offset?: number | null, length?: number | null, position?: number | null): Promise>; - read(options?: FileReadOptions): Promise>; + read( + buffer: T, + offset?: number | null, + length?: number | null, + position?: number | null, + ): Promise>; + read(options?: FileReadOptions): Promise>; + /** + * Returns a `ReadableStream` that may be used to read the files data. + * + * An error will be thrown if this method is called more than once or is called + * after the `FileHandle` is closed or closing. + * + * ```js + * import { + * open, + * } from 'node:fs/promises'; + * + * const file = await open('./some/file/to/read'); + * + * for await (const chunk of file.readableWebStream()) + * console.log(chunk); + * + * await file.close(); + * ``` + * + * While the `ReadableStream` will read the file to completion, it will not + * close the `FileHandle` automatically. User code must still call the`fileHandle.close()` method. + * @since v17.0.0 + * @experimental + */ + readableWebStream(options?: ReadableWebStreamOptions): ReadableStream; /** * Asynchronously reads the entire contents of a file. * @@ -228,7 +279,7 @@ declare module 'fs/promises' { options?: { encoding?: null | undefined; flag?: OpenMode | undefined; - } | null + } | null, ): Promise; /** * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically. @@ -239,10 +290,10 @@ declare module 'fs/promises' { readFile( options: | { - encoding: BufferEncoding; - flag?: OpenMode | undefined; - } - | BufferEncoding + encoding: BufferEncoding; + flag?: OpenMode | undefined; + } + | BufferEncoding, ): Promise; /** * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically. @@ -253,11 +304,27 @@ declare module 'fs/promises' { readFile( options?: | (ObjectEncodingOptions & { - flag?: OpenMode | undefined; - }) + flag?: OpenMode | undefined; + }) | BufferEncoding - | null + | null, ): Promise; + /** + * Convenience method to create a `readline` interface and stream over the file. + * See `filehandle.createReadStream()` for the options. + * + * ```js + * import { open } from 'node:fs/promises'; + * + * const file = await open('./some/file/to/read'); + * + * for await (const line of file.readLines()) { + * console.log(line); + * } + * ``` + * @since v18.11.0 + */ + readLines(options?: CreateReadStreamOptions): ReadlineInterface; /** * @since v10.0.0 * @return Fulfills with an {fs.Stats} for the file. @@ -265,12 +332,12 @@ declare module 'fs/promises' { stat( opts?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; stat( opts: StatOptions & { bigint: true; - } + }, ): Promise; stat(opts?: StatOptions): Promise; /** @@ -282,7 +349,7 @@ declare module 'fs/promises' { * The following example retains only the first four bytes of the file: * * ```js - * import { open } from 'fs/promises'; + * import { open } from 'node:fs/promises'; * * let filehandle = null; * try { @@ -303,55 +370,58 @@ declare module 'fs/promises' { */ truncate(len?: number): Promise; /** - * Change the file system timestamps of the object referenced by the `FileHandle` then resolves the promise with no arguments upon success. + * Change the file system timestamps of the object referenced by the `FileHandle` then fulfills the promise with no arguments upon success. * @since v10.0.0 */ - utimes(atime: string | number | Date, mtime: string | number | Date): Promise; + utimes(atime: TimeLike, mtime: TimeLike): Promise; /** * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an - * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface) or - * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object, or an - * object with an own `toString` function - * property. The promise is resolved with no arguments upon success. + * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface), or an + * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object. + * The promise is fulfilled with no arguments upon success. * * If `options` is a string, then it specifies the `encoding`. * * The `FileHandle` has to support writing. * * It is unsafe to use `filehandle.writeFile()` multiple times on the same file - * without waiting for the promise to be resolved (or rejected). + * without waiting for the promise to be fulfilled (or rejected). * * If one or more `filehandle.write()` calls are made on a file handle and then a`filehandle.writeFile()` call is made, the data will be written from the * current position till the end of the file. It doesn't always write from the * beginning of the file. * @since v10.0.0 */ - writeFile(data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode & Abortable) | BufferEncoding | null): Promise; + writeFile( + data: string | Uint8Array, + options?: + | (ObjectEncodingOptions & FlagAndOpenMode & Abortable & { flush?: boolean | undefined }) + | BufferEncoding + | null, + ): Promise; /** * Write `buffer` to the file. * - * If `buffer` is a plain object, it must have an own (not inherited) `toString`function property. - * - * The promise is resolved with an object containing two properties: + * The promise is fulfilled with an object containing two properties: * * It is unsafe to use `filehandle.write()` multiple times on the same file - * without waiting for the promise to be resolved (or rejected). For this - * scenario, use `fs.createWriteStream()`. + * without waiting for the promise to be fulfilled (or rejected). For this + * scenario, use `filehandle.createWriteStream()`. * * On Linux, positional writes do not work when the file is opened in append mode. * The kernel ignores the position argument and always appends the data to * the end of the file. * @since v10.0.0 - * @param [offset=0] The start position from within `buffer` where the data to write begins. - * @param [length=buffer.byteLength] The number of bytes from `buffer` to write. - * @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. - * See the POSIX pwrite(2) documentation for more detail. + * @param offset The start position from within `buffer` where the data to write begins. + * @param [length=buffer.byteLength - offset] The number of bytes from `buffer` to write. + * @param [position='null'] 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. See the POSIX pwrite(2) documentation for more detail. */ write( buffer: TBuffer, offset?: number | null, length?: number | null, - position?: number | null + position?: number | null, ): Promise<{ bytesWritten: number; buffer: TBuffer; @@ -359,7 +429,7 @@ declare module 'fs/promises' { write( data: string, position?: number | null, - encoding?: BufferEncoding | null + encoding?: BufferEncoding | null, ): Promise<{ bytesWritten: number; buffer: string; @@ -367,32 +437,32 @@ declare module 'fs/promises' { /** * Write an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s to the file. * - * The promise is resolved with an object containing a two properties: + * The promise is fulfilled with an object containing a two properties: * * It is unsafe to call `writev()` multiple times on the same file without waiting - * for the promise to be resolved (or rejected). + * for the promise to be fulfilled (or rejected). * * On Linux, positional writes don't work when the file is opened in append mode. * The kernel ignores the position argument and always appends the data to * the end of the file. * @since v12.9.0 - * @param position The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current + * @param [position='null'] The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current * position. */ - writev(buffers: ReadonlyArray, position?: number): Promise; + writev(buffers: readonly NodeJS.ArrayBufferView[], position?: number): Promise; /** * Read from a file and write to an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s * @since v13.13.0, v12.17.0 - * @param position The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position. + * @param [position='null'] The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position. * @return Fulfills upon success an object containing two properties: */ - readv(buffers: ReadonlyArray, position?: number): Promise; + readv(buffers: readonly NodeJS.ArrayBufferView[], position?: number): Promise; /** * Closes the file handle after waiting for any pending operation on the handle to * complete. * * ```js - * import { open } from 'fs/promises'; + * import { open } from 'node:fs/promises'; * * let filehandle; * try { @@ -405,24 +475,27 @@ declare module 'fs/promises' { * @return Fulfills with `undefined` upon success. */ close(): Promise; + /** + * An alias for {@link FileHandle.close()}. + * @since v20.4.0 + */ + [Symbol.asyncDispose](): Promise; } - const constants: typeof fsConstants; /** * Tests a user's permissions for the file or directory specified by `path`. * The `mode` argument is an optional integer that specifies the accessibility - * checks to be performed. Check `File access constants` for possible values - * of `mode`. It is possible to create a mask consisting of the bitwise OR of - * two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). + * checks to be performed. `mode` should be either the value `fs.constants.F_OK`or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`,`fs.constants.W_OK`, and `fs.constants.X_OK` + * (e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for + * possible values of `mode`. * - * If the accessibility check is successful, the promise is resolved with no + * If the accessibility check is successful, the promise is fulfilled with no * value. If any of the accessibility checks fail, the promise is rejected * with an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object. The following example checks if the file`/etc/passwd` can be read and * written by the current process. * * ```js - * import { access } from 'fs/promises'; - * import { constants } from 'fs'; + * import { access, constants } from 'node:fs/promises'; * * try { * await access('/etc/passwd', constants.R_OK | constants.W_OK); @@ -451,14 +524,13 @@ declare module 'fs/promises' { * will be made to remove the destination. * * ```js - * import { constants } from 'fs'; - * import { copyFile } from 'fs/promises'; + * import { copyFile, constants } from 'node:fs/promises'; * * try { * await copyFile('source.txt', 'destination.txt'); * console.log('source.txt was copied to destination.txt'); * } catch { - * console.log('The file could not be copied'); + * console.error('The file could not be copied'); * } * * // By using COPYFILE_EXCL, the operation will fail if destination.txt exists. @@ -466,7 +538,7 @@ declare module 'fs/promises' { * await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL); * console.log('source.txt was copied to destination.txt'); * } catch { - * console.log('The file could not be copied'); + * console.error('The file could not be copied'); * } * ``` * @since v10.0.0 @@ -528,6 +600,19 @@ declare module 'fs/promises' { * and sticky bits), or an object with a `mode` property and a `recursive`property indicating whether parent directories should be created. Calling`fsPromises.mkdir()` when `path` is a directory * that exists results in a * rejection only when `recursive` is false. + * + * ```js + * import { mkdir } from 'node:fs/promises'; + * + * try { + * const projectFolder = new URL('./test/project/', import.meta.url); + * const createDir = await mkdir(projectFolder, { recursive: true }); + * + * console.log(`created ${createDir}`); + * } catch (err) { + * console.error(err.message); + * } + * ``` * @since v10.0.0 * @return Upon success, fulfills with `undefined` if `recursive` is `false`, or the first directory path created if `recursive` is `true`. */ @@ -535,7 +620,7 @@ declare module 'fs/promises' { path: PathLike, options: MakeDirectoryOptions & { recursive: true; - } + }, ): Promise; /** * Asynchronous mkdir(2) - create a directory. @@ -548,9 +633,9 @@ declare module 'fs/promises' { options?: | Mode | (MakeDirectoryOptions & { - recursive?: false | undefined; - }) - | null + recursive?: false | undefined; + }) + | null, ): Promise; /** * Asynchronous mkdir(2) - create a directory. @@ -567,10 +652,10 @@ declare module 'fs/promises' { * the filenames. If the `encoding` is set to `'buffer'`, the filenames returned * will be passed as `Buffer` objects. * - * If `options.withFileTypes` is set to `true`, the resolved array will contain `fs.Dirent` objects. + * If `options.withFileTypes` is set to `true`, the returned array will contain `fs.Dirent` objects. * * ```js - * import { readdir } from 'fs/promises'; + * import { readdir } from 'node:fs/promises'; * * try { * const files = await readdir(path); @@ -587,10 +672,11 @@ declare module 'fs/promises' { path: PathLike, options?: | (ObjectEncodingOptions & { - withFileTypes?: false | undefined; - }) + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }) | BufferEncoding - | null + | null, ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -601,10 +687,11 @@ declare module 'fs/promises' { path: PathLike, options: | { - encoding: 'buffer'; - withFileTypes?: false | undefined; - } - | 'buffer' + encoding: "buffer"; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } + | "buffer", ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -615,10 +702,11 @@ declare module 'fs/promises' { path: PathLike, options?: | (ObjectEncodingOptions & { - withFileTypes?: false | undefined; - }) + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }) | BufferEncoding - | null + | null, ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -629,11 +717,12 @@ declare module 'fs/promises' { path: PathLike, options: ObjectEncodingOptions & { withFileTypes: true; - } + recursive?: boolean | undefined; + }, ): Promise; /** * Reads the contents of the symbolic link referred to by `path`. See the POSIX [`readlink(2)`](http://man7.org/linux/man-pages/man2/readlink.2.html) documentation for more detail. The promise is - * resolved with the`linkString` upon success. + * fulfilled with the`linkString` upon success. * * The optional `options` argument can be a string specifying an encoding, or an * object with an `encoding` property specifying the character encoding to use for @@ -658,11 +747,14 @@ declare module 'fs/promises' { /** * Creates a symbolic link. * - * The `type` argument is only used on Windows platforms and can be one of `'dir'`,`'file'`, or `'junction'`. Windows junction points require the destination path - * to be absolute. When using `'junction'`, the `target` argument will - * automatically be normalized to absolute path. + * The `type` argument is only used on Windows platforms and can be one of `'dir'`,`'file'`, or `'junction'`. If the `type` argument is not a string, Node.js will + * autodetect `target` type and use `'file'` or `'dir'`. If the `target` does not + * exist, `'file'` will be used. Windows junction points require the destination + * path to be absolute. When using `'junction'`, the `target` argument will + * automatically be normalized to absolute path. Junction points on NTFS volumes + * can only point to directories. * @since v10.0.0 - * @param [type='file'] + * @param [type='null'] * @return Fulfills with `undefined` upon success. */ function symlink(target: PathLike, path: PathLike, type?: string | null): Promise; @@ -677,13 +769,13 @@ declare module 'fs/promises' { path: PathLike, opts?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; function lstat( path: PathLike, opts: StatOptions & { bigint: true; - } + }, ): Promise; function lstat(path: PathLike, opts?: StatOptions): Promise; /** @@ -694,15 +786,32 @@ declare module 'fs/promises' { path: PathLike, opts?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; function stat( path: PathLike, opts: StatOptions & { bigint: true; - } + }, ): Promise; function stat(path: PathLike, opts?: StatOptions): Promise; + /** + * @since v19.6.0, v18.15.0 + * @return Fulfills with the {fs.StatFs} object for the given `path`. + */ + function statfs( + path: PathLike, + opts?: StatFsOptions & { + bigint?: false | undefined; + }, + ): Promise; + function statfs( + path: PathLike, + opts: StatFsOptions & { + bigint: true; + }, + ): Promise; + function statfs(path: PathLike, opts?: StatFsOptions): Promise; /** * Creates a new link from the `existingPath` to the `newPath`. See the POSIX [`link(2)`](http://man7.org/linux/man-pages/man2/link.2.html) documentation for more detail. * @since v10.0.0 @@ -744,7 +853,7 @@ declare module 'fs/promises' { * @since v14.5.0, v12.19.0 * @return Fulfills with `undefined` upon success. */ - function lutimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date): Promise; + function lutimes(path: PathLike, atime: TimeLike, mtime: TimeLike): Promise; /** * Changes the ownership of a file. * @since v10.0.0 @@ -758,11 +867,11 @@ declare module 'fs/promises' { * * * Values can be either numbers representing Unix epoch time, `Date`s, or a * numeric string like `'123456789.0'`. - * * If the value can not be converted to a number, or is `NaN`, `Infinity` or`-Infinity`, an `Error` will be thrown. + * * If the value can not be converted to a number, or is `NaN`, `Infinity`, or`-Infinity`, an `Error` will be thrown. * @since v10.0.0 * @return Fulfills with `undefined` upon success. */ - function utimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date): Promise; + function utimes(path: PathLike, atime: TimeLike, mtime: TimeLike): Promise; /** * Determines the actual location of `path` using the same semantics as the`fs.realpath.native()` function. * @@ -791,7 +900,10 @@ declare module 'fs/promises' { * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - function realpath(path: PathLike, options?: ObjectEncodingOptions | BufferEncoding | null): Promise; + function realpath( + path: PathLike, + options?: ObjectEncodingOptions | BufferEncoding | null, + ): Promise; /** * Creates a unique temporary directory. A unique directory name is generated by * appending six random characters to the end of the provided `prefix`. Due to @@ -803,10 +915,12 @@ declare module 'fs/promises' { * object with an `encoding` property specifying the character encoding to use. * * ```js - * import { mkdtemp } from 'fs/promises'; + * import { mkdtemp } from 'node:fs/promises'; + * import { join } from 'node:path'; + * import { tmpdir } from 'node:os'; * * try { - * await mkdtemp(path.join(os.tmpdir(), 'foo-')); + * await mkdtemp(join(tmpdir(), 'foo-')); * } catch (err) { * console.error(err); * } @@ -815,9 +929,9 @@ declare module 'fs/promises' { * The `fsPromises.mkdtemp()` method will append the six randomly selected * characters directly to the `prefix` string. For instance, given a directory`/tmp`, if the intention is to create a temporary directory _within_`/tmp`, the`prefix` must end with a trailing * platform-specific path separator - * (`require('path').sep`). + * (`require('node:path').sep`). * @since v10.0.0 - * @return Fulfills with a string containing the filesystem path of the newly created temporary directory. + * @return Fulfills with a string containing the file system path of the newly created temporary directory. */ function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise; /** @@ -833,7 +947,9 @@ declare module 'fs/promises' { */ function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise; /** - * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a `Buffer`, or, an object with an own (not inherited)`toString` function property. + * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an + * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface), or an + * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object. * * The `encoding` option is ignored if `data` is a buffer. * @@ -848,15 +964,15 @@ declare module 'fs/promises' { * * Similarly to `fsPromises.readFile` \- `fsPromises.writeFile` is a convenience * method that performs multiple `write` calls internally to write the buffer - * passed to it. For performance sensitive code consider using `fs.createWriteStream()`. + * passed to it. For performance sensitive code consider using `fs.createWriteStream()` or `filehandle.createWriteStream()`. * * It is possible to use an `AbortSignal` to cancel an `fsPromises.writeFile()`. * Cancelation is "best effort", and some amount of data is likely still * to be written. * * ```js - * import { writeFile } from 'fs/promises'; - * import { Buffer } from 'buffer'; + * import { writeFile } from 'node:fs/promises'; + * import { Buffer } from 'node:buffer'; * * try { * const controller = new AbortController(); @@ -882,14 +998,19 @@ declare module 'fs/promises' { */ function writeFile( file: PathLike | FileHandle, - data: string | NodeJS.ArrayBufferView | Iterable | AsyncIterable | Stream, + data: + | string + | NodeJS.ArrayBufferView + | Iterable + | AsyncIterable + | Stream, options?: | (ObjectEncodingOptions & { - mode?: Mode | undefined; - flag?: OpenMode | undefined; - } & Abortable) + mode?: Mode | undefined; + flag?: OpenMode | undefined; + } & Abortable) | BufferEncoding - | null + | null, ): Promise; /** * Asynchronously append data to a file, creating the file if it does not yet @@ -905,7 +1026,11 @@ declare module 'fs/promises' { * @param path filename or {FileHandle} * @return Fulfills with `undefined` upon success. */ - function appendFile(path: PathLike | FileHandle, data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null): Promise; + function appendFile( + path: PathLike | FileHandle, + data: string | Uint8Array, + options?: (ObjectEncodingOptions & FlagAndOpenMode & { flush?: boolean | undefined }) | BufferEncoding | null, + ): Promise; /** * Asynchronously reads the entire contents of a file. * @@ -919,11 +1044,25 @@ declare module 'fs/promises' { * with an error. On FreeBSD, a representation of the directory's contents will be * returned. * + * An example of reading a `package.json` file located in the same directory of the + * running code: + * + * ```js + * import { readFile } from 'node:fs/promises'; + * try { + * const filePath = new URL('./package.json', import.meta.url); + * const contents = await readFile(filePath, { encoding: 'utf8' }); + * console.log(contents); + * } catch (err) { + * console.error(err.message); + * } + * ``` + * * It is possible to abort an ongoing `readFile` using an `AbortSignal`. If a * request is aborted the promise returned is rejected with an `AbortError`: * * ```js - * import { readFile } from 'fs/promises'; + * import { readFile } from 'node:fs/promises'; * * try { * const controller = new AbortController(); @@ -952,10 +1091,10 @@ declare module 'fs/promises' { path: PathLike | FileHandle, options?: | ({ - encoding?: null | undefined; - flag?: OpenMode | undefined; - } & Abortable) - | null + encoding?: null | undefined; + flag?: OpenMode | undefined; + } & Abortable) + | null, ): Promise; /** * Asynchronously reads the entire contents of a file. @@ -968,10 +1107,10 @@ declare module 'fs/promises' { path: PathLike | FileHandle, options: | ({ - encoding: BufferEncoding; - flag?: OpenMode | undefined; - } & Abortable) - | BufferEncoding + encoding: BufferEncoding; + flag?: OpenMode | undefined; + } & Abortable) + | BufferEncoding, ): Promise; /** * Asynchronously reads the entire contents of a file. @@ -983,12 +1122,15 @@ declare module 'fs/promises' { function readFile( path: PathLike | FileHandle, options?: - | (ObjectEncodingOptions & - Abortable & { - flag?: OpenMode | undefined; - }) + | ( + & ObjectEncodingOptions + & Abortable + & { + flag?: OpenMode | undefined; + } + ) | BufferEncoding - | null + | null, ): Promise; /** * Asynchronously open a directory for iterative scanning. See the POSIX [`opendir(3)`](http://man7.org/linux/man-pages/man3/opendir.3.html) documentation for more detail. @@ -1002,7 +1144,7 @@ declare module 'fs/promises' { * Example using async iteration: * * ```js - * import { opendir } from 'fs/promises'; + * import { opendir } from 'node:fs/promises'; * * try { * const dir = await opendir('./'); @@ -1023,7 +1165,7 @@ declare module 'fs/promises' { * Returns an async iterator that watches for changes on `filename`, where `filename`is either a file or a directory. * * ```js - * const { watch } = require('fs/promises'); + * const { watch } = require('node:fs/promises'); * * const ac = new AbortController(); * const { signal } = ac; @@ -1046,16 +1188,16 @@ declare module 'fs/promises' { * disappears in the directory. * * All the `caveats` for `fs.watch()` also apply to `fsPromises.watch()`. - * @since v15.9.0 + * @since v15.9.0, v14.18.0 * @return of objects with the properties: */ function watch( filename: PathLike, options: | (WatchOptions & { - encoding: 'buffer'; - }) - | 'buffer' + encoding: "buffer"; + }) + | "buffer", ): AsyncIterable>; /** * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`. @@ -1074,7 +1216,10 @@ declare module 'fs/promises' { * If `persistent` is not supplied, the default of `true` is used. * If `recursive` is not supplied, the default of `false` is used. */ - function watch(filename: PathLike, options: WatchOptions | string): AsyncIterable> | AsyncIterable>; + function watch( + filename: PathLike, + options: WatchOptions | string, + ): AsyncIterable> | AsyncIterable>; /** * Asynchronously copies the entire directory structure from `src` to `dest`, * including subdirectories and files. @@ -1089,6 +1234,6 @@ declare module 'fs/promises' { */ function cp(source: string | URL, destination: string | URL, opts?: CopyOptions): Promise; } -declare module 'node:fs/promises' { - export * from 'fs/promises'; +declare module "node:fs/promises" { + export * from "fs/promises"; } diff --git a/node_modules/@types/node/globals.d.ts b/node_modules/@types/node/globals.d.ts old mode 100755 new mode 100644 index 8317359..5f25006 --- a/node_modules/@types/node/globals.d.ts +++ b/node_modules/@types/node/globals.d.ts @@ -1,286 +1,411 @@ -// Declare "static" methods in Error -interface ErrorConstructor { - /** Create .stack property on a target object */ - captureStackTrace(targetObject: object, constructorOpt?: Function): void; +export {}; // Make this a module - /** - * Optional override for formatting stack traces - * - * @see https://v8.dev/docs/stack-trace-api#customizing-stack-traces - */ - prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined; +// #region Fetch and friends +// Conditional type aliases, used at the end of this file. +// Will either be empty if lib-dom is included, or the undici version otherwise. +type _Request = typeof globalThis extends { onmessage: any } ? {} : import("undici-types").Request; +type _Response = typeof globalThis extends { onmessage: any } ? {} : import("undici-types").Response; +type _FormData = typeof globalThis extends { onmessage: any } ? {} : import("undici-types").FormData; +type _Headers = typeof globalThis extends { onmessage: any } ? {} : import("undici-types").Headers; +type _RequestInit = typeof globalThis extends { onmessage: any } ? {} + : import("undici-types").RequestInit; +type _ResponseInit = typeof globalThis extends { onmessage: any } ? {} + : import("undici-types").ResponseInit; +type _File = typeof globalThis extends { onmessage: any } ? {} : import("node:buffer").File; +// #endregion Fetch and friends - stackTraceLimit: number; -} - -/*-----------------------------------------------* - * * - * GLOBAL * - * * - ------------------------------------------------*/ - -// For backwards compability -interface NodeRequire extends NodeJS.Require { } -interface RequireResolve extends NodeJS.RequireResolve { } -interface NodeModule extends NodeJS.Module { } - -declare var process: NodeJS.Process; -declare var console: Console; - -declare var __filename: string; -declare var __dirname: string; - -declare var require: NodeRequire; -declare var module: NodeModule; - -// Same as module.exports -declare var exports: any; - -/** - * Only available if `--expose-gc` is passed to the process. - */ -declare var gc: undefined | (() => void); - -//#region borrowed -// from https://github.com/microsoft/TypeScript/blob/38da7c600c83e7b31193a62495239a0fe478cb67/lib/lib.webworker.d.ts#L633 until moved to separate lib -/** A controller object that allows you to abort one or more DOM requests as and when desired. */ -interface AbortController { - /** - * Returns the AbortSignal object associated with this object. - */ - - readonly signal: AbortSignal; - /** - * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted. - */ - abort(): void; -} - -/** A signal object that allows you to communicate with a DOM request (such as a Fetch) and abort it if required via an AbortController object. */ -interface AbortSignal { - /** - * Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise. - */ - readonly aborted: boolean; -} - -declare var AbortController: { - prototype: AbortController; - new(): AbortController; -}; - -declare var AbortSignal: { - prototype: AbortSignal; - new(): AbortSignal; - // TODO: Add abort() static - timeout(milliseconds: number): AbortSignal; -}; -//#endregion borrowed - -//#region ArrayLike.at() -interface RelativeIndexable { - /** - * Takes an integer value and returns the item at that index, - * allowing for positive and negative integers. - * Negative integers count back from the last item in the array. - */ - at(index: number): T | undefined; -} -interface String extends RelativeIndexable {} -interface Array extends RelativeIndexable {} -interface ReadonlyArray extends RelativeIndexable {} -interface Int8Array extends RelativeIndexable {} -interface Uint8Array extends RelativeIndexable {} -interface Uint8ClampedArray extends RelativeIndexable {} -interface Int16Array extends RelativeIndexable {} -interface Uint16Array extends RelativeIndexable {} -interface Int32Array extends RelativeIndexable {} -interface Uint32Array extends RelativeIndexable {} -interface Float32Array extends RelativeIndexable {} -interface Float64Array extends RelativeIndexable {} -interface BigInt64Array extends RelativeIndexable {} -interface BigUint64Array extends RelativeIndexable {} -//#endregion ArrayLike.at() end - -/*----------------------------------------------* -* * -* GLOBAL INTERFACES * -* * -*-----------------------------------------------*/ -declare namespace NodeJS { - interface CallSite { - /** - * Value of "this" - */ - getThis(): unknown; +declare global { + // Declare "static" methods in Error + interface ErrorConstructor { + /** Create .stack property on a target object */ + captureStackTrace(targetObject: object, constructorOpt?: Function): void; /** - * Type of "this" as a string. - * This is the name of the function stored in the constructor field of - * "this", if available. Otherwise the object's [[Class]] internal - * property. - */ - getTypeName(): string | null; - - /** - * Current function - */ - getFunction(): Function | undefined; - - /** - * Name of the current function, typically its name property. - * If a name property is not available an attempt will be made to try - * to infer a name from the function's context. - */ - getFunctionName(): string | null; - - /** - * Name of the property [of "this" or one of its prototypes] that holds - * the current function - */ - getMethodName(): string | null; - - /** - * Name of the script [if this function was defined in a script] - */ - getFileName(): string | null; - - /** - * Current line number [if this function was defined in a script] - */ - getLineNumber(): number | null; - - /** - * Current column number [if this function was defined in a script] - */ - getColumnNumber(): number | null; - - /** - * A call site object representing the location where eval was called - * [if this function was created using a call to eval] - */ - getEvalOrigin(): string | undefined; - - /** - * Is this a toplevel invocation, that is, is "this" the global object? - */ - isToplevel(): boolean; - - /** - * Does this call take place in code defined by a call to eval? - */ - isEval(): boolean; - - /** - * Is this call in native V8 code? - */ - isNative(): boolean; - - /** - * Is this a constructor call? - */ - isConstructor(): boolean; - } - - interface ErrnoException extends Error { - errno?: number | undefined; - code?: string | undefined; - path?: string | undefined; - syscall?: string | undefined; - } - - interface ReadableStream extends EventEmitter { - readable: boolean; - read(size?: number): string | Buffer; - setEncoding(encoding: BufferEncoding): this; - pause(): this; - resume(): this; - isPaused(): boolean; - pipe(destination: T, options?: { end?: boolean | undefined; }): T; - unpipe(destination?: WritableStream): this; - unshift(chunk: string | Uint8Array, encoding?: BufferEncoding): void; - wrap(oldStream: ReadableStream): this; - [Symbol.asyncIterator](): AsyncIterableIterator; - } - - interface WritableStream extends EventEmitter { - writable: boolean; - write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean; - write(str: string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean; - end(cb?: () => void): void; - end(data: string | Uint8Array, cb?: () => void): void; - end(str: string, encoding?: BufferEncoding, cb?: () => void): void; - } - - interface ReadWriteStream extends ReadableStream, WritableStream { } - - interface RefCounted { - ref(): this; - unref(): this; - } - - type TypedArray = - | Uint8Array - | Uint8ClampedArray - | Uint16Array - | Uint32Array - | Int8Array - | Int16Array - | Int32Array - | BigUint64Array - | BigInt64Array - | Float32Array - | Float64Array; - type ArrayBufferView = TypedArray | DataView; - - interface Require { - (id: string): any; - resolve: RequireResolve; - cache: Dict; - /** - * @deprecated - */ - extensions: RequireExtensions; - main: Module | undefined; - } - - interface RequireResolve { - (id: string, options?: { paths?: string[] | undefined; }): string; - paths(request: string): string[] | null; - } - - interface RequireExtensions extends Dict<(m: Module, filename: string) => any> { - '.js': (m: Module, filename: string) => any; - '.json': (m: Module, filename: string) => any; - '.node': (m: Module, filename: string) => any; - } - interface Module { - /** - * `true` if the module is running during the Node.js preload - */ - isPreloading: boolean; - exports: any; - require: Require; - id: string; - filename: string; - loaded: boolean; - /** @deprecated since v14.6.0 Please use `require.main` and `module.children` instead. */ - parent: Module | null | undefined; - children: Module[]; - /** - * @since v11.14.0 + * Optional override for formatting stack traces * - * The directory name of the module. This is usually the same as the path.dirname() of the module.id. + * @see https://v8.dev/docs/stack-trace-api#customizing-stack-traces */ - path: string; - paths: string[]; + prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined; + + stackTraceLimit: number; } - interface Dict { - [key: string]: T | undefined; + /*-----------------------------------------------* + * * + * GLOBAL * + * * + ------------------------------------------------*/ + + // For backwards compability + interface NodeRequire extends NodeJS.Require {} + interface RequireResolve extends NodeJS.RequireResolve {} + interface NodeModule extends NodeJS.Module {} + + var process: NodeJS.Process; + var console: Console; + + var __filename: string; + var __dirname: string; + + var require: NodeRequire; + var module: NodeModule; + + // Same as module.exports + var exports: any; + + /** + * Only available if `--expose-gc` is passed to the process. + */ + var gc: undefined | (() => void); + + // #region borrowed + // from https://github.com/microsoft/TypeScript/blob/38da7c600c83e7b31193a62495239a0fe478cb67/lib/lib.webworker.d.ts#L633 until moved to separate lib + /** A controller object that allows you to abort one or more DOM requests as and when desired. */ + interface AbortController { + /** + * Returns the AbortSignal object associated with this object. + */ + + readonly signal: AbortSignal; + /** + * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted. + */ + abort(reason?: any): void; } - interface ReadOnlyDict { - readonly [key: string]: T | undefined; + /** A signal object that allows you to communicate with a DOM request (such as a Fetch) and abort it if required via an AbortController object. */ + interface AbortSignal extends EventTarget { + /** + * Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise. + */ + readonly aborted: boolean; + readonly reason: any; + onabort: null | ((this: AbortSignal, event: Event) => any); + throwIfAborted(): void; } + + var AbortController: typeof globalThis extends { onmessage: any; AbortController: infer T } ? T + : { + prototype: AbortController; + new(): AbortController; + }; + + var AbortSignal: typeof globalThis extends { onmessage: any; AbortSignal: infer T } ? T + : { + prototype: AbortSignal; + new(): AbortSignal; + abort(reason?: any): AbortSignal; + timeout(milliseconds: number): AbortSignal; + }; + // #endregion borrowed + + // #region Disposable + interface SymbolConstructor { + /** + * A method that is used to release resources held by an object. Called by the semantics of the `using` statement. + */ + readonly dispose: unique symbol; + + /** + * A method that is used to asynchronously release resources held by an object. Called by the semantics of the `await using` statement. + */ + readonly asyncDispose: unique symbol; + } + + interface Disposable { + [Symbol.dispose](): void; + } + + interface AsyncDisposable { + [Symbol.asyncDispose](): PromiseLike; + } + // #endregion Disposable + + // #region ArrayLike.at() + interface RelativeIndexable { + /** + * Takes an integer value and returns the item at that index, + * allowing for positive and negative integers. + * Negative integers count back from the last item in the array. + */ + at(index: number): T | undefined; + } + interface String extends RelativeIndexable {} + interface Array extends RelativeIndexable {} + interface ReadonlyArray extends RelativeIndexable {} + interface Int8Array extends RelativeIndexable {} + interface Uint8Array extends RelativeIndexable {} + interface Uint8ClampedArray extends RelativeIndexable {} + interface Int16Array extends RelativeIndexable {} + interface Uint16Array extends RelativeIndexable {} + interface Int32Array extends RelativeIndexable {} + interface Uint32Array extends RelativeIndexable {} + interface Float32Array extends RelativeIndexable {} + interface Float64Array extends RelativeIndexable {} + interface BigInt64Array extends RelativeIndexable {} + interface BigUint64Array extends RelativeIndexable {} + // #endregion ArrayLike.at() end + + /** + * @since v17.0.0 + * + * Creates a deep clone of an object. + */ + function structuredClone( + value: T, + transfer?: { transfer: ReadonlyArray }, + ): T; + + /*----------------------------------------------* + * * + * GLOBAL INTERFACES * + * * + *-----------------------------------------------*/ + namespace NodeJS { + interface CallSite { + /** + * Value of "this" + */ + getThis(): unknown; + + /** + * Type of "this" as a string. + * This is the name of the function stored in the constructor field of + * "this", if available. Otherwise the object's [[Class]] internal + * property. + */ + getTypeName(): string | null; + + /** + * Current function + */ + getFunction(): Function | undefined; + + /** + * Name of the current function, typically its name property. + * If a name property is not available an attempt will be made to try + * to infer a name from the function's context. + */ + getFunctionName(): string | null; + + /** + * Name of the property [of "this" or one of its prototypes] that holds + * the current function + */ + getMethodName(): string | null; + + /** + * Name of the script [if this function was defined in a script] + */ + getFileName(): string | undefined; + + /** + * Current line number [if this function was defined in a script] + */ + getLineNumber(): number | null; + + /** + * Current column number [if this function was defined in a script] + */ + getColumnNumber(): number | null; + + /** + * A call site object representing the location where eval was called + * [if this function was created using a call to eval] + */ + getEvalOrigin(): string | undefined; + + /** + * Is this a toplevel invocation, that is, is "this" the global object? + */ + isToplevel(): boolean; + + /** + * Does this call take place in code defined by a call to eval? + */ + isEval(): boolean; + + /** + * Is this call in native V8 code? + */ + isNative(): boolean; + + /** + * Is this a constructor call? + */ + isConstructor(): boolean; + + /** + * is this an async call (i.e. await, Promise.all(), or Promise.any())? + */ + isAsync(): boolean; + + /** + * is this an async call to Promise.all()? + */ + isPromiseAll(): boolean; + + /** + * returns the index of the promise element that was followed in + * Promise.all() or Promise.any() for async stack traces, or null + * if the CallSite is not an async + */ + getPromiseIndex(): number | null; + + getScriptNameOrSourceURL(): string; + getScriptHash(): string; + + getEnclosingColumnNumber(): number; + getEnclosingLineNumber(): number; + getPosition(): number; + + toString(): string; + } + + interface ErrnoException extends Error { + errno?: number | undefined; + code?: string | undefined; + path?: string | undefined; + syscall?: string | undefined; + } + + interface ReadableStream extends EventEmitter { + readable: boolean; + read(size?: number): string | Buffer; + setEncoding(encoding: BufferEncoding): this; + pause(): this; + resume(): this; + isPaused(): boolean; + pipe(destination: T, options?: { end?: boolean | undefined }): T; + unpipe(destination?: WritableStream): this; + unshift(chunk: string | Uint8Array, encoding?: BufferEncoding): void; + wrap(oldStream: ReadableStream): this; + [Symbol.asyncIterator](): AsyncIterableIterator; + } + + interface WritableStream extends EventEmitter { + writable: boolean; + write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean; + write(str: string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean; + end(cb?: () => void): this; + end(data: string | Uint8Array, cb?: () => void): this; + end(str: string, encoding?: BufferEncoding, cb?: () => void): this; + } + + interface ReadWriteStream extends ReadableStream, WritableStream {} + + interface RefCounted { + ref(): this; + unref(): this; + } + + type TypedArray = + | Uint8Array + | Uint8ClampedArray + | Uint16Array + | Uint32Array + | Int8Array + | Int16Array + | Int32Array + | BigUint64Array + | BigInt64Array + | Float32Array + | Float64Array; + type ArrayBufferView = TypedArray | DataView; + + interface Require { + (id: string): any; + resolve: RequireResolve; + cache: Dict; + /** + * @deprecated + */ + extensions: RequireExtensions; + main: Module | undefined; + } + + interface RequireResolve { + (id: string, options?: { paths?: string[] | undefined }): string; + paths(request: string): string[] | null; + } + + interface RequireExtensions extends Dict<(m: Module, filename: string) => any> { + ".js": (m: Module, filename: string) => any; + ".json": (m: Module, filename: string) => any; + ".node": (m: Module, filename: string) => any; + } + interface Module { + /** + * `true` if the module is running during the Node.js preload + */ + isPreloading: boolean; + exports: any; + require: Require; + id: string; + filename: string; + loaded: boolean; + /** @deprecated since v14.6.0 Please use `require.main` and `module.children` instead. */ + parent: Module | null | undefined; + children: Module[]; + /** + * @since v11.14.0 + * + * The directory name of the module. This is usually the same as the path.dirname() of the module.id. + */ + path: string; + paths: string[]; + } + + interface Dict { + [key: string]: T | undefined; + } + + interface ReadOnlyDict { + readonly [key: string]: T | undefined; + } + } + + interface RequestInit extends _RequestInit {} + + function fetch( + input: string | URL | globalThis.Request, + init?: RequestInit, + ): Promise; + + interface Request extends _Request {} + var Request: typeof globalThis extends { + onmessage: any; + Request: infer T; + } ? T + : typeof import("undici-types").Request; + + interface ResponseInit extends _ResponseInit {} + + interface Response extends _Response {} + var Response: typeof globalThis extends { + onmessage: any; + Response: infer T; + } ? T + : typeof import("undici-types").Response; + + interface FormData extends _FormData {} + var FormData: typeof globalThis extends { + onmessage: any; + FormData: infer T; + } ? T + : typeof import("undici-types").FormData; + + interface Headers extends _Headers {} + var Headers: typeof globalThis extends { + onmessage: any; + Headers: infer T; + } ? T + : typeof import("undici-types").Headers; + + interface File extends _File {} + var File: typeof globalThis extends { + onmessage: any; + File: infer T; + } ? T + : typeof import("node:buffer").File; } diff --git a/node_modules/@types/node/globals.global.d.ts b/node_modules/@types/node/globals.global.d.ts old mode 100755 new mode 100644 diff --git a/node_modules/@types/node/http.d.ts b/node_modules/@types/node/http.d.ts old mode 100755 new mode 100644 index ed05862..710fe59 --- a/node_modules/@types/node/http.d.ts +++ b/node_modules/@types/node/http.d.ts @@ -1,5 +1,5 @@ /** - * To use the HTTP server and client one must `require('http')`. + * To use the HTTP server and client one must `require('node:http')`. * * The HTTP interfaces in Node.js are designed to support many features * of the protocol which have been traditionally difficult to use. @@ -9,12 +9,12 @@ * * HTTP message headers are represented by an object like this: * - * ```js - * { 'content-length': '123', - * 'content-type': 'text/plain', - * 'connection': 'keep-alive', - * 'host': 'mysite.com', - * 'accept': '*' } + * ```json + * { "content-length": "123", + * "content-type": "text/plain", + * "connection": "keep-alive", + * "host": "example.com", + * "accept": "*" } * ``` * * Keys are lowercased. Values are not modified. @@ -34,42 +34,44 @@ * 'content-LENGTH', '123', * 'content-type', 'text/plain', * 'CONNECTION', 'keep-alive', - * 'Host', 'mysite.com', + * 'Host', 'example.com', * 'accepT', '*' ] * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/http.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/http.js) */ -declare module 'http' { - import * as stream from 'node:stream'; - import { URL } from 'node:url'; - import { TcpSocketConnectOpts, Socket, Server as NetServer, LookupFunction } from 'node:net'; +declare module "http" { + import * as stream from "node:stream"; + import { URL } from "node:url"; + import { LookupOptions } from "node:dns"; + import { EventEmitter } from "node:events"; + import { LookupFunction, Server as NetServer, Socket, TcpSocketConnectOpts } from "node:net"; // incoming headers will never contain number interface IncomingHttpHeaders extends NodeJS.Dict { accept?: string | undefined; - 'accept-language'?: string | undefined; - 'accept-patch'?: string | undefined; - 'accept-ranges'?: string | undefined; - 'access-control-allow-credentials'?: string | undefined; - 'access-control-allow-headers'?: string | undefined; - 'access-control-allow-methods'?: string | undefined; - 'access-control-allow-origin'?: string | undefined; - 'access-control-expose-headers'?: string | undefined; - 'access-control-max-age'?: string | undefined; - 'access-control-request-headers'?: string | undefined; - 'access-control-request-method'?: string | undefined; + "accept-language"?: string | undefined; + "accept-patch"?: string | undefined; + "accept-ranges"?: string | undefined; + "access-control-allow-credentials"?: string | undefined; + "access-control-allow-headers"?: string | undefined; + "access-control-allow-methods"?: string | undefined; + "access-control-allow-origin"?: string | undefined; + "access-control-expose-headers"?: string | undefined; + "access-control-max-age"?: string | undefined; + "access-control-request-headers"?: string | undefined; + "access-control-request-method"?: string | undefined; age?: string | undefined; allow?: string | undefined; - 'alt-svc'?: string | undefined; + "alt-svc"?: string | undefined; authorization?: string | undefined; - 'cache-control'?: string | undefined; + "cache-control"?: string | undefined; connection?: string | undefined; - 'content-disposition'?: string | undefined; - 'content-encoding'?: string | undefined; - 'content-language'?: string | undefined; - 'content-length'?: string | undefined; - 'content-location'?: string | undefined; - 'content-range'?: string | undefined; - 'content-type'?: string | undefined; + "content-disposition"?: string | undefined; + "content-encoding"?: string | undefined; + "content-language"?: string | undefined; + "content-length"?: string | undefined; + "content-location"?: string | undefined; + "content-range"?: string | undefined; + "content-type"?: string | undefined; cookie?: string | undefined; date?: string | undefined; etag?: string | undefined; @@ -78,91 +80,216 @@ declare module 'http' { forwarded?: string | undefined; from?: string | undefined; host?: string | undefined; - 'if-match'?: string | undefined; - 'if-modified-since'?: string | undefined; - 'if-none-match'?: string | undefined; - 'if-unmodified-since'?: string | undefined; - 'last-modified'?: string | undefined; + "if-match"?: string | undefined; + "if-modified-since"?: string | undefined; + "if-none-match"?: string | undefined; + "if-unmodified-since"?: string | undefined; + "last-modified"?: string | undefined; location?: string | undefined; origin?: string | undefined; pragma?: string | undefined; - 'proxy-authenticate'?: string | undefined; - 'proxy-authorization'?: string | undefined; - 'public-key-pins'?: string | undefined; + "proxy-authenticate"?: string | undefined; + "proxy-authorization"?: string | undefined; + "public-key-pins"?: string | undefined; range?: string | undefined; referer?: string | undefined; - 'retry-after'?: string | undefined; - 'sec-websocket-accept'?: string | undefined; - 'sec-websocket-extensions'?: string | undefined; - 'sec-websocket-key'?: string | undefined; - 'sec-websocket-protocol'?: string | undefined; - 'sec-websocket-version'?: string | undefined; - 'set-cookie'?: string[] | undefined; - 'strict-transport-security'?: string | undefined; + "retry-after"?: string | undefined; + "sec-websocket-accept"?: string | undefined; + "sec-websocket-extensions"?: string | undefined; + "sec-websocket-key"?: string | undefined; + "sec-websocket-protocol"?: string | undefined; + "sec-websocket-version"?: string | undefined; + "set-cookie"?: string[] | undefined; + "strict-transport-security"?: string | undefined; tk?: string | undefined; trailer?: string | undefined; - 'transfer-encoding'?: string | undefined; + "transfer-encoding"?: string | undefined; upgrade?: string | undefined; - 'user-agent'?: string | undefined; + "user-agent"?: string | undefined; vary?: string | undefined; via?: string | undefined; warning?: string | undefined; - 'www-authenticate'?: string | undefined; + "www-authenticate"?: string | undefined; } // outgoing headers allows numbers (as they are converted internally to strings) type OutgoingHttpHeader = number | string | string[]; - interface OutgoingHttpHeaders extends NodeJS.Dict {} + interface OutgoingHttpHeaders extends NodeJS.Dict { + accept?: string | string[] | undefined; + "accept-charset"?: string | string[] | undefined; + "accept-encoding"?: string | string[] | undefined; + "accept-language"?: string | string[] | undefined; + "accept-ranges"?: string | undefined; + "access-control-allow-credentials"?: string | undefined; + "access-control-allow-headers"?: string | undefined; + "access-control-allow-methods"?: string | undefined; + "access-control-allow-origin"?: string | undefined; + "access-control-expose-headers"?: string | undefined; + "access-control-max-age"?: string | undefined; + "access-control-request-headers"?: string | undefined; + "access-control-request-method"?: string | undefined; + age?: string | undefined; + allow?: string | undefined; + authorization?: string | undefined; + "cache-control"?: string | undefined; + "cdn-cache-control"?: string | undefined; + connection?: string | string[] | undefined; + "content-disposition"?: string | undefined; + "content-encoding"?: string | undefined; + "content-language"?: string | undefined; + "content-length"?: string | number | undefined; + "content-location"?: string | undefined; + "content-range"?: string | undefined; + "content-security-policy"?: string | undefined; + "content-security-policy-report-only"?: string | undefined; + cookie?: string | string[] | undefined; + dav?: string | string[] | undefined; + dnt?: string | undefined; + date?: string | undefined; + etag?: string | undefined; + expect?: string | undefined; + expires?: string | undefined; + forwarded?: string | undefined; + from?: string | undefined; + host?: string | undefined; + "if-match"?: string | undefined; + "if-modified-since"?: string | undefined; + "if-none-match"?: string | undefined; + "if-range"?: string | undefined; + "if-unmodified-since"?: string | undefined; + "last-modified"?: string | undefined; + link?: string | string[] | undefined; + location?: string | undefined; + "max-forwards"?: string | undefined; + origin?: string | undefined; + prgama?: string | string[] | undefined; + "proxy-authenticate"?: string | string[] | undefined; + "proxy-authorization"?: string | undefined; + "public-key-pins"?: string | undefined; + "public-key-pins-report-only"?: string | undefined; + range?: string | undefined; + referer?: string | undefined; + "referrer-policy"?: string | undefined; + refresh?: string | undefined; + "retry-after"?: string | undefined; + "sec-websocket-accept"?: string | undefined; + "sec-websocket-extensions"?: string | string[] | undefined; + "sec-websocket-key"?: string | undefined; + "sec-websocket-protocol"?: string | string[] | undefined; + "sec-websocket-version"?: string | undefined; + server?: string | undefined; + "set-cookie"?: string | string[] | undefined; + "strict-transport-security"?: string | undefined; + te?: string | undefined; + trailer?: string | undefined; + "transfer-encoding"?: string | undefined; + "user-agent"?: string | undefined; + upgrade?: string | undefined; + "upgrade-insecure-requests"?: string | undefined; + vary?: string | undefined; + via?: string | string[] | undefined; + warning?: string | undefined; + "www-authenticate"?: string | string[] | undefined; + "x-content-type-options"?: string | undefined; + "x-dns-prefetch-control"?: string | undefined; + "x-frame-options"?: string | undefined; + "x-xss-protection"?: string | undefined; + } interface ClientRequestArgs { - signal?: AbortSignal | undefined; - protocol?: string | null | undefined; - host?: string | null | undefined; - hostname?: string | null | undefined; - family?: number | undefined; - port?: number | string | null | undefined; - defaultPort?: number | string | undefined; - localAddress?: string | undefined; - socketPath?: string | undefined; - /** - * @default 8192 - */ - maxHeaderSize?: number | undefined; - method?: string | undefined; - path?: string | null | undefined; - headers?: OutgoingHttpHeaders | undefined; - auth?: string | null | undefined; - agent?: Agent | boolean | undefined; _defaultAgent?: Agent | undefined; - timeout?: number | undefined; - setHost?: boolean | undefined; + agent?: Agent | boolean | undefined; + auth?: string | null | undefined; // https://github.com/nodejs/node/blob/master/lib/_http_client.js#L278 createConnection?: | ((options: ClientRequestArgs, oncreate: (err: Error, socket: Socket) => void) => Socket) | undefined; + defaultPort?: number | string | undefined; + family?: number | undefined; + headers?: OutgoingHttpHeaders | undefined; + hints?: LookupOptions["hints"]; + host?: string | null | undefined; + hostname?: string | null | undefined; + insecureHTTPParser?: boolean | undefined; + localAddress?: string | undefined; + localPort?: number | undefined; lookup?: LookupFunction | undefined; + /** + * @default 16384 + */ + maxHeaderSize?: number | undefined; + method?: string | undefined; + path?: string | null | undefined; + port?: number | string | null | undefined; + protocol?: string | null | undefined; + setHost?: boolean | undefined; + signal?: AbortSignal | undefined; + socketPath?: string | undefined; + timeout?: number | undefined; + uniqueHeaders?: Array | undefined; + joinDuplicateHeaders?: boolean; } interface ServerOptions< Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse, > { + /** + * Specifies the `IncomingMessage` class to be used. Useful for extending the original `IncomingMessage`. + */ IncomingMessage?: Request | undefined; + /** + * Specifies the `ServerResponse` class to be used. Useful for extending the original `ServerResponse`. + */ ServerResponse?: Response | undefined; /** - * Optionally overrides the value of - * `--max-http-header-size` for requests received by this server, i.e. - * the maximum length of request headers in bytes. - * @default 8192 + * Sets the timeout value in milliseconds for receiving the entire request from the client. + * @see Server.requestTimeout for more information. + * @default 300000 + * @since v18.0.0 */ - maxHeaderSize?: number | undefined; + requestTimeout?: number | undefined; /** - * Use an insecure HTTP parser that accepts invalid HTTP headers when true. + * It joins the field line values of multiple headers in a request with `, ` instead of discarding the duplicates. + * @default false + * @since v18.14.0 + */ + joinDuplicateHeaders?: boolean; + /** + * The number of milliseconds of inactivity a server needs to wait for additional incoming data, + * after it has finished writing the last response, before a socket will be destroyed. + * @see Server.keepAliveTimeout for more information. + * @default 5000 + * @since v18.0.0 + */ + keepAliveTimeout?: number | undefined; + /** + * Sets the interval value in milliseconds to check for request and headers timeout in incomplete requests. + * @default 30000 + */ + connectionsCheckingInterval?: number | undefined; + /** + * Optionally overrides all `socket`s' `readableHighWaterMark` and `writableHighWaterMark`. + * This affects `highWaterMark` property of both `IncomingMessage` and `ServerResponse`. + * Default: @see stream.getDefaultHighWaterMark(). + * @since v20.1.0 + */ + highWaterMark?: number | undefined; + /** + * Use an insecure HTTP parser that accepts invalid HTTP headers when `true`. * Using the insecure parser should be avoided. * See --insecure-http-parser for more information. * @default false */ insecureHTTPParser?: boolean | undefined; + /** + * Optionally overrides the value of + * `--max-http-header-size` for requests received by this server, i.e. + * the maximum length of request headers in bytes. + * @default 16384 + * @since v13.3.0 + */ + maxHeaderSize?: number | undefined; /** * If set to `true`, it disables the use of Nagle's algorithm immediately after a new incoming connection is received. - * @default false + * @default true * @since v16.5.0 */ noDelay?: boolean | undefined; @@ -179,6 +306,11 @@ declare module 'http' { * @since v16.5.0 */ keepAliveInitialDelay?: number | undefined; + /** + * A list of response headers that should be sent only once. + * If the header's value is an array, the items will be joined using `; `. + */ + uniqueHeaders?: Array | undefined; } type RequestListener< Request extends typeof IncomingMessage = typeof IncomingMessage, @@ -241,14 +373,12 @@ declare module 'http' { * Limit the amount of time the parser will wait to receive the complete HTTP * headers. * - * In case of inactivity, the rules defined in `server.timeout` apply. However, - * that inactivity based timeout would still allow the connection to be kept open - * if the headers are being sent very slowly (by default, up to a byte per 2 - * minutes). In order to prevent this, whenever header data arrives an additional - * check is made that more than `server.headersTimeout` milliseconds has not - * passed since the connection was established. If the check fails, a `'timeout'`event is emitted on the server object, and (by default) the socket is destroyed. - * See `server.timeout` for more information on how timeout behavior can be - * customized. + * If the timeout expires, the server responds with status 408 without + * forwarding the request to the request listener and then closes the connection. + * + * It must be set to a non-zero value (e.g. 120 seconds) to protect against + * potential Denial-of-Service attacks in case the server is deployed without a + * reverse proxy in front. * @since v11.3.0, v10.14.0 */ headersTimeout: number; @@ -281,112 +411,135 @@ declare module 'http' { * @since v14.11.0 */ requestTimeout: number; + /** + * Closes all connections connected to this server. + * @since v18.2.0 + */ + closeAllConnections(): void; + /** + * Closes all connections connected to this server which are not sending a request + * or waiting for a response. + * @since v18.2.0 + */ + closeIdleConnections(): void; addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'connection', listener: (socket: Socket) => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'listening', listener: () => void): this; - addListener(event: 'checkContinue', listener: RequestListener): this; - addListener(event: 'checkExpectation', listener: RequestListener): this; - addListener(event: 'clientError', listener: (err: Error, socket: stream.Duplex) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "connection", listener: (socket: Socket) => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "listening", listener: () => void): this; + addListener(event: "checkContinue", listener: RequestListener): this; + addListener(event: "checkExpectation", listener: RequestListener): this; + addListener(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this; addListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; - addListener(event: 'request', listener: RequestListener): this; + addListener(event: "dropRequest", listener: (req: InstanceType, socket: stream.Duplex) => void): this; + addListener(event: "request", listener: RequestListener): this; addListener( - event: 'upgrade', + event: "upgrade", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; emit(event: string, ...args: any[]): boolean; - emit(event: 'close'): boolean; - emit(event: 'connection', socket: Socket): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'listening'): boolean; + emit(event: "close"): boolean; + emit(event: "connection", socket: Socket): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "listening"): boolean; emit( - event: 'checkContinue', + event: "checkContinue", req: InstanceType, res: InstanceType & { req: InstanceType }, ): boolean; emit( - event: 'checkExpectation', + event: "checkExpectation", req: InstanceType, res: InstanceType & { req: InstanceType }, ): boolean; - emit(event: 'clientError', err: Error, socket: stream.Duplex): boolean; - emit(event: 'connect', req: InstanceType, socket: stream.Duplex, head: Buffer): boolean; + emit(event: "clientError", err: Error, socket: stream.Duplex): boolean; + emit(event: "connect", req: InstanceType, socket: stream.Duplex, head: Buffer): boolean; + emit(event: "dropRequest", req: InstanceType, socket: stream.Duplex): boolean; emit( - event: 'request', + event: "request", req: InstanceType, res: InstanceType & { req: InstanceType }, ): boolean; - emit(event: 'upgrade', req: InstanceType, socket: stream.Duplex, head: Buffer): boolean; + emit(event: "upgrade", req: InstanceType, socket: stream.Duplex, head: Buffer): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'connection', listener: (socket: Socket) => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'listening', listener: () => void): this; - on(event: 'checkContinue', listener: RequestListener): this; - on(event: 'checkExpectation', listener: RequestListener): this; - on(event: 'clientError', listener: (err: Error, socket: stream.Duplex) => void): this; - on(event: 'connect', listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void): this; - on(event: 'request', listener: RequestListener): this; - on(event: 'upgrade', listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void): this; + on(event: "close", listener: () => void): this; + on(event: "connection", listener: (socket: Socket) => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "listening", listener: () => void): this; + on(event: "checkContinue", listener: RequestListener): this; + on(event: "checkExpectation", listener: RequestListener): this; + on(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this; + on(event: "connect", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void): this; + on(event: "dropRequest", listener: (req: InstanceType, socket: stream.Duplex) => void): this; + on(event: "request", listener: RequestListener): this; + on(event: "upgrade", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'connection', listener: (socket: Socket) => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'listening', listener: () => void): this; - once(event: 'checkContinue', listener: RequestListener): this; - once(event: 'checkExpectation', listener: RequestListener): this; - once(event: 'clientError', listener: (err: Error, socket: stream.Duplex) => void): this; + once(event: "close", listener: () => void): this; + once(event: "connection", listener: (socket: Socket) => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "listening", listener: () => void): this; + once(event: "checkContinue", listener: RequestListener): this; + once(event: "checkExpectation", listener: RequestListener): this; + once(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this; once( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; - once(event: 'request', listener: RequestListener): this; + once(event: "dropRequest", listener: (req: InstanceType, socket: stream.Duplex) => void): this; + once(event: "request", listener: RequestListener): this; once( - event: 'upgrade', + event: "upgrade", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'connection', listener: (socket: Socket) => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'listening', listener: () => void): this; - prependListener(event: 'checkContinue', listener: RequestListener): this; - prependListener(event: 'checkExpectation', listener: RequestListener): this; - prependListener(event: 'clientError', listener: (err: Error, socket: stream.Duplex) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "connection", listener: (socket: Socket) => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "listening", listener: () => void): this; + prependListener(event: "checkContinue", listener: RequestListener): this; + prependListener(event: "checkExpectation", listener: RequestListener): this; + prependListener(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this; prependListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; - prependListener(event: 'request', listener: RequestListener): this; prependListener( - event: 'upgrade', + event: "dropRequest", + listener: (req: InstanceType, socket: stream.Duplex) => void, + ): this; + prependListener(event: "request", listener: RequestListener): this; + prependListener( + event: "upgrade", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'connection', listener: (socket: Socket) => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'listening', listener: () => void): this; - prependOnceListener(event: 'checkContinue', listener: RequestListener): this; - prependOnceListener(event: 'checkExpectation', listener: RequestListener): this; - prependOnceListener(event: 'clientError', listener: (err: Error, socket: stream.Duplex) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "connection", listener: (socket: Socket) => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "listening", listener: () => void): this; + prependOnceListener(event: "checkContinue", listener: RequestListener): this; + prependOnceListener(event: "checkExpectation", listener: RequestListener): this; + prependOnceListener(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this; prependOnceListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; - prependOnceListener(event: 'request', listener: RequestListener): this; prependOnceListener( - event: 'upgrade', + event: "dropRequest", + listener: (req: InstanceType, socket: stream.Duplex) => void, + ): this; + prependOnceListener(event: "request", listener: RequestListener): this; + prependOnceListener( + event: "upgrade", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; } /** - * This class serves as the parent class of {@link ClientRequest} and {@link ServerResponse}. It is an abstract of outgoing message from - * the perspective of the participants of HTTP transaction. + * This class serves as the parent class of {@link ClientRequest} and {@link ServerResponse}. It is an abstract outgoing message from + * the perspective of the participants of an HTTP transaction. * @since v0.1.17 */ class OutgoingMessage extends stream.Writable { @@ -405,9 +558,9 @@ declare module 'http' { */ readonly headersSent: boolean; /** - * Aliases of `outgoingMessage.socket` + * Alias of `outgoingMessage.socket`. * @since v0.3.0 - * @deprecated Since v15.12.0 - Use `socket` instead. + * @deprecated Since v15.12.0,v14.17.1 - Use `socket` instead. */ readonly connection: Socket | null; /** @@ -426,15 +579,33 @@ declare module 'http' { */ setTimeout(msecs: number, callback?: () => void): this; /** - * Sets a single header value for the header object. + * Sets a single header value. If the header already exists in the to-be-sent + * headers, its value will be replaced. Use an array of strings to send multiple + * headers with the same name. * @since v0.4.0 * @param name Header name * @param value Header value */ - setHeader(name: string, value: number | string | ReadonlyArray): this; + setHeader(name: string, value: number | string | readonly string[]): this; /** - * Gets the value of HTTP header with the given name. If such a name doesn't - * exist in message, it will be `undefined`. + * Append a single header value for the header object. + * + * If the value is an array, this is equivalent of calling this method multiple + * times. + * + * If there were no previous value for the header, this is equivalent of calling `outgoingMessage.setHeader(name, value)`. + * + * Depending of the value of `options.uniqueHeaders` when the client request or the + * server were created, this will end up in the header being sent multiple times or + * a single time with values joined using `; `. + * @since v18.3.0, v16.17.0 + * @param name Header name + * @param value Header value + */ + appendHeader(name: string, value: string | readonly string[]): this; + /** + * Gets the value of the HTTP header with the given name. If that header is not + * set, the returned value will be `undefined`. * @since v0.4.0 * @param name Name of header */ @@ -447,8 +618,8 @@ declare module 'http' { * values. All header names are lowercase. * * The object returned by the `outgoingMessage.getHeaders()` method does - * not prototypically inherit from the JavaScript Object. This means that - * typical Object methods such as `obj.toString()`, `obj.hasOwnProperty()`, + * not prototypically inherit from the JavaScript `Object`. This means that + * typical `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, * and others are not defined and will not work. * * ```js @@ -458,13 +629,13 @@ declare module 'http' { * const headers = outgoingMessage.getHeaders(); * // headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } * ``` - * @since v8.0.0 + * @since v7.7.0 */ getHeaders(): OutgoingHttpHeaders; /** - * Returns an array of names of headers of the outgoing outgoingMessage. All - * names are lowercase. - * @since v8.0.0 + * Returns an array containing the unique names of the current outgoing headers. + * All names are lowercase. + * @since v7.7.0 */ getHeaderNames(): string[]; /** @@ -474,7 +645,7 @@ declare module 'http' { * ```js * const hasContentType = outgoingMessage.hasHeader('content-type'); * ``` - * @since v8.0.0 + * @since v7.7.0 */ hasHeader(name: string): boolean; /** @@ -484,16 +655,17 @@ declare module 'http' { * outgoingMessage.removeHeader('Content-Encoding'); * ``` * @since v0.4.0 + * @param name Header name */ removeHeader(name: string): void; /** * Adds HTTP trailers (headers but at the end of the message) to the message. * - * Trailers are **only** be emitted if the message is chunked encoded. If not, - * the trailer will be silently discarded. + * Trailers will **only** be emitted if the message is chunked encoded. If not, + * the trailers will be silently discarded. * * HTTP requires the `Trailer` header to be sent to emit trailers, - * with a list of header fields in its value, e.g. + * with a list of header field names in its value, e.g. * * ```js * message.writeHead(200, { 'Content-Type': 'text/plain', @@ -509,7 +681,7 @@ declare module 'http' { */ addTrailers(headers: OutgoingHttpHeaders | ReadonlyArray<[string, string]>): void; /** - * Compulsorily flushes the message headers + * Flushes the message headers. * * For efficiency reason, Node.js normally buffers the message headers * until `outgoingMessage.end()` is called or the first chunk of message data @@ -517,7 +689,7 @@ declare module 'http' { * packet. * * It is usually desired (it saves a TCP round-trip), but not when the first - * data is not sent until possibly much later. `outgoingMessage.flushHeaders()`bypasses the optimization and kickstarts the request. + * data is not sent until possibly much later. `outgoingMessage.flushHeaders()`bypasses the optimization and kickstarts the message. * @since v1.6.0 */ flushHeaders(): void; @@ -557,15 +729,56 @@ declare module 'http' { * @since v0.11.8 */ statusMessage: string; + /** + * If set to `true`, Node.js will check whether the `Content-Length`header value and the size of the body, in bytes, are equal. + * Mismatching the `Content-Length` header value will result + * in an `Error` being thrown, identified by `code:``'ERR_HTTP_CONTENT_LENGTH_MISMATCH'`. + * @since v18.10.0, v16.18.0 + */ + strictContentLength: boolean; constructor(req: Request); assignSocket(socket: Socket): void; detachSocket(socket: Socket): void; /** - * Sends a HTTP/1.1 100 Continue message to the client, indicating that + * Sends an HTTP/1.1 100 Continue message to the client, indicating that * the request body should be sent. See the `'checkContinue'` event on`Server`. * @since v0.3.0 */ writeContinue(callback?: () => void): void; + /** + * Sends an HTTP/1.1 103 Early Hints message to the client with a Link header, + * indicating that the user agent can preload/preconnect the linked resources. + * The `hints` is an object containing the values of headers to be sent with + * early hints message. The optional `callback` argument will be called when + * the response message has been written. + * + * **Example** + * + * ```js + * const earlyHintsLink = '; rel=preload; as=style'; + * response.writeEarlyHints({ + * 'link': earlyHintsLink, + * }); + * + * const earlyHintsLinks = [ + * '; rel=preload; as=style', + * '; rel=preload; as=script', + * ]; + * response.writeEarlyHints({ + * 'link': earlyHintsLinks, + * 'x-trace-id': 'id for diagnostics', + * }); + * + * const earlyHintsCallback = () => console.log('early hints message sent'); + * response.writeEarlyHints({ + * 'link': earlyHintsLinks, + * }, earlyHintsCallback); + * ``` + * @since v18.11.0 + * @param hints An object containing the values of headers + * @param callback Will be called when the response message has been written + */ + writeEarlyHints(hints: Record, callback?: () => void): void; /** * Sends a response header to the request. The status code is a 3-digit HTTP * status code, like `404`. The last argument, `headers`, are the response headers. @@ -584,7 +797,7 @@ declare module 'http' { * response * .writeHead(200, { * 'Content-Length': Buffer.byteLength(body), - * 'Content-Type': 'text/plain' + * 'Content-Type': 'text/plain', * }) * .end(body); * ``` @@ -615,12 +828,12 @@ declare module 'http' { * }); * ``` * - * `Content-Length` is given in bytes, not characters. Use `Buffer.byteLength()` to determine the length of the body in bytes. Node.js - * does not check whether `Content-Length` and the length of the body which has + * `Content-Length` is read in bytes, not characters. Use `Buffer.byteLength()` to determine the length of the body in bytes. Node.js + * will check whether `Content-Length` and the length of the body which has * been transmitted are equal or not. * * Attempting to set a header field name or value that contains invalid characters - * will result in a `TypeError` being thrown. + * will result in a \[`Error`\]\[\] being thrown. * @since v0.1.30 */ writeHead( @@ -669,8 +882,11 @@ declare module 'http' { * * For backward compatibility, `res` will only emit `'error'` if there is an`'error'` listener registered. * - * Node.js does not check whether Content-Length and the length of the - * body which has been transmitted are equal or not. + * Set `Content-Length` header to limit the response body size. + * If `response.strictContentLength` is set to `true`, mismatching the`Content-Length` header value will result in an `Error` being thrown, + * identified by `code:``'ERR_HTTP_CONTENT_LENGTH_MISMATCH'`. + * + * `Content-Length` value should be in bytes, not characters. Use `Buffer.byteLength()` to determine the length of the body in bytes. * @since v0.1.17 */ class ClientRequest extends OutgoingMessage { @@ -678,6 +894,7 @@ declare module 'http' { * The `request.aborted` property will be `true` if the request has * been aborted. * @since v0.11.14 + * @deprecated Since v17.0.0,v16.12.0 - Check `destroyed` instead. */ aborted: boolean; /** @@ -691,13 +908,58 @@ declare module 'http' { */ protocol: string; /** - * Whether the request is send through a reused socket. + * When sending request through a keep-alive enabled agent, the underlying socket + * might be reused. But if server closes connection at unfortunate time, client + * may run into a 'ECONNRESET' error. + * + * ```js + * import http from 'node:http'; + * + * // Server has a 5 seconds keep-alive timeout by default + * http + * .createServer((req, res) => { + * res.write('hello\n'); + * res.end(); + * }) + * .listen(3000); + * + * setInterval(() => { + * // Adapting a keep-alive agent + * http.get('http://localhost:3000', { agent }, (res) => { + * res.on('data', (data) => { + * // Do nothing + * }); + * }); + * }, 5000); // Sending request on 5s interval so it's easy to hit idle timeout + * ``` + * + * By marking a request whether it reused socket or not, we can do + * automatic error retry base on it. + * + * ```js + * import http from 'node:http'; + * const agent = new http.Agent({ keepAlive: true }); + * + * function retriableRequest() { + * const req = http + * .get('http://localhost:3000', { agent }, (res) => { + * // ... + * }) + * .on('error', (err) => { + * // Check if retry is needed + * if (req.reusedSocket && err.code === 'ECONNRESET') { + * retriableRequest(); + * } + * }); + * } + * + * retriableRequest(); + * ``` * @since v13.0.0, v12.16.0 */ reusedSocket: boolean; /** * Limits maximum response headers count. If set to 0, no limit will be applied. - * @default 2000 */ maxHeadersCount: number; constructor(url: string | URL | ClientRequestArgs, cb?: (res: IncomingMessage) => void); @@ -747,107 +1009,122 @@ declare module 'http' { * const headerNames = request.getRawHeaderNames(); * // headerNames === ['Foo', 'Set-Cookie'] * ``` - * @since v15.13.0 + * @since v15.13.0, v14.17.0 */ getRawHeaderNames(): string[]; - addListener(event: 'abort', listener: () => void): this; + /** + * @deprecated + */ + addListener(event: "abort", listener: () => void): this; addListener( - event: 'connect', + event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - addListener(event: 'continue', listener: () => void): this; - addListener(event: 'information', listener: (info: InformationEvent) => void): this; - addListener(event: 'response', listener: (response: IncomingMessage) => void): this; - addListener(event: 'socket', listener: (socket: Socket) => void): this; - addListener(event: 'timeout', listener: () => void): this; + addListener(event: "continue", listener: () => void): this; + addListener(event: "information", listener: (info: InformationEvent) => void): this; + addListener(event: "response", listener: (response: IncomingMessage) => void): this; + addListener(event: "socket", listener: (socket: Socket) => void): this; + addListener(event: "timeout", listener: () => void): this; addListener( - event: 'upgrade', + event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'finish', listener: () => void): this; - addListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - addListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "pipe", listener: (src: stream.Readable) => void): this; + addListener(event: "unpipe", listener: (src: stream.Readable) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - on(event: 'abort', listener: () => void): this; - on(event: 'connect', listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; - on(event: 'continue', listener: () => void): this; - on(event: 'information', listener: (info: InformationEvent) => void): this; - on(event: 'response', listener: (response: IncomingMessage) => void): this; - on(event: 'socket', listener: (socket: Socket) => void): this; - on(event: 'timeout', listener: () => void): this; - on(event: 'upgrade', listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'finish', listener: () => void): this; - on(event: 'pipe', listener: (src: stream.Readable) => void): this; - on(event: 'unpipe', listener: (src: stream.Readable) => void): this; + /** + * @deprecated + */ + on(event: "abort", listener: () => void): this; + on(event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; + on(event: "continue", listener: () => void): this; + on(event: "information", listener: (info: InformationEvent) => void): this; + on(event: "response", listener: (response: IncomingMessage) => void): this; + on(event: "socket", listener: (socket: Socket) => void): this; + on(event: "timeout", listener: () => void): this; + on(event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; + on(event: "close", listener: () => void): this; + on(event: "drain", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "pipe", listener: (src: stream.Readable) => void): this; + on(event: "unpipe", listener: (src: stream.Readable) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'abort', listener: () => void): this; - once(event: 'connect', listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; - once(event: 'continue', listener: () => void): this; - once(event: 'information', listener: (info: InformationEvent) => void): this; - once(event: 'response', listener: (response: IncomingMessage) => void): this; - once(event: 'socket', listener: (socket: Socket) => void): this; - once(event: 'timeout', listener: () => void): this; - once(event: 'upgrade', listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'finish', listener: () => void): this; - once(event: 'pipe', listener: (src: stream.Readable) => void): this; - once(event: 'unpipe', listener: (src: stream.Readable) => void): this; + /** + * @deprecated + */ + once(event: "abort", listener: () => void): this; + once(event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; + once(event: "continue", listener: () => void): this; + once(event: "information", listener: (info: InformationEvent) => void): this; + once(event: "response", listener: (response: IncomingMessage) => void): this; + once(event: "socket", listener: (socket: Socket) => void): this; + once(event: "timeout", listener: () => void): this; + once(event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; + once(event: "close", listener: () => void): this; + once(event: "drain", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "pipe", listener: (src: stream.Readable) => void): this; + once(event: "unpipe", listener: (src: stream.Readable) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'abort', listener: () => void): this; + /** + * @deprecated + */ + prependListener(event: "abort", listener: () => void): this; prependListener( - event: 'connect', + event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - prependListener(event: 'continue', listener: () => void): this; - prependListener(event: 'information', listener: (info: InformationEvent) => void): this; - prependListener(event: 'response', listener: (response: IncomingMessage) => void): this; - prependListener(event: 'socket', listener: (socket: Socket) => void): this; - prependListener(event: 'timeout', listener: () => void): this; + prependListener(event: "continue", listener: () => void): this; + prependListener(event: "information", listener: (info: InformationEvent) => void): this; + prependListener(event: "response", listener: (response: IncomingMessage) => void): this; + prependListener(event: "socket", listener: (socket: Socket) => void): this; + prependListener(event: "timeout", listener: () => void): this; prependListener( - event: 'upgrade', + event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'finish', listener: () => void): this; - prependListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'abort', listener: () => void): this; + /** + * @deprecated + */ + prependOnceListener(event: "abort", listener: () => void): this; prependOnceListener( - event: 'connect', + event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - prependOnceListener(event: 'continue', listener: () => void): this; - prependOnceListener(event: 'information', listener: (info: InformationEvent) => void): this; - prependOnceListener(event: 'response', listener: (response: IncomingMessage) => void): this; - prependOnceListener(event: 'socket', listener: (socket: Socket) => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; + prependOnceListener(event: "continue", listener: () => void): this; + prependOnceListener(event: "information", listener: (info: InformationEvent) => void): this; + prependOnceListener(event: "response", listener: (response: IncomingMessage) => void): this; + prependOnceListener(event: "socket", listener: (socket: Socket) => void): this; + prependOnceListener(event: "timeout", listener: () => void): this; prependOnceListener( - event: 'upgrade', + event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'finish', listener: () => void): this; - prependOnceListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependOnceListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } /** * An `IncomingMessage` object is created by {@link Server} or {@link ClientRequest} and passed as the first argument to the `'request'` and `'response'` event respectively. It may be used to * access response - * status, headers and data. + * status, headers, and data. * * Different from its `socket` value which is a subclass of `stream.Duplex`, the`IncomingMessage` itself extends `stream.Readable` and is created separately to * parse and emit the incoming HTTP headers and payload, as the underlying socket @@ -860,6 +1137,7 @@ declare module 'http' { * The `message.aborted` property will be `true` if the request has * been aborted. * @since v10.1.0 + * @deprecated Since v17.0.0,v16.12.0 - Check `message.destroyed` from stream.Readable. */ aborted: boolean; /** @@ -884,7 +1162,7 @@ declare module 'http' { * const req = http.request({ * host: '127.0.0.1', * port: 8080, - * method: 'POST' + * method: 'POST', * }, (res) => { * res.resume(); * res.on('end', () => { @@ -911,7 +1189,7 @@ declare module 'http' { * * This property is guaranteed to be an instance of the `net.Socket` class, * a subclass of `stream.Duplex`, unless the user specified a socket - * type other than `net.Socket`. + * type other than `net.Socket` or internally nulled. * @since v0.3.0 */ socket: Socket; @@ -934,12 +1212,30 @@ declare module 'http' { * * * Duplicates of `age`, `authorization`, `content-length`, `content-type`,`etag`, `expires`, `from`, `host`, `if-modified-since`, `if-unmodified-since`,`last-modified`, `location`, * `max-forwards`, `proxy-authorization`, `referer`,`retry-after`, `server`, or `user-agent` are discarded. + * To allow duplicate values of the headers listed above to be joined, + * use the option `joinDuplicateHeaders` in {@link request} and {@link createServer}. See RFC 9110 Section 5.3 for more + * information. * * `set-cookie` is always an array. Duplicates are added to the array. - * * For duplicate `cookie` headers, the values are joined together with '; '. - * * For all other headers, the values are joined together with ', '. + * * For duplicate `cookie` headers, the values are joined together with `; `. + * * For all other headers, the values are joined together with `, `. * @since v0.1.5 */ headers: IncomingHttpHeaders; + /** + * Similar to `message.headers`, but there is no join logic and the values are + * always arrays of strings, even for headers received just once. + * + * ```js + * // Prints something like: + * // + * // { 'user-agent': ['curl/7.22.0'], + * // host: ['127.0.0.1:8000'], + * // accept: ['*'] } + * console.log(request.headersDistinct); + * ``` + * @since v18.3.0, v16.17.0 + */ + headersDistinct: NodeJS.Dict; /** * The raw request/response headers list exactly as they were received. * @@ -970,6 +1266,13 @@ declare module 'http' { * @since v0.3.0 */ trailers: NodeJS.Dict; + /** + * Similar to `message.trailers`, but there is no join logic and the values are + * always arrays of strings, even for headers received just once. + * Only populated at the `'end'` event. + * @since v18.3.0, v16.17.0 + */ + trailersDistinct: NodeJS.Dict; /** * The raw request/response trailer keys and values exactly as they were * received. Only populated at the `'end'` event. @@ -1005,7 +1308,7 @@ declare module 'http' { * new URL(request.url, `http://${request.headers.host}`); * ``` * - * When `request.url` is `'/status?name=ryan'` and`request.headers.host` is `'localhost:3000'`: + * When `request.url` is `'/status?name=ryan'` and `request.headers.host` is`'localhost:3000'`: * * ```console * $ node @@ -1079,7 +1382,7 @@ declare module 'http' { * Scheduling strategy to apply when picking the next free socket to use. * @default `lifo` */ - scheduling?: 'fifo' | 'lifo' | undefined; + scheduling?: "fifo" | "lifo" | undefined; } /** * An `Agent` is responsible for managing connection persistence @@ -1129,16 +1432,16 @@ declare module 'http' { * hostname: 'localhost', * port: 80, * path: '/', - * agent: false // Create a new agent just for this one request + * agent: false, // Create a new agent just for this one request * }, (res) => { * // Do stuff with response * }); * ``` * @since v0.3.4 */ - class Agent { + class Agent extends EventEmitter { /** - * By default set to 256\. For agents with `keepAlive` enabled, this + * By default set to 256. For agents with `keepAlive` enabled, this * sets the maximum number of sockets that will be left open in the free * state. * @since v0.11.7 @@ -1200,6 +1503,37 @@ declare module 'http' { * * The `requestListener` is a function which is automatically * added to the `'request'` event. + * + * ```js + * import http from 'node:http'; + * + * // Create a local server to receive data from + * const server = http.createServer((req, res) => { + * res.writeHead(200, { 'Content-Type': 'application/json' }); + * res.end(JSON.stringify({ + * data: 'Hello World!', + * })); + * }); + * + * server.listen(8000); + * ``` + * + * ```js + * import http from 'node:http'; + * + * // Create a local server to receive data from + * const server = http.createServer(); + * + * // Listen to the request event + * server.on('request', (request, res) => { + * res.writeHead(200, { 'Content-Type': 'application/json' }); + * res.end(JSON.stringify({ + * data: 'Hello World!', + * })); + * }); + * + * server.listen(8000); + * ``` * @since v0.1.13 */ function createServer< @@ -1209,11 +1543,16 @@ declare module 'http' { function createServer< Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse, - >(options: ServerOptions, requestListener?: RequestListener): Server; + >( + options: ServerOptions, + requestListener?: RequestListener, + ): Server; // although RequestOptions are passed as ClientRequestArgs to ClientRequest directly, // create interface RequestOptions would make the naming more clear to developers interface RequestOptions extends ClientRequestArgs {} /** + * `options` in `socket.connect()` are also supported. + * * Node.js maintains several connections per server to make HTTP requests. * This function allows one to transparently issue requests. * @@ -1229,10 +1568,11 @@ declare module 'http' { * upload a file with a POST request, then write to the `ClientRequest` object. * * ```js - * const http = require('http'); + * import http from 'node:http'; + * import { Buffer } from 'node:buffer'; * * const postData = JSON.stringify({ - * 'msg': 'Hello World!' + * 'msg': 'Hello World!', * }); * * const options = { @@ -1242,8 +1582,8 @@ declare module 'http' { * method: 'POST', * headers: { * 'Content-Type': 'application/json', - * 'Content-Length': Buffer.byteLength(postData) - * } + * 'Content-Length': Buffer.byteLength(postData), + * }, * }; * * const req = http.request(options, (res) => { @@ -1330,7 +1670,7 @@ declare module 'http' { * * `'data'` any number of times, on the `res` object * * (connection closed here) * * `'aborted'` on the `res` object - * * `'error'` on the `res` object with an error with message`'Error: aborted'` and code `'ECONNRESET'`. + * * `'error'` on the `res` object with an error with message`'Error: aborted'` and code `'ECONNRESET'` * * `'close'` * * `'close'` on the `res` object * @@ -1338,7 +1678,7 @@ declare module 'http' { * events will be emitted in the following order: * * * (`req.destroy()` called here) - * * `'error'` with an error with message `'Error: socket hang up'` and code`'ECONNRESET'` + * * `'error'` with an error with message `'Error: socket hang up'` and code`'ECONNRESET'`, or the error with which `req.destroy()` was called * * `'close'` * * If `req.destroy()` is called before the connection succeeds, the following @@ -1346,7 +1686,7 @@ declare module 'http' { * * * `'socket'` * * (`req.destroy()` called here) - * * `'error'` with an error with message `'Error: socket hang up'` and code`'ECONNRESET'` + * * `'error'` with an error with message `'Error: socket hang up'` and code`'ECONNRESET'`, or the error with which `req.destroy()` was called * * `'close'` * * If `req.destroy()` is called after the response is received, the following @@ -1357,7 +1697,7 @@ declare module 'http' { * * `'data'` any number of times, on the `res` object * * (`req.destroy()` called here) * * `'aborted'` on the `res` object - * * `'error'` on the `res` object with an error with message`'Error: aborted'` and code `'ECONNRESET'`. + * * `'error'` on the `res` object with an error with message `'Error: aborted'`and code `'ECONNRESET'`, or the error with which `req.destroy()` was called * * `'close'` * * `'close'` on the `res` object * @@ -1393,8 +1733,9 @@ declare module 'http' { * Setting the `timeout` option or using the `setTimeout()` function will * not abort the request or do anything besides add a `'timeout'` event. * - * Passing an `AbortSignal` and then calling `abort` on the corresponding`AbortController` will behave the same way as calling `.destroy()` on the - * request itself. + * Passing an `AbortSignal` and then calling `abort()` on the corresponding`AbortController` will behave the same way as calling `.destroy()` on the + * request. Specifically, the `'error'` event will be emitted with an error with + * the message `'AbortError: The operation was aborted'`, the code `'ABORT_ERR'`and the `cause`, if one was provided. * @since v0.3.6 */ function request(options: RequestOptions | string | URL, callback?: (res: IncomingMessage) => void): ClientRequest; @@ -1405,8 +1746,8 @@ declare module 'http' { ): ClientRequest; /** * Since most requests are GET requests without bodies, Node.js provides this - * convenience method. The only difference between this method and {@link request} is that it sets the method to GET and calls `req.end()`automatically. The callback must take care to consume the - * response + * convenience method. The only difference between this method and {@link request} is that it sets the method to GET by default and calls `req.end()`automatically. The callback must take care to + * consume the response * data for reasons stated in {@link ClientRequest} section. * * The `callback` is invoked with a single argument that is an instance of {@link IncomingMessage}. @@ -1454,17 +1795,86 @@ declare module 'http' { * const server = http.createServer((req, res) => { * res.writeHead(200, { 'Content-Type': 'application/json' }); * res.end(JSON.stringify({ - * data: 'Hello World!' + * data: 'Hello World!', * })); * }); * * server.listen(8000); * ``` * @since v0.3.6 - * @param options Accepts the same `options` as {@link request}, with the `method` always set to `GET`. Properties that are inherited from the prototype are ignored. + * @param options Accepts the same `options` as {@link request}, with the method set to GET by default. */ function get(options: RequestOptions | string | URL, callback?: (res: IncomingMessage) => void): ClientRequest; function get(url: string | URL, options: RequestOptions, callback?: (res: IncomingMessage) => void): ClientRequest; + /** + * Performs the low-level validations on the provided `name` that are done when`res.setHeader(name, value)` is called. + * + * Passing illegal value as `name` will result in a `TypeError` being thrown, + * identified by `code: 'ERR_INVALID_HTTP_TOKEN'`. + * + * It is not necessary to use this method before passing headers to an HTTP request + * or response. The HTTP module will automatically validate such headers. + * + * Example: + * + * ```js + * import { validateHeaderName } from 'node:http'; + * + * try { + * validateHeaderName(''); + * } catch (err) { + * console.error(err instanceof TypeError); // --> true + * console.error(err.code); // --> 'ERR_INVALID_HTTP_TOKEN' + * console.error(err.message); // --> 'Header name must be a valid HTTP token [""]' + * } + * ``` + * @since v14.3.0 + * @param [label='Header name'] Label for error message. + */ + function validateHeaderName(name: string): void; + /** + * Performs the low-level validations on the provided `value` that are done when`res.setHeader(name, value)` is called. + * + * Passing illegal value as `value` will result in a `TypeError` being thrown. + * + * * Undefined value error is identified by `code: 'ERR_HTTP_INVALID_HEADER_VALUE'`. + * * Invalid value character error is identified by `code: 'ERR_INVALID_CHAR'`. + * + * It is not necessary to use this method before passing headers to an HTTP request + * or response. The HTTP module will automatically validate such headers. + * + * Examples: + * + * ```js + * import { validateHeaderValue } from 'node:http'; + * + * try { + * validateHeaderValue('x-my-header', undefined); + * } catch (err) { + * console.error(err instanceof TypeError); // --> true + * console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE'); // --> true + * console.error(err.message); // --> 'Invalid value "undefined" for header "x-my-header"' + * } + * + * try { + * validateHeaderValue('x-my-header', 'oʊmɪɡə'); + * } catch (err) { + * console.error(err instanceof TypeError); // --> true + * console.error(err.code === 'ERR_INVALID_CHAR'); // --> true + * console.error(err.message); // --> 'Invalid character in header content ["x-my-header"]' + * } + * ``` + * @since v14.3.0 + * @param name Header name + * @param value Header value + */ + function validateHeaderValue(name: string, value: string): void; + /** + * Set the maximum number of idle HTTP parsers. + * @since v18.8.0, v16.18.0 + * @param [max=1000] + */ + function setMaxIdleHTTPParsers(max: number): void; let globalAgent: Agent; /** * Read-only property specifying the maximum allowed size of HTTP headers in bytes. @@ -1472,6 +1882,6 @@ declare module 'http' { */ const maxHeaderSize: number; } -declare module 'node:http' { - export * from 'http'; +declare module "node:http" { + export * from "http"; } diff --git a/node_modules/@types/node/http2.d.ts b/node_modules/@types/node/http2.d.ts old mode 100755 new mode 100644 index f46a33e..c3b3e8e --- a/node_modules/@types/node/http2.d.ts +++ b/node_modules/@types/node/http2.d.ts @@ -1,30 +1,35 @@ /** - * The `http2` module provides an implementation of the [HTTP/2](https://tools.ietf.org/html/rfc7540) protocol. It - * can be accessed using: + * The `node:http2` module provides an implementation of the [HTTP/2](https://tools.ietf.org/html/rfc7540) protocol. + * It can be accessed using: * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * ``` * @since v8.4.0 - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/http2.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/http2.js) */ -declare module 'http2' { - import EventEmitter = require('node:events'); - import * as fs from 'node:fs'; - import * as net from 'node:net'; - import * as stream from 'node:stream'; - import * as tls from 'node:tls'; - import * as url from 'node:url'; - import { IncomingHttpHeaders as Http1IncomingHttpHeaders, OutgoingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http'; - export { OutgoingHttpHeaders } from 'node:http'; +declare module "http2" { + import EventEmitter = require("node:events"); + import * as fs from "node:fs"; + import * as net from "node:net"; + import * as stream from "node:stream"; + import * as tls from "node:tls"; + import * as url from "node:url"; + import { + IncomingHttpHeaders as Http1IncomingHttpHeaders, + IncomingMessage, + OutgoingHttpHeaders, + ServerResponse, + } from "node:http"; + export { OutgoingHttpHeaders } from "node:http"; export interface IncomingHttpStatusHeader { - ':status'?: number | undefined; + ":status"?: number | undefined; } export interface IncomingHttpHeaders extends Http1IncomingHttpHeaders { - ':path'?: string | undefined; - ':method'?: string | undefined; - ':authority'?: string | undefined; - ':scheme'?: string | undefined; + ":path"?: string | undefined; + ":method"?: string | undefined; + ":authority"?: string | undefined; + ":scheme"?: string | undefined; } // Http2Stream export interface StreamPriorityOptions { @@ -50,6 +55,7 @@ declare module 'http2' { length: number; } export interface ServerStreamFileResponseOptions { + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type statCheck?(stats: fs.Stats, headers: OutgoingHttpHeaders, statOptions: StatOptions): void | boolean; waitForTrailers?: boolean | undefined; offset?: number | undefined; @@ -83,7 +89,7 @@ declare module 'http2' { */ readonly destroyed: boolean; /** - * Set the `true` if the `END_STREAM` flag was set in the request or response + * Set to `true` if the `END_STREAM` flag was set in the request or response * HEADERS frame received, indicating that no additional data should be received * and the readable side of the `Http2Stream` will be closed. * @since v10.11.0 @@ -128,7 +134,7 @@ declare module 'http2' { * value will be `undefined` after the `Http2Stream` instance is destroyed. * @since v8.4.0 */ - readonly session: Http2Session; + readonly session: Http2Session | undefined; /** * Provides miscellaneous information about the current state of the`Http2Stream`. * @@ -151,7 +157,7 @@ declare module 'http2' { priority(options: StreamPriorityOptions): void; /** * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const client = http2.connect('http://example.org:8000'); * const { NGHTTP2_CANCEL } = http2.constants; * const req = client.request({ ':path': '/' }); @@ -171,7 +177,7 @@ declare module 'http2' { * trailers can be sent. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * stream.respond(undefined, { waitForTrailers: true }); @@ -187,127 +193,157 @@ declare module 'http2' { * @since v10.0.0 */ sendTrailers(headers: OutgoingHttpHeaders): void; - addListener(event: 'aborted', listener: () => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'end', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'finish', listener: () => void): this; - addListener(event: 'frameError', listener: (frameType: number, errorCode: number) => void): this; - addListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - addListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; - addListener(event: 'streamClosed', listener: (code: number) => void): this; - addListener(event: 'timeout', listener: () => void): this; - addListener(event: 'trailers', listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; - addListener(event: 'wantTrailers', listener: () => void): this; + addListener(event: "aborted", listener: () => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: Buffer | string) => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "frameError", listener: (frameType: number, errorCode: number) => void): this; + addListener(event: "pipe", listener: (src: stream.Readable) => void): this; + addListener(event: "unpipe", listener: (src: stream.Readable) => void): this; + addListener(event: "streamClosed", listener: (code: number) => void): this; + addListener(event: "timeout", listener: () => void): this; + addListener(event: "trailers", listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; + addListener(event: "wantTrailers", listener: () => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'aborted'): boolean; - emit(event: 'close'): boolean; - emit(event: 'data', chunk: Buffer | string): boolean; - emit(event: 'drain'): boolean; - emit(event: 'end'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'finish'): boolean; - emit(event: 'frameError', frameType: number, errorCode: number): boolean; - emit(event: 'pipe', src: stream.Readable): boolean; - emit(event: 'unpipe', src: stream.Readable): boolean; - emit(event: 'streamClosed', code: number): boolean; - emit(event: 'timeout'): boolean; - emit(event: 'trailers', trailers: IncomingHttpHeaders, flags: number): boolean; - emit(event: 'wantTrailers'): boolean; + emit(event: "aborted"): boolean; + emit(event: "close"): boolean; + emit(event: "data", chunk: Buffer | string): boolean; + emit(event: "drain"): boolean; + emit(event: "end"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "finish"): boolean; + emit(event: "frameError", frameType: number, errorCode: number): boolean; + emit(event: "pipe", src: stream.Readable): boolean; + emit(event: "unpipe", src: stream.Readable): boolean; + emit(event: "streamClosed", code: number): boolean; + emit(event: "timeout"): boolean; + emit(event: "trailers", trailers: IncomingHttpHeaders, flags: number): boolean; + emit(event: "wantTrailers"): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'aborted', listener: () => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'data', listener: (chunk: Buffer | string) => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'end', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'finish', listener: () => void): this; - on(event: 'frameError', listener: (frameType: number, errorCode: number) => void): this; - on(event: 'pipe', listener: (src: stream.Readable) => void): this; - on(event: 'unpipe', listener: (src: stream.Readable) => void): this; - on(event: 'streamClosed', listener: (code: number) => void): this; - on(event: 'timeout', listener: () => void): this; - on(event: 'trailers', listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; - on(event: 'wantTrailers', listener: () => void): this; + on(event: "aborted", listener: () => void): this; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: Buffer | string) => void): this; + on(event: "drain", listener: () => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "frameError", listener: (frameType: number, errorCode: number) => void): this; + on(event: "pipe", listener: (src: stream.Readable) => void): this; + on(event: "unpipe", listener: (src: stream.Readable) => void): this; + on(event: "streamClosed", listener: (code: number) => void): this; + on(event: "timeout", listener: () => void): this; + on(event: "trailers", listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; + on(event: "wantTrailers", listener: () => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'aborted', listener: () => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'data', listener: (chunk: Buffer | string) => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'end', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'finish', listener: () => void): this; - once(event: 'frameError', listener: (frameType: number, errorCode: number) => void): this; - once(event: 'pipe', listener: (src: stream.Readable) => void): this; - once(event: 'unpipe', listener: (src: stream.Readable) => void): this; - once(event: 'streamClosed', listener: (code: number) => void): this; - once(event: 'timeout', listener: () => void): this; - once(event: 'trailers', listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; - once(event: 'wantTrailers', listener: () => void): this; + once(event: "aborted", listener: () => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: Buffer | string) => void): this; + once(event: "drain", listener: () => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "frameError", listener: (frameType: number, errorCode: number) => void): this; + once(event: "pipe", listener: (src: stream.Readable) => void): this; + once(event: "unpipe", listener: (src: stream.Readable) => void): this; + once(event: "streamClosed", listener: (code: number) => void): this; + once(event: "timeout", listener: () => void): this; + once(event: "trailers", listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; + once(event: "wantTrailers", listener: () => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'aborted', listener: () => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'end', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'finish', listener: () => void): this; - prependListener(event: 'frameError', listener: (frameType: number, errorCode: number) => void): this; - prependListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; - prependListener(event: 'streamClosed', listener: (code: number) => void): this; - prependListener(event: 'timeout', listener: () => void): this; - prependListener(event: 'trailers', listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; - prependListener(event: 'wantTrailers', listener: () => void): this; + prependListener(event: "aborted", listener: () => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "frameError", listener: (frameType: number, errorCode: number) => void): this; + prependListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependListener(event: "unpipe", listener: (src: stream.Readable) => void): this; + prependListener(event: "streamClosed", listener: (code: number) => void): this; + prependListener(event: "timeout", listener: () => void): this; + prependListener(event: "trailers", listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; + prependListener(event: "wantTrailers", listener: () => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'aborted', listener: () => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'end', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'finish', listener: () => void): this; - prependOnceListener(event: 'frameError', listener: (frameType: number, errorCode: number) => void): this; - prependOnceListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependOnceListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; - prependOnceListener(event: 'streamClosed', listener: (code: number) => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; - prependOnceListener(event: 'trailers', listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; - prependOnceListener(event: 'wantTrailers', listener: () => void): this; + prependOnceListener(event: "aborted", listener: () => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "frameError", listener: (frameType: number, errorCode: number) => void): this; + prependOnceListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "unpipe", listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "streamClosed", listener: (code: number) => void): this; + prependOnceListener(event: "timeout", listener: () => void): this; + prependOnceListener(event: "trailers", listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; + prependOnceListener(event: "wantTrailers", listener: () => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export interface ClientHttp2Stream extends Http2Stream { - addListener(event: 'continue', listener: () => {}): this; - addListener(event: 'headers', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; - addListener(event: 'push', listener: (headers: IncomingHttpHeaders, flags: number) => void): this; - addListener(event: 'response', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + addListener(event: "continue", listener: () => {}): this; + addListener( + event: "headers", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; + addListener(event: "push", listener: (headers: IncomingHttpHeaders, flags: number) => void): this; + addListener( + event: "response", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'continue'): boolean; - emit(event: 'headers', headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number): boolean; - emit(event: 'push', headers: IncomingHttpHeaders, flags: number): boolean; - emit(event: 'response', headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number): boolean; + emit(event: "continue"): boolean; + emit(event: "headers", headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number): boolean; + emit(event: "push", headers: IncomingHttpHeaders, flags: number): boolean; + emit(event: "response", headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'continue', listener: () => {}): this; - on(event: 'headers', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; - on(event: 'push', listener: (headers: IncomingHttpHeaders, flags: number) => void): this; - on(event: 'response', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + on(event: "continue", listener: () => {}): this; + on( + event: "headers", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; + on(event: "push", listener: (headers: IncomingHttpHeaders, flags: number) => void): this; + on( + event: "response", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'continue', listener: () => {}): this; - once(event: 'headers', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; - once(event: 'push', listener: (headers: IncomingHttpHeaders, flags: number) => void): this; - once(event: 'response', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + once(event: "continue", listener: () => {}): this; + once( + event: "headers", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; + once(event: "push", listener: (headers: IncomingHttpHeaders, flags: number) => void): this; + once( + event: "response", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'continue', listener: () => {}): this; - prependListener(event: 'headers', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; - prependListener(event: 'push', listener: (headers: IncomingHttpHeaders, flags: number) => void): this; - prependListener(event: 'response', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + prependListener(event: "continue", listener: () => {}): this; + prependListener( + event: "headers", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; + prependListener(event: "push", listener: (headers: IncomingHttpHeaders, flags: number) => void): this; + prependListener( + event: "response", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'continue', listener: () => {}): this; - prependOnceListener(event: 'headers', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; - prependOnceListener(event: 'push', listener: (headers: IncomingHttpHeaders, flags: number) => void): this; - prependOnceListener(event: 'response', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + prependOnceListener(event: "continue", listener: () => {}): this; + prependOnceListener( + event: "headers", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; + prependOnceListener(event: "push", listener: (headers: IncomingHttpHeaders, flags: number) => void): this; + prependOnceListener( + event: "response", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export interface ServerHttp2Stream extends Http2Stream { @@ -332,7 +368,7 @@ declare module 'http2' { * Initiates a push stream. The callback is invoked with the new `Http2Stream`instance created for the push stream passed as the second argument, or an`Error` passed as the first argument. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * stream.respond({ ':status': 200 }); @@ -353,11 +389,18 @@ declare module 'http2' { * @since v8.4.0 * @param callback Callback that is called once the push stream has been initiated. */ - pushStream(headers: OutgoingHttpHeaders, callback?: (err: Error | null, pushStream: ServerHttp2Stream, headers: OutgoingHttpHeaders) => void): void; - pushStream(headers: OutgoingHttpHeaders, options?: StreamPriorityOptions, callback?: (err: Error | null, pushStream: ServerHttp2Stream, headers: OutgoingHttpHeaders) => void): void; + pushStream( + headers: OutgoingHttpHeaders, + callback?: (err: Error | null, pushStream: ServerHttp2Stream, headers: OutgoingHttpHeaders) => void, + ): void; + pushStream( + headers: OutgoingHttpHeaders, + options?: StreamPriorityOptions, + callback?: (err: Error | null, pushStream: ServerHttp2Stream, headers: OutgoingHttpHeaders) => void, + ): void; /** * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * stream.respond({ ':status': 200 }); @@ -365,16 +408,15 @@ declare module 'http2' { * }); * ``` * - * When the `options.waitForTrailers` option is set, the `'wantTrailers'` event - * will be emitted immediately after queuing the last chunk of payload data to be - * sent. The `http2stream.sendTrailers()` method can then be used to sent trailing - * header fields to the peer. + * Initiates a response. When the `options.waitForTrailers` option is set, the`'wantTrailers'` event will be emitted immediately after queuing the last chunk + * of payload data to be sent. The `http2stream.sendTrailers()` method can then be + * used to sent trailing header fields to the peer. * * When `options.waitForTrailers` is set, the `Http2Stream` will not automatically * close when the final `DATA` frame is transmitted. User code must call either`http2stream.sendTrailers()` or `http2stream.close()` to close the`Http2Stream`. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * stream.respond({ ':status': 200 }, { waitForTrailers: true }); @@ -397,8 +439,8 @@ declare module 'http2' { * automatically. * * ```js - * const http2 = require('http2'); - * const fs = require('fs'); + * const http2 = require('node:http2'); + * const fs = require('node:fs'); * * const server = http2.createServer(); * server.on('stream', (stream) => { @@ -408,7 +450,7 @@ declare module 'http2' { * const headers = { * 'content-length': stat.size, * 'last-modified': stat.mtime.toUTCString(), - * 'content-type': 'text/plain; charset=utf-8' + * 'content-type': 'text/plain; charset=utf-8', * }; * stream.respondWithFD(fd, headers); * stream.on('close', () => fs.closeSync(fd)); @@ -439,8 +481,8 @@ declare module 'http2' { * close when the final `DATA` frame is transmitted. User code _must_ call either`http2stream.sendTrailers()` or `http2stream.close()` to close the`Http2Stream`. * * ```js - * const http2 = require('http2'); - * const fs = require('fs'); + * const http2 = require('node:http2'); + * const fs = require('node:fs'); * * const server = http2.createServer(); * server.on('stream', (stream) => { @@ -450,7 +492,7 @@ declare module 'http2' { * const headers = { * 'content-length': stat.size, * 'last-modified': stat.mtime.toUTCString(), - * 'content-type': 'text/plain; charset=utf-8' + * 'content-type': 'text/plain; charset=utf-8', * }; * stream.respondWithFD(fd, headers, { waitForTrailers: true }); * stream.on('wantTrailers', () => { @@ -463,7 +505,11 @@ declare module 'http2' { * @since v8.4.0 * @param fd A readable file descriptor. */ - respondWithFD(fd: number | fs.promises.FileHandle, headers?: OutgoingHttpHeaders, options?: ServerStreamFileResponseOptions): void; + respondWithFD( + fd: number | fs.promises.FileHandle, + headers?: OutgoingHttpHeaders, + options?: ServerStreamFileResponseOptions, + ): void; /** * Sends a regular file as the response. The `path` must specify a regular file * or an `'error'` event will be emitted on the `Http2Stream` object. @@ -482,7 +528,7 @@ declare module 'http2' { * Example using a file path: * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * function statCheck(stat, headers) { @@ -500,7 +546,7 @@ declare module 'http2' { * } * } catch (err) { * // Perform actual error handling. - * console.log(err); + * console.error(err); * } * stream.end(); * } @@ -516,7 +562,7 @@ declare module 'http2' { * results to determine if the file has been modified to return an appropriate`304` response: * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * function statCheck(stat, headers) { @@ -549,7 +595,7 @@ declare module 'http2' { * close when the final `DATA` frame is transmitted. User code must call either`http2stream.sendTrailers()` or `http2stream.close()` to close the`Http2Stream`. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * stream.respondWithFile('/some/file', @@ -562,7 +608,11 @@ declare module 'http2' { * ``` * @since v8.4.0 */ - respondWithFile(path: string, headers?: OutgoingHttpHeaders, options?: ServerStreamFileResponseOptionsWithError): void; + respondWithFile( + path: string, + headers?: OutgoingHttpHeaders, + options?: ServerStreamFileResponseOptionsWithError, + ): void; } // Http2Session export interface Settings { @@ -736,7 +786,10 @@ declare module 'http2' { * @param payload Optional ping payload. */ ping(callback: (err: Error | null, duration: number, payload: Buffer) => void): boolean; - ping(payload: NodeJS.ArrayBufferView, callback: (err: Error | null, duration: number, payload: Buffer) => void): boolean; + ping( + payload: NodeJS.ArrayBufferView, + callback: (err: Error | null, duration: number, payload: Buffer) => void, + ): boolean; /** * Calls `ref()` on this `Http2Session`instance's underlying `net.Socket`. * @since v9.4.0 @@ -748,7 +801,7 @@ declare module 'http2' { * the delta. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * * const server = http2.createServer(); * const expectedWindowSize = 2 ** 20; @@ -758,7 +811,7 @@ declare module 'http2' { * session.setLocalWindowSize(expectedWindowSize); * }); * ``` - * @since v15.3.0 + * @since v15.3.0, v14.18.0 */ setLocalWindowSize(windowSize: number): void; /** @@ -780,65 +833,86 @@ declare module 'http2' { * @since v8.4.0 * @param callback Callback that is called once the session is connected or right away if the session is already connected. */ - settings(settings: Settings, callback?: (err: Error | null, settings: Settings, duration: number) => void): void; + settings( + settings: Settings, + callback?: (err: Error | null, settings: Settings, duration: number) => void, + ): void; /** * Calls `unref()` on this `Http2Session`instance's underlying `net.Socket`. * @since v9.4.0 */ unref(): void; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'frameError', listener: (frameType: number, errorCode: number, streamID: number) => void): this; - addListener(event: 'goaway', listener: (errorCode: number, lastStreamID: number, opaqueData: Buffer) => void): this; - addListener(event: 'localSettings', listener: (settings: Settings) => void): this; - addListener(event: 'ping', listener: () => void): this; - addListener(event: 'remoteSettings', listener: (settings: Settings) => void): this; - addListener(event: 'timeout', listener: () => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener( + event: "frameError", + listener: (frameType: number, errorCode: number, streamID: number) => void, + ): this; + addListener( + event: "goaway", + listener: (errorCode: number, lastStreamID: number, opaqueData?: Buffer) => void, + ): this; + addListener(event: "localSettings", listener: (settings: Settings) => void): this; + addListener(event: "ping", listener: () => void): this; + addListener(event: "remoteSettings", listener: (settings: Settings) => void): this; + addListener(event: "timeout", listener: () => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'close'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'frameError', frameType: number, errorCode: number, streamID: number): boolean; - emit(event: 'goaway', errorCode: number, lastStreamID: number, opaqueData: Buffer): boolean; - emit(event: 'localSettings', settings: Settings): boolean; - emit(event: 'ping'): boolean; - emit(event: 'remoteSettings', settings: Settings): boolean; - emit(event: 'timeout'): boolean; + emit(event: "close"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "frameError", frameType: number, errorCode: number, streamID: number): boolean; + emit(event: "goaway", errorCode: number, lastStreamID: number, opaqueData?: Buffer): boolean; + emit(event: "localSettings", settings: Settings): boolean; + emit(event: "ping"): boolean; + emit(event: "remoteSettings", settings: Settings): boolean; + emit(event: "timeout"): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'close', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'frameError', listener: (frameType: number, errorCode: number, streamID: number) => void): this; - on(event: 'goaway', listener: (errorCode: number, lastStreamID: number, opaqueData: Buffer) => void): this; - on(event: 'localSettings', listener: (settings: Settings) => void): this; - on(event: 'ping', listener: () => void): this; - on(event: 'remoteSettings', listener: (settings: Settings) => void): this; - on(event: 'timeout', listener: () => void): this; + on(event: "close", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "frameError", listener: (frameType: number, errorCode: number, streamID: number) => void): this; + on(event: "goaway", listener: (errorCode: number, lastStreamID: number, opaqueData?: Buffer) => void): this; + on(event: "localSettings", listener: (settings: Settings) => void): this; + on(event: "ping", listener: () => void): this; + on(event: "remoteSettings", listener: (settings: Settings) => void): this; + on(event: "timeout", listener: () => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'frameError', listener: (frameType: number, errorCode: number, streamID: number) => void): this; - once(event: 'goaway', listener: (errorCode: number, lastStreamID: number, opaqueData: Buffer) => void): this; - once(event: 'localSettings', listener: (settings: Settings) => void): this; - once(event: 'ping', listener: () => void): this; - once(event: 'remoteSettings', listener: (settings: Settings) => void): this; - once(event: 'timeout', listener: () => void): this; + once(event: "close", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "frameError", listener: (frameType: number, errorCode: number, streamID: number) => void): this; + once(event: "goaway", listener: (errorCode: number, lastStreamID: number, opaqueData?: Buffer) => void): this; + once(event: "localSettings", listener: (settings: Settings) => void): this; + once(event: "ping", listener: () => void): this; + once(event: "remoteSettings", listener: (settings: Settings) => void): this; + once(event: "timeout", listener: () => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'frameError', listener: (frameType: number, errorCode: number, streamID: number) => void): this; - prependListener(event: 'goaway', listener: (errorCode: number, lastStreamID: number, opaqueData: Buffer) => void): this; - prependListener(event: 'localSettings', listener: (settings: Settings) => void): this; - prependListener(event: 'ping', listener: () => void): this; - prependListener(event: 'remoteSettings', listener: (settings: Settings) => void): this; - prependListener(event: 'timeout', listener: () => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener( + event: "frameError", + listener: (frameType: number, errorCode: number, streamID: number) => void, + ): this; + prependListener( + event: "goaway", + listener: (errorCode: number, lastStreamID: number, opaqueData?: Buffer) => void, + ): this; + prependListener(event: "localSettings", listener: (settings: Settings) => void): this; + prependListener(event: "ping", listener: () => void): this; + prependListener(event: "remoteSettings", listener: (settings: Settings) => void): this; + prependListener(event: "timeout", listener: () => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'frameError', listener: (frameType: number, errorCode: number, streamID: number) => void): this; - prependOnceListener(event: 'goaway', listener: (errorCode: number, lastStreamID: number, opaqueData: Buffer) => void): this; - prependOnceListener(event: 'localSettings', listener: (settings: Settings) => void): this; - prependOnceListener(event: 'ping', listener: () => void): this; - prependOnceListener(event: 'remoteSettings', listener: (settings: Settings) => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener( + event: "frameError", + listener: (frameType: number, errorCode: number, streamID: number) => void, + ): this; + prependOnceListener( + event: "goaway", + listener: (errorCode: number, lastStreamID: number, opaqueData?: Buffer) => void, + ): this; + prependOnceListener(event: "localSettings", listener: (settings: Settings) => void): this; + prependOnceListener(event: "ping", listener: () => void): this; + prependOnceListener(event: "remoteSettings", listener: (settings: Settings) => void): this; + prependOnceListener(event: "timeout", listener: () => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export interface ClientHttp2Session extends Http2Session { @@ -846,14 +920,19 @@ declare module 'http2' { * For HTTP/2 Client `Http2Session` instances only, the `http2session.request()`creates and returns an `Http2Stream` instance that can be used to send an * HTTP/2 request to the connected server. * + * When a `ClientHttp2Session` is first created, the socket may not yet be + * connected. if `clienthttp2session.request()` is called during this time, the + * actual request will be deferred until the socket is ready to go. + * If the `session` is closed before the actual request be executed, an`ERR_HTTP2_GOAWAY_SESSION` is thrown. + * * This method is only available if `http2session.type` is equal to`http2.constants.NGHTTP2_SESSION_CLIENT`. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const clientSession = http2.connect('https://localhost:1234'); * const { * HTTP2_HEADER_PATH, - * HTTP2_HEADER_STATUS + * HTTP2_HEADER_STATUS, * } = http2.constants; * * const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' }); @@ -883,35 +962,87 @@ declare module 'http2' { * @since v8.4.0 */ request(headers?: OutgoingHttpHeaders, options?: ClientSessionRequestOptions): ClientHttp2Stream; - addListener(event: 'altsvc', listener: (alt: string, origin: string, stream: number) => void): this; - addListener(event: 'origin', listener: (origins: string[]) => void): this; - addListener(event: 'connect', listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - addListener(event: 'stream', listener: (stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + addListener(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; + addListener(event: "origin", listener: (origins: string[]) => void): this; + addListener( + event: "connect", + listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + addListener( + event: "stream", + listener: ( + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ) => void, + ): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'altsvc', alt: string, origin: string, stream: number): boolean; - emit(event: 'origin', origins: ReadonlyArray): boolean; - emit(event: 'connect', session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket): boolean; - emit(event: 'stream', stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number): boolean; + emit(event: "altsvc", alt: string, origin: string, stream: number): boolean; + emit(event: "origin", origins: readonly string[]): boolean; + emit(event: "connect", session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket): boolean; + emit( + event: "stream", + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'altsvc', listener: (alt: string, origin: string, stream: number) => void): this; - on(event: 'origin', listener: (origins: string[]) => void): this; - on(event: 'connect', listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - on(event: 'stream', listener: (stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + on(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; + on(event: "origin", listener: (origins: string[]) => void): this; + on(event: "connect", listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; + on( + event: "stream", + listener: ( + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ) => void, + ): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'altsvc', listener: (alt: string, origin: string, stream: number) => void): this; - once(event: 'origin', listener: (origins: string[]) => void): this; - once(event: 'connect', listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - once(event: 'stream', listener: (stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + once(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; + once(event: "origin", listener: (origins: string[]) => void): this; + once( + event: "connect", + listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + once( + event: "stream", + listener: ( + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ) => void, + ): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'altsvc', listener: (alt: string, origin: string, stream: number) => void): this; - prependListener(event: 'origin', listener: (origins: string[]) => void): this; - prependListener(event: 'connect', listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - prependListener(event: 'stream', listener: (stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + prependListener(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; + prependListener(event: "origin", listener: (origins: string[]) => void): this; + prependListener( + event: "connect", + listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + prependListener( + event: "stream", + listener: ( + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ) => void, + ): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'altsvc', listener: (alt: string, origin: string, stream: number) => void): this; - prependOnceListener(event: 'origin', listener: (origins: string[]) => void): this; - prependOnceListener(event: 'connect', listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - prependOnceListener(event: 'stream', listener: (stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + prependOnceListener(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; + prependOnceListener(event: "origin", listener: (origins: string[]) => void): this; + prependOnceListener( + event: "connect", + listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + prependOnceListener( + event: "stream", + listener: ( + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ) => void, + ): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export interface AlternativeServiceOptions { @@ -923,7 +1054,7 @@ declare module 'http2' { * Submits an `ALTSVC` frame (as defined by [RFC 7838](https://tools.ietf.org/html/rfc7838)) to the connected client. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * * const server = http2.createServer(); * server.on('session', (session) => { @@ -964,7 +1095,7 @@ declare module 'http2' { * authoritative responses. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const options = getSecureOptionsSomehow(); * const server = http2.createSecureServer(options); * server.on('stream', (stream) => { @@ -990,7 +1121,7 @@ declare module 'http2' { * server using the `http2.createSecureServer()` method: * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const options = getSecureOptionsSomehow(); * options.origins = ['https://example.com', 'https://example.org']; * const server = http2.createSecureServer(options); @@ -1007,27 +1138,54 @@ declare module 'http2' { | string | url.URL | { - origin: string; - } + origin: string; + } > ): void; - addListener(event: 'connect', listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - addListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; + addListener( + event: "connect", + listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + addListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'connect', session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket): boolean; - emit(event: 'stream', stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; + emit(event: "connect", session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket): boolean; + emit(event: "stream", stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'connect', listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - on(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; + on(event: "connect", listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; + on( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'connect', listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - once(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; + once( + event: "connect", + listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + once( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'connect', listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - prependListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; + prependListener( + event: "connect", + listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + prependListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'connect', listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - prependOnceListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; + prependOnceListener( + event: "connect", + listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + prependOnceListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } // Http2Server @@ -1048,12 +1206,11 @@ declare module 'http2' { */ unknownProtocolTimeout?: number | undefined; selectPadding?(frameLen: number, maxFrameLen: number): number; - createConnection?(authority: url.URL, option: SessionOptions): stream.Duplex; } export interface ClientSessionOptions extends SessionOptions { maxReservedRemoteStreams?: number | undefined; createConnection?: ((authority: url.URL, option: SessionOptions) => stream.Duplex) | undefined; - protocol?: 'http:' | 'https:' | undefined; + protocol?: "http:" | "https:" | undefined; } export interface ServerSessionOptions extends SessionOptions { Http1IncomingMessage?: typeof IncomingMessage | undefined; @@ -1077,97 +1234,175 @@ declare module 'http2' { updateSettings(settings: Settings): void; } export interface Http2Server extends net.Server, HTTP2ServerCommon { - addListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - addListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - addListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - addListener(event: 'sessionError', listener: (err: Error) => void): this; - addListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - addListener(event: 'timeout', listener: () => void): this; + addListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + addListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + addListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + addListener(event: "sessionError", listener: (err: Error) => void): this; + addListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + addListener(event: "timeout", listener: () => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'checkContinue', request: Http2ServerRequest, response: Http2ServerResponse): boolean; - emit(event: 'request', request: Http2ServerRequest, response: Http2ServerResponse): boolean; - emit(event: 'session', session: ServerHttp2Session): boolean; - emit(event: 'sessionError', err: Error): boolean; - emit(event: 'stream', stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; - emit(event: 'timeout'): boolean; + emit(event: "checkContinue", request: Http2ServerRequest, response: Http2ServerResponse): boolean; + emit(event: "request", request: Http2ServerRequest, response: Http2ServerResponse): boolean; + emit(event: "session", session: ServerHttp2Session): boolean; + emit(event: "sessionError", err: Error): boolean; + emit(event: "stream", stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; + emit(event: "timeout"): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - on(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - on(event: 'session', listener: (session: ServerHttp2Session) => void): this; - on(event: 'sessionError', listener: (err: Error) => void): this; - on(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - on(event: 'timeout', listener: () => void): this; + on( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + on(event: "request", listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; + on(event: "session", listener: (session: ServerHttp2Session) => void): this; + on(event: "sessionError", listener: (err: Error) => void): this; + on( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + on(event: "timeout", listener: () => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - once(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - once(event: 'session', listener: (session: ServerHttp2Session) => void): this; - once(event: 'sessionError', listener: (err: Error) => void): this; - once(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - once(event: 'timeout', listener: () => void): this; + once( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + once(event: "request", listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; + once(event: "session", listener: (session: ServerHttp2Session) => void): this; + once(event: "sessionError", listener: (err: Error) => void): this; + once( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + once(event: "timeout", listener: () => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - prependListener(event: 'sessionError', listener: (err: Error) => void): this; - prependListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - prependListener(event: 'timeout', listener: () => void): this; + prependListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + prependListener(event: "sessionError", listener: (err: Error) => void): this; + prependListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + prependListener(event: "timeout", listener: () => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependOnceListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependOnceListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - prependOnceListener(event: 'sessionError', listener: (err: Error) => void): this; - prependOnceListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; + prependOnceListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependOnceListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependOnceListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + prependOnceListener(event: "sessionError", listener: (err: Error) => void): this; + prependOnceListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + prependOnceListener(event: "timeout", listener: () => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export interface Http2SecureServer extends tls.Server, HTTP2ServerCommon { - addListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - addListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - addListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - addListener(event: 'sessionError', listener: (err: Error) => void): this; - addListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - addListener(event: 'timeout', listener: () => void): this; - addListener(event: 'unknownProtocol', listener: (socket: tls.TLSSocket) => void): this; + addListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + addListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + addListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + addListener(event: "sessionError", listener: (err: Error) => void): this; + addListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + addListener(event: "timeout", listener: () => void): this; + addListener(event: "unknownProtocol", listener: (socket: tls.TLSSocket) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'checkContinue', request: Http2ServerRequest, response: Http2ServerResponse): boolean; - emit(event: 'request', request: Http2ServerRequest, response: Http2ServerResponse): boolean; - emit(event: 'session', session: ServerHttp2Session): boolean; - emit(event: 'sessionError', err: Error): boolean; - emit(event: 'stream', stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; - emit(event: 'timeout'): boolean; - emit(event: 'unknownProtocol', socket: tls.TLSSocket): boolean; + emit(event: "checkContinue", request: Http2ServerRequest, response: Http2ServerResponse): boolean; + emit(event: "request", request: Http2ServerRequest, response: Http2ServerResponse): boolean; + emit(event: "session", session: ServerHttp2Session): boolean; + emit(event: "sessionError", err: Error): boolean; + emit(event: "stream", stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; + emit(event: "timeout"): boolean; + emit(event: "unknownProtocol", socket: tls.TLSSocket): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - on(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - on(event: 'session', listener: (session: ServerHttp2Session) => void): this; - on(event: 'sessionError', listener: (err: Error) => void): this; - on(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - on(event: 'timeout', listener: () => void): this; - on(event: 'unknownProtocol', listener: (socket: tls.TLSSocket) => void): this; + on( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + on(event: "request", listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; + on(event: "session", listener: (session: ServerHttp2Session) => void): this; + on(event: "sessionError", listener: (err: Error) => void): this; + on( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + on(event: "timeout", listener: () => void): this; + on(event: "unknownProtocol", listener: (socket: tls.TLSSocket) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - once(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - once(event: 'session', listener: (session: ServerHttp2Session) => void): this; - once(event: 'sessionError', listener: (err: Error) => void): this; - once(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - once(event: 'timeout', listener: () => void): this; - once(event: 'unknownProtocol', listener: (socket: tls.TLSSocket) => void): this; + once( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + once(event: "request", listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; + once(event: "session", listener: (session: ServerHttp2Session) => void): this; + once(event: "sessionError", listener: (err: Error) => void): this; + once( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + once(event: "timeout", listener: () => void): this; + once(event: "unknownProtocol", listener: (socket: tls.TLSSocket) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - prependListener(event: 'sessionError', listener: (err: Error) => void): this; - prependListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - prependListener(event: 'timeout', listener: () => void): this; - prependListener(event: 'unknownProtocol', listener: (socket: tls.TLSSocket) => void): this; + prependListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + prependListener(event: "sessionError", listener: (err: Error) => void): this; + prependListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + prependListener(event: "timeout", listener: () => void): this; + prependListener(event: "unknownProtocol", listener: (socket: tls.TLSSocket) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependOnceListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependOnceListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - prependOnceListener(event: 'sessionError', listener: (err: Error) => void): this; - prependOnceListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; - prependOnceListener(event: 'unknownProtocol', listener: (socket: tls.TLSSocket) => void): this; + prependOnceListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependOnceListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependOnceListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + prependOnceListener(event: "sessionError", listener: (err: Error) => void): this; + prependOnceListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + prependOnceListener(event: "timeout", listener: () => void): this; + prependOnceListener(event: "unknownProtocol", listener: (socket: tls.TLSSocket) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } /** @@ -1177,7 +1412,12 @@ declare module 'http2' { * @since v8.4.0 */ export class Http2ServerRequest extends stream.Readable { - constructor(stream: ServerHttp2Stream, headers: IncomingHttpHeaders, options: stream.ReadableOptions, rawHeaders: ReadonlyArray); + constructor( + stream: ServerHttp2Stream, + headers: IncomingHttpHeaders, + options: stream.ReadableOptions, + rawHeaders: readonly string[], + ); /** * The `request.aborted` property will be `true` if the request has * been aborted. @@ -1363,47 +1603,47 @@ declare module 'http2' { */ setTimeout(msecs: number, callback?: () => void): void; read(size?: number): Buffer | string | null; - addListener(event: 'aborted', listener: (hadError: boolean, code: number) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - addListener(event: 'end', listener: () => void): this; - addListener(event: 'readable', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; + addListener(event: "aborted", listener: (hadError: boolean, code: number) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: Buffer | string) => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "readable", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'aborted', hadError: boolean, code: number): boolean; - emit(event: 'close'): boolean; - emit(event: 'data', chunk: Buffer | string): boolean; - emit(event: 'end'): boolean; - emit(event: 'readable'): boolean; - emit(event: 'error', err: Error): boolean; + emit(event: "aborted", hadError: boolean, code: number): boolean; + emit(event: "close"): boolean; + emit(event: "data", chunk: Buffer | string): boolean; + emit(event: "end"): boolean; + emit(event: "readable"): boolean; + emit(event: "error", err: Error): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'aborted', listener: (hadError: boolean, code: number) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'data', listener: (chunk: Buffer | string) => void): this; - on(event: 'end', listener: () => void): this; - on(event: 'readable', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; + on(event: "aborted", listener: (hadError: boolean, code: number) => void): this; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: Buffer | string) => void): this; + on(event: "end", listener: () => void): this; + on(event: "readable", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'aborted', listener: (hadError: boolean, code: number) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'data', listener: (chunk: Buffer | string) => void): this; - once(event: 'end', listener: () => void): this; - once(event: 'readable', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; + once(event: "aborted", listener: (hadError: boolean, code: number) => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: Buffer | string) => void): this; + once(event: "end", listener: () => void): this; + once(event: "readable", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'aborted', listener: (hadError: boolean, code: number) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependListener(event: 'end', listener: () => void): this; - prependListener(event: 'readable', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; + prependListener(event: "aborted", listener: (hadError: boolean, code: number) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "readable", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'aborted', listener: (hadError: boolean, code: number) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependOnceListener(event: 'end', listener: () => void): this; - prependOnceListener(event: 'readable', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; + prependOnceListener(event: "aborted", listener: (hadError: boolean, code: number) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "readable", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } /** @@ -1432,7 +1672,7 @@ declare module 'http2' { */ readonly headersSent: boolean; /** - * A reference to the original HTTP2 request object. + * A reference to the original HTTP2 `request` object. * @since v15.7.0 */ readonly req: Http2ServerRequest; @@ -1453,7 +1693,7 @@ declare module 'http2' { * All other interactions will be routed directly to the socket. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer((req, res) => { * const ip = req.socket.remoteAddress; * const port = req.socket.remotePort; @@ -1496,7 +1736,7 @@ declare module 'http2' { * an empty string. * @since v8.4.0 */ - statusMessage: ''; + statusMessage: ""; /** * This method adds HTTP trailing headers (a header but at the end of the * message) to the response. @@ -1617,7 +1857,7 @@ declare module 'http2' { * ``` * @since v8.4.0 */ - setHeader(name: string, value: number | string | ReadonlyArray): void; + setHeader(name: string, value: number | string | readonly string[]): void; /** * Sets the `Http2Stream`'s timeout value to `msecs`. If a callback is * provided, then it is added as a listener on the `'timeout'` event on @@ -1636,8 +1876,8 @@ declare module 'http2' { * This sends a chunk of the response body. This method may * be called multiple times to provide successive parts of the body. * - * In the `http` module, the response body is omitted when the - * request is a HEAD request. Similarly, the `204` and `304` responses_must not_ include a message body. + * In the `node:http` module, the response body is omitted when the + * request is a HEAD request. Similarly, the `204` and `304` responses _must not_ include a message body. * * `chunk` can be a string or a buffer. If `chunk` is a string, * the second parameter specifies how to encode it into a byte stream. @@ -1665,6 +1905,31 @@ declare module 'http2' { * @since v8.4.0 */ writeContinue(): void; + /** + * Sends a status `103 Early Hints` to the client with a Link header, + * indicating that the user agent can preload/preconnect the linked resources. + * The `hints` is an object containing the values of headers to be sent with + * early hints message. + * + * **Example** + * + * ```js + * const earlyHintsLink = '; rel=preload; as=style'; + * response.writeEarlyHints({ + * 'link': earlyHintsLink, + * }); + * + * const earlyHintsLinks = [ + * '; rel=preload; as=style', + * '; rel=preload; as=script', + * ]; + * response.writeEarlyHints({ + * 'link': earlyHintsLinks, + * }); + * ``` + * @since v18.11.0 + */ + writeEarlyHints(hints: Record): void; /** * Sends a response header to the request. The status code is a 3-digit HTTP * status code, like `404`. The last argument, `headers`, are the response headers. @@ -1724,48 +1989,51 @@ declare module 'http2' { * @param callback Called once `http2stream.pushStream()` is finished, or either when the attempt to create the pushed `Http2Stream` has failed or has been rejected, or the state of * `Http2ServerRequest` is closed prior to calling the `http2stream.pushStream()` method */ - createPushResponse(headers: OutgoingHttpHeaders, callback: (err: Error | null, res: Http2ServerResponse) => void): void; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'error', listener: (error: Error) => void): this; - addListener(event: 'finish', listener: () => void): this; - addListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - addListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + createPushResponse( + headers: OutgoingHttpHeaders, + callback: (err: Error | null, res: Http2ServerResponse) => void, + ): void; + addListener(event: "close", listener: () => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "error", listener: (error: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "pipe", listener: (src: stream.Readable) => void): this; + addListener(event: "unpipe", listener: (src: stream.Readable) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'close'): boolean; - emit(event: 'drain'): boolean; - emit(event: 'error', error: Error): boolean; - emit(event: 'finish'): boolean; - emit(event: 'pipe', src: stream.Readable): boolean; - emit(event: 'unpipe', src: stream.Readable): boolean; + emit(event: "close"): boolean; + emit(event: "drain"): boolean; + emit(event: "error", error: Error): boolean; + emit(event: "finish"): boolean; + emit(event: "pipe", src: stream.Readable): boolean; + emit(event: "unpipe", src: stream.Readable): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'close', listener: () => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'error', listener: (error: Error) => void): this; - on(event: 'finish', listener: () => void): this; - on(event: 'pipe', listener: (src: stream.Readable) => void): this; - on(event: 'unpipe', listener: (src: stream.Readable) => void): this; + on(event: "close", listener: () => void): this; + on(event: "drain", listener: () => void): this; + on(event: "error", listener: (error: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "pipe", listener: (src: stream.Readable) => void): this; + on(event: "unpipe", listener: (src: stream.Readable) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'error', listener: (error: Error) => void): this; - once(event: 'finish', listener: () => void): this; - once(event: 'pipe', listener: (src: stream.Readable) => void): this; - once(event: 'unpipe', listener: (src: stream.Readable) => void): this; + once(event: "close", listener: () => void): this; + once(event: "drain", listener: () => void): this; + once(event: "error", listener: (error: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "pipe", listener: (src: stream.Readable) => void): this; + once(event: "unpipe", listener: (src: stream.Readable) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'error', listener: (error: Error) => void): this; - prependListener(event: 'finish', listener: () => void): this; - prependListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "error", listener: (error: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'error', listener: (error: Error) => void): this; - prependOnceListener(event: 'finish', listener: () => void): this; - prependOnceListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependOnceListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "error", listener: (error: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export namespace constants { @@ -1995,7 +2263,7 @@ declare module 'http2' { * for use with the `HTTP2-Settings` header field. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * * const packed = http2.getPackedSettings({ enablePush: false }); * @@ -2020,7 +2288,7 @@ declare module 'http2' { * with browser clients. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * * // Create an unencrypted HTTP/2 server. * // Since there are no browsers known that support @@ -2031,28 +2299,33 @@ declare module 'http2' { * server.on('stream', (stream, headers) => { * stream.respond({ * 'content-type': 'text/html; charset=utf-8', - * ':status': 200 + * ':status': 200, * }); * stream.end('

Hello World

'); * }); * - * server.listen(80); + * server.listen(8000); * ``` * @since v8.4.0 * @param onRequestHandler See `Compatibility API` */ - export function createServer(onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void): Http2Server; - export function createServer(options: ServerOptions, onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void): Http2Server; + export function createServer( + onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): Http2Server; + export function createServer( + options: ServerOptions, + onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): Http2Server; /** * Returns a `tls.Server` instance that creates and manages `Http2Session`instances. * * ```js - * const http2 = require('http2'); - * const fs = require('fs'); + * const http2 = require('node:http2'); + * const fs = require('node:fs'); * * const options = { * key: fs.readFileSync('server-key.pem'), - * cert: fs.readFileSync('server-cert.pem') + * cert: fs.readFileSync('server-cert.pem'), * }; * * // Create a secure HTTP/2 server @@ -2061,23 +2334,28 @@ declare module 'http2' { * server.on('stream', (stream, headers) => { * stream.respond({ * 'content-type': 'text/html; charset=utf-8', - * ':status': 200 + * ':status': 200, * }); * stream.end('

Hello World

'); * }); * - * server.listen(80); + * server.listen(8443); * ``` * @since v8.4.0 * @param onRequestHandler See `Compatibility API` */ - export function createSecureServer(onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void): Http2SecureServer; - export function createSecureServer(options: SecureServerOptions, onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void): Http2SecureServer; + export function createSecureServer( + onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): Http2SecureServer; + export function createSecureServer( + options: SecureServerOptions, + onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): Http2SecureServer; /** * Returns a `ClientHttp2Session` instance. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const client = http2.connect('https://localhost:1234'); * * // Use the client @@ -2089,13 +2367,16 @@ declare module 'http2' { * is used). Userinfo (user ID and password), path, querystring, and fragment details in the URL will be ignored. * @param listener Will be registered as a one-time listener of the {@link 'connect'} event. */ - export function connect(authority: string | url.URL, listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): ClientHttp2Session; + export function connect( + authority: string | url.URL, + listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): ClientHttp2Session; export function connect( authority: string | url.URL, options?: ClientSessionOptions | SecureClientSessionOptions, - listener?: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void + listener?: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, ): ClientHttp2Session; } -declare module 'node:http2' { - export * from 'http2'; +declare module "node:http2" { + export * from "http2"; } diff --git a/node_modules/@types/node/https.d.ts b/node_modules/@types/node/https.d.ts old mode 100755 new mode 100644 index 9514866..36ae5b2 --- a/node_modules/@types/node/https.d.ts +++ b/node_modules/@types/node/https.d.ts @@ -1,19 +1,22 @@ /** * HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a * separate module. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/https.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/https.js) */ -declare module 'https' { - import { Duplex } from 'node:stream'; - import * as tls from 'node:tls'; - import * as http from 'node:http'; - import { URL } from 'node:url'; +declare module "https" { + import { Duplex } from "node:stream"; + import * as tls from "node:tls"; + import * as http from "node:http"; + import { URL } from "node:url"; type ServerOptions< Request extends typeof http.IncomingMessage = typeof http.IncomingMessage, Response extends typeof http.ServerResponse = typeof http.ServerResponse, > = tls.SecureContextOptions & tls.TlsOptions & http.ServerOptions; - type RequestOptions = http.RequestOptions & - tls.SecureContextOptions & { + type RequestOptions = + & http.RequestOptions + & tls.SecureContextOptions + & { + checkServerIdentity?: typeof tls.checkServerIdentity | undefined; rejectUnauthorized?: boolean | undefined; // Defaults to true servername?: string | undefined; // SNI TLS Extension }; @@ -46,14 +49,24 @@ declare module 'https' { options: ServerOptions, requestListener?: http.RequestListener, ); + /** + * Closes all connections connected to this server. + * @since v18.2.0 + */ + closeAllConnections(): void; + /** + * Closes all connections connected to this server which are not sending a request or waiting for a response. + * @since v18.2.0 + */ + closeIdleConnections(): void; addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; + addListener(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; addListener( - event: 'newSession', + event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, ): this; addListener( - event: 'OCSPRequest', + event: "OCSPRequest", listener: ( certificate: Buffer, issuer: Buffer, @@ -61,74 +74,80 @@ declare module 'https' { ) => void, ): this; addListener( - event: 'resumeSession', + event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, ): this; - addListener(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this; - addListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'connection', listener: (socket: Duplex) => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'listening', listener: () => void): this; - addListener(event: 'checkContinue', listener: http.RequestListener): this; - addListener(event: 'checkExpectation', listener: http.RequestListener): this; - addListener(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this; + addListener(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; + addListener(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "connection", listener: (socket: Duplex) => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "listening", listener: () => void): this; + addListener(event: "checkContinue", listener: http.RequestListener): this; + addListener(event: "checkExpectation", listener: http.RequestListener): this; + addListener(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; addListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; - addListener(event: 'request', listener: http.RequestListener): this; + addListener(event: "request", listener: http.RequestListener): this; addListener( - event: 'upgrade', + event: "upgrade", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; emit(event: string, ...args: any[]): boolean; - emit(event: 'keylog', line: Buffer, tlsSocket: tls.TLSSocket): boolean; + emit(event: "keylog", line: Buffer, tlsSocket: tls.TLSSocket): boolean; emit( - event: 'newSession', + event: "newSession", sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void, ): boolean; emit( - event: 'OCSPRequest', + event: "OCSPRequest", certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void, ): boolean; - emit(event: 'resumeSession', sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void): boolean; - emit(event: 'secureConnection', tlsSocket: tls.TLSSocket): boolean; - emit(event: 'tlsClientError', err: Error, tlsSocket: tls.TLSSocket): boolean; - emit(event: 'close'): boolean; - emit(event: 'connection', socket: Duplex): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'listening'): boolean; + emit(event: "resumeSession", sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void): boolean; + emit(event: "secureConnection", tlsSocket: tls.TLSSocket): boolean; + emit(event: "tlsClientError", err: Error, tlsSocket: tls.TLSSocket): boolean; + emit(event: "close"): boolean; + emit(event: "connection", socket: Duplex): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "listening"): boolean; emit( - event: 'checkContinue', + event: "checkContinue", req: InstanceType, - res: InstanceType & { req: InstanceType }, + res: InstanceType & { + req: InstanceType; + }, ): boolean; emit( - event: 'checkExpectation', + event: "checkExpectation", req: InstanceType, - res: InstanceType & { req: InstanceType }, + res: InstanceType & { + req: InstanceType; + }, ): boolean; - emit(event: 'clientError', err: Error, socket: Duplex): boolean; - emit(event: 'connect', req: InstanceType, socket: Duplex, head: Buffer): boolean; + emit(event: "clientError", err: Error, socket: Duplex): boolean; + emit(event: "connect", req: InstanceType, socket: Duplex, head: Buffer): boolean; emit( - event: 'request', + event: "request", req: InstanceType, - res: InstanceType & { req: InstanceType }, + res: InstanceType & { + req: InstanceType; + }, ): boolean; - emit(event: 'upgrade', req: InstanceType, socket: Duplex, head: Buffer): boolean; + emit(event: "upgrade", req: InstanceType, socket: Duplex, head: Buffer): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; + on(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; on( - event: 'newSession', + event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, ): this; on( - event: 'OCSPRequest', + event: "OCSPRequest", listener: ( certificate: Buffer, issuer: Buffer, @@ -136,29 +155,29 @@ declare module 'https' { ) => void, ): this; on( - event: 'resumeSession', + event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, ): this; - on(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this; - on(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'connection', listener: (socket: Duplex) => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'listening', listener: () => void): this; - on(event: 'checkContinue', listener: http.RequestListener): this; - on(event: 'checkExpectation', listener: http.RequestListener): this; - on(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this; - on(event: 'connect', listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; - on(event: 'request', listener: http.RequestListener): this; - on(event: 'upgrade', listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; + on(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; + on(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; + on(event: "close", listener: () => void): this; + on(event: "connection", listener: (socket: Duplex) => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "listening", listener: () => void): this; + on(event: "checkContinue", listener: http.RequestListener): this; + on(event: "checkExpectation", listener: http.RequestListener): this; + on(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; + on(event: "connect", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; + on(event: "request", listener: http.RequestListener): this; + on(event: "upgrade", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; + once(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; once( - event: 'newSession', + event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, ): this; once( - event: 'OCSPRequest', + event: "OCSPRequest", listener: ( certificate: Buffer, issuer: Buffer, @@ -166,29 +185,29 @@ declare module 'https' { ) => void, ): this; once( - event: 'resumeSession', + event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, ): this; - once(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this; - once(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'connection', listener: (socket: Duplex) => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'listening', listener: () => void): this; - once(event: 'checkContinue', listener: http.RequestListener): this; - once(event: 'checkExpectation', listener: http.RequestListener): this; - once(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this; - once(event: 'connect', listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; - once(event: 'request', listener: http.RequestListener): this; - once(event: 'upgrade', listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; + once(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; + once(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; + once(event: "close", listener: () => void): this; + once(event: "connection", listener: (socket: Duplex) => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "listening", listener: () => void): this; + once(event: "checkContinue", listener: http.RequestListener): this; + once(event: "checkExpectation", listener: http.RequestListener): this; + once(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; + once(event: "connect", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; + once(event: "request", listener: http.RequestListener): this; + once(event: "upgrade", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; + prependListener(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; prependListener( - event: 'newSession', + event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, ): this; prependListener( - event: 'OCSPRequest', + event: "OCSPRequest", listener: ( certificate: Buffer, issuer: Buffer, @@ -196,35 +215,35 @@ declare module 'https' { ) => void, ): this; prependListener( - event: 'resumeSession', + event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, ): this; - prependListener(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this; - prependListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'connection', listener: (socket: Duplex) => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'listening', listener: () => void): this; - prependListener(event: 'checkContinue', listener: http.RequestListener): this; - prependListener(event: 'checkExpectation', listener: http.RequestListener): this; - prependListener(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this; + prependListener(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; + prependListener(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "connection", listener: (socket: Duplex) => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "listening", listener: () => void): this; + prependListener(event: "checkContinue", listener: http.RequestListener): this; + prependListener(event: "checkExpectation", listener: http.RequestListener): this; + prependListener(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; prependListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; - prependListener(event: 'request', listener: http.RequestListener): this; + prependListener(event: "request", listener: http.RequestListener): this; prependListener( - event: 'upgrade', + event: "upgrade", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; + prependOnceListener(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; prependOnceListener( - event: 'newSession', + event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, ): this; prependOnceListener( - event: 'OCSPRequest', + event: "OCSPRequest", listener: ( certificate: Buffer, issuer: Buffer, @@ -232,37 +251,37 @@ declare module 'https' { ) => void, ): this; prependOnceListener( - event: 'resumeSession', + event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, ): this; - prependOnceListener(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this; - prependOnceListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'connection', listener: (socket: Duplex) => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'listening', listener: () => void): this; - prependOnceListener(event: 'checkContinue', listener: http.RequestListener): this; - prependOnceListener(event: 'checkExpectation', listener: http.RequestListener): this; - prependOnceListener(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this; + prependOnceListener(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; + prependOnceListener(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "connection", listener: (socket: Duplex) => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "listening", listener: () => void): this; + prependOnceListener(event: "checkContinue", listener: http.RequestListener): this; + prependOnceListener(event: "checkExpectation", listener: http.RequestListener): this; + prependOnceListener(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; prependOnceListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; - prependOnceListener(event: 'request', listener: http.RequestListener): this; + prependOnceListener(event: "request", listener: http.RequestListener): this; prependOnceListener( - event: 'upgrade', + event: "upgrade", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; } /** * ```js * // curl -k https://localhost:8000/ - * const https = require('https'); - * const fs = require('fs'); + * const https = require('node:https'); + * const fs = require('node:fs'); * * const options = { * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), - * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem') + * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'), * }; * * https.createServer(options, (req, res) => { @@ -274,12 +293,12 @@ declare module 'https' { * Or * * ```js - * const https = require('https'); - * const fs = require('fs'); + * const https = require('node:https'); + * const fs = require('node:fs'); * * const options = { * pfx: fs.readFileSync('test/fixtures/test_cert.pfx'), - * passphrase: 'sample' + * passphrase: 'sample', * }; * * https.createServer(options, (req, res) => { @@ -315,13 +334,13 @@ declare module 'https' { * upload a file with a POST request, then write to the `ClientRequest` object. * * ```js - * const https = require('https'); + * const https = require('node:https'); * * const options = { * hostname: 'encrypted.google.com', * port: 443, * path: '/', - * method: 'GET' + * method: 'GET', * }; * * const req = https.request(options, (res) => { @@ -348,7 +367,7 @@ declare module 'https' { * path: '/', * method: 'GET', * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), - * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem') + * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'), * }; * options.agent = new https.Agent(options); * @@ -367,7 +386,7 @@ declare module 'https' { * method: 'GET', * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'), - * agent: false + * agent: false, * }; * * const req = https.request(options, (res) => { @@ -388,9 +407,9 @@ declare module 'https' { * Example pinning on certificate fingerprint, or the public key (similar to`pin-sha256`): * * ```js - * const tls = require('tls'); - * const https = require('https'); - * const crypto = require('crypto'); + * const tls = require('node:tls'); + * const https = require('node:https'); + * const crypto = require('node:crypto'); * * function sha256(s) { * return crypto.createHash('sha256').update(s).digest('base64'); @@ -407,7 +426,7 @@ declare module 'https' { * return err; * } * - * // Pin the public key, similar to HPKP pin-sha25 pinning + * // Pin the public key, similar to HPKP pin-sha256 pinning * const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU='; * if (sha256(cert.pubkey) !== pubkey256) { * const msg = 'Certificate verification error: ' + @@ -498,7 +517,7 @@ declare module 'https' { * string, it is automatically parsed with `new URL()`. If it is a `URL` object, it will be automatically converted to an ordinary `options` object. * * ```js - * const https = require('https'); + * const https = require('node:https'); * * https.get('https://encrypted.google.com/', (res) => { * console.log('statusCode:', res.statusCode); @@ -526,6 +545,6 @@ declare module 'https' { ): http.ClientRequest; let globalAgent: Agent; } -declare module 'node:https' { - export * from 'https'; +declare module "node:https" { + export * from "https"; } diff --git a/node_modules/@types/node/index.d.ts b/node_modules/@types/node/index.d.ts old mode 100755 new mode 100644 index 9922458..a596cad --- a/node_modules/@types/node/index.d.ts +++ b/node_modules/@types/node/index.d.ts @@ -1,48 +1,3 @@ -// Type definitions for non-npm package Node.js 16.11 -// Project: https://nodejs.org/ -// Definitions by: Microsoft TypeScript -// DefinitelyTyped -// Alberto Schiabel -// Alvis HT Tang -// Andrew Makarov -// Benjamin Toueg -// Chigozirim C. -// David Junger -// Deividas Bakanas -// Eugene Y. Q. Shen -// Hannes Magnusson -// Huw -// Kelvin Jin -// Klaus Meinhardt -// Lishude -// Mariusz Wiktorczyk -// Mohsen Azimi -// Nicolas Even -// Nikita Galkin -// Parambir Singh -// Sebastian Silbermann -// Seth Westphal -// Simon Schick -// Thomas den Hollander -// Wilco Bakker -// wwwy3y3 -// Samuel Ainsworth -// Kyle Uehlein -// Thanik Bhongbhibhat -// Marcin Kopacz -// Trivikram Kamat -// Junxiao Shi -// Ilia Baryshnikov -// ExE Boss -// Piotr Błażejewicz -// Anna Henningsen -// Victor Perin -// Yongsheng Zhang -// NodeJS Contributors -// Linus Unnebäck -// wafuwafu13 -// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped - /** * License for programmatically and manually incorporated * documentation aka. `JSDoc` from https://github.com/nodejs/node/tree/master/doc @@ -92,6 +47,7 @@ /// /// /// +/// /// /// /// @@ -108,6 +64,7 @@ /// /// /// +/// /// /// /// diff --git a/node_modules/@types/node/inspector.d.ts b/node_modules/@types/node/inspector.d.ts old mode 100755 new mode 100644 index f79313f..3927b81 --- a/node_modules/@types/node/inspector.d.ts +++ b/node_modules/@types/node/inspector.d.ts @@ -1,21 +1,26 @@ -// eslint-disable-next-line dt-header // Type definitions for inspector // These definitions are auto-generated. // Please see https://github.com/DefinitelyTyped/DefinitelyTyped/pull/19330 // for more information. -// tslint:disable:max-line-length /** - * The `inspector` module provides an API for interacting with the V8 inspector. + * The `node:inspector` module provides an API for interacting with the V8 + * inspector. * * It can be accessed using: * * ```js - * const inspector = require('inspector'); + * import * as inspector from 'node:inspector/promises'; * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/inspector.js) + * + * or + * + * ```js + * import * as inspector from 'node:inspector'; + * ``` + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/inspector.js) */ declare module 'inspector' { import EventEmitter = require('node:events'); @@ -1688,7 +1693,7 @@ declare module 'inspector' { /** * Controls how the trace buffer stores data. */ - recordMode?: string; + recordMode?: string | undefined; /** * Included category filters. */ @@ -1778,13 +1783,6 @@ declare module 'inspector' { * @since v8.0.0 */ connect(): void; - /** - * Connects a session to the main thread inspector back-end. - * An exception will be thrown if this API was not called on a Worker - * thread. - * @since v12.11.0 - */ - connectToMainThread(): void; /** * Immediately close the session. All pending message callbacks will be called * with an error. `session.connect()` will need to be called to be able to send @@ -2696,7 +2694,7 @@ declare module 'inspector' { prependOnceListener(event: 'NodeRuntime.waitingForDisconnect', listener: () => void): this; } /** - * Activate inspector on host and port. Equivalent to `node --inspect=[[host:]port]`, but can be done programmatically after node has + * Activate inspector on host and port. Equivalent to`node --inspect=[[host:]port]`, but can be done programmatically after node has * started. * * If wait is `true`, will block until a client has connected to the inspect port @@ -2706,8 +2704,9 @@ declare module 'inspector' { * @param [port='what was specified on the CLI'] Port to listen on for inspector connections. Optional. * @param [host='what was specified on the CLI'] Host to listen on for inspector connections. Optional. * @param [wait=false] Block until a client has connected. Optional. + * @returns Disposable that calls `inspector.close()`. */ - function open(port?: number, host?: string, wait?: boolean): void; + function open(port?: number, host?: string, wait?: boolean): Disposable; /** * Deactivate the inspector. Blocks until there are no active connections. */ @@ -2718,12 +2717,12 @@ declare module 'inspector' { * ```console * $ node --inspect -p 'inspector.url()' * Debugger listening on ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34 - * For help see https://nodejs.org/en/docs/inspector + * For help, see: https://nodejs.org/en/docs/inspector * ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34 * * $ node --inspect=localhost:3000 -p 'inspector.url()' * Debugger listening on ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a - * For help see https://nodejs.org/en/docs/inspector + * For help, see: https://nodejs.org/en/docs/inspector * ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a * * $ node -p 'inspector.url()' @@ -2739,7 +2738,10 @@ declare module 'inspector' { */ function waitForDebugger(): void; } +/** + * The inspector module provides an API for interacting with the V8 inspector. + */ declare module 'node:inspector' { - import EventEmitter = require('inspector'); - export = EventEmitter; + import inspector = require('inspector'); + export = inspector; } diff --git a/node_modules/@types/node/module.d.ts b/node_modules/@types/node/module.d.ts old mode 100755 new mode 100644 index d83aec9..c38a9b8 --- a/node_modules/@types/node/module.d.ts +++ b/node_modules/@types/node/module.d.ts @@ -1,8 +1,10 @@ /** * @since v0.3.7 + * @experimental */ -declare module 'module' { - import { URL } from 'node:url'; +declare module "module" { + import { URL } from "node:url"; + import { MessagePort } from "node:worker_threads"; namespace Module { /** * The `module.syncBuiltinESMExports()` method updates all the live bindings for @@ -10,9 +12,9 @@ declare module 'module' { * does not add or remove exported names from the `ES Modules`. * * ```js - * const fs = require('fs'); - * const assert = require('assert'); - * const { syncBuiltinESMExports } = require('module'); + * const fs = require('node:fs'); + * const assert = require('node:assert'); + * const { syncBuiltinESMExports } = require('node:module'); * * fs.readFile = newAPI; * @@ -26,7 +28,7 @@ declare module 'module' { * * syncBuiltinESMExports(); * - * import('fs').then((esmFS) => { + * import('node:fs').then((esmFS) => { * // It syncs the existing readFile property with the new value * assert.strictEqual(esmFS.readFile, newAPI); * // readFileSync has been deleted from the required fs @@ -44,6 +46,7 @@ declare module 'module' { * `path` is the resolved path for the file for which a corresponding source map * should be fetched. * @since v13.7.0, v12.17.0 + * @return Returns `module.SourceMap` if a source map is found, `undefined` otherwise. */ function findSourceMap(path: string, error?: Error): SourceMap; interface SourceMapPayload { @@ -62,6 +65,24 @@ declare module 'module' { originalLine: number; originalColumn: number; } + interface SourceOrigin { + /** + * The name of the range in the source map, if one was provided + */ + name?: string; + /** + * The file name of the original source, as reported in the SourceMap + */ + fileName: string; + /** + * The 1-indexed lineNumber of the corresponding call site in the original source + */ + lineNumber: number; + /** + * The 1-indexed columnNumber of the corresponding call site in the original source + */ + columnNumber: number; + } /** * @since v13.7.0, v12.17.0 */ @@ -72,12 +93,170 @@ declare module 'module' { readonly payload: SourceMapPayload; constructor(payload: SourceMapPayload); /** - * Given a line number and column number in the generated source file, returns - * an object representing the position in the original file. The object returned - * consists of the following keys: + * Given a line offset and column offset in the generated source + * file, returns an object representing the SourceMap range in the + * original file if found, or an empty object if not. + * + * The object returned contains the following keys: + * + * The returned value represents the raw range as it appears in the + * SourceMap, based on zero-indexed offsets, _not_ 1-indexed line and + * column numbers as they appear in Error messages and CallSite + * objects. + * + * To get the corresponding 1-indexed line and column numbers from a + * lineNumber and columnNumber as they are reported by Error stacks + * and CallSite objects, use `sourceMap.findOrigin(lineNumber, columnNumber)` + * @param lineOffset The zero-indexed line number offset in the generated source + * @param columnOffset The zero-indexed column number offset in the generated source */ - findEntry(line: number, column: number): SourceMapping; + findEntry(lineOffset: number, columnOffset: number): SourceMapping; + /** + * Given a 1-indexed `lineNumber` and `columnNumber` from a call site in the generated source, + * find the corresponding call site location in the original source. + * + * If the `lineNumber` and `columnNumber` provided are not found in any source map, + * then an empty object is returned. + * @param lineNumber The 1-indexed line number of the call site in the generated source + * @param columnNumber The 1-indexed column number of the call site in the generated source + */ + findOrigin(lineNumber: number, columnNumber: number): SourceOrigin | {}; } + /** @deprecated Use `ImportAttributes` instead */ + interface ImportAssertions extends ImportAttributes {} + interface ImportAttributes extends NodeJS.Dict { + type?: string | undefined; + } + type ModuleFormat = "builtin" | "commonjs" | "json" | "module" | "wasm"; + type ModuleSource = string | ArrayBuffer | NodeJS.TypedArray; + interface GlobalPreloadContext { + port: MessagePort; + } + /** + * @deprecated This hook will be removed in a future version. + * Use `initialize` instead. When a loader has an `initialize` export, `globalPreload` will be ignored. + * + * Sometimes it might be necessary to run some code inside of the same global scope that the application runs in. + * This hook allows the return of a string that is run as a sloppy-mode script on startup. + * + * @param context Information to assist the preload code + * @return Code to run before application startup + */ + type GlobalPreloadHook = (context: GlobalPreloadContext) => string; + /** + * The `initialize` hook provides a way to define a custom function that runs in the hooks thread + * when the hooks module is initialized. Initialization happens when the hooks module is registered via `register`. + * + * This hook can receive data from a `register` invocation, including ports and other transferrable objects. + * The return value of `initialize` can be a `Promise`, in which case it will be awaited before the main application thread execution resumes. + */ + type InitializeHook = (data: Data) => void | Promise; + interface ResolveHookContext { + /** + * Export conditions of the relevant `package.json` + */ + conditions: string[]; + /** + * @deprecated Use `importAttributes` instead + */ + importAssertions: ImportAttributes; + /** + * An object whose key-value pairs represent the assertions for the module to import + */ + importAttributes: ImportAttributes; + /** + * The module importing this one, or undefined if this is the Node.js entry point + */ + parentURL: string | undefined; + } + interface ResolveFnOutput { + /** + * A hint to the load hook (it might be ignored) + */ + format?: ModuleFormat | null | undefined; + /** + * @deprecated Use `importAttributes` instead + */ + importAssertions?: ImportAttributes | undefined; + /** + * The import attributes to use when caching the module (optional; if excluded the input will be used) + */ + importAttributes?: ImportAttributes | undefined; + /** + * A signal that this hook intends to terminate the chain of `resolve` hooks. + * @default false + */ + shortCircuit?: boolean | undefined; + /** + * The absolute URL to which this input resolves + */ + url: string; + } + /** + * The `resolve` hook chain is responsible for resolving file URL for a given module specifier and parent URL, and optionally its format (such as `'module'`) as a hint to the `load` hook. + * If a format is specified, the load hook is ultimately responsible for providing the final `format` value (and it is free to ignore the hint provided by `resolve`); + * if `resolve` provides a format, a custom `load` hook is required even if only to pass the value to the Node.js default `load` hook. + * + * @param specifier The specified URL path of the module to be resolved + * @param context + * @param nextResolve The subsequent `resolve` hook in the chain, or the Node.js default `resolve` hook after the last user-supplied resolve hook + */ + type ResolveHook = ( + specifier: string, + context: ResolveHookContext, + nextResolve: ( + specifier: string, + context?: ResolveHookContext, + ) => ResolveFnOutput | Promise, + ) => ResolveFnOutput | Promise; + interface LoadHookContext { + /** + * Export conditions of the relevant `package.json` + */ + conditions: string[]; + /** + * The format optionally supplied by the `resolve` hook chain + */ + format: ModuleFormat; + /** + * @deprecated Use `importAttributes` instead + */ + importAssertions: ImportAttributes; + /** + * An object whose key-value pairs represent the assertions for the module to import + */ + importAttributes: ImportAttributes; + } + interface LoadFnOutput { + format: ModuleFormat; + /** + * A signal that this hook intends to terminate the chain of `resolve` hooks. + * @default false + */ + shortCircuit?: boolean | undefined; + /** + * The source for Node.js to evaluate + */ + source?: ModuleSource; + } + /** + * The `load` hook provides a way to define a custom method of determining how a URL should be interpreted, retrieved, and parsed. + * It is also in charge of validating the import assertion. + * + * @param url The URL/path of the module to be loaded + * @param context Metadata about the module + * @param nextLoad The subsequent `load` hook in the chain, or the Node.js default `load` hook after the last user-supplied `load` hook + */ + type LoadHook = ( + url: string, + context: LoadHookContext, + nextLoad: (url: string, context?: LoadHookContext) => LoadFnOutput | Promise, + ) => LoadFnOutput | Promise; + } + interface RegisterOptions { + parentURL: string | URL; + data?: Data | undefined; + transferList?: any[] | undefined; } interface Module extends NodeModule {} class Module { @@ -85,30 +264,52 @@ declare module 'module' { static wrap(code: string): string; static createRequire(path: string | URL): NodeRequire; static builtinModules: string[]; + static isBuiltin(moduleName: string): boolean; static Module: typeof Module; + static register( + specifier: string | URL, + parentURL?: string | URL, + options?: RegisterOptions, + ): void; + static register(specifier: string | URL, options?: RegisterOptions): void; constructor(id: string, parent?: Module); } global { interface ImportMeta { + /** + * The directory name of the current module. This is the same as the `path.dirname()` of the `import.meta.filename`. + * **Caveat:** only present on `file:` modules. + */ + dirname: string; + /** + * The full absolute path and filename of the current module, with symlinks resolved. + * This is the same as the `url.fileURLToPath()` of the `import.meta.url`. + * **Caveat:** only local modules support this property. Modules not using the `file:` protocol will not provide it. + */ + filename: string; + /** + * The absolute `file:` URL of the module. + */ url: string; /** - * @experimental - * This feature is only available with the `--experimental-import-meta-resolve` - * command flag enabled. - * * Provides a module-relative resolution function scoped to each module, returning * the URL string. * - * @param specified The module specifier to resolve relative to `parent`. - * @param parent The absolute parent module URL to resolve from. If none - * is specified, the value of `import.meta.url` is used as the default. + * Second `parent` parameter is only used when the `--experimental-import-meta-resolve` + * command flag enabled. + * + * @since v20.6.0 + * + * @param specifier The module specifier to resolve relative to `parent`. + * @param parent The absolute parent module URL to resolve from. + * @returns The absolute (`file:`) URL string for the resolved module. */ - resolve?(specified: string, parent?: string | URL): Promise; + resolve(specifier: string, parent?: string | URL | undefined): string; } } export = Module; } -declare module 'node:module' { - import module = require('module'); +declare module "node:module" { + import module = require("module"); export = module; } diff --git a/node_modules/@types/node/net.d.ts b/node_modules/@types/node/net.d.ts old mode 100755 new mode 100644 index 195b393..70789e1 --- a/node_modules/@types/node/net.d.ts +++ b/node_modules/@types/node/net.d.ts @@ -1,22 +1,26 @@ /** * > Stability: 2 - Stable * - * The `net` module provides an asynchronous network API for creating stream-based + * The `node:net` module provides an asynchronous network API for creating stream-based * TCP or `IPC` servers ({@link createServer}) and clients * ({@link createConnection}). * * It can be accessed using: * * ```js - * const net = require('net'); + * const net = require('node:net'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/net.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/net.js) */ -declare module 'net' { - import * as stream from 'node:stream'; - import { Abortable, EventEmitter } from 'node:events'; - import * as dns from 'node:dns'; - type LookupFunction = (hostname: string, options: dns.LookupOneOptions, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void) => void; +declare module "net" { + import * as stream from "node:stream"; + import { Abortable, EventEmitter } from "node:events"; + import * as dns from "node:dns"; + type LookupFunction = ( + hostname: string, + options: dns.LookupAllOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: dns.LookupAddress[]) => void, + ) => void; interface AddressInfo { address: string; family: string; @@ -57,12 +61,20 @@ declare module 'net' { noDelay?: boolean | undefined; keepAlive?: boolean | undefined; keepAliveInitialDelay?: number | undefined; + /** + * @since v18.13.0 + */ + autoSelectFamily?: boolean | undefined; + /** + * @since v18.13.0 + */ + autoSelectFamilyAttemptTimeout?: number | undefined; } interface IpcSocketConnectOpts extends ConnectOpts { path: string; } type SocketConnectOpts = TcpSocketConnectOpts | IpcSocketConnectOpts; - type SocketReadyState = 'opening' | 'open' | 'readOnly' | 'writeOnly' | 'closed'; + type SocketReadyState = "opening" | "open" | "readOnly" | "writeOnly" | "closed"; /** * This class is an abstraction of a TCP socket or a streaming `IPC` endpoint * (uses named pipes on Windows, and Unix domain sockets otherwise). It is also @@ -79,6 +91,12 @@ declare module 'net' { */ class Socket extends stream.Duplex { constructor(options?: SocketConstructorOpts); + /** + * Destroys the socket after all data is written. If the `finish` event was already emitted the socket is destroyed immediately. + * If the socket is still writable it implicitly calls `socket.end()`. + * @since v0.3.4 + */ + destroySoon(): void; /** * Sends data on the socket. The second parameter specifies the encoding in the * case of a string. It defaults to UTF8 encoding. @@ -131,6 +149,14 @@ declare module 'net' { * @return The socket itself. */ pause(): this; + /** + * Close the TCP connection by sending an RST packet and destroy the stream. + * If this TCP socket is in connecting status, it will send an RST packet and destroy this TCP socket once it is connected. + * Otherwise, it will call `socket.destroy` with an `ERR_SOCKET_CLOSED` Error. + * If this is not a TCP socket (for example, a pipe), calling this method will immediately throw an `ERR_INVALID_HANDLE_TYPE` Error. + * @since v18.3.0, v16.17.0 + */ + resetAndDestroy(): this; /** * Resumes reading after a call to `socket.pause()`. * @return The socket itself. @@ -208,12 +234,21 @@ declare module 'net' { */ unref(): this; /** - * Opposite of `unref()`, calling `ref()` on a previously `unref`ed socket will_not_ let the program exit if it's the only socket left (the default behavior). + * Opposite of `unref()`, calling `ref()` on a previously `unref`ed socket will _not_ let the program exit if it's the only socket left (the default behavior). * If the socket is `ref`ed calling `ref` again will have no effect. * @since v0.9.1 * @return The socket itself. */ ref(): this; + /** + * This property is only present if the family autoselection algorithm is enabled in `socket.connect(options)` + * and it is an array of the addresses that have been attempted. + * + * Each address is a string in the form of `$IP:$PORT`. + * If the connection was successful, then the last address is the one that the socket is currently connected to. + * @since v19.4.0 + */ + readonly autoSelectFamilyAttemptedAddresses: string[]; /** * This property shows the number of characters buffered for writing. The buffer * may contain strings whose length after encoding is not yet known. So this number @@ -250,6 +285,12 @@ declare module 'net' { * @since v6.1.0 */ readonly connecting: boolean; + /** + * This is `true` if the socket is not connected yet, either because `.connect()`has not yet been called or because it is still in the process of connecting + * (see `socket.connecting`). + * @since v11.2.0, v10.16.0 + */ + readonly pending: boolean; /** * See `writable.destroyed` for further details. */ @@ -266,9 +307,18 @@ declare module 'net' { * @since v0.9.6 */ readonly localPort?: number; + /** + * The string representation of the local IP family. `'IPv4'` or `'IPv6'`. + * @since v18.8.0, v16.18.0 + */ + readonly localFamily?: string; /** * This property represents the state of the connection as a string. - * @see {https://nodejs.org/api/net.html#socketreadystate} + * + * * If the stream is connecting `socket.readyState` is `opening`. + * * If the stream is readable and writable, it is `open`. + * * If the stream is readable and not writable, it is `readOnly`. + * * If the stream is not readable and writable, it is `writeOnly`. * @since v0.5.0 */ readonly readyState: SocketReadyState; @@ -279,17 +329,20 @@ declare module 'net' { */ readonly remoteAddress?: string | undefined; /** - * The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. + * The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. Value may be `undefined` if + * the socket is destroyed (for example, if the client disconnected). * @since v0.11.14 */ readonly remoteFamily?: string | undefined; /** - * The numeric representation of the remote port. For example, `80` or `21`. + * The numeric representation of the remote port. For example, `80` or `21`. Value may be `undefined` if + * the socket is destroyed (for example, if the client disconnected). * @since v0.5.10 */ readonly remotePort?: number | undefined; /** - * The socket timeout in milliseconds as set by socket.setTimeout(). It is undefined if a timeout has not been set. + * The socket timeout in milliseconds as set by `socket.setTimeout()`. + * It is `undefined` if a timeout has not been set. * @since v10.7.0 */ readonly timeout?: number | undefined; @@ -315,68 +368,84 @@ declare module 'net' { * 5. end * 6. error * 7. lookup - * 8. timeout + * 8. ready + * 9. timeout */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: (hadError: boolean) => void): this; - addListener(event: 'connect', listener: () => void): this; - addListener(event: 'data', listener: (data: Buffer) => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'end', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'lookup', listener: (err: Error, address: string, family: string | number, host: string) => void): this; - addListener(event: 'ready', listener: () => void): this; - addListener(event: 'timeout', listener: () => void): this; + addListener(event: "close", listener: (hadError: boolean) => void): this; + addListener(event: "connect", listener: () => void): this; + addListener(event: "data", listener: (data: Buffer) => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener( + event: "lookup", + listener: (err: Error, address: string, family: string | number, host: string) => void, + ): this; + addListener(event: "ready", listener: () => void): this; + addListener(event: "timeout", listener: () => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close', hadError: boolean): boolean; - emit(event: 'connect'): boolean; - emit(event: 'data', data: Buffer): boolean; - emit(event: 'drain'): boolean; - emit(event: 'end'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'lookup', err: Error, address: string, family: string | number, host: string): boolean; - emit(event: 'ready'): boolean; - emit(event: 'timeout'): boolean; + emit(event: "close", hadError: boolean): boolean; + emit(event: "connect"): boolean; + emit(event: "data", data: Buffer): boolean; + emit(event: "drain"): boolean; + emit(event: "end"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "lookup", err: Error, address: string, family: string | number, host: string): boolean; + emit(event: "ready"): boolean; + emit(event: "timeout"): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: (hadError: boolean) => void): this; - on(event: 'connect', listener: () => void): this; - on(event: 'data', listener: (data: Buffer) => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'end', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'lookup', listener: (err: Error, address: string, family: string | number, host: string) => void): this; - on(event: 'ready', listener: () => void): this; - on(event: 'timeout', listener: () => void): this; + on(event: "close", listener: (hadError: boolean) => void): this; + on(event: "connect", listener: () => void): this; + on(event: "data", listener: (data: Buffer) => void): this; + on(event: "drain", listener: () => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on( + event: "lookup", + listener: (err: Error, address: string, family: string | number, host: string) => void, + ): this; + on(event: "ready", listener: () => void): this; + on(event: "timeout", listener: () => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: (hadError: boolean) => void): this; - once(event: 'connect', listener: () => void): this; - once(event: 'data', listener: (data: Buffer) => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'end', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'lookup', listener: (err: Error, address: string, family: string | number, host: string) => void): this; - once(event: 'ready', listener: () => void): this; - once(event: 'timeout', listener: () => void): this; + once(event: "close", listener: (hadError: boolean) => void): this; + once(event: "connect", listener: () => void): this; + once(event: "data", listener: (data: Buffer) => void): this; + once(event: "drain", listener: () => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once( + event: "lookup", + listener: (err: Error, address: string, family: string | number, host: string) => void, + ): this; + once(event: "ready", listener: () => void): this; + once(event: "timeout", listener: () => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: (hadError: boolean) => void): this; - prependListener(event: 'connect', listener: () => void): this; - prependListener(event: 'data', listener: (data: Buffer) => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'end', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'lookup', listener: (err: Error, address: string, family: string | number, host: string) => void): this; - prependListener(event: 'ready', listener: () => void): this; - prependListener(event: 'timeout', listener: () => void): this; + prependListener(event: "close", listener: (hadError: boolean) => void): this; + prependListener(event: "connect", listener: () => void): this; + prependListener(event: "data", listener: (data: Buffer) => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener( + event: "lookup", + listener: (err: Error, address: string, family: string | number, host: string) => void, + ): this; + prependListener(event: "ready", listener: () => void): this; + prependListener(event: "timeout", listener: () => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: (hadError: boolean) => void): this; - prependOnceListener(event: 'connect', listener: () => void): this; - prependOnceListener(event: 'data', listener: (data: Buffer) => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'end', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'lookup', listener: (err: Error, address: string, family: string | number, host: string) => void): this; - prependOnceListener(event: 'ready', listener: () => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; + prependOnceListener(event: "close", listener: (hadError: boolean) => void): this; + prependOnceListener(event: "connect", listener: () => void): this; + prependOnceListener(event: "data", listener: (data: Buffer) => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener( + event: "lookup", + listener: (err: Error, address: string, family: string | number, host: string) => void, + ): this; + prependOnceListener(event: "ready", listener: () => void): this; + prependOnceListener(event: "timeout", listener: () => void): this; } interface ListenOptions extends Abortable { port?: number | undefined; @@ -422,6 +491,14 @@ declare module 'net' { */ keepAliveInitialDelay?: number | undefined; } + interface DropArgument { + localAddress?: string; + localPort?: number; + localFamily?: string; + remoteAddress?: string; + remotePort?: number; + remoteFamily?: string; + } /** * This class is used to create a TCP or `IPC` server. * @since v0.1.90 @@ -461,7 +538,7 @@ declare module 'net' { * ```js * server.on('error', (e) => { * if (e.code === 'EADDRINUSE') { - * console.log('Address in use, retrying...'); + * console.error('Address in use, retrying...'); * setTimeout(() => { * server.close(); * server.listen(PORT, HOST); @@ -526,7 +603,7 @@ declare module 'net' { */ getConnections(cb: (error: Error | null, count: number) => void): void; /** - * Opposite of `unref()`, calling `ref()` on a previously `unref`ed server will_not_ let the program exit if it's the only server left (the default behavior). + * Opposite of `unref()`, calling `ref()` on a previously `unref`ed server will _not_ let the program exit if it's the only server left (the default behavior). * If the server is `ref`ed calling `ref()` again will have no effect. * @since v0.9.1 */ @@ -558,49 +635,61 @@ declare module 'net' { * 2. connection * 3. error * 4. listening + * 5. drop */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'connection', listener: (socket: Socket) => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'listening', listener: () => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "connection", listener: (socket: Socket) => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "listening", listener: () => void): this; + addListener(event: "drop", listener: (data?: DropArgument) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close'): boolean; - emit(event: 'connection', socket: Socket): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'listening'): boolean; + emit(event: "close"): boolean; + emit(event: "connection", socket: Socket): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "listening"): boolean; + emit(event: "drop", data?: DropArgument): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'connection', listener: (socket: Socket) => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'listening', listener: () => void): this; + on(event: "close", listener: () => void): this; + on(event: "connection", listener: (socket: Socket) => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "listening", listener: () => void): this; + on(event: "drop", listener: (data?: DropArgument) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'connection', listener: (socket: Socket) => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'listening', listener: () => void): this; + once(event: "close", listener: () => void): this; + once(event: "connection", listener: (socket: Socket) => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "listening", listener: () => void): this; + once(event: "drop", listener: (data?: DropArgument) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'connection', listener: (socket: Socket) => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'listening', listener: () => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "connection", listener: (socket: Socket) => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "listening", listener: () => void): this; + prependListener(event: "drop", listener: (data?: DropArgument) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'connection', listener: (socket: Socket) => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'listening', listener: () => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "connection", listener: (socket: Socket) => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "listening", listener: () => void): this; + prependOnceListener(event: "drop", listener: (data?: DropArgument) => void): this; + /** + * Calls {@link Server.close()} and returns a promise that fulfills when the server has closed. + * @since v20.5.0 + */ + [Symbol.asyncDispose](): Promise; } - type IPVersion = 'ipv4' | 'ipv6'; + type IPVersion = "ipv4" | "ipv6"; /** * The `BlockList` object can be used with some network APIs to specify rules for * disabling inbound or outbound access to specific IP addresses, IP ranges, or * IP subnets. - * @since v15.0.0 + * @since v15.0.0, v14.18.0 */ class BlockList { /** * Adds a rule to block the given IP address. - * @since v15.0.0 + * @since v15.0.0, v14.18.0 * @param address An IPv4 or IPv6 address. * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. */ @@ -608,7 +697,7 @@ declare module 'net' { addAddress(address: SocketAddress): void; /** * Adds a rule to block a range of IP addresses from `start` (inclusive) to`end` (inclusive). - * @since v15.0.0 + * @since v15.0.0, v14.18.0 * @param start The starting IPv4 or IPv6 address in the range. * @param end The ending IPv4 or IPv6 address in the range. * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. @@ -617,7 +706,7 @@ declare module 'net' { addRange(start: SocketAddress, end: SocketAddress): void; /** * Adds a rule to block a range of IP addresses specified as a subnet mask. - * @since v15.0.0 + * @since v15.0.0, v14.18.0 * @param net The network IPv4 or IPv6 address. * @param prefix The number of CIDR prefix bits. For IPv4, this must be a value between `0` and `32`. For IPv6, this must be between `0` and `128`. * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. @@ -641,7 +730,7 @@ declare module 'net' { * console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true * console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true * ``` - * @since v15.0.0 + * @since v15.0.0, v14.18.0 * @param address The IP address to check * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. */ @@ -672,11 +761,11 @@ declare module 'net' { * * The server can be a TCP server or an `IPC` server, depending on what it `listen()` to. * - * Here is an example of an TCP echo server which listens for connections + * Here is an example of a TCP echo server which listens for connections * on port 8124: * * ```js - * const net = require('net'); + * const net = require('node:net'); * const server = net.createServer((c) => { * // 'connection' listener. * console.log('client connected'); @@ -696,8 +785,8 @@ declare module 'net' { * * Test this by using `telnet`: * - * ```console - * $ telnet localhost 8124 + * ```bash + * telnet localhost 8124 * ``` * * To listen on the socket `/tmp/echo.sock`: @@ -710,8 +799,8 @@ declare module 'net' { * * Use `nc` to connect to a Unix domain socket server: * - * ```console - * $ nc -U /tmp/echo.sock + * ```bash + * nc -U /tmp/echo.sock * ``` * @since v0.5.0 * @param connectionListener Automatically set as a listener for the {@link 'connection'} event. @@ -751,19 +840,61 @@ declare module 'net' { function createConnection(port: number, host?: string, connectionListener?: () => void): Socket; function createConnection(path: string, connectionListener?: () => void): Socket; /** - * Tests if input is an IP address. Returns `0` for invalid strings, - * returns `4` for IP version 4 addresses, and returns `6` for IP version 6 - * addresses. + * Gets the current default value of the `autoSelectFamily` option of `socket.connect(options)`. + * The initial default value is `true`, unless the command line option`--no-network-family-autoselection` is provided. + * @since v19.4.0 + */ + function getDefaultAutoSelectFamily(): boolean; + /** + * Sets the default value of the `autoSelectFamily` option of `socket.connect(options)`. + * @since v19.4.0 + */ + function setDefaultAutoSelectFamily(value: boolean): void; + /** + * Gets the current default value of the `autoSelectFamilyAttemptTimeout` option of `socket.connect(options)`. + * The initial default value is `250`. + * @since v19.8.0 + */ + function getDefaultAutoSelectFamilyAttemptTimeout(): number; + /** + * Sets the default value of the `autoSelectFamilyAttemptTimeout` option of `socket.connect(options)`. + * @since v19.8.0 + */ + function setDefaultAutoSelectFamilyAttemptTimeout(value: number): void; + /** + * Returns `6` if `input` is an IPv6 address. Returns `4` if `input` is an IPv4 + * address in [dot-decimal notation](https://en.wikipedia.org/wiki/Dot-decimal_notation) with no leading zeroes. Otherwise, returns`0`. + * + * ```js + * net.isIP('::1'); // returns 6 + * net.isIP('127.0.0.1'); // returns 4 + * net.isIP('127.000.000.001'); // returns 0 + * net.isIP('127.0.0.1/24'); // returns 0 + * net.isIP('fhqwhgads'); // returns 0 + * ``` * @since v0.3.0 */ function isIP(input: string): number; /** - * Returns `true` if input is a version 4 IP address, otherwise returns `false`. + * Returns `true` if `input` is an IPv4 address in [dot-decimal notation](https://en.wikipedia.org/wiki/Dot-decimal_notation) with no + * leading zeroes. Otherwise, returns `false`. + * + * ```js + * net.isIPv4('127.0.0.1'); // returns true + * net.isIPv4('127.000.000.001'); // returns false + * net.isIPv4('127.0.0.1/24'); // returns false + * net.isIPv4('fhqwhgads'); // returns false + * ``` * @since v0.3.0 */ function isIPv4(input: string): boolean; /** - * Returns `true` if input is a version 6 IP address, otherwise returns `false`. + * Returns `true` if `input` is an IPv6 address. Otherwise, returns `false`. + * + * ```js + * net.isIPv6('::1'); // returns true + * net.isIPv6('fhqwhgads'); // returns false + * ``` * @since v0.3.0 */ function isIPv6(input: string): boolean; @@ -789,29 +920,30 @@ declare module 'net' { port?: number | undefined; } /** - * @since v15.14.0 + * @since v15.14.0, v14.18.0 */ class SocketAddress { constructor(options: SocketAddressInitOptions); /** - * @since v15.14.0 + * Either \`'ipv4'\` or \`'ipv6'\`. + * @since v15.14.0, v14.18.0 */ readonly address: string; /** * Either \`'ipv4'\` or \`'ipv6'\`. - * @since v15.14.0 + * @since v15.14.0, v14.18.0 */ readonly family: IPVersion; /** - * @since v15.14.0 + * @since v15.14.0, v14.18.0 */ readonly port: number; /** - * @since v15.14.0 + * @since v15.14.0, v14.18.0 */ readonly flowlabel: number; } } -declare module 'node:net' { - export * from 'net'; +declare module "node:net" { + export * from "net"; } diff --git a/node_modules/@types/node/os.d.ts b/node_modules/@types/node/os.d.ts old mode 100755 new mode 100644 index f9cd242..39a33f7 --- a/node_modules/@types/node/os.d.ts +++ b/node_modules/@types/node/os.d.ts @@ -1,13 +1,13 @@ /** - * The `os` module provides operating system-related utility methods and + * The `node:os` module provides operating system-related utility methods and * properties. It can be accessed using: * * ```js - * const os = require('os'); + * const os = require('node:os'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/os.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/os.js) */ -declare module 'os' { +declare module "os" { interface CpuInfo { model: string; speed: number; @@ -27,17 +27,18 @@ declare module 'os' { cidr: string | null; } interface NetworkInterfaceInfoIPv4 extends NetworkInterfaceBase { - family: 'IPv4'; + family: "IPv4"; + scopeid?: undefined; } interface NetworkInterfaceInfoIPv6 extends NetworkInterfaceBase { - family: 'IPv6'; + family: "IPv6"; scopeid: number; } interface UserInfo { username: T; uid: number; gid: number; - shell: T; + shell: T | null; homedir: T; } type NetworkInterfaceInfo = NetworkInterfaceInfoIPv4 | NetworkInterfaceInfoIPv6; @@ -74,6 +75,7 @@ declare module 'os' { function totalmem(): number; /** * Returns an array of objects containing information about each logical CPU core. + * The array will be empty if no CPU information is available, such as if the`/proc` file system is unavailable. * * The properties included on each object include: * @@ -87,8 +89,8 @@ declare module 'os' { * nice: 0, * sys: 30340, * idle: 1070356870, - * irq: 0 - * } + * irq: 0, + * }, * }, * { * model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', @@ -98,8 +100,8 @@ declare module 'os' { * nice: 0, * sys: 26980, * idle: 1071569080, - * irq: 0 - * } + * irq: 0, + * }, * }, * { * model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', @@ -109,8 +111,8 @@ declare module 'os' { * nice: 0, * sys: 21750, * idle: 1070919370, - * irq: 0 - * } + * irq: 0, + * }, * }, * { * model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', @@ -120,17 +122,28 @@ declare module 'os' { * nice: 0, * sys: 19430, * idle: 1070905480, - * irq: 20 - * } + * irq: 20, + * }, * }, * ] * ``` * * `nice` values are POSIX-only. On Windows, the `nice` values of all processors * are always 0. + * + * `os.cpus().length` should not be used to calculate the amount of parallelism + * available to an application. Use {@link availableParallelism} for this purpose. * @since v0.3.3 */ function cpus(): CpuInfo[]; + /** + * Returns an estimate of the default amount of parallelism a program should use. + * Always returns a value greater than zero. + * + * This function is a small wrapper about libuv's [`uv_available_parallelism()`](https://docs.libuv.org/en/v1.x/misc.html#c.uv_available_parallelism). + * @since v19.4.0, v18.14.0 + */ + function availableParallelism(): number; /** * Returns the operating system name as returned by [`uname(3)`](https://linux.die.net/man/3/uname). For example, it * returns `'Linux'` on Linux, `'Darwin'` on macOS, and `'Windows_NT'` on Windows. @@ -226,7 +239,7 @@ declare module 'os' { * Throws a `SystemError` if a user has no `username` or `homedir`. * @since v6.0.0 */ - function userInfo(options: { encoding: 'buffer' }): UserInfo; + function userInfo(options: { encoding: "buffer" }): UserInfo; function userInfo(options?: { encoding: BufferEncoding }): UserInfo; type SignalConstants = { [key in NodeJS.Signals]: number; @@ -387,7 +400,8 @@ declare module 'os' { const EOL: string; /** * Returns the operating system CPU architecture for which the Node.js binary was - * compiled. Possible values are `'arm'`, `'arm64'`, `'ia32'`, `'mips'`,`'mipsel'`, `'ppc'`, `'ppc64'`, `'s390'`, `'s390x'`, `'x32'`, and `'x64'`. + * compiled. Possible values are `'arm'`, `'arm64'`, `'ia32'`, `'loong64'`,`'mips'`, `'mipsel'`, `'ppc'`, `'ppc64'`, `'riscv64'`, `'s390'`, `'s390x'`, + * and `'x64'`. * * The return value is equivalent to `process.arch`. * @since v0.5.0 @@ -402,8 +416,9 @@ declare module 'os' { */ function version(): string; /** - * Returns a string identifying the operating system platform. The value is set - * at compile time. Possible values are `'aix'`, `'darwin'`, `'freebsd'`,`'linux'`, `'openbsd'`, `'sunos'`, and `'win32'`. + * Returns a string identifying the operating system platform for which + * the Node.js binary was compiled. The value is set at compile time. + * Possible values are `'aix'`, `'darwin'`, `'freebsd'`,`'linux'`,`'openbsd'`, `'sunos'`, and `'win32'`. * * The return value is equivalent to `process.platform`. * @@ -412,6 +427,14 @@ declare module 'os' { * @since v0.5.0 */ function platform(): NodeJS.Platform; + /** + * Returns the machine type as a string, such as `arm`, `arm64`, `aarch64`,`mips`, `mips64`, `ppc64`, `ppc64le`, `s390`, `s390x`, `i386`, `i686`, `x86_64`. + * + * On POSIX systems, the machine type is determined by calling [`uname(3)`](https://linux.die.net/man/3/uname). On Windows, `RtlGetVersion()` is used, and if it is not + * available, `GetVersionExW()` will be used. See [https://en.wikipedia.org/wiki/Uname#Examples](https://en.wikipedia.org/wiki/Uname#Examples) for more information. + * @since v18.9.0, v16.18.0 + */ + function machine(): string; /** * Returns the operating system's default directory for temporary files as a * string. @@ -425,7 +448,7 @@ declare module 'os' { * Possible values are `'BE'` for big endian and `'LE'` for little endian. * @since v0.9.4 */ - function endianness(): 'BE' | 'LE'; + function endianness(): "BE" | "LE"; /** * Returns the scheduling priority for the process specified by `pid`. If `pid` is * not provided or is `0`, the priority of the current process is returned. @@ -450,6 +473,6 @@ declare module 'os' { function setPriority(priority: number): void; function setPriority(pid: number, priority: number): void; } -declare module 'node:os' { - export * from 'os'; +declare module "node:os" { + export * from "os"; } diff --git a/node_modules/@types/node/package.json b/node_modules/@types/node/package.json old mode 100755 new mode 100644 index c22a6e9..21ee850 --- a/node_modules/@types/node/package.json +++ b/node_modules/@types/node/package.json @@ -1,220 +1,215 @@ { "name": "@types/node", - "version": "16.11.64", - "description": "TypeScript definitions for Node.js", + "version": "20.11.6", + "description": "TypeScript definitions for node", "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node", "license": "MIT", "contributors": [ { "name": "Microsoft TypeScript", - "url": "https://github.com/Microsoft", - "githubUsername": "Microsoft" - }, - { - "name": "DefinitelyTyped", - "url": "https://github.com/DefinitelyTyped", - "githubUsername": "DefinitelyTyped" + "githubUsername": "Microsoft", + "url": "https://github.com/Microsoft" }, { "name": "Alberto Schiabel", - "url": "https://github.com/jkomyno", - "githubUsername": "jkomyno" + "githubUsername": "jkomyno", + "url": "https://github.com/jkomyno" }, { "name": "Alvis HT Tang", - "url": "https://github.com/alvis", - "githubUsername": "alvis" + "githubUsername": "alvis", + "url": "https://github.com/alvis" }, { "name": "Andrew Makarov", - "url": "https://github.com/r3nya", - "githubUsername": "r3nya" + "githubUsername": "r3nya", + "url": "https://github.com/r3nya" }, { "name": "Benjamin Toueg", - "url": "https://github.com/btoueg", - "githubUsername": "btoueg" + "githubUsername": "btoueg", + "url": "https://github.com/btoueg" }, { "name": "Chigozirim C.", - "url": "https://github.com/smac89", - "githubUsername": "smac89" + "githubUsername": "smac89", + "url": "https://github.com/smac89" }, { "name": "David Junger", - "url": "https://github.com/touffy", - "githubUsername": "touffy" + "githubUsername": "touffy", + "url": "https://github.com/touffy" }, { "name": "Deividas Bakanas", - "url": "https://github.com/DeividasBakanas", - "githubUsername": "DeividasBakanas" + "githubUsername": "DeividasBakanas", + "url": "https://github.com/DeividasBakanas" }, { "name": "Eugene Y. Q. Shen", - "url": "https://github.com/eyqs", - "githubUsername": "eyqs" + "githubUsername": "eyqs", + "url": "https://github.com/eyqs" }, { "name": "Hannes Magnusson", - "url": "https://github.com/Hannes-Magnusson-CK", - "githubUsername": "Hannes-Magnusson-CK" + "githubUsername": "Hannes-Magnusson-CK", + "url": "https://github.com/Hannes-Magnusson-CK" }, { "name": "Huw", - "url": "https://github.com/hoo29", - "githubUsername": "hoo29" + "githubUsername": "hoo29", + "url": "https://github.com/hoo29" }, { "name": "Kelvin Jin", - "url": "https://github.com/kjin", - "githubUsername": "kjin" + "githubUsername": "kjin", + "url": "https://github.com/kjin" }, { "name": "Klaus Meinhardt", - "url": "https://github.com/ajafff", - "githubUsername": "ajafff" + "githubUsername": "ajafff", + "url": "https://github.com/ajafff" }, { "name": "Lishude", - "url": "https://github.com/islishude", - "githubUsername": "islishude" + "githubUsername": "islishude", + "url": "https://github.com/islishude" }, { "name": "Mariusz Wiktorczyk", - "url": "https://github.com/mwiktorczyk", - "githubUsername": "mwiktorczyk" + "githubUsername": "mwiktorczyk", + "url": "https://github.com/mwiktorczyk" }, { "name": "Mohsen Azimi", - "url": "https://github.com/mohsen1", - "githubUsername": "mohsen1" + "githubUsername": "mohsen1", + "url": "https://github.com/mohsen1" }, { "name": "Nicolas Even", - "url": "https://github.com/n-e", - "githubUsername": "n-e" + "githubUsername": "n-e", + "url": "https://github.com/n-e" }, { "name": "Nikita Galkin", - "url": "https://github.com/galkin", - "githubUsername": "galkin" + "githubUsername": "galkin", + "url": "https://github.com/galkin" }, { "name": "Parambir Singh", - "url": "https://github.com/parambirs", - "githubUsername": "parambirs" + "githubUsername": "parambirs", + "url": "https://github.com/parambirs" }, { "name": "Sebastian Silbermann", - "url": "https://github.com/eps1lon", - "githubUsername": "eps1lon" - }, - { - "name": "Seth Westphal", - "url": "https://github.com/westy92", - "githubUsername": "westy92" - }, - { - "name": "Simon Schick", - "url": "https://github.com/SimonSchick", - "githubUsername": "SimonSchick" + "githubUsername": "eps1lon", + "url": "https://github.com/eps1lon" }, { "name": "Thomas den Hollander", - "url": "https://github.com/ThomasdenH", - "githubUsername": "ThomasdenH" + "githubUsername": "ThomasdenH", + "url": "https://github.com/ThomasdenH" }, { "name": "Wilco Bakker", - "url": "https://github.com/WilcoBakker", - "githubUsername": "WilcoBakker" + "githubUsername": "WilcoBakker", + "url": "https://github.com/WilcoBakker" }, { "name": "wwwy3y3", - "url": "https://github.com/wwwy3y3", - "githubUsername": "wwwy3y3" + "githubUsername": "wwwy3y3", + "url": "https://github.com/wwwy3y3" }, { "name": "Samuel Ainsworth", - "url": "https://github.com/samuela", - "githubUsername": "samuela" + "githubUsername": "samuela", + "url": "https://github.com/samuela" }, { "name": "Kyle Uehlein", - "url": "https://github.com/kuehlein", - "githubUsername": "kuehlein" + "githubUsername": "kuehlein", + "url": "https://github.com/kuehlein" }, { "name": "Thanik Bhongbhibhat", - "url": "https://github.com/bhongy", - "githubUsername": "bhongy" + "githubUsername": "bhongy", + "url": "https://github.com/bhongy" }, { "name": "Marcin Kopacz", - "url": "https://github.com/chyzwar", - "githubUsername": "chyzwar" + "githubUsername": "chyzwar", + "url": "https://github.com/chyzwar" }, { "name": "Trivikram Kamat", - "url": "https://github.com/trivikr", - "githubUsername": "trivikr" + "githubUsername": "trivikr", + "url": "https://github.com/trivikr" }, { "name": "Junxiao Shi", - "url": "https://github.com/yoursunny", - "githubUsername": "yoursunny" + "githubUsername": "yoursunny", + "url": "https://github.com/yoursunny" }, { "name": "Ilia Baryshnikov", - "url": "https://github.com/qwelias", - "githubUsername": "qwelias" + "githubUsername": "qwelias", + "url": "https://github.com/qwelias" }, { "name": "ExE Boss", - "url": "https://github.com/ExE-Boss", - "githubUsername": "ExE-Boss" + "githubUsername": "ExE-Boss", + "url": "https://github.com/ExE-Boss" }, { "name": "Piotr Błażejewicz", - "url": "https://github.com/peterblazejewicz", - "githubUsername": "peterblazejewicz" + "githubUsername": "peterblazejewicz", + "url": "https://github.com/peterblazejewicz" }, { "name": "Anna Henningsen", - "url": "https://github.com/addaleax", - "githubUsername": "addaleax" + "githubUsername": "addaleax", + "url": "https://github.com/addaleax" }, { "name": "Victor Perin", - "url": "https://github.com/victorperin", - "githubUsername": "victorperin" + "githubUsername": "victorperin", + "url": "https://github.com/victorperin" }, { "name": "Yongsheng Zhang", - "url": "https://github.com/ZYSzys", - "githubUsername": "ZYSzys" + "githubUsername": "ZYSzys", + "url": "https://github.com/ZYSzys" }, { "name": "NodeJS Contributors", - "url": "https://github.com/NodeJS", - "githubUsername": "NodeJS" + "githubUsername": "NodeJS", + "url": "https://github.com/NodeJS" }, { "name": "Linus Unnebäck", - "url": "https://github.com/LinusU", - "githubUsername": "LinusU" + "githubUsername": "LinusU", + "url": "https://github.com/LinusU" }, { "name": "wafuwafu13", - "url": "https://github.com/wafuwafu13", - "githubUsername": "wafuwafu13" + "githubUsername": "wafuwafu13", + "url": "https://github.com/wafuwafu13" + }, + { + "name": "Matteo Collina", + "githubUsername": "mcollina", + "url": "https://github.com/mcollina" + }, + { + "name": "Dmitry Semigradsky", + "githubUsername": "Semigradsky", + "url": "https://github.com/Semigradsky" } ], "main": "", "types": "index.d.ts", "typesVersions": { - "<4.9.0-0": { + "<=4.8": { "*": [ "ts4.8/*" ] @@ -226,7 +221,10 @@ "directory": "types/node" }, "scripts": {}, - "dependencies": {}, - "typesPublisherContentHash": "ee1afca298a6f737a7b417dcc5bdf25fb305bf10e06a5b5b5becdb6cde8ee564", - "typeScriptVersion": "4.1" + "dependencies": { + "undici-types": "~5.26.4" + }, + "typesPublisherContentHash": "4672df994f41fe8261bb8674f0ae453a191329e23938a5bf005572caa3a878fc", + "typeScriptVersion": "4.6", + "nonNpm": true } \ No newline at end of file diff --git a/node_modules/@types/node/path.d.ts b/node_modules/@types/node/path.d.ts old mode 100755 new mode 100644 index a647f13..6f07681 --- a/node_modules/@types/node/path.d.ts +++ b/node_modules/@types/node/path.d.ts @@ -1,21 +1,21 @@ -declare module 'path/posix' { - import path = require('path'); +declare module "path/posix" { + import path = require("path"); export = path; } -declare module 'path/win32' { - import path = require('path'); +declare module "path/win32" { + import path = require("path"); export = path; } /** - * The `path` module provides utilities for working with file and directory paths. - * It can be accessed using: + * The `node:path` module provides utilities for working with file and directory + * paths. It can be accessed using: * * ```js - * const path = require('path'); + * const path = require('node:path'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/path.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/path.js) */ -declare module 'path' { +declare module "path" { namespace path { /** * A parsed path object generated by path.parse() or consumed by path.format(). @@ -90,7 +90,7 @@ declare module 'path' { * the current working directory is used as well. The resulting path is normalized, * and trailing slashes are removed unless the path gets resolved to the root directory. * - * @param paths string paths to join. + * @param paths A sequence of paths or path segments. * @throws {TypeError} if any of the arguments is not a string. */ resolve(...paths: string[]): string; @@ -122,10 +122,10 @@ declare module 'path' { * Often used to extract the file name from a fully qualified path. * * @param path the path to evaluate. - * @param ext optionally, an extension to remove from the result. + * @param suffix optionally, an extension to remove from the result. * @throws {TypeError} if `path` is not a string or if `ext` is given and is not a string. */ - basename(path: string, ext?: string): string; + basename(path: string, suffix?: string): string; /** * Return the extension of the path, from the last '.' to end of string in the last portion of the path. * If there is no '.' in the last portion of the path or the first character of it is '.', then it returns an empty string. @@ -137,11 +137,11 @@ declare module 'path' { /** * The platform-specific file separator. '\\' or '/'. */ - readonly sep: '\\' | '/'; + readonly sep: "\\" | "/"; /** * The platform-specific file delimiter. ';' or ':'. */ - readonly delimiter: ';' | ':'; + readonly delimiter: ";" | ":"; /** * Returns an object from a path string - the opposite of format(). * @@ -177,15 +177,15 @@ declare module 'path' { const path: path.PlatformPath; export = path; } -declare module 'node:path' { - import path = require('path'); +declare module "node:path" { + import path = require("path"); export = path; } -declare module 'node:path/posix' { - import path = require('path/posix'); +declare module "node:path/posix" { + import path = require("path/posix"); export = path; } -declare module 'node:path/win32' { - import path = require('path/win32'); +declare module "node:path/win32" { + import path = require("path/win32"); export = path; } diff --git a/node_modules/@types/node/perf_hooks.d.ts b/node_modules/@types/node/perf_hooks.d.ts old mode 100755 new mode 100644 index 6d57bb7..c0ce852 --- a/node_modules/@types/node/perf_hooks.d.ts +++ b/node_modules/@types/node/perf_hooks.d.ts @@ -7,9 +7,10 @@ * * [High Resolution Time](https://www.w3.org/TR/hr-time-2) * * [Performance Timeline](https://w3c.github.io/performance-timeline/) * * [User Timing](https://www.w3.org/TR/user-timing/) + * * [Resource Timing](https://www.w3.org/TR/resource-timing-2/) * * ```js - * const { PerformanceObserver, performance } = require('perf_hooks'); + * const { PerformanceObserver, performance } = require('node:perf_hooks'); * * const obs = new PerformanceObserver((items) => { * console.log(items.getEntries()[0].duration); @@ -26,11 +27,11 @@ * performance.measure('A to B', 'A', 'B'); * }); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/perf_hooks.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/perf_hooks.js) */ -declare module 'perf_hooks' { - import { AsyncResource } from 'node:async_hooks'; - type EntryType = 'node' | 'mark' | 'measure' | 'gc' | 'function' | 'http2' | 'http'; +declare module "perf_hooks" { + import { AsyncResource } from "node:async_hooks"; + type EntryType = "node" | "mark" | "measure" | "gc" | "function" | "http2" | "http" | "dns" | "net"; interface NodeGCPerformanceDetail { /** * When `performanceEntry.entryType` is equal to 'gc', `the performance.kind` property identifies @@ -46,6 +47,7 @@ declare module 'perf_hooks' { readonly flags?: number | undefined; } /** + * The constructor of this class is not exposed to users directly. * @since v8.5.0 */ class PerformanceEntry { @@ -85,6 +87,24 @@ declare module 'perf_hooks' { * @since v16.0.0 */ readonly detail?: NodeGCPerformanceDetail | unknown | undefined; // TODO: Narrow this based on entry type. + toJSON(): any; + } + /** + * Exposes marks created via the `Performance.mark()` method. + * @since v18.2.0, v16.17.0 + */ + class PerformanceMark extends PerformanceEntry { + readonly duration: 0; + readonly entryType: "mark"; + } + /** + * Exposes measures created via the `Performance.measure()` method. + * + * The constructor of this class is not exposed to users directly. + * @since v18.2.0, v16.17.0 + */ + class PerformanceMeasure extends PerformanceEntry { + readonly entryType: "measure"; } /** * _This property is an extension by Node.js. It is not available in Web browsers._ @@ -146,7 +166,10 @@ declare module 'perf_hooks' { * @param util1 The result of a previous call to eventLoopUtilization() * @param util2 The result of a previous call to eventLoopUtilization() prior to util1 */ - type EventLoopUtilityFunction = (util1?: EventLoopUtilization, util2?: EventLoopUtilization) => EventLoopUtilization; + type EventLoopUtilityFunction = ( + util1?: EventLoopUtilization, + util2?: EventLoopUtilization, + ) => EventLoopUtilization; interface MarkOptions { /** * Additional optional detail to include with the mark. @@ -226,8 +249,9 @@ declare module 'perf_hooks' { * and whose performanceEntry.duration is always 0. * Performance marks are used to mark specific significant moments in the Performance Timeline. * @param name + * @return The PerformanceMark entry that was created */ - mark(name?: string, options?: MarkOptions): void; + mark(name?: string, options?: MarkOptions): PerformanceMark; /** * Creates a new PerformanceMeasure entry in the Performance Timeline. * A PerformanceMeasure is a subclass of PerformanceEntry whose performanceEntry.entryType is always 'measure', @@ -242,9 +266,10 @@ declare module 'perf_hooks' { * @param name * @param startMark * @param endMark + * @return The PerformanceMeasure entry that was created */ - measure(name: string, startMark?: string, endMark?: string): void; - measure(name: string, options: MeasureOptions): void; + measure(name: string, startMark?: string, endMark?: string): PerformanceMeasure; + measure(name: string, options: MeasureOptions): PerformanceMeasure; /** * An instance of the PerformanceNodeTiming class that provides performance metrics for specific Node.js operational milestones. */ @@ -278,8 +303,8 @@ declare module 'perf_hooks' { * ```js * const { * performance, - * PerformanceObserver - * } = require('perf_hooks'); + * PerformanceObserver, + * } = require('node:perf_hooks'); * * const obs = new PerformanceObserver((perfObserverList, observer) => { * console.log(perfObserverList.getEntries()); @@ -289,16 +314,20 @@ declare module 'perf_hooks' { * * name: 'test', * * entryType: 'mark', * * startTime: 81.465639, - * * duration: 0 + * * duration: 0, + * * detail: null * * }, * * PerformanceEntry { * * name: 'meow', * * entryType: 'mark', * * startTime: 81.860064, - * * duration: 0 + * * duration: 0, + * * detail: null * * } * * ] * + * performance.clearMarks(); + * performance.clearMeasures(); * observer.disconnect(); * }); * obs.observe({ type: 'mark' }); @@ -317,8 +346,8 @@ declare module 'perf_hooks' { * ```js * const { * performance, - * PerformanceObserver - * } = require('perf_hooks'); + * PerformanceObserver, + * } = require('node:perf_hooks'); * * const obs = new PerformanceObserver((perfObserverList, observer) => { * console.log(perfObserverList.getEntriesByName('meow')); @@ -328,7 +357,8 @@ declare module 'perf_hooks' { * * name: 'meow', * * entryType: 'mark', * * startTime: 98.545991, - * * duration: 0 + * * duration: 0, + * * detail: null * * } * * ] * @@ -341,11 +371,15 @@ declare module 'perf_hooks' { * * name: 'test', * * entryType: 'mark', * * startTime: 63.518931, - * * duration: 0 + * * duration: 0, + * * detail: null * * } * * ] * * console.log(perfObserverList.getEntriesByName('test', 'measure')); // [] + * + * performance.clearMarks(); + * performance.clearMeasures(); * observer.disconnect(); * }); * obs.observe({ entryTypes: ['mark', 'measure'] }); @@ -363,8 +397,8 @@ declare module 'perf_hooks' { * ```js * const { * performance, - * PerformanceObserver - * } = require('perf_hooks'); + * PerformanceObserver, + * } = require('node:perf_hooks'); * * const obs = new PerformanceObserver((perfObserverList, observer) => { * console.log(perfObserverList.getEntriesByType('mark')); @@ -374,16 +408,20 @@ declare module 'perf_hooks' { * * name: 'test', * * entryType: 'mark', * * startTime: 55.897834, - * * duration: 0 + * * duration: 0, + * * detail: null * * }, * * PerformanceEntry { * * name: 'meow', * * entryType: 'mark', * * startTime: 56.350146, - * * duration: 0 + * * duration: 0, + * * detail: null * * } * * ] * + * performance.clearMarks(); + * performance.clearMeasures(); * observer.disconnect(); * }); * obs.observe({ type: 'mark' }); @@ -396,6 +434,9 @@ declare module 'perf_hooks' { getEntriesByType(type: EntryType): PerformanceEntry[]; } type PerformanceObserverCallback = (list: PerformanceObserverEntryList, observer: PerformanceObserver) => void; + /** + * @since v8.5.0 + */ class PerformanceObserver extends AsyncResource { constructor(callback: PerformanceObserverCallback); /** @@ -409,11 +450,11 @@ declare module 'perf_hooks' { * ```js * const { * performance, - * PerformanceObserver - * } = require('perf_hooks'); + * PerformanceObserver, + * } = require('node:perf_hooks'); * * const obs = new PerformanceObserver((list, observer) => { - * // Called three times synchronously. `list` contains one item. + * // Called once asynchronously. `list` contains three items. * }); * obs.observe({ type: 'mark' }); * @@ -425,13 +466,13 @@ declare module 'perf_hooks' { observe( options: | { - entryTypes: ReadonlyArray; - buffered?: boolean | undefined; - } + entryTypes: readonly EntryType[]; + buffered?: boolean | undefined; + } | { - type: EntryType; - buffered?: boolean | undefined; - } + type: EntryType; + buffered?: boolean | undefined; + }, ): void; } namespace constants { @@ -516,7 +557,7 @@ declare module 'perf_hooks' { } interface RecordableHistogram extends Histogram { /** - * @since v15.9.0 + * @since v15.9.0, v14.18.0 * @param val The amount to record in the histogram. */ record(val: number | bigint): void; @@ -525,9 +566,14 @@ declare module 'perf_hooks' { * previous call to `recordDelta()` and records that amount in the histogram. * * ## Examples - * @since v15.9.0 + * @since v15.9.0, v14.18.0 */ recordDelta(): void; + /** + * Adds the values from `other` to this histogram. + * @since v17.4.0, v16.14.0 + */ + add(other: RecordableHistogram): void; } /** * _This property is an extension by Node.js. It is not available in Web browsers._ @@ -542,7 +588,7 @@ declare module 'perf_hooks' { * detect. * * ```js - * const { monitorEventLoopDelay } = require('perf_hooks'); + * const { monitorEventLoopDelay } = require('node:perf_hooks'); * const h = monitorEventLoopDelay({ resolution: 20 }); * h.enable(); * // Do something. @@ -577,10 +623,23 @@ declare module 'perf_hooks' { } /** * Returns a `RecordableHistogram`. - * @since v15.9.0 + * @since v15.9.0, v14.18.0 */ function createHistogram(options?: CreateHistogramOptions): RecordableHistogram; + import { performance as _performance } from "perf_hooks"; + global { + /** + * `performance` is a global reference for `require('perf_hooks').performance` + * https://nodejs.org/api/globals.html#performance + * @since v16.0.0 + */ + var performance: typeof globalThis extends { + onmessage: any; + performance: infer T; + } ? T + : typeof _performance; + } } -declare module 'node:perf_hooks' { - export * from 'perf_hooks'; +declare module "node:perf_hooks" { + export * from "perf_hooks"; } diff --git a/node_modules/@types/node/process.d.ts b/node_modules/@types/node/process.d.ts old mode 100755 new mode 100644 index 2d0ef86..d22308f --- a/node_modules/@types/node/process.d.ts +++ b/node_modules/@types/node/process.d.ts @@ -1,6 +1,6 @@ -declare module 'process' { - import * as tty from 'node:tty'; - import { Worker } from 'node:worker_threads'; +declare module "process" { + import * as tty from "node:tty"; + import { Worker } from "node:worker_threads"; global { var process: NodeJS.Process; namespace NodeJS { @@ -48,47 +48,70 @@ declare module 'process' { modules: string; openssl: string; } - type Platform = 'aix' | 'android' | 'darwin' | 'freebsd' | 'haiku' | 'linux' | 'openbsd' | 'sunos' | 'win32' | 'cygwin' | 'netbsd'; + type Platform = + | "aix" + | "android" + | "darwin" + | "freebsd" + | "haiku" + | "linux" + | "openbsd" + | "sunos" + | "win32" + | "cygwin" + | "netbsd"; + type Architecture = + | "arm" + | "arm64" + | "ia32" + | "mips" + | "mipsel" + | "ppc" + | "ppc64" + | "riscv64" + | "s390" + | "s390x" + | "x64"; type Signals = - | 'SIGABRT' - | 'SIGALRM' - | 'SIGBUS' - | 'SIGCHLD' - | 'SIGCONT' - | 'SIGFPE' - | 'SIGHUP' - | 'SIGILL' - | 'SIGINT' - | 'SIGIO' - | 'SIGIOT' - | 'SIGKILL' - | 'SIGPIPE' - | 'SIGPOLL' - | 'SIGPROF' - | 'SIGPWR' - | 'SIGQUIT' - | 'SIGSEGV' - | 'SIGSTKFLT' - | 'SIGSTOP' - | 'SIGSYS' - | 'SIGTERM' - | 'SIGTRAP' - | 'SIGTSTP' - | 'SIGTTIN' - | 'SIGTTOU' - | 'SIGUNUSED' - | 'SIGURG' - | 'SIGUSR1' - | 'SIGUSR2' - | 'SIGVTALRM' - | 'SIGWINCH' - | 'SIGXCPU' - | 'SIGXFSZ' - | 'SIGBREAK' - | 'SIGLOST' - | 'SIGINFO'; - type UncaughtExceptionOrigin = 'uncaughtException' | 'unhandledRejection'; - type MultipleResolveType = 'resolve' | 'reject'; + | "SIGABRT" + | "SIGALRM" + | "SIGBUS" + | "SIGCHLD" + | "SIGCONT" + | "SIGFPE" + | "SIGHUP" + | "SIGILL" + | "SIGINT" + | "SIGIO" + | "SIGIOT" + | "SIGKILL" + | "SIGPIPE" + | "SIGPOLL" + | "SIGPROF" + | "SIGPWR" + | "SIGQUIT" + | "SIGSEGV" + | "SIGSTKFLT" + | "SIGSTOP" + | "SIGSYS" + | "SIGTERM" + | "SIGTRAP" + | "SIGTSTP" + | "SIGTTIN" + | "SIGTTOU" + | "SIGUNUSED" + | "SIGURG" + | "SIGUSR1" + | "SIGUSR2" + | "SIGVTALRM" + | "SIGWINCH" + | "SIGXCPU" + | "SIGXFSZ" + | "SIGBREAK" + | "SIGLOST" + | "SIGINFO"; + type UncaughtExceptionOrigin = "uncaughtException" | "unhandledRejection"; + type MultipleResolveType = "resolve" | "reject"; type BeforeExitListener = (code: number) => void; type DisconnectListener = () => void; type ExitListener = (code: number) => void; @@ -96,13 +119,17 @@ declare module 'process' { type UncaughtExceptionListener = (error: Error, origin: UncaughtExceptionOrigin) => void; /** * Most of the time the unhandledRejection will be an Error, but this should not be relied upon - * as *anything* can be thrown/rejected, it is therefore unsafe to assume the the value is an Error. + * as *anything* can be thrown/rejected, it is therefore unsafe to assume that the value is an Error. */ type UnhandledRejectionListener = (reason: unknown, promise: Promise) => void; type WarningListener = (warning: Error) => void; type MessageListener = (message: unknown, sendHandle: unknown) => void; type SignalsListener = (signal: Signals) => void; - type MultipleResolveListener = (type: MultipleResolveType, promise: Promise, value: unknown) => void; + type MultipleResolveListener = ( + type: MultipleResolveType, + promise: Promise, + value: unknown, + ) => void; type WorkerListener = (worker: Worker) => void; interface Socket extends ReadWriteStream { isTTY?: true | undefined; @@ -249,7 +276,7 @@ declare module 'process' { * For example, to copy `process.stdin` to `process.stdout`: * * ```js - * import { stdin, stdout } from 'process'; + * import { stdin, stdout } from 'node:process'; * * stdin.pipe(stdout); * ``` @@ -296,7 +323,7 @@ declare module 'process' { * For example, assuming the following script for `process-args.js`: * * ```js - * import { argv } from 'process'; + * import { argv } from 'node:process'; * * // print process.argv * argv.forEach((val, index) => { @@ -306,8 +333,8 @@ declare module 'process' { * * Launching the Node.js process as: * - * ```console - * $ node process-args.js one two=three four + * ```bash + * node process-args.js one two=three four * ``` * * Would generate the output: @@ -343,8 +370,8 @@ declare module 'process' { * the script name. These options are useful in order to spawn child processes with * the same execution environment as the parent. * - * ```console - * $ node --harmony script.js --version + * ```bash + * node --harmony script.js --version * ``` * * Results in `process.execArgv`: @@ -388,7 +415,7 @@ declare module 'process' { * the specified `directory` does not exist). * * ```js - * import { chdir, cwd } from 'process'; + * import { chdir, cwd } from 'node:process'; * * console.log(`Starting directory: ${cwd()}`); * try { @@ -408,7 +435,7 @@ declare module 'process' { * process. * * ```js - * import { cwd } from 'process'; + * import { cwd } from 'node:process'; * * console.log(`Current directory: ${cwd()}`); * ``` @@ -419,7 +446,7 @@ declare module 'process' { * The port used by the Node.js debugger when enabled. * * ```js - * import process from 'process'; + * import process from 'node:process'; * * process.debugPort = 5858; * ``` @@ -431,12 +458,12 @@ declare module 'process' { * specific process warnings. These can be listened for by adding a handler to the `'warning'` event. * * ```js - * import { emitWarning } from 'process'; + * import { emitWarning } from 'node:process'; * * // Emit a warning with a code and additional detail. * emitWarning('Something happened!', { * code: 'MY_WARNING', - * detail: 'This is some additional information' + * detail: 'This is some additional information', * }); * // Emits: * // (node:56338) [MY_WARNING] Warning: Something happened! @@ -446,7 +473,7 @@ declare module 'process' { * In this example, an `Error` object is generated internally by`process.emitWarning()` and passed through to the `'warning'` handler. * * ```js - * import process from 'process'; + * import process from 'node:process'; * * process.on('warning', (warning) => { * console.warn(warning.name); // 'Warning' @@ -491,14 +518,14 @@ declare module 'process' { * to other `Worker` threads. * In other words, the following example would not work: * - * ```console - * $ node -e 'process.env.foo = "bar"' && echo $foo + * ```bash + * node -e 'process.env.foo = "bar"' && echo $foo * ``` * * While the following will: * * ```js - * import { env } from 'process'; + * import { env } from 'node:process'; * * env.foo = 'bar'; * console.log(env.foo); @@ -509,7 +536,7 @@ declare module 'process' { * throw an error when the value is not a string, number, or boolean. * * ```js - * import { env } from 'process'; + * import { env } from 'node:process'; * * env.test = null; * console.log(env.test); @@ -522,7 +549,7 @@ declare module 'process' { * Use `delete` to delete a property from `process.env`. * * ```js - * import { env } from 'process'; + * import { env } from 'node:process'; * * env.TEST = 1; * delete env.TEST; @@ -533,7 +560,7 @@ declare module 'process' { * On Windows operating systems, environment variables are case-insensitive. * * ```js - * import { env } from 'process'; + * import { env } from 'node:process'; * * env.TEST = 1; * console.log(env.test); @@ -542,10 +569,11 @@ declare module 'process' { * * Unless explicitly specified when creating a `Worker` instance, * each `Worker` thread has its own copy of `process.env`, based on its - * parent thread’s `process.env`, or whatever was specified as the `env` option + * parent thread's `process.env`, or whatever was specified as the `env` option * to the `Worker` constructor. Changes to `process.env` will not be visible * across `Worker` threads, and only the main thread can make changes that - * are visible to the operating system or to native add-ons. + * are visible to the operating system or to native add-ons. On Windows, a copy of`process.env` on a `Worker` instance operates in a case-sensitive manner + * unlike the main thread. * @since v0.1.27 */ env: ProcessEnv; @@ -559,7 +587,7 @@ declare module 'process' { * To exit with a 'failure' code: * * ```js - * import { exit } from 'process'; + * import { exit } from 'node:process'; * * exit(1); * ``` @@ -578,7 +606,7 @@ declare module 'process' { * truncated and lost: * * ```js - * import { exit } from 'process'; + * import { exit } from 'node:process'; * * // This is an example of what *not* to do: * if (someConditionNotMet()) { @@ -589,13 +617,13 @@ declare module 'process' { * * The reason this is problematic is because writes to `process.stdout` in Node.js * are sometimes _asynchronous_ and may occur over multiple ticks of the Node.js - * event loop. Calling `process.exit()`, however, forces the process to exit_before_ those additional writes to `stdout` can be performed. + * event loop. Calling `process.exit()`, however, forces the process to exit _before_ those additional writes to `stdout` can be performed. * * Rather than calling `process.exit()` directly, the code _should_ set the`process.exitCode` and allow the process to exit naturally by avoiding * scheduling any additional work for the event loop: * * ```js - * import process from 'process'; + * import process from 'node:process'; * * // How to properly set the exit code while letting * // the process exit gracefully. @@ -612,7 +640,7 @@ declare module 'process' { * In `Worker` threads, this function stops the current thread rather * than the current process. * @since v0.1.13 - * @param [code=0] The exit code. + * @param [code=0] The exit code. For string type, only integer strings (e.g.,'1') are allowed. */ exit(code?: number): never; /** @@ -641,7 +669,7 @@ declare module 'process' { * Android). * @since v0.1.31 */ - getgid(): number; + getgid?: () => number; /** * The `process.setgid()` method sets the group identity of the process. (See [`setgid(2)`](http://man7.org/linux/man-pages/man2/setgid.2.html).) The `id` can be passed as either a * numeric ID or a group name @@ -668,7 +696,7 @@ declare module 'process' { * @since v0.1.31 * @param id The group name or ID */ - setgid(id: number | string): void; + setgid?: (id: number | string) => void; /** * The `process.getuid()` method returns the numeric user identity of the process. * (See [`getuid(2)`](http://man7.org/linux/man-pages/man2/getuid.2.html).) @@ -685,7 +713,7 @@ declare module 'process' { * Android). * @since v0.1.28 */ - getuid(): number; + getuid?: () => number; /** * The `process.setuid(id)` method sets the user identity of the process. (See [`setuid(2)`](http://man7.org/linux/man-pages/man2/setuid.2.html).) The `id` can be passed as either a * numeric ID or a username string. @@ -711,7 +739,7 @@ declare module 'process' { * This feature is not available in `Worker` threads. * @since v0.1.28 */ - setuid(id: number | string): void; + setuid?: (id: number | string) => void; /** * The `process.geteuid()` method returns the numerical effective user identity of * the process. (See [`geteuid(2)`](http://man7.org/linux/man-pages/man2/geteuid.2.html).) @@ -728,7 +756,7 @@ declare module 'process' { * Android). * @since v2.0.0 */ - geteuid(): number; + geteuid?: () => number; /** * The `process.seteuid()` method sets the effective user identity of the process. * (See [`seteuid(2)`](http://man7.org/linux/man-pages/man2/seteuid.2.html).) The `id` can be passed as either a numeric ID or a username @@ -755,7 +783,7 @@ declare module 'process' { * @since v2.0.0 * @param id A user name or ID */ - seteuid(id: number | string): void; + seteuid?: (id: number | string) => void; /** * The `process.getegid()` method returns the numerical effective group identity * of the Node.js process. (See [`getegid(2)`](http://man7.org/linux/man-pages/man2/getegid.2.html).) @@ -772,7 +800,7 @@ declare module 'process' { * Android). * @since v2.0.0 */ - getegid(): number; + getegid?: () => number; /** * The `process.setegid()` method sets the effective group identity of the process. * (See [`setegid(2)`](http://man7.org/linux/man-pages/man2/setegid.2.html).) The `id` can be passed as either a numeric ID or a group @@ -799,7 +827,7 @@ declare module 'process' { * @since v2.0.0 * @param id A group name or ID */ - setegid(id: number | string): void; + setegid?: (id: number | string) => void; /** * The `process.getgroups()` method returns an array with the supplementary group * IDs. POSIX leaves it unspecified if the effective group ID is included but @@ -817,7 +845,7 @@ declare module 'process' { * Android). * @since v0.9.4 */ - getgroups(): number[]; + getgroups?: () => number[]; /** * The `process.setgroups()` method sets the supplementary group IDs for the * Node.js process. This is a privileged operation that requires the Node.js @@ -843,7 +871,7 @@ declare module 'process' { * This feature is not available in `Worker` threads. * @since v0.9.4 */ - setgroups(groups: ReadonlyArray): void; + setgroups?: (groups: ReadonlyArray) => void; /** * The `process.setUncaughtExceptionCaptureCallback()` function sets a function * that will be invoked when an uncaught exception occurs, which will receive the @@ -868,11 +896,29 @@ declare module 'process' { * @since v9.3.0 */ hasUncaughtExceptionCaptureCallback(): boolean; + /** + * The `process.sourceMapsEnabled` property returns whether the [Source Map v3](https://sourcemaps.info/spec.html) support for stack traces is enabled. + * @since v20.7.0 + * @experimental + */ + readonly sourceMapsEnabled: boolean; + /** + * This function enables or disables the [Source Map v3](https://sourcemaps.info/spec.html) support for + * stack traces. + * + * It provides same features as launching Node.js process with commandline options`--enable-source-maps`. + * + * Only source maps in JavaScript files that are loaded after source maps has been + * enabled will be parsed and loaded. + * @since v16.6.0, v14.18.0 + * @experimental + */ + setSourceMapsEnabled(value: boolean): void; /** * The `process.version` property contains the Node.js version string. * * ```js - * import { version } from 'process'; + * import { version } from 'node:process'; * * console.log(`Version: ${version}`); * // Version: v14.8.0 @@ -889,7 +935,7 @@ declare module 'process' { * to load modules that were compiled against a different module ABI version. * * ```js - * import { versions } from 'process'; + * import { versions } from 'node:process'; * * console.log(versions); * ``` @@ -897,30 +943,39 @@ declare module 'process' { * Will generate an object similar to: * * ```console - * { node: '11.13.0', - * v8: '7.0.276.38-node.18', - * uv: '1.27.0', - * zlib: '1.2.11', - * brotli: '1.0.7', - * ares: '1.15.0', - * modules: '67', - * nghttp2: '1.34.0', - * napi: '4', - * llhttp: '1.1.1', - * openssl: '1.1.1b', - * cldr: '34.0', - * icu: '63.1', - * tz: '2018e', - * unicode: '11.0' } + * { node: '20.2.0', + * acorn: '8.8.2', + * ada: '2.4.0', + * ares: '1.19.0', + * base64: '0.5.0', + * brotli: '1.0.9', + * cjs_module_lexer: '1.2.2', + * cldr: '43.0', + * icu: '73.1', + * llhttp: '8.1.0', + * modules: '115', + * napi: '8', + * nghttp2: '1.52.0', + * nghttp3: '0.7.0', + * ngtcp2: '0.8.1', + * openssl: '3.0.8+quic', + * simdutf: '3.2.9', + * tz: '2023c', + * undici: '5.22.0', + * unicode: '15.0', + * uv: '1.44.2', + * uvwasi: '0.0.16', + * v8: '11.3.244.8-node.9', + * zlib: '1.2.13' } * ``` * @since v0.2.0 */ readonly versions: ProcessVersions; /** - * The `process.config` property returns an `Object` containing the JavaScript - * representation of the configure options used to compile the current Node.js - * executable. This is the same as the `config.gypi` file that was produced when - * running the `./configure` script. + * The `process.config` property returns a frozen `Object` containing the + * JavaScript representation of the configure options used to compile the current + * Node.js executable. This is the same as the `config.gypi` file that was produced + * when running the `./configure` script. * * An example of the possible output looks like: * @@ -942,7 +997,6 @@ declare module 'process' { * node_shared_http_parser: 'false', * node_shared_libuv: 'false', * node_shared_zlib: 'false', - * node_use_dtrace: 'false', * node_use_openssl: 'true', * node_shared_openssl: 'false', * strict_aliasing: 'true', @@ -951,13 +1005,6 @@ declare module 'process' { * } * } * ``` - * - * The `process.config` property is **not** read-only and there are existing - * modules in the ecosystem that are known to extend, modify, or entirely replace - * the value of `process.config`. - * - * Modifying the `process.config` property, or any child-property of the`process.config` object has been deprecated. The `process.config` will be made - * read-only in a future release. * @since v0.7.7 */ readonly config: ProcessConfig; @@ -976,7 +1023,7 @@ declare module 'process' { * other than kill the target process. * * ```js - * import process, { kill } from 'process'; + * import process, { kill } from 'node:process'; * * process.on('SIGHUP', () => { * console.log('Got SIGHUP signal.'); @@ -1001,7 +1048,7 @@ declare module 'process' { * The `process.pid` property returns the PID of the process. * * ```js - * import { pid } from 'process'; + * import { pid } from 'node:process'; * * console.log(`This process is pid ${pid}`); * ``` @@ -1013,7 +1060,7 @@ declare module 'process' { * current process. * * ```js - * import { ppid } from 'process'; + * import { ppid } from 'node:process'; * * console.log(`The parent process is pid ${ppid}`); * ``` @@ -1040,19 +1087,19 @@ declare module 'process' { title: string; /** * The operating system CPU architecture for which the Node.js binary was compiled. - * Possible values are: `'arm'`, `'arm64'`, `'ia32'`, `'mips'`,`'mipsel'`, `'ppc'`,`'ppc64'`, `'s390'`, `'s390x'`, `'x32'`, and `'x64'`. + * Possible values are: `'arm'`, `'arm64'`, `'ia32'`, `'loong64'`, `'mips'`,`'mipsel'`, `'ppc'`, `'ppc64'`, `'riscv64'`, `'s390'`, `'s390x'`, and `'x64'`. * * ```js - * import { arch } from 'process'; + * import { arch } from 'node:process'; * * console.log(`This processor architecture is ${arch}`); * ``` * @since v0.5.0 */ - readonly arch: string; + readonly arch: Architecture; /** * The `process.platform` property returns a string identifying the operating - * system platform on which the Node.js process is running. + * system platform for which the Node.js binary was compiled. * * Currently possible values are: * @@ -1065,7 +1112,7 @@ declare module 'process' { * * `'win32'` * * ```js - * import { platform } from 'process'; + * import { platform } from 'node:process'; * * console.log(`This platform is ${platform}`); * ``` @@ -1088,6 +1135,17 @@ declare module 'process' { */ mainModule?: Module | undefined; memoryUsage: MemoryUsageFn; + /** + * Gets the amount of memory available to the process (in bytes) based on + * limits imposed by the OS. If there is no such constraint, or the constraint + * is unknown, `undefined` is returned. + * + * See [`uv_get_constrained_memory`](https://docs.libuv.org/en/v1.x/misc.html#c.uv_get_constrained_memory) for more + * information. + * @since v19.6.0, v18.15.0 + * @experimental + */ + constrainedMemory(): number | undefined; /** * The `process.cpuUsage()` method returns the user and system CPU time usage of * the current process, in an object with properties `user` and `system`, whose @@ -1099,7 +1157,7 @@ declare module 'process' { * argument to the function, to get a diff reading. * * ```js - * import { cpuUsage } from 'process'; + * import { cpuUsage } from 'node:process'; * * const startUsage = cpuUsage(); * // { user: 38579, system: 6986 } @@ -1123,7 +1181,7 @@ declare module 'process' { * See the [Event Loop](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/#process-nexttick) guide for more background. * * ```js - * import { nextTick } from 'process'; + * import { nextTick } from 'node:process'; * * console.log('start'); * nextTick(() => { @@ -1141,7 +1199,7 @@ declare module 'process' { * I/O has occurred: * * ```js - * import { nextTick } from 'process'; + * import { nextTick } from 'node:process'; * * function MyThing(options) { * this.setupOptions(options); @@ -1189,7 +1247,7 @@ declare module 'process' { * The following approach is much better: * * ```js - * import { nextTick } from 'process'; + * import { nextTick } from 'node:process'; * * function definitelyAsync(arg, cb) { * if (arg) { @@ -1214,10 +1272,10 @@ declare module 'process' { * ```js * { * name: 'node', - * lts: 'Erbium', - * sourceUrl: 'https://nodejs.org/download/release/v12.18.1/node-v12.18.1.tar.gz', - * headersUrl: 'https://nodejs.org/download/release/v12.18.1/node-v12.18.1-headers.tar.gz', - * libUrl: 'https://nodejs.org/download/release/v12.18.1/win-x64/node.lib' + * lts: 'Hydrogen', + * sourceUrl: 'https://nodejs.org/download/release/v18.12.0/node-v18.12.0.tar.gz', + * headersUrl: 'https://nodejs.org/download/release/v18.12.0/node-v18.12.0-headers.tar.gz', + * libUrl: 'https://nodejs.org/download/release/v18.12.0/win-x64/node.lib' * } * ``` * @@ -1258,11 +1316,28 @@ declare module 'process' { */ uptime(): number; hrtime: HRTime; + /** + * If the Node.js process was spawned with an IPC channel, the process.channel property is a reference to the IPC channel. + * If no IPC channel exists, this property is undefined. + * @since v7.1.0 + */ + channel?: { + /** + * This method makes the IPC channel keep the event loop of the process running if .unref() has been called before. + * @since v7.1.0 + */ + ref(): void; + /** + * This method makes the IPC channel not keep the event loop of the process running, and lets it finish even while the channel is open. + * @since v7.1.0 + */ + unref(): void; + }; /** * If Node.js is spawned with an IPC channel, the `process.send()` method can be * used to send messages to the parent process. Messages will be received as a `'message'` event on the parent's `ChildProcess` object. * - * If Node.js was not spawned with an IPC channel, `process.send` will be`undefined`. + * If Node.js was not spawned with an IPC channel, `process.send` will be `undefined`. * * The message goes through serialization and parsing. The resulting message might * not be the same as what is originally sent. @@ -1275,7 +1350,7 @@ declare module 'process' { options?: { swallowErrors?: boolean | undefined; }, - callback?: (error: Error | null) => void + callback?: (error: Error | null) => void, ): boolean; /** * If the Node.js process is spawned with an IPC channel (see the `Child Process` and `Cluster` documentation), the `process.disconnect()` method will close the @@ -1321,7 +1396,7 @@ declare module 'process' { * dashes: * * ```js - * import { allowedNodeEnvironmentFlags } from 'process'; + * import { allowedNodeEnvironmentFlags } from 'node:process'; * * allowedNodeEnvironmentFlags.forEach((flag) => { * // -r @@ -1347,7 +1422,7 @@ declare module 'process' { report?: ProcessReport | undefined; /** * ```js - * import { resourceUsage } from 'process'; + * import { resourceUsage } from 'node:process'; * * console.log(resourceUsage()); * /* @@ -1384,98 +1459,103 @@ declare module 'process' { */ traceDeprecation: boolean; /* EventEmitter */ - addListener(event: 'beforeExit', listener: BeforeExitListener): this; - addListener(event: 'disconnect', listener: DisconnectListener): this; - addListener(event: 'exit', listener: ExitListener): this; - addListener(event: 'rejectionHandled', listener: RejectionHandledListener): this; - addListener(event: 'uncaughtException', listener: UncaughtExceptionListener): this; - addListener(event: 'uncaughtExceptionMonitor', listener: UncaughtExceptionListener): this; - addListener(event: 'unhandledRejection', listener: UnhandledRejectionListener): this; - addListener(event: 'warning', listener: WarningListener): this; - addListener(event: 'message', listener: MessageListener): this; + addListener(event: "beforeExit", listener: BeforeExitListener): this; + addListener(event: "disconnect", listener: DisconnectListener): this; + addListener(event: "exit", listener: ExitListener): this; + addListener(event: "rejectionHandled", listener: RejectionHandledListener): this; + addListener(event: "uncaughtException", listener: UncaughtExceptionListener): this; + addListener(event: "uncaughtExceptionMonitor", listener: UncaughtExceptionListener): this; + addListener(event: "unhandledRejection", listener: UnhandledRejectionListener): this; + addListener(event: "warning", listener: WarningListener): this; + addListener(event: "message", listener: MessageListener): this; addListener(event: Signals, listener: SignalsListener): this; - addListener(event: 'multipleResolves', listener: MultipleResolveListener): this; - addListener(event: 'worker', listener: WorkerListener): this; - emit(event: 'beforeExit', code: number): boolean; - emit(event: 'disconnect'): boolean; - emit(event: 'exit', code: number): boolean; - emit(event: 'rejectionHandled', promise: Promise): boolean; - emit(event: 'uncaughtException', error: Error): boolean; - emit(event: 'uncaughtExceptionMonitor', error: Error): boolean; - emit(event: 'unhandledRejection', reason: unknown, promise: Promise): boolean; - emit(event: 'warning', warning: Error): boolean; - emit(event: 'message', message: unknown, sendHandle: unknown): this; - emit(event: Signals, signal: Signals): boolean; - emit(event: 'multipleResolves', type: MultipleResolveType, promise: Promise, value: unknown): this; - emit(event: 'worker', listener: WorkerListener): this; - on(event: 'beforeExit', listener: BeforeExitListener): this; - on(event: 'disconnect', listener: DisconnectListener): this; - on(event: 'exit', listener: ExitListener): this; - on(event: 'rejectionHandled', listener: RejectionHandledListener): this; - on(event: 'uncaughtException', listener: UncaughtExceptionListener): this; - on(event: 'uncaughtExceptionMonitor', listener: UncaughtExceptionListener): this; - on(event: 'unhandledRejection', listener: UnhandledRejectionListener): this; - on(event: 'warning', listener: WarningListener): this; - on(event: 'message', listener: MessageListener): this; + addListener(event: "multipleResolves", listener: MultipleResolveListener): this; + addListener(event: "worker", listener: WorkerListener): this; + emit(event: "beforeExit", code: number): boolean; + emit(event: "disconnect"): boolean; + emit(event: "exit", code: number): boolean; + emit(event: "rejectionHandled", promise: Promise): boolean; + emit(event: "uncaughtException", error: Error): boolean; + emit(event: "uncaughtExceptionMonitor", error: Error): boolean; + emit(event: "unhandledRejection", reason: unknown, promise: Promise): boolean; + emit(event: "warning", warning: Error): boolean; + emit(event: "message", message: unknown, sendHandle: unknown): this; + emit(event: Signals, signal?: Signals): boolean; + emit( + event: "multipleResolves", + type: MultipleResolveType, + promise: Promise, + value: unknown, + ): this; + emit(event: "worker", listener: WorkerListener): this; + on(event: "beforeExit", listener: BeforeExitListener): this; + on(event: "disconnect", listener: DisconnectListener): this; + on(event: "exit", listener: ExitListener): this; + on(event: "rejectionHandled", listener: RejectionHandledListener): this; + on(event: "uncaughtException", listener: UncaughtExceptionListener): this; + on(event: "uncaughtExceptionMonitor", listener: UncaughtExceptionListener): this; + on(event: "unhandledRejection", listener: UnhandledRejectionListener): this; + on(event: "warning", listener: WarningListener): this; + on(event: "message", listener: MessageListener): this; on(event: Signals, listener: SignalsListener): this; - on(event: 'multipleResolves', listener: MultipleResolveListener): this; - on(event: 'worker', listener: WorkerListener): this; + on(event: "multipleResolves", listener: MultipleResolveListener): this; + on(event: "worker", listener: WorkerListener): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'beforeExit', listener: BeforeExitListener): this; - once(event: 'disconnect', listener: DisconnectListener): this; - once(event: 'exit', listener: ExitListener): this; - once(event: 'rejectionHandled', listener: RejectionHandledListener): this; - once(event: 'uncaughtException', listener: UncaughtExceptionListener): this; - once(event: 'uncaughtExceptionMonitor', listener: UncaughtExceptionListener): this; - once(event: 'unhandledRejection', listener: UnhandledRejectionListener): this; - once(event: 'warning', listener: WarningListener): this; - once(event: 'message', listener: MessageListener): this; + once(event: "beforeExit", listener: BeforeExitListener): this; + once(event: "disconnect", listener: DisconnectListener): this; + once(event: "exit", listener: ExitListener): this; + once(event: "rejectionHandled", listener: RejectionHandledListener): this; + once(event: "uncaughtException", listener: UncaughtExceptionListener): this; + once(event: "uncaughtExceptionMonitor", listener: UncaughtExceptionListener): this; + once(event: "unhandledRejection", listener: UnhandledRejectionListener): this; + once(event: "warning", listener: WarningListener): this; + once(event: "message", listener: MessageListener): this; once(event: Signals, listener: SignalsListener): this; - once(event: 'multipleResolves', listener: MultipleResolveListener): this; - once(event: 'worker', listener: WorkerListener): this; + once(event: "multipleResolves", listener: MultipleResolveListener): this; + once(event: "worker", listener: WorkerListener): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'beforeExit', listener: BeforeExitListener): this; - prependListener(event: 'disconnect', listener: DisconnectListener): this; - prependListener(event: 'exit', listener: ExitListener): this; - prependListener(event: 'rejectionHandled', listener: RejectionHandledListener): this; - prependListener(event: 'uncaughtException', listener: UncaughtExceptionListener): this; - prependListener(event: 'uncaughtExceptionMonitor', listener: UncaughtExceptionListener): this; - prependListener(event: 'unhandledRejection', listener: UnhandledRejectionListener): this; - prependListener(event: 'warning', listener: WarningListener): this; - prependListener(event: 'message', listener: MessageListener): this; + prependListener(event: "beforeExit", listener: BeforeExitListener): this; + prependListener(event: "disconnect", listener: DisconnectListener): this; + prependListener(event: "exit", listener: ExitListener): this; + prependListener(event: "rejectionHandled", listener: RejectionHandledListener): this; + prependListener(event: "uncaughtException", listener: UncaughtExceptionListener): this; + prependListener(event: "uncaughtExceptionMonitor", listener: UncaughtExceptionListener): this; + prependListener(event: "unhandledRejection", listener: UnhandledRejectionListener): this; + prependListener(event: "warning", listener: WarningListener): this; + prependListener(event: "message", listener: MessageListener): this; prependListener(event: Signals, listener: SignalsListener): this; - prependListener(event: 'multipleResolves', listener: MultipleResolveListener): this; - prependListener(event: 'worker', listener: WorkerListener): this; - prependOnceListener(event: 'beforeExit', listener: BeforeExitListener): this; - prependOnceListener(event: 'disconnect', listener: DisconnectListener): this; - prependOnceListener(event: 'exit', listener: ExitListener): this; - prependOnceListener(event: 'rejectionHandled', listener: RejectionHandledListener): this; - prependOnceListener(event: 'uncaughtException', listener: UncaughtExceptionListener): this; - prependOnceListener(event: 'uncaughtExceptionMonitor', listener: UncaughtExceptionListener): this; - prependOnceListener(event: 'unhandledRejection', listener: UnhandledRejectionListener): this; - prependOnceListener(event: 'warning', listener: WarningListener): this; - prependOnceListener(event: 'message', listener: MessageListener): this; + prependListener(event: "multipleResolves", listener: MultipleResolveListener): this; + prependListener(event: "worker", listener: WorkerListener): this; + prependOnceListener(event: "beforeExit", listener: BeforeExitListener): this; + prependOnceListener(event: "disconnect", listener: DisconnectListener): this; + prependOnceListener(event: "exit", listener: ExitListener): this; + prependOnceListener(event: "rejectionHandled", listener: RejectionHandledListener): this; + prependOnceListener(event: "uncaughtException", listener: UncaughtExceptionListener): this; + prependOnceListener(event: "uncaughtExceptionMonitor", listener: UncaughtExceptionListener): this; + prependOnceListener(event: "unhandledRejection", listener: UnhandledRejectionListener): this; + prependOnceListener(event: "warning", listener: WarningListener): this; + prependOnceListener(event: "message", listener: MessageListener): this; prependOnceListener(event: Signals, listener: SignalsListener): this; - prependOnceListener(event: 'multipleResolves', listener: MultipleResolveListener): this; - prependOnceListener(event: 'worker', listener: WorkerListener): this; - listeners(event: 'beforeExit'): BeforeExitListener[]; - listeners(event: 'disconnect'): DisconnectListener[]; - listeners(event: 'exit'): ExitListener[]; - listeners(event: 'rejectionHandled'): RejectionHandledListener[]; - listeners(event: 'uncaughtException'): UncaughtExceptionListener[]; - listeners(event: 'uncaughtExceptionMonitor'): UncaughtExceptionListener[]; - listeners(event: 'unhandledRejection'): UnhandledRejectionListener[]; - listeners(event: 'warning'): WarningListener[]; - listeners(event: 'message'): MessageListener[]; + prependOnceListener(event: "multipleResolves", listener: MultipleResolveListener): this; + prependOnceListener(event: "worker", listener: WorkerListener): this; + listeners(event: "beforeExit"): BeforeExitListener[]; + listeners(event: "disconnect"): DisconnectListener[]; + listeners(event: "exit"): ExitListener[]; + listeners(event: "rejectionHandled"): RejectionHandledListener[]; + listeners(event: "uncaughtException"): UncaughtExceptionListener[]; + listeners(event: "uncaughtExceptionMonitor"): UncaughtExceptionListener[]; + listeners(event: "unhandledRejection"): UnhandledRejectionListener[]; + listeners(event: "warning"): WarningListener[]; + listeners(event: "message"): MessageListener[]; listeners(event: Signals): SignalsListener[]; - listeners(event: 'multipleResolves'): MultipleResolveListener[]; - listeners(event: 'worker'): WorkerListener[]; + listeners(event: "multipleResolves"): MultipleResolveListener[]; + listeners(event: "worker"): WorkerListener[]; } } } export = process; } -declare module 'node:process' { - import process = require('process'); +declare module "node:process" { + import process = require("process"); export = process; } diff --git a/node_modules/@types/node/punycode.d.ts b/node_modules/@types/node/punycode.d.ts old mode 100755 new mode 100644 index 345af53..d2fc9f9 --- a/node_modules/@types/node/punycode.d.ts +++ b/node_modules/@types/node/punycode.d.ts @@ -24,9 +24,9 @@ * made available to developers as a convenience. Fixes or other modifications to * the module must be directed to the [Punycode.js](https://github.com/bestiejs/punycode.js) project. * @deprecated Since v7.0.0 - Deprecated - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/punycode.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/punycode.js) */ -declare module 'punycode' { +declare module "punycode" { /** * The `punycode.decode()` method converts a [Punycode](https://tools.ietf.org/html/rfc3492) string of ASCII-only * characters to the equivalent string of Unicode codepoints. @@ -101,7 +101,7 @@ declare module 'punycode' { * Users currently depending on the punycode module should switch to using * the userland-provided Punycode.js module instead. */ - encode(codePoints: ReadonlyArray): string; + encode(codePoints: readonly number[]): string; } /** * @deprecated since v7.0.0 @@ -112,6 +112,6 @@ declare module 'punycode' { */ const version: string; } -declare module 'node:punycode' { - export * from 'punycode'; +declare module "node:punycode" { + export * from "punycode"; } diff --git a/node_modules/@types/node/querystring.d.ts b/node_modules/@types/node/querystring.d.ts old mode 100755 new mode 100644 index 892440b..b36ea2c --- a/node_modules/@types/node/querystring.d.ts +++ b/node_modules/@types/node/querystring.d.ts @@ -1,17 +1,17 @@ /** - * The `querystring` module provides utilities for parsing and formatting URL + * The `node:querystring` module provides utilities for parsing and formatting URL * query strings. It can be accessed using: * * ```js - * const querystring = require('querystring'); + * const querystring = require('node:querystring'); * ``` * - * The `querystring` API is considered Legacy. While it is still maintained, - * new code should use the `URLSearchParams` API instead. - * @deprecated Legacy - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/querystring.js) + * `querystring` is more performant than `URLSearchParams` but is not a + * standardized API. Use `URLSearchParams` when performance is not critical or + * when compatibility with browser code is desirable. + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/querystring.js) */ -declare module 'querystring' { +declare module "querystring" { interface StringifyOptions { encodeURIComponent?: ((str: string) => string) | undefined; } @@ -20,7 +20,17 @@ declare module 'querystring' { decodeURIComponent?: ((str: string) => string) | undefined; } interface ParsedUrlQuery extends NodeJS.Dict {} - interface ParsedUrlQueryInput extends NodeJS.Dict | ReadonlyArray | ReadonlyArray | null> {} + interface ParsedUrlQueryInput extends + NodeJS.Dict< + | string + | number + | boolean + | readonly string[] + | readonly number[] + | readonly boolean[] + | null + > + {} /** * The `querystring.stringify()` method produces a URL query string from a * given `obj` by iterating through the object's "own properties". @@ -64,10 +74,10 @@ declare module 'querystring' { * * For example, the query string `'foo=bar&abc=xyz&abc=123'` is parsed into: * - * ```js + * ```json * { - * foo: 'bar', - * abc: ['xyz', '123'] + * "foo": "bar", + * "abc": ["xyz", "123"] * } * ``` * @@ -126,6 +136,6 @@ declare module 'querystring' { */ function unescape(str: string): string; } -declare module 'node:querystring' { - export * from 'querystring'; +declare module "node:querystring" { + export * from "querystring"; } diff --git a/node_modules/@types/node/readline.d.ts b/node_modules/@types/node/readline.d.ts old mode 100755 new mode 100644 index f1545fa..b06d58b --- a/node_modules/@types/node/readline.d.ts +++ b/node_modules/@types/node/readline.d.ts @@ -1,36 +1,42 @@ /** - * The `readline` module provides an interface for reading data from a `Readable` stream (such as `process.stdin`) one line at a time. It can be accessed - * using: + * The `node:readline` module provides an interface for reading data from a `Readable` stream (such as `process.stdin`) one line at a time. + * + * To use the promise-based APIs: * * ```js - * const readline = require('readline'); + * import * as readline from 'node:readline/promises'; * ``` * - * The following simple example illustrates the basic use of the `readline` module. + * To use the callback and sync APIs: * * ```js - * const readline = require('readline'); + * import * as readline from 'node:readline'; + * ``` * - * const rl = readline.createInterface({ - * input: process.stdin, - * output: process.stdout - * }); + * The following simple example illustrates the basic use of the `node:readline`module. * - * rl.question('What do you think of Node.js? ', (answer) => { - * // TODO: Log the answer in a database - * console.log(`Thank you for your valuable feedback: ${answer}`); + * ```js + * import * as readline from 'node:readline/promises'; + * import { stdin as input, stdout as output } from 'node:process'; * - * rl.close(); - * }); + * const rl = readline.createInterface({ input, output }); + * + * const answer = await rl.question('What do you think of Node.js? '); + * + * console.log(`Thank you for your valuable feedback: ${answer}`); + * + * rl.close(); * ``` * * Once this code is invoked, the Node.js application will not terminate until the`readline.Interface` is closed because the interface waits for data to be * received on the `input` stream. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/readline.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/readline.js) */ -declare module 'readline' { - import { Abortable, EventEmitter } from 'node:events'; - interface Key { +declare module "readline" { + import { Abortable, EventEmitter } from "node:events"; + import * as promises from "node:readline/promises"; + export { promises }; + export interface Key { sequence?: string | undefined; name?: string | undefined; ctrl?: boolean | undefined; @@ -44,7 +50,7 @@ declare module 'readline' { * and is read from, the `input` stream. * @since v0.1.104 */ - class Interface extends EventEmitter { + export class Interface extends EventEmitter { readonly terminal: boolean; /** * The current input data being processed by node. @@ -67,7 +73,7 @@ declare module 'readline' { * const showResults = debounce(() => { * console.log( * '\n', - * values.filter((val) => val.startsWith(rl.line)).join(' ') + * values.filter((val) => val.startsWith(rl.line)).join(' '), * ); * }, 300); * process.stdin.on('keypress', (c, k) => { @@ -93,21 +99,26 @@ declare module 'readline' { * > Instances of the `readline.Interface` class are constructed using the * > `readline.createInterface()` method. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/readline.html#readline_class_interface + * @see https://nodejs.org/dist/latest-v20.x/docs/api/readline.html#class-interfaceconstructor */ - protected constructor(input: NodeJS.ReadableStream, output?: NodeJS.WritableStream, completer?: Completer | AsyncCompleter, terminal?: boolean); + protected constructor( + input: NodeJS.ReadableStream, + output?: NodeJS.WritableStream, + completer?: Completer | AsyncCompleter, + terminal?: boolean, + ); /** * NOTE: According to the documentation: * * > Instances of the `readline.Interface` class are constructed using the * > `readline.createInterface()` method. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/readline.html#readline_class_interface + * @see https://nodejs.org/dist/latest-v20.x/docs/api/readline.html#class-interfaceconstructor */ protected constructor(options: ReadLineOptions); /** * The `rl.getPrompt()` method returns the current prompt used by `rl.prompt()`. - * @since v15.3.0 + * @since v15.3.0, v14.17.0 * @return the current prompt string */ getPrompt(): string; @@ -117,13 +128,13 @@ declare module 'readline' { */ setPrompt(prompt: string): void; /** - * The `rl.prompt()` method writes the `readline.Interface` instances configured`prompt` to a new line in `output` in order to provide a user with a new + * The `rl.prompt()` method writes the `Interface` instances configured`prompt` to a new line in `output` in order to provide a user with a new * location at which to provide input. * * When called, `rl.prompt()` will resume the `input` stream if it has been * paused. * - * If the `readline.Interface` was created with `output` set to `null` or`undefined` the prompt is not written. + * If the `Interface` was created with `output` set to `null` or`undefined` the prompt is not written. * @since v0.1.98 * @param preserveCursor If `true`, prevents the cursor placement from being reset to `0`. */ @@ -135,12 +146,14 @@ declare module 'readline' { * When called, `rl.question()` will resume the `input` stream if it has been * paused. * - * If the `readline.Interface` was created with `output` set to `null` or`undefined` the `query` is not written. + * If the `Interface` was created with `output` set to `null` or`undefined` the `query` is not written. * * The `callback` function passed to `rl.question()` does not follow the typical * pattern of accepting an `Error` object or `null` as the first argument. * The `callback` is called with the provided answer as the only argument. * + * An error will be thrown if calling `rl.question()` after `rl.close()`. + * * Example usage: * * ```js @@ -165,25 +178,6 @@ declare module 'readline' { * * setTimeout(() => ac.abort(), 10000); * ``` - * - * If this method is invoked as it's util.promisify()ed version, it returns a - * Promise that fulfills with the answer. If the question is canceled using - * an `AbortController` it will reject with an `AbortError`. - * - * ```js - * const util = require('util'); - * const question = util.promisify(rl.question).bind(rl); - * - * async function questionExample() { - * try { - * const answer = await question('What is you favorite food? '); - * console.log(`Oh, so your favorite food is ${answer}`); - * } catch (err) { - * console.error('Question rejected', err); - * } - * } - * questionExample(); - * ``` * @since v0.3.3 * @param query A statement or query to write to `output`, prepended to the prompt. * @param callback A callback function that is invoked with the user's input in response to the `query`. @@ -194,7 +188,7 @@ declare module 'readline' { * The `rl.pause()` method pauses the `input` stream, allowing it to be resumed * later if necessary. * - * Calling `rl.pause()` does not immediately pause other events (including`'line'`) from being emitted by the `readline.Interface` instance. + * Calling `rl.pause()` does not immediately pause other events (including`'line'`) from being emitted by the `Interface` instance. * @since v0.3.4 */ pause(): this; @@ -204,12 +198,12 @@ declare module 'readline' { */ resume(): this; /** - * The `rl.close()` method closes the `readline.Interface` instance and + * The `rl.close()` method closes the `Interface` instance and * relinquishes control over the `input` and `output` streams. When called, * the `'close'` event will be emitted. * * Calling `rl.close()` does not immediately stop other events (including `'line'`) - * from being emitted by the `readline.Interface` instance. + * from being emitted by the `Interface` instance. * @since v0.1.98 */ close(): void; @@ -224,7 +218,7 @@ declare module 'readline' { * When called, `rl.write()` will resume the `input` stream if it has been * paused. * - * If the `readline.Interface` was created with `output` set to `null` or`undefined` the `data` and `key` are not written. + * If the `Interface` was created with `output` set to `null` or`undefined` the `data` and `key` are not written. * * ```js * rl.write('Delete this!'); @@ -256,66 +250,69 @@ declare module 'readline' { * 8. history */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'line', listener: (input: string) => void): this; - addListener(event: 'pause', listener: () => void): this; - addListener(event: 'resume', listener: () => void): this; - addListener(event: 'SIGCONT', listener: () => void): this; - addListener(event: 'SIGINT', listener: () => void): this; - addListener(event: 'SIGTSTP', listener: () => void): this; - addListener(event: 'history', listener: (history: string[]) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "line", listener: (input: string) => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; + addListener(event: "SIGCONT", listener: () => void): this; + addListener(event: "SIGINT", listener: () => void): this; + addListener(event: "SIGTSTP", listener: () => void): this; + addListener(event: "history", listener: (history: string[]) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close'): boolean; - emit(event: 'line', input: string): boolean; - emit(event: 'pause'): boolean; - emit(event: 'resume'): boolean; - emit(event: 'SIGCONT'): boolean; - emit(event: 'SIGINT'): boolean; - emit(event: 'SIGTSTP'): boolean; - emit(event: 'history', history: string[]): boolean; + emit(event: "close"): boolean; + emit(event: "line", input: string): boolean; + emit(event: "pause"): boolean; + emit(event: "resume"): boolean; + emit(event: "SIGCONT"): boolean; + emit(event: "SIGINT"): boolean; + emit(event: "SIGTSTP"): boolean; + emit(event: "history", history: string[]): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'line', listener: (input: string) => void): this; - on(event: 'pause', listener: () => void): this; - on(event: 'resume', listener: () => void): this; - on(event: 'SIGCONT', listener: () => void): this; - on(event: 'SIGINT', listener: () => void): this; - on(event: 'SIGTSTP', listener: () => void): this; - on(event: 'history', listener: (history: string[]) => void): this; + on(event: "close", listener: () => void): this; + on(event: "line", listener: (input: string) => void): this; + on(event: "pause", listener: () => void): this; + on(event: "resume", listener: () => void): this; + on(event: "SIGCONT", listener: () => void): this; + on(event: "SIGINT", listener: () => void): this; + on(event: "SIGTSTP", listener: () => void): this; + on(event: "history", listener: (history: string[]) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'line', listener: (input: string) => void): this; - once(event: 'pause', listener: () => void): this; - once(event: 'resume', listener: () => void): this; - once(event: 'SIGCONT', listener: () => void): this; - once(event: 'SIGINT', listener: () => void): this; - once(event: 'SIGTSTP', listener: () => void): this; - once(event: 'history', listener: (history: string[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "line", listener: (input: string) => void): this; + once(event: "pause", listener: () => void): this; + once(event: "resume", listener: () => void): this; + once(event: "SIGCONT", listener: () => void): this; + once(event: "SIGINT", listener: () => void): this; + once(event: "SIGTSTP", listener: () => void): this; + once(event: "history", listener: (history: string[]) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'line', listener: (input: string) => void): this; - prependListener(event: 'pause', listener: () => void): this; - prependListener(event: 'resume', listener: () => void): this; - prependListener(event: 'SIGCONT', listener: () => void): this; - prependListener(event: 'SIGINT', listener: () => void): this; - prependListener(event: 'SIGTSTP', listener: () => void): this; - prependListener(event: 'history', listener: (history: string[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "line", listener: (input: string) => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; + prependListener(event: "SIGCONT", listener: () => void): this; + prependListener(event: "SIGINT", listener: () => void): this; + prependListener(event: "SIGTSTP", listener: () => void): this; + prependListener(event: "history", listener: (history: string[]) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'line', listener: (input: string) => void): this; - prependOnceListener(event: 'pause', listener: () => void): this; - prependOnceListener(event: 'resume', listener: () => void): this; - prependOnceListener(event: 'SIGCONT', listener: () => void): this; - prependOnceListener(event: 'SIGINT', listener: () => void): this; - prependOnceListener(event: 'SIGTSTP', listener: () => void): this; - prependOnceListener(event: 'history', listener: (history: string[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "line", listener: (input: string) => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; + prependOnceListener(event: "SIGCONT", listener: () => void): this; + prependOnceListener(event: "SIGINT", listener: () => void): this; + prependOnceListener(event: "SIGTSTP", listener: () => void): this; + prependOnceListener(event: "history", listener: (history: string[]) => void): this; [Symbol.asyncIterator](): AsyncIterableIterator; } - type ReadLine = Interface; // type forwarded for backwards compatibility - type Completer = (line: string) => CompleterResult; - type AsyncCompleter = (line: string, callback: (err?: null | Error, result?: CompleterResult) => void) => void; - type CompleterResult = [string[], string]; - interface ReadLineOptions { + export type ReadLine = Interface; // type forwarded for backwards compatibility + export type Completer = (line: string) => CompleterResult; + export type AsyncCompleter = ( + line: string, + callback: (err?: null | Error, result?: CompleterResult) => void, + ) => void; + export type CompleterResult = [string[], string]; + export interface ReadLineOptions { input: NodeJS.ReadableStream; output?: NodeJS.WritableStream | undefined; completer?: Completer | AsyncCompleter | undefined; @@ -344,10 +341,10 @@ declare module 'readline' { * The `readline.createInterface()` method creates a new `readline.Interface`instance. * * ```js - * const readline = require('readline'); + * const readline = require('node:readline'); * const rl = readline.createInterface({ * input: process.stdin, - * output: process.stdout + * output: process.stdout, * }); * ``` * @@ -366,18 +363,17 @@ declare module 'readline' { * (`process.stdout` does this automatically when it is a TTY). * * When creating a `readline.Interface` using `stdin` as input, the program - * will not terminate until it receives `EOF` (Ctrl+D on - * Linux/macOS, Ctrl+Z followed by Return on - * Windows). - * If you want your application to exit without waiting for user input, you can `unref()` the standard input stream: - * - * ```js - * process.stdin.unref(); - * ``` + * will not terminate until it receives an [EOF character](https://en.wikipedia.org/wiki/End-of-file#EOF_character). To exit without + * waiting for user input, call `process.stdin.unref()`. * @since v0.1.98 */ - function createInterface(input: NodeJS.ReadableStream, output?: NodeJS.WritableStream, completer?: Completer | AsyncCompleter, terminal?: boolean): Interface; - function createInterface(options: ReadLineOptions): Interface; + export function createInterface( + input: NodeJS.ReadableStream, + output?: NodeJS.WritableStream, + completer?: Completer | AsyncCompleter, + terminal?: boolean, + ): Interface; + export function createInterface(options: ReadLineOptions): Interface; /** * The `readline.emitKeypressEvents()` method causes the given `Readable` stream to begin emitting `'keypress'` events corresponding to received input. * @@ -394,41 +390,6 @@ declare module 'readline' { * if (process.stdin.isTTY) * process.stdin.setRawMode(true); * ``` - * @since v0.7.7 - */ - function emitKeypressEvents(stream: NodeJS.ReadableStream, readlineInterface?: Interface): void; - type Direction = -1 | 0 | 1; - interface CursorPos { - rows: number; - cols: number; - } - /** - * The `readline.clearLine()` method clears current line of given `TTY` stream - * in a specified direction identified by `dir`. - * @since v0.7.7 - * @param callback Invoked once the operation completes. - * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. - */ - function clearLine(stream: NodeJS.WritableStream, dir: Direction, callback?: () => void): boolean; - /** - * The `readline.clearScreenDown()` method clears the given `TTY` stream from - * the current position of the cursor down. - * @since v0.7.7 - * @param callback Invoked once the operation completes. - * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. - */ - function clearScreenDown(stream: NodeJS.WritableStream, callback?: () => void): boolean; - /** - * The `readline.cursorTo()` method moves cursor to the specified position in a - * given `TTY` `stream`. - * @since v0.7.7 - * @param callback Invoked once the operation completes. - * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. - */ - function cursorTo(stream: NodeJS.WritableStream, x: number, y?: number, callback?: () => void): boolean; - /** - * The `readline.moveCursor()` method moves the cursor _relative_ to its current - * position in a given `TTY` `stream`. * * ## Example: Tiny CLI * @@ -436,11 +397,11 @@ declare module 'readline' { * implement a small command-line interface: * * ```js - * const readline = require('readline'); + * const readline = require('node:readline'); * const rl = readline.createInterface({ * input: process.stdin, * output: process.stdout, - * prompt: 'OHAI> ' + * prompt: 'OHAI> ', * }); * * rl.prompt(); @@ -468,15 +429,15 @@ declare module 'readline' { * well as a `for await...of` loop: * * ```js - * const fs = require('fs'); - * const readline = require('readline'); + * const fs = require('node:fs'); + * const readline = require('node:readline'); * * async function processLineByLine() { * const fileStream = fs.createReadStream('input.txt'); * * const rl = readline.createInterface({ * input: fileStream, - * crlfDelay: Infinity + * crlfDelay: Infinity, * }); * // Note: we use the crlfDelay option to recognize all instances of CR LF * // ('\r\n') in input.txt as a single line break. @@ -493,12 +454,12 @@ declare module 'readline' { * Alternatively, one could use the `'line'` event: * * ```js - * const fs = require('fs'); - * const readline = require('readline'); + * const fs = require('node:fs'); + * const readline = require('node:readline'); * * const rl = readline.createInterface({ * input: fs.createReadStream('sample.txt'), - * crlfDelay: Infinity + * crlfDelay: Infinity, * }); * * rl.on('line', (line) => { @@ -509,15 +470,15 @@ declare module 'readline' { * Currently, `for await...of` loop can be a bit slower. If `async` / `await`flow and speed are both essential, a mixed approach can be applied: * * ```js - * const { once } = require('events'); - * const { createReadStream } = require('fs'); - * const { createInterface } = require('readline'); + * const { once } = require('node:events'); + * const { createReadStream } = require('node:fs'); + * const { createInterface } = require('node:readline'); * * (async function processLineByLine() { * try { * const rl = createInterface({ * input: createReadStream('big-file.txt'), - * crlfDelay: Infinity + * crlfDelay: Infinity, * }); * * rl.on('line', (line) => { @@ -533,11 +494,46 @@ declare module 'readline' { * })(); * ``` * @since v0.7.7 + */ + export function emitKeypressEvents(stream: NodeJS.ReadableStream, readlineInterface?: Interface): void; + export type Direction = -1 | 0 | 1; + export interface CursorPos { + rows: number; + cols: number; + } + /** + * The `readline.clearLine()` method clears current line of given `TTY` stream + * in a specified direction identified by `dir`. + * @since v0.7.7 * @param callback Invoked once the operation completes. * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. */ - function moveCursor(stream: NodeJS.WritableStream, dx: number, dy: number, callback?: () => void): boolean; + export function clearLine(stream: NodeJS.WritableStream, dir: Direction, callback?: () => void): boolean; + /** + * The `readline.clearScreenDown()` method clears the given `TTY` stream from + * the current position of the cursor down. + * @since v0.7.7 + * @param callback Invoked once the operation completes. + * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. + */ + export function clearScreenDown(stream: NodeJS.WritableStream, callback?: () => void): boolean; + /** + * The `readline.cursorTo()` method moves cursor to the specified position in a + * given `TTY` `stream`. + * @since v0.7.7 + * @param callback Invoked once the operation completes. + * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. + */ + export function cursorTo(stream: NodeJS.WritableStream, x: number, y?: number, callback?: () => void): boolean; + /** + * The `readline.moveCursor()` method moves the cursor _relative_ to its current + * position in a given `TTY` `stream`. + * @since v0.7.7 + * @param callback Invoked once the operation completes. + * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. + */ + export function moveCursor(stream: NodeJS.WritableStream, dx: number, dy: number, callback?: () => void): boolean; } -declare module 'node:readline' { - export * from 'readline'; +declare module "node:readline" { + export * from "readline"; } diff --git a/node_modules/@types/node/readline/promises.d.ts b/node_modules/@types/node/readline/promises.d.ts new file mode 100644 index 0000000..73fb111 --- /dev/null +++ b/node_modules/@types/node/readline/promises.d.ts @@ -0,0 +1,150 @@ +/** + * @since v17.0.0 + * @experimental + */ +declare module "readline/promises" { + import { AsyncCompleter, Completer, Direction, Interface as _Interface, ReadLineOptions } from "node:readline"; + import { Abortable } from "node:events"; + /** + * Instances of the `readlinePromises.Interface` class are constructed using the`readlinePromises.createInterface()` method. Every instance is associated with a + * single `input` `Readable` stream and a single `output` `Writable` stream. + * The `output` stream is used to print prompts for user input that arrives on, + * and is read from, the `input` stream. + * @since v17.0.0 + */ + class Interface extends _Interface { + /** + * The `rl.question()` method displays the `query` by writing it to the `output`, + * waits for user input to be provided on `input`, then invokes the `callback`function passing the provided input as the first argument. + * + * When called, `rl.question()` will resume the `input` stream if it has been + * paused. + * + * If the `Interface` was created with `output` set to `null` or`undefined` the `query` is not written. + * + * If the question is called after `rl.close()`, it returns a rejected promise. + * + * Example usage: + * + * ```js + * const answer = await rl.question('What is your favorite food? '); + * console.log(`Oh, so your favorite food is ${answer}`); + * ``` + * + * Using an `AbortSignal` to cancel a question. + * + * ```js + * const signal = AbortSignal.timeout(10_000); + * + * signal.addEventListener('abort', () => { + * console.log('The food question timed out'); + * }, { once: true }); + * + * const answer = await rl.question('What is your favorite food? ', { signal }); + * console.log(`Oh, so your favorite food is ${answer}`); + * ``` + * @since v17.0.0 + * @param query A statement or query to write to `output`, prepended to the prompt. + * @return A promise that is fulfilled with the user's input in response to the `query`. + */ + question(query: string): Promise; + question(query: string, options: Abortable): Promise; + } + /** + * @since v17.0.0 + */ + class Readline { + /** + * @param stream A TTY stream. + */ + constructor( + stream: NodeJS.WritableStream, + options?: { + autoCommit?: boolean; + }, + ); + /** + * The `rl.clearLine()` method adds to the internal list of pending action an + * action that clears current line of the associated `stream` in a specified + * direction identified by `dir`. + * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor. + * @since v17.0.0 + * @return this + */ + clearLine(dir: Direction): this; + /** + * The `rl.clearScreenDown()` method adds to the internal list of pending action an + * action that clears the associated stream from the current position of the + * cursor down. + * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor. + * @since v17.0.0 + * @return this + */ + clearScreenDown(): this; + /** + * The `rl.commit()` method sends all the pending actions to the associated`stream` and clears the internal list of pending actions. + * @since v17.0.0 + */ + commit(): Promise; + /** + * The `rl.cursorTo()` method adds to the internal list of pending action an action + * that moves cursor to the specified position in the associated `stream`. + * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor. + * @since v17.0.0 + * @return this + */ + cursorTo(x: number, y?: number): this; + /** + * The `rl.moveCursor()` method adds to the internal list of pending action an + * action that moves the cursor _relative_ to its current position in the + * associated `stream`. + * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor. + * @since v17.0.0 + * @return this + */ + moveCursor(dx: number, dy: number): this; + /** + * The `rl.rollback` methods clears the internal list of pending actions without + * sending it to the associated `stream`. + * @since v17.0.0 + * @return this + */ + rollback(): this; + } + /** + * The `readlinePromises.createInterface()` method creates a new `readlinePromises.Interface`instance. + * + * ```js + * const readlinePromises = require('node:readline/promises'); + * const rl = readlinePromises.createInterface({ + * input: process.stdin, + * output: process.stdout, + * }); + * ``` + * + * Once the `readlinePromises.Interface` instance is created, the most common case + * is to listen for the `'line'` event: + * + * ```js + * rl.on('line', (line) => { + * console.log(`Received: ${line}`); + * }); + * ``` + * + * If `terminal` is `true` for this instance then the `output` stream will get + * the best compatibility if it defines an `output.columns` property and emits + * a `'resize'` event on the `output` if or when the columns ever change + * (`process.stdout` does this automatically when it is a TTY). + * @since v17.0.0 + */ + function createInterface( + input: NodeJS.ReadableStream, + output?: NodeJS.WritableStream, + completer?: Completer | AsyncCompleter, + terminal?: boolean, + ): Interface; + function createInterface(options: ReadLineOptions): Interface; +} +declare module "node:readline/promises" { + export * from "readline/promises"; +} diff --git a/node_modules/@types/node/repl.d.ts b/node_modules/@types/node/repl.d.ts old mode 100755 new mode 100644 index 04f64e1..6c5f81b --- a/node_modules/@types/node/repl.d.ts +++ b/node_modules/@types/node/repl.d.ts @@ -1,17 +1,17 @@ /** - * The `repl` module provides a Read-Eval-Print-Loop (REPL) implementation that - * is available both as a standalone program or includible in other applications. - * It can be accessed using: + * The `node:repl` module provides a Read-Eval-Print-Loop (REPL) implementation + * that is available both as a standalone program or includible in other + * applications. It can be accessed using: * * ```js - * const repl = require('repl'); + * const repl = require('node:repl'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/repl.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/repl.js) */ -declare module 'repl' { - import { Interface, Completer, AsyncCompleter } from 'node:readline'; - import { Context } from 'node:vm'; - import { InspectOptions } from 'node:util'; +declare module "repl" { + import { AsyncCompleter, Completer, Interface } from "node:readline"; + import { Context } from "node:vm"; + import { InspectOptions } from "node:util"; interface ReplOptions { /** * The input prompt to display. @@ -41,8 +41,8 @@ declare module 'repl' { * error with `repl.Recoverable` to indicate the input was incomplete and prompt for * additional lines. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_default_evaluation - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_custom_evaluation_functions + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_default_evaluation + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_custom_evaluation_functions */ eval?: REPLEval | undefined; /** @@ -74,13 +74,13 @@ declare module 'repl' { * The function to invoke to format the output of each command before writing to `output`. * Default: a wrapper for `util.inspect`. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_customizing_repl_output + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_customizing_repl_output */ writer?: REPLWriter | undefined; /** * An optional function used for custom Tab auto completion. * - * @see https://nodejs.org/dist/latest-v11.x/docs/api/readline.html#readline_use_of_the_completer_function + * @see https://nodejs.org/dist/latest-v20.x/docs/api/readline.html#readline_use_of_the_completer_function */ completer?: Completer | AsyncCompleter | undefined; /** @@ -99,7 +99,13 @@ declare module 'repl' { */ breakEvalOnSigint?: boolean | undefined; } - type REPLEval = (this: REPLServer, evalCmd: string, context: Context, file: string, cb: (err: Error | null, result: any) => void) => void; + type REPLEval = ( + this: REPLServer, + evalCmd: string, + context: Context, + file: string, + cb: (err: Error | null, result: any) => void, + ) => void; type REPLWriter = (this: REPLServer, obj: any) => string; /** * This is the default "writer" value, if none is passed in the REPL options, @@ -124,7 +130,7 @@ declare module 'repl' { * or directly using the JavaScript `new` keyword. * * ```js - * const repl = require('repl'); + * const repl = require('node:repl'); * * const options = { useColors: true }; * @@ -162,33 +168,33 @@ declare module 'repl' { /** * A value indicating whether the REPL is currently in "editor mode". * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_commands_and_special_keys + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_commands_and_special_keys */ readonly editorMode: boolean; /** * A value indicating whether the `_` variable has been assigned. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable */ readonly underscoreAssigned: boolean; /** * The last evaluation result from the REPL (assigned to the `_` variable inside of the REPL). * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable */ readonly last: any; /** * A value indicating whether the `_error` variable has been assigned. * * @since v9.8.0 - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable */ readonly underscoreErrAssigned: boolean; /** * The last error raised inside the REPL (assigned to the `_error` variable inside of the REPL). * * @since v9.8.0 - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable */ readonly lastError: any; /** @@ -240,7 +246,7 @@ declare module 'repl' { * * `REPLServer` cannot be subclassed due to implementation specifics in NodeJS. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_class_replserver + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_class_replserver */ private constructor(); /** @@ -251,7 +257,7 @@ declare module 'repl' { * The following example shows two new commands added to the REPL instance: * * ```js - * const repl = require('repl'); + * const repl = require('node:repl'); * * const replServer = repl.start({ prompt: '> ' }); * replServer.defineCommand('sayhello', { @@ -260,7 +266,7 @@ declare module 'repl' { * this.clearBufferedCommand(); * console.log(`Hello, ${name}!`); * this.displayPrompt(); - * } + * }, * }); * replServer.defineCommand('saybye', function saybye() { * console.log('Goodbye!'); @@ -277,7 +283,7 @@ declare module 'repl' { * Goodbye! * ``` * @since v0.3.0 - * @param keyword The command keyword (*without* a leading `.` character). + * @param keyword The command keyword (_without_ a leading `.` character). * @param cmd The function to invoke when the command is processed. */ defineCommand(keyword: string, cmd: REPLCommandAction | REPLCommand): void; @@ -326,65 +332,65 @@ declare module 'repl' { * 9. reset */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'line', listener: (input: string) => void): this; - addListener(event: 'pause', listener: () => void): this; - addListener(event: 'resume', listener: () => void): this; - addListener(event: 'SIGCONT', listener: () => void): this; - addListener(event: 'SIGINT', listener: () => void): this; - addListener(event: 'SIGTSTP', listener: () => void): this; - addListener(event: 'exit', listener: () => void): this; - addListener(event: 'reset', listener: (context: Context) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "line", listener: (input: string) => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; + addListener(event: "SIGCONT", listener: () => void): this; + addListener(event: "SIGINT", listener: () => void): this; + addListener(event: "SIGTSTP", listener: () => void): this; + addListener(event: "exit", listener: () => void): this; + addListener(event: "reset", listener: (context: Context) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close'): boolean; - emit(event: 'line', input: string): boolean; - emit(event: 'pause'): boolean; - emit(event: 'resume'): boolean; - emit(event: 'SIGCONT'): boolean; - emit(event: 'SIGINT'): boolean; - emit(event: 'SIGTSTP'): boolean; - emit(event: 'exit'): boolean; - emit(event: 'reset', context: Context): boolean; + emit(event: "close"): boolean; + emit(event: "line", input: string): boolean; + emit(event: "pause"): boolean; + emit(event: "resume"): boolean; + emit(event: "SIGCONT"): boolean; + emit(event: "SIGINT"): boolean; + emit(event: "SIGTSTP"): boolean; + emit(event: "exit"): boolean; + emit(event: "reset", context: Context): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'line', listener: (input: string) => void): this; - on(event: 'pause', listener: () => void): this; - on(event: 'resume', listener: () => void): this; - on(event: 'SIGCONT', listener: () => void): this; - on(event: 'SIGINT', listener: () => void): this; - on(event: 'SIGTSTP', listener: () => void): this; - on(event: 'exit', listener: () => void): this; - on(event: 'reset', listener: (context: Context) => void): this; + on(event: "close", listener: () => void): this; + on(event: "line", listener: (input: string) => void): this; + on(event: "pause", listener: () => void): this; + on(event: "resume", listener: () => void): this; + on(event: "SIGCONT", listener: () => void): this; + on(event: "SIGINT", listener: () => void): this; + on(event: "SIGTSTP", listener: () => void): this; + on(event: "exit", listener: () => void): this; + on(event: "reset", listener: (context: Context) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'line', listener: (input: string) => void): this; - once(event: 'pause', listener: () => void): this; - once(event: 'resume', listener: () => void): this; - once(event: 'SIGCONT', listener: () => void): this; - once(event: 'SIGINT', listener: () => void): this; - once(event: 'SIGTSTP', listener: () => void): this; - once(event: 'exit', listener: () => void): this; - once(event: 'reset', listener: (context: Context) => void): this; + once(event: "close", listener: () => void): this; + once(event: "line", listener: (input: string) => void): this; + once(event: "pause", listener: () => void): this; + once(event: "resume", listener: () => void): this; + once(event: "SIGCONT", listener: () => void): this; + once(event: "SIGINT", listener: () => void): this; + once(event: "SIGTSTP", listener: () => void): this; + once(event: "exit", listener: () => void): this; + once(event: "reset", listener: (context: Context) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'line', listener: (input: string) => void): this; - prependListener(event: 'pause', listener: () => void): this; - prependListener(event: 'resume', listener: () => void): this; - prependListener(event: 'SIGCONT', listener: () => void): this; - prependListener(event: 'SIGINT', listener: () => void): this; - prependListener(event: 'SIGTSTP', listener: () => void): this; - prependListener(event: 'exit', listener: () => void): this; - prependListener(event: 'reset', listener: (context: Context) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "line", listener: (input: string) => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; + prependListener(event: "SIGCONT", listener: () => void): this; + prependListener(event: "SIGINT", listener: () => void): this; + prependListener(event: "SIGTSTP", listener: () => void): this; + prependListener(event: "exit", listener: () => void): this; + prependListener(event: "reset", listener: (context: Context) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'line', listener: (input: string) => void): this; - prependOnceListener(event: 'pause', listener: () => void): this; - prependOnceListener(event: 'resume', listener: () => void): this; - prependOnceListener(event: 'SIGCONT', listener: () => void): this; - prependOnceListener(event: 'SIGINT', listener: () => void): this; - prependOnceListener(event: 'SIGTSTP', listener: () => void): this; - prependOnceListener(event: 'exit', listener: () => void): this; - prependOnceListener(event: 'reset', listener: (context: Context) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "line", listener: (input: string) => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; + prependOnceListener(event: "SIGCONT", listener: () => void): this; + prependOnceListener(event: "SIGINT", listener: () => void): this; + prependOnceListener(event: "SIGTSTP", listener: () => void): this; + prependOnceListener(event: "exit", listener: () => void): this; + prependOnceListener(event: "reset", listener: (context: Context) => void): this; } /** * A flag passed in the REPL options. Evaluates expressions in sloppy mode. @@ -401,7 +407,7 @@ declare module 'repl' { * If `options` is a string, then it specifies the input prompt: * * ```js - * const repl = require('repl'); + * const repl = require('node:repl'); * * // a Unix style prompt * repl.start('$ '); @@ -412,13 +418,13 @@ declare module 'repl' { /** * Indicates a recoverable error that a `REPLServer` can use to support multi-line input. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_recoverable_errors + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_recoverable_errors */ class Recoverable extends SyntaxError { err: Error; constructor(err: Error); } } -declare module 'node:repl' { - export * from 'repl'; +declare module "node:repl" { + export * from "repl"; } diff --git a/node_modules/@types/node/stream.d.ts b/node_modules/@types/node/stream.d.ts old mode 100755 new mode 100644 index 06c27bf..947a019 --- a/node_modules/@types/node/stream.d.ts +++ b/node_modules/@types/node/stream.d.ts @@ -1,32 +1,943 @@ /** * A stream is an abstract interface for working with streaming data in Node.js. - * The `stream` module provides an API for implementing the stream interface. + * The `node:stream` module provides an API for implementing the stream interface. * * There are many stream objects provided by Node.js. For instance, a `request to an HTTP server` and `process.stdout` are both stream instances. * * Streams can be readable, writable, or both. All streams are instances of `EventEmitter`. * - * To access the `stream` module: + * To access the `node:stream` module: * * ```js - * const stream = require('stream'); + * const stream = require('node:stream'); * ``` * - * The `stream` module is useful for creating new types of stream instances. It is - * usually not necessary to use the `stream` module to consume streams. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/stream.js) + * The `node:stream` module is useful for creating new types of stream instances. + * It is usually not necessary to use the `node:stream` module to consume streams. + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/stream.js) */ -declare module 'stream' { - import { EventEmitter, Abortable } from 'node:events'; - import * as streamPromises from 'node:stream/promises'; - import * as streamConsumers from 'node:stream/consumers'; +declare module "stream" { + import { Abortable, EventEmitter } from "node:events"; + import { Blob as NodeBlob } from "node:buffer"; + import * as streamPromises from "node:stream/promises"; + import * as streamConsumers from "node:stream/consumers"; + import * as streamWeb from "node:stream/web"; + + type ComposeFnParam = (source: any) => void; + class internal extends EventEmitter { pipe( destination: T, options?: { end?: boolean | undefined; - } + }, ): T; + compose( + stream: T | ComposeFnParam | Iterable | AsyncIterable, + options?: { signal: AbortSignal }, + ): T; + } + import Stream = internal.Stream; + import Readable = internal.Readable; + import ReadableOptions = internal.ReadableOptions; + interface ArrayOptions { + /** the maximum concurrent invocations of `fn` to call on the stream at once. **Default: 1**. */ + concurrency?: number; + /** allows destroying the stream if the signal is aborted. */ + signal?: AbortSignal; + } + class ReadableBase extends Stream implements NodeJS.ReadableStream { + /** + * A utility method for creating Readable Streams out of iterators. + */ + static from(iterable: Iterable | AsyncIterable, options?: ReadableOptions): Readable; + /** + * Returns whether the stream has been read from or cancelled. + * @since v16.8.0 + */ + static isDisturbed(stream: Readable | NodeJS.ReadableStream): boolean; + /** + * Returns whether the stream was destroyed or errored before emitting `'end'`. + * @since v16.8.0 + * @experimental + */ + readonly readableAborted: boolean; + /** + * Is `true` if it is safe to call `readable.read()`, which means + * the stream has not been destroyed or emitted `'error'` or `'end'`. + * @since v11.4.0 + */ + readable: boolean; + /** + * Returns whether `'data'` has been emitted. + * @since v16.7.0, v14.18.0 + * @experimental + */ + readonly readableDidRead: boolean; + /** + * Getter for the property `encoding` of a given `Readable` stream. The `encoding`property can be set using the `readable.setEncoding()` method. + * @since v12.7.0 + */ + readonly readableEncoding: BufferEncoding | null; + /** + * Becomes `true` when `'end'` event is emitted. + * @since v12.9.0 + */ + readonly readableEnded: boolean; + /** + * This property reflects the current state of a `Readable` stream as described + * in the `Three states` section. + * @since v9.4.0 + */ + readonly readableFlowing: boolean | null; + /** + * Returns the value of `highWaterMark` passed when creating this `Readable`. + * @since v9.3.0 + */ + readonly readableHighWaterMark: number; + /** + * This property contains the number of bytes (or objects) in the queue + * ready to be read. The value provides introspection data regarding + * the status of the `highWaterMark`. + * @since v9.4.0 + */ + readonly readableLength: number; + /** + * Getter for the property `objectMode` of a given `Readable` stream. + * @since v12.3.0 + */ + readonly readableObjectMode: boolean; + /** + * Is `true` after `readable.destroy()` has been called. + * @since v8.0.0 + */ + destroyed: boolean; + /** + * Is `true` after `'close'` has been emitted. + * @since v18.0.0 + */ + readonly closed: boolean; + /** + * Returns error if the stream has been destroyed with an error. + * @since v18.0.0 + */ + readonly errored: Error | null; + constructor(opts?: ReadableOptions); + _construct?(callback: (error?: Error | null) => void): void; + _read(size: number): void; + /** + * The `readable.read()` method reads data out of the internal buffer and + * returns it. If no data is available to be read, `null` is returned. By default, + * the data is returned as a `Buffer` object unless an encoding has been + * specified using the `readable.setEncoding()` method or the stream is operating + * in object mode. + * + * The optional `size` argument specifies a specific number of bytes to read. If`size` bytes are not available to be read, `null` will be returned _unless_the stream has ended, in which + * case all of the data remaining in the internal + * buffer will be returned. + * + * If the `size` argument is not specified, all of the data contained in the + * internal buffer will be returned. + * + * The `size` argument must be less than or equal to 1 GiB. + * + * The `readable.read()` method should only be called on `Readable` streams + * operating in paused mode. In flowing mode, `readable.read()` is called + * automatically until the internal buffer is fully drained. + * + * ```js + * const readable = getReadableStreamSomehow(); + * + * // 'readable' may be triggered multiple times as data is buffered in + * readable.on('readable', () => { + * let chunk; + * console.log('Stream is readable (new data received in buffer)'); + * // Use a loop to make sure we read all currently available data + * while (null !== (chunk = readable.read())) { + * console.log(`Read ${chunk.length} bytes of data...`); + * } + * }); + * + * // 'end' will be triggered once when there is no more data available + * readable.on('end', () => { + * console.log('Reached end of stream.'); + * }); + * ``` + * + * Each call to `readable.read()` returns a chunk of data, or `null`. The chunks + * are not concatenated. A `while` loop is necessary to consume all data + * currently in the buffer. When reading a large file `.read()` may return `null`, + * having consumed all buffered content so far, but there is still more data to + * come not yet buffered. In this case a new `'readable'` event will be emitted + * when there is more data in the buffer. Finally the `'end'` event will be + * emitted when there is no more data to come. + * + * Therefore to read a file's whole contents from a `readable`, it is necessary + * to collect chunks across multiple `'readable'` events: + * + * ```js + * const chunks = []; + * + * readable.on('readable', () => { + * let chunk; + * while (null !== (chunk = readable.read())) { + * chunks.push(chunk); + * } + * }); + * + * readable.on('end', () => { + * const content = chunks.join(''); + * }); + * ``` + * + * A `Readable` stream in object mode will always return a single item from + * a call to `readable.read(size)`, regardless of the value of the`size` argument. + * + * If the `readable.read()` method returns a chunk of data, a `'data'` event will + * also be emitted. + * + * Calling {@link read} after the `'end'` event has + * been emitted will return `null`. No runtime error will be raised. + * @since v0.9.4 + * @param size Optional argument to specify how much data to read. + */ + read(size?: number): any; + /** + * The `readable.setEncoding()` method sets the character encoding for + * data read from the `Readable` stream. + * + * By default, no encoding is assigned and stream data will be returned as`Buffer` objects. Setting an encoding causes the stream data + * to be returned as strings of the specified encoding rather than as `Buffer`objects. For instance, calling `readable.setEncoding('utf8')` will cause the + * output data to be interpreted as UTF-8 data, and passed as strings. Calling`readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal + * string format. + * + * The `Readable` stream will properly handle multi-byte characters delivered + * through the stream that would otherwise become improperly decoded if simply + * pulled from the stream as `Buffer` objects. + * + * ```js + * const readable = getReadableStreamSomehow(); + * readable.setEncoding('utf8'); + * readable.on('data', (chunk) => { + * assert.equal(typeof chunk, 'string'); + * console.log('Got %d characters of string data:', chunk.length); + * }); + * ``` + * @since v0.9.4 + * @param encoding The encoding to use. + */ + setEncoding(encoding: BufferEncoding): this; + /** + * The `readable.pause()` method will cause a stream in flowing mode to stop + * emitting `'data'` events, switching out of flowing mode. Any data that + * becomes available will remain in the internal buffer. + * + * ```js + * const readable = getReadableStreamSomehow(); + * readable.on('data', (chunk) => { + * console.log(`Received ${chunk.length} bytes of data.`); + * readable.pause(); + * console.log('There will be no additional data for 1 second.'); + * setTimeout(() => { + * console.log('Now data will start flowing again.'); + * readable.resume(); + * }, 1000); + * }); + * ``` + * + * The `readable.pause()` method has no effect if there is a `'readable'`event listener. + * @since v0.9.4 + */ + pause(): this; + /** + * The `readable.resume()` method causes an explicitly paused `Readable` stream to + * resume emitting `'data'` events, switching the stream into flowing mode. + * + * The `readable.resume()` method can be used to fully consume the data from a + * stream without actually processing any of that data: + * + * ```js + * getReadableStreamSomehow() + * .resume() + * .on('end', () => { + * console.log('Reached the end, but did not read anything.'); + * }); + * ``` + * + * The `readable.resume()` method has no effect if there is a `'readable'`event listener. + * @since v0.9.4 + */ + resume(): this; + /** + * The `readable.isPaused()` method returns the current operating state of the`Readable`. This is used primarily by the mechanism that underlies the`readable.pipe()` method. In most + * typical cases, there will be no reason to + * use this method directly. + * + * ```js + * const readable = new stream.Readable(); + * + * readable.isPaused(); // === false + * readable.pause(); + * readable.isPaused(); // === true + * readable.resume(); + * readable.isPaused(); // === false + * ``` + * @since v0.11.14 + */ + isPaused(): boolean; + /** + * The `readable.unpipe()` method detaches a `Writable` stream previously attached + * using the {@link pipe} method. + * + * If the `destination` is not specified, then _all_ pipes are detached. + * + * If the `destination` is specified, but no pipe is set up for it, then + * the method does nothing. + * + * ```js + * const fs = require('node:fs'); + * const readable = getReadableStreamSomehow(); + * const writable = fs.createWriteStream('file.txt'); + * // All the data from readable goes into 'file.txt', + * // but only for the first second. + * readable.pipe(writable); + * setTimeout(() => { + * console.log('Stop writing to file.txt.'); + * readable.unpipe(writable); + * console.log('Manually close the file stream.'); + * writable.end(); + * }, 1000); + * ``` + * @since v0.9.4 + * @param destination Optional specific stream to unpipe + */ + unpipe(destination?: NodeJS.WritableStream): this; + /** + * Passing `chunk` as `null` signals the end of the stream (EOF) and behaves the + * same as `readable.push(null)`, after which no more data can be written. The EOF + * signal is put at the end of the buffer and any buffered data will still be + * flushed. + * + * The `readable.unshift()` method pushes a chunk of data back into the internal + * buffer. This is useful in certain situations where a stream is being consumed by + * code that needs to "un-consume" some amount of data that it has optimistically + * pulled out of the source, so that the data can be passed on to some other party. + * + * The `stream.unshift(chunk)` method cannot be called after the `'end'` event + * has been emitted or a runtime error will be thrown. + * + * Developers using `stream.unshift()` often should consider switching to + * use of a `Transform` stream instead. See the `API for stream implementers` section for more information. + * + * ```js + * // Pull off a header delimited by \n\n. + * // Use unshift() if we get too much. + * // Call the callback with (error, header, stream). + * const { StringDecoder } = require('node:string_decoder'); + * function parseHeader(stream, callback) { + * stream.on('error', callback); + * stream.on('readable', onReadable); + * const decoder = new StringDecoder('utf8'); + * let header = ''; + * function onReadable() { + * let chunk; + * while (null !== (chunk = stream.read())) { + * const str = decoder.write(chunk); + * if (str.includes('\n\n')) { + * // Found the header boundary. + * const split = str.split(/\n\n/); + * header += split.shift(); + * const remaining = split.join('\n\n'); + * const buf = Buffer.from(remaining, 'utf8'); + * stream.removeListener('error', callback); + * // Remove the 'readable' listener before unshifting. + * stream.removeListener('readable', onReadable); + * if (buf.length) + * stream.unshift(buf); + * // Now the body of the message can be read from the stream. + * callback(null, header, stream); + * return; + * } + * // Still reading the header. + * header += str; + * } + * } + * } + * ``` + * + * Unlike {@link push}, `stream.unshift(chunk)` will not + * end the reading process by resetting the internal reading state of the stream. + * This can cause unexpected results if `readable.unshift()` is called during a + * read (i.e. from within a {@link _read} implementation on a + * custom stream). Following the call to `readable.unshift()` with an immediate {@link push} will reset the reading state appropriately, + * however it is best to simply avoid calling `readable.unshift()` while in the + * process of performing a read. + * @since v0.9.11 + * @param chunk Chunk of data to unshift onto the read queue. For streams not operating in object mode, `chunk` must be a string, `Buffer`, `Uint8Array`, or `null`. For object mode + * streams, `chunk` may be any JavaScript value. + * @param encoding Encoding of string chunks. Must be a valid `Buffer` encoding, such as `'utf8'` or `'ascii'`. + */ + unshift(chunk: any, encoding?: BufferEncoding): void; + /** + * Prior to Node.js 0.10, streams did not implement the entire `node:stream`module API as it is currently defined. (See `Compatibility` for more + * information.) + * + * When using an older Node.js library that emits `'data'` events and has a {@link pause} method that is advisory only, the`readable.wrap()` method can be used to create a `Readable` + * stream that uses + * the old stream as its data source. + * + * It will rarely be necessary to use `readable.wrap()` but the method has been + * provided as a convenience for interacting with older Node.js applications and + * libraries. + * + * ```js + * const { OldReader } = require('./old-api-module.js'); + * const { Readable } = require('node:stream'); + * const oreader = new OldReader(); + * const myReader = new Readable().wrap(oreader); + * + * myReader.on('readable', () => { + * myReader.read(); // etc. + * }); + * ``` + * @since v0.9.4 + * @param stream An "old style" readable stream + */ + wrap(stream: NodeJS.ReadableStream): this; + push(chunk: any, encoding?: BufferEncoding): boolean; + /** + * The iterator created by this method gives users the option to cancel the destruction + * of the stream if the `for await...of` loop is exited by `return`, `break`, or `throw`, + * or if the iterator should destroy the stream if the stream emitted an error during iteration. + * @since v16.3.0 + * @param options.destroyOnReturn When set to `false`, calling `return` on the async iterator, + * or exiting a `for await...of` iteration using a `break`, `return`, or `throw` will not destroy the stream. + * **Default: `true`**. + */ + iterator(options?: { destroyOnReturn?: boolean }): AsyncIterableIterator; + /** + * This method allows mapping over the stream. The *fn* function will be called for every chunk in the stream. + * If the *fn* function returns a promise - that promise will be `await`ed before being passed to the result stream. + * @since v17.4.0, v16.14.0 + * @param fn a function to map over every chunk in the stream. Async or not. + * @returns a stream mapped with the function *fn*. + */ + map(fn: (data: any, options?: Pick) => any, options?: ArrayOptions): Readable; + /** + * This method allows filtering the stream. For each chunk in the stream the *fn* function will be called + * and if it returns a truthy value, the chunk will be passed to the result stream. + * If the *fn* function returns a promise - that promise will be `await`ed. + * @since v17.4.0, v16.14.0 + * @param fn a function to filter chunks from the stream. Async or not. + * @returns a stream filtered with the predicate *fn*. + */ + filter( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Readable; + /** + * This method allows iterating a stream. For each chunk in the stream the *fn* function will be called. + * If the *fn* function returns a promise - that promise will be `await`ed. + * + * This method is different from `for await...of` loops in that it can optionally process chunks concurrently. + * In addition, a `forEach` iteration can only be stopped by having passed a `signal` option + * and aborting the related AbortController while `for await...of` can be stopped with `break` or `return`. + * In either case the stream will be destroyed. + * + * This method is different from listening to the `'data'` event in that it uses the `readable` event + * in the underlying machinary and can limit the number of concurrent *fn* calls. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise for when the stream has finished. + */ + forEach( + fn: (data: any, options?: Pick) => void | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method allows easily obtaining the contents of a stream. + * + * As this method reads the entire stream into memory, it negates the benefits of streams. It's intended + * for interoperability and convenience, not as the primary way to consume streams. + * @since v17.5.0 + * @returns a promise containing an array with the contents of the stream. + */ + toArray(options?: Pick): Promise; + /** + * This method is similar to `Array.prototype.some` and calls *fn* on each chunk in the stream + * until the awaited return value is `true` (or any truthy value). Once an *fn* call on a chunk + * `await`ed return value is truthy, the stream is destroyed and the promise is fulfilled with `true`. + * If none of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `false`. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise evaluating to `true` if *fn* returned a truthy value for at least one of the chunks. + */ + some( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method is similar to `Array.prototype.find` and calls *fn* on each chunk in the stream + * to find a chunk with a truthy value for *fn*. Once an *fn* call's awaited return value is truthy, + * the stream is destroyed and the promise is fulfilled with value for which *fn* returned a truthy value. + * If all of the *fn* calls on the chunks return a falsy value, the promise is fulfilled with `undefined`. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise evaluating to the first chunk for which *fn* evaluated with a truthy value, + * or `undefined` if no element was found. + */ + find( + fn: (data: any, options?: Pick) => data is T, + options?: ArrayOptions, + ): Promise; + find( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method is similar to `Array.prototype.every` and calls *fn* on each chunk in the stream + * to check if all awaited return values are truthy value for *fn*. Once an *fn* call on a chunk + * `await`ed return value is falsy, the stream is destroyed and the promise is fulfilled with `false`. + * If all of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `true`. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise evaluating to `true` if *fn* returned a truthy value for every one of the chunks. + */ + every( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method returns a new stream by applying the given callback to each chunk of the stream + * and then flattening the result. + * + * It is possible to return a stream or another iterable or async iterable from *fn* and the result streams + * will be merged (flattened) into the returned stream. + * @since v17.5.0 + * @param fn a function to map over every chunk in the stream. May be async. May be a stream or generator. + * @returns a stream flat-mapped with the function *fn*. + */ + flatMap(fn: (data: any, options?: Pick) => any, options?: ArrayOptions): Readable; + /** + * This method returns a new stream with the first *limit* chunks dropped from the start. + * @since v17.5.0 + * @param limit the number of chunks to drop from the readable. + * @returns a stream with *limit* chunks dropped from the start. + */ + drop(limit: number, options?: Pick): Readable; + /** + * This method returns a new stream with the first *limit* chunks. + * @since v17.5.0 + * @param limit the number of chunks to take from the readable. + * @returns a stream with *limit* chunks taken. + */ + take(limit: number, options?: Pick): Readable; + /** + * This method returns a new stream with chunks of the underlying stream paired with a counter + * in the form `[index, chunk]`. The first index value is `0` and it increases by 1 for each chunk produced. + * @since v17.5.0 + * @returns a stream of indexed pairs. + */ + asIndexedPairs(options?: Pick): Readable; + /** + * This method calls *fn* on each chunk of the stream in order, passing it the result from the calculation + * on the previous element. It returns a promise for the final value of the reduction. + * + * If no *initial* value is supplied the first chunk of the stream is used as the initial value. + * If the stream is empty, the promise is rejected with a `TypeError` with the `ERR_INVALID_ARGS` code property. + * + * The reducer function iterates the stream element-by-element which means that there is no *concurrency* parameter + * or parallelism. To perform a reduce concurrently, you can extract the async function to `readable.map` method. + * @since v17.5.0 + * @param fn a reducer function to call over every chunk in the stream. Async or not. + * @param initial the initial value to use in the reduction. + * @returns a promise for the final value of the reduction. + */ + reduce( + fn: (previous: any, data: any, options?: Pick) => T, + initial?: undefined, + options?: Pick, + ): Promise; + reduce( + fn: (previous: T, data: any, options?: Pick) => T, + initial: T, + options?: Pick, + ): Promise; + _destroy(error: Error | null, callback: (error?: Error | null) => void): void; + /** + * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'`event (unless `emitClose` is set to `false`). After this call, the readable + * stream will release any internal resources and subsequent calls to `push()`will be ignored. + * + * Once `destroy()` has been called any further calls will be a no-op and no + * further errors except from `_destroy()` may be emitted as `'error'`. + * + * Implementors should not override this method, but instead implement `readable._destroy()`. + * @since v8.0.0 + * @param error Error which will be passed as payload in `'error'` event + */ + destroy(error?: Error): this; + /** + * Event emitter + * The defined events on documents including: + * 1. close + * 2. data + * 3. end + * 4. error + * 5. pause + * 6. readable + * 7. resume + */ + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: any) => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "readable", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; + addListener(event: string | symbol, listener: (...args: any[]) => void): this; + emit(event: "close"): boolean; + emit(event: "data", chunk: any): boolean; + emit(event: "end"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "pause"): boolean; + emit(event: "readable"): boolean; + emit(event: "resume"): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: any) => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "pause", listener: () => void): this; + on(event: "readable", listener: () => void): this; + on(event: "resume", listener: () => void): this; + on(event: string | symbol, listener: (...args: any[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: any) => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "pause", listener: () => void): this; + once(event: "readable", listener: () => void): this; + once(event: "resume", listener: () => void): this; + once(event: string | symbol, listener: (...args: any[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: any) => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "readable", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; + prependListener(event: string | symbol, listener: (...args: any[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: any) => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "readable", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; + prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "data", listener: (chunk: any) => void): this; + removeListener(event: "end", listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "pause", listener: () => void): this; + removeListener(event: "readable", listener: () => void): this; + removeListener(event: "resume", listener: () => void): this; + removeListener(event: string | symbol, listener: (...args: any[]) => void): this; + [Symbol.asyncIterator](): AsyncIterableIterator; + /** + * Calls `readable.destroy()` with an `AbortError` and returns a promise that fulfills when the stream is finished. + * @since v20.4.0 + */ + [Symbol.asyncDispose](): Promise; + } + import WritableOptions = internal.WritableOptions; + class WritableBase extends Stream implements NodeJS.WritableStream { + /** + * Is `true` if it is safe to call `writable.write()`, which means + * the stream has not been destroyed, errored, or ended. + * @since v11.4.0 + */ + readonly writable: boolean; + /** + * Is `true` after `writable.end()` has been called. This property + * does not indicate whether the data has been flushed, for this use `writable.writableFinished` instead. + * @since v12.9.0 + */ + readonly writableEnded: boolean; + /** + * Is set to `true` immediately before the `'finish'` event is emitted. + * @since v12.6.0 + */ + readonly writableFinished: boolean; + /** + * Return the value of `highWaterMark` passed when creating this `Writable`. + * @since v9.3.0 + */ + readonly writableHighWaterMark: number; + /** + * This property contains the number of bytes (or objects) in the queue + * ready to be written. The value provides introspection data regarding + * the status of the `highWaterMark`. + * @since v9.4.0 + */ + readonly writableLength: number; + /** + * Getter for the property `objectMode` of a given `Writable` stream. + * @since v12.3.0 + */ + readonly writableObjectMode: boolean; + /** + * Number of times `writable.uncork()` needs to be + * called in order to fully uncork the stream. + * @since v13.2.0, v12.16.0 + */ + readonly writableCorked: number; + /** + * Is `true` after `writable.destroy()` has been called. + * @since v8.0.0 + */ + destroyed: boolean; + /** + * Is `true` after `'close'` has been emitted. + * @since v18.0.0 + */ + readonly closed: boolean; + /** + * Returns error if the stream has been destroyed with an error. + * @since v18.0.0 + */ + readonly errored: Error | null; + /** + * Is `true` if the stream's buffer has been full and stream will emit `'drain'`. + * @since v15.2.0, v14.17.0 + */ + readonly writableNeedDrain: boolean; + constructor(opts?: WritableOptions); + _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; + _writev?( + chunks: Array<{ + chunk: any; + encoding: BufferEncoding; + }>, + callback: (error?: Error | null) => void, + ): void; + _construct?(callback: (error?: Error | null) => void): void; + _destroy(error: Error | null, callback: (error?: Error | null) => void): void; + _final(callback: (error?: Error | null) => void): void; + /** + * The `writable.write()` method writes some data to the stream, and calls the + * supplied `callback` once the data has been fully handled. If an error + * occurs, the `callback` will be called with the error as its + * first argument. The `callback` is called asynchronously and before `'error'` is + * emitted. + * + * The return value is `true` if the internal buffer is less than the`highWaterMark` configured when the stream was created after admitting `chunk`. + * If `false` is returned, further attempts to write data to the stream should + * stop until the `'drain'` event is emitted. + * + * While a stream is not draining, calls to `write()` will buffer `chunk`, and + * return false. Once all currently buffered chunks are drained (accepted for + * delivery by the operating system), the `'drain'` event will be emitted. + * Once `write()` returns false, do not write more chunks + * until the `'drain'` event is emitted. While calling `write()` on a stream that + * is not draining is allowed, Node.js will buffer all written chunks until + * maximum memory usage occurs, at which point it will abort unconditionally. + * Even before it aborts, high memory usage will cause poor garbage collector + * performance and high RSS (which is not typically released back to the system, + * even after the memory is no longer required). Since TCP sockets may never + * drain if the remote peer does not read the data, writing a socket that is + * not draining may lead to a remotely exploitable vulnerability. + * + * Writing data while the stream is not draining is particularly + * problematic for a `Transform`, because the `Transform` streams are paused + * by default until they are piped or a `'data'` or `'readable'` event handler + * is added. + * + * If the data to be written can be generated or fetched on demand, it is + * recommended to encapsulate the logic into a `Readable` and use {@link pipe}. However, if calling `write()` is preferred, it is + * possible to respect backpressure and avoid memory issues using the `'drain'` event: + * + * ```js + * function write(data, cb) { + * if (!stream.write(data)) { + * stream.once('drain', cb); + * } else { + * process.nextTick(cb); + * } + * } + * + * // Wait for cb to be called before doing any other write. + * write('hello', () => { + * console.log('Write completed, do more writes now.'); + * }); + * ``` + * + * A `Writable` stream in object mode will always ignore the `encoding` argument. + * @since v0.9.4 + * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a string, `Buffer` or `Uint8Array`. For object mode streams, `chunk` may be any + * JavaScript value other than `null`. + * @param [encoding='utf8'] The encoding, if `chunk` is a string. + * @param callback Callback for when this chunk of data is flushed. + * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. + */ + write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean; + write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean; + /** + * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream. + * @since v0.11.15 + * @param encoding The new default encoding + */ + setDefaultEncoding(encoding: BufferEncoding): this; + /** + * Calling the `writable.end()` method signals that no more data will be written + * to the `Writable`. The optional `chunk` and `encoding` arguments allow one + * final additional chunk of data to be written immediately before closing the + * stream. + * + * Calling the {@link write} method after calling {@link end} will raise an error. + * + * ```js + * // Write 'hello, ' and then end with 'world!'. + * const fs = require('node:fs'); + * const file = fs.createWriteStream('example.txt'); + * file.write('hello, '); + * file.end('world!'); + * // Writing more now is not allowed! + * ``` + * @since v0.9.4 + * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a string, `Buffer` or `Uint8Array`. For object mode streams, `chunk` may be any + * JavaScript value other than `null`. + * @param encoding The encoding if `chunk` is a string + * @param callback Callback for when the stream is finished. + */ + end(cb?: () => void): this; + end(chunk: any, cb?: () => void): this; + end(chunk: any, encoding: BufferEncoding, cb?: () => void): this; + /** + * The `writable.cork()` method forces all written data to be buffered in memory. + * The buffered data will be flushed when either the {@link uncork} or {@link end} methods are called. + * + * The primary intent of `writable.cork()` is to accommodate a situation in which + * several small chunks are written to the stream in rapid succession. Instead of + * immediately forwarding them to the underlying destination, `writable.cork()`buffers all the chunks until `writable.uncork()` is called, which will pass them + * all to `writable._writev()`, if present. This prevents a head-of-line blocking + * situation where data is being buffered while waiting for the first small chunk + * to be processed. However, use of `writable.cork()` without implementing`writable._writev()` may have an adverse effect on throughput. + * + * See also: `writable.uncork()`, `writable._writev()`. + * @since v0.11.2 + */ + cork(): void; + /** + * The `writable.uncork()` method flushes all data buffered since {@link cork} was called. + * + * When using `writable.cork()` and `writable.uncork()` to manage the buffering + * of writes to a stream, defer calls to `writable.uncork()` using`process.nextTick()`. Doing so allows batching of all`writable.write()` calls that occur within a given Node.js event + * loop phase. + * + * ```js + * stream.cork(); + * stream.write('some '); + * stream.write('data '); + * process.nextTick(() => stream.uncork()); + * ``` + * + * If the `writable.cork()` method is called multiple times on a stream, the + * same number of calls to `writable.uncork()` must be called to flush the buffered + * data. + * + * ```js + * stream.cork(); + * stream.write('some '); + * stream.cork(); + * stream.write('data '); + * process.nextTick(() => { + * stream.uncork(); + * // The data will not be flushed until uncork() is called a second time. + * stream.uncork(); + * }); + * ``` + * + * See also: `writable.cork()`. + * @since v0.11.2 + */ + uncork(): void; + /** + * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'`event (unless `emitClose` is set to `false`). After this call, the writable + * stream has ended and subsequent calls to `write()` or `end()` will result in + * an `ERR_STREAM_DESTROYED` error. + * This is a destructive and immediate way to destroy a stream. Previous calls to`write()` may not have drained, and may trigger an `ERR_STREAM_DESTROYED` error. + * Use `end()` instead of destroy if data should flush before close, or wait for + * the `'drain'` event before destroying the stream. + * + * Once `destroy()` has been called any further calls will be a no-op and no + * further errors except from `_destroy()` may be emitted as `'error'`. + * + * Implementors should not override this method, + * but instead implement `writable._destroy()`. + * @since v8.0.0 + * @param error Optional, an error to emit with `'error'` event. + */ + destroy(error?: Error): this; + /** + * Event emitter + * The defined events on documents including: + * 1. close + * 2. drain + * 3. error + * 4. finish + * 5. pipe + * 6. unpipe + */ + addListener(event: "close", listener: () => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "pipe", listener: (src: Readable) => void): this; + addListener(event: "unpipe", listener: (src: Readable) => void): this; + addListener(event: string | symbol, listener: (...args: any[]) => void): this; + emit(event: "close"): boolean; + emit(event: "drain"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "finish"): boolean; + emit(event: "pipe", src: Readable): boolean; + emit(event: "unpipe", src: Readable): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "close", listener: () => void): this; + on(event: "drain", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "pipe", listener: (src: Readable) => void): this; + on(event: "unpipe", listener: (src: Readable) => void): this; + on(event: string | symbol, listener: (...args: any[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "drain", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "pipe", listener: (src: Readable) => void): this; + once(event: "unpipe", listener: (src: Readable) => void): this; + once(event: string | symbol, listener: (...args: any[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "pipe", listener: (src: Readable) => void): this; + prependListener(event: "unpipe", listener: (src: Readable) => void): this; + prependListener(event: string | symbol, listener: (...args: any[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "pipe", listener: (src: Readable) => void): this; + prependOnceListener(event: "unpipe", listener: (src: Readable) => void): this; + prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "drain", listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "finish", listener: () => void): this; + removeListener(event: "pipe", listener: (src: Readable) => void): this; + removeListener(event: "unpipe", listener: (src: Readable) => void): this; + removeListener(event: string | symbol, listener: (...args: any[]) => void): this; } namespace internal { class Stream extends internal { @@ -37,7 +948,7 @@ declare module 'stream' { highWaterMark?: number | undefined; objectMode?: boolean | undefined; construct?(this: T, callback: (error?: Error | null) => void): void; - destroy?(this: T, error: Error | null, callback: (error: Error | null) => void): void; + destroy?(this: T, error: Error | null, callback: (error?: Error | null) => void): void; autoDestroy?: boolean | undefined; } interface ReadableOptions extends StreamOptions { @@ -47,726 +958,61 @@ declare module 'stream' { /** * @since v0.9.4 */ - class Readable extends Stream implements NodeJS.ReadableStream { + class Readable extends ReadableBase { /** - * A utility method for creating Readable Streams out of iterators. - */ - static from(iterable: Iterable | AsyncIterable, options?: ReadableOptions): Readable; - /** - * Returns whether the stream has been read from or cancelled. - * @since v16.8.0 - */ - static isDisturbed(stream: Readable | NodeJS.ReadableStream): boolean; - /** - * Returns whether the stream was destroyed or errored before emitting `'end'`. - * @since v16.8.0 + * A utility method for creating a `Readable` from a web `ReadableStream`. + * @since v17.0.0 * @experimental */ - readonly readableAborted: boolean; + static fromWeb( + readableStream: streamWeb.ReadableStream, + options?: Pick, + ): Readable; /** - * Is `true` if it is safe to call `readable.read()`, which means - * the stream has not been destroyed or emitted `'error'` or `'end'`. - * @since v11.4.0 - */ - readable: boolean; - /** - * Returns whether `'data'` has been emitted. - * @since v16.7.0 + * A utility method for creating a web `ReadableStream` from a `Readable`. + * @since v17.0.0 * @experimental */ - readonly readableDidRead: boolean; - /** - * Getter for the property `encoding` of a given `Readable` stream. The `encoding`property can be set using the `readable.setEncoding()` method. - * @since v12.7.0 - */ - readonly readableEncoding: BufferEncoding | null; - /** - * Becomes `true` when `'end'` event is emitted. - * @since v12.9.0 - */ - readonly readableEnded: boolean; - /** - * This property reflects the current state of a `Readable` stream as described - * in the `Three states` section. - * @since v9.4.0 - */ - readonly readableFlowing: boolean | null; - /** - * Returns the value of `highWaterMark` passed when creating this `Readable`. - * @since v9.3.0 - */ - readonly readableHighWaterMark: number; - /** - * This property contains the number of bytes (or objects) in the queue - * ready to be read. The value provides introspection data regarding - * the status of the `highWaterMark`. - * @since v9.4.0 - */ - readonly readableLength: number; - /** - * Getter for the property `objectMode` of a given `Readable` stream. - * @since v12.3.0 - */ - readonly readableObjectMode: boolean; - /** - * Is `true` after `readable.destroy()` has been called. - * @since v8.0.0 - */ - destroyed: boolean; - constructor(opts?: ReadableOptions); - _construct?(callback: (error?: Error | null) => void): void; - _read(size: number): void; - /** - * The `readable.read()` method pulls some data out of the internal buffer and - * returns it. If no data available to be read, `null` is returned. By default, - * the data will be returned as a `Buffer` object unless an encoding has been - * specified using the `readable.setEncoding()` method or the stream is operating - * in object mode. - * - * The optional `size` argument specifies a specific number of bytes to read. If`size` bytes are not available to be read, `null` will be returned _unless_the stream has ended, in which - * case all of the data remaining in the internal - * buffer will be returned. - * - * If the `size` argument is not specified, all of the data contained in the - * internal buffer will be returned. - * - * The `size` argument must be less than or equal to 1 GiB. - * - * The `readable.read()` method should only be called on `Readable` streams - * operating in paused mode. In flowing mode, `readable.read()` is called - * automatically until the internal buffer is fully drained. - * - * ```js - * const readable = getReadableStreamSomehow(); - * - * // 'readable' may be triggered multiple times as data is buffered in - * readable.on('readable', () => { - * let chunk; - * console.log('Stream is readable (new data received in buffer)'); - * // Use a loop to make sure we read all currently available data - * while (null !== (chunk = readable.read())) { - * console.log(`Read ${chunk.length} bytes of data...`); - * } - * }); - * - * // 'end' will be triggered once when there is no more data available - * readable.on('end', () => { - * console.log('Reached end of stream.'); - * }); - * ``` - * - * Each call to `readable.read()` returns a chunk of data, or `null`. The chunks - * are not concatenated. A `while` loop is necessary to consume all data - * currently in the buffer. When reading a large file `.read()` may return `null`, - * having consumed all buffered content so far, but there is still more data to - * come not yet buffered. In this case a new `'readable'` event will be emitted - * when there is more data in the buffer. Finally the `'end'` event will be - * emitted when there is no more data to come. - * - * Therefore to read a file's whole contents from a `readable`, it is necessary - * to collect chunks across multiple `'readable'` events: - * - * ```js - * const chunks = []; - * - * readable.on('readable', () => { - * let chunk; - * while (null !== (chunk = readable.read())) { - * chunks.push(chunk); - * } - * }); - * - * readable.on('end', () => { - * const content = chunks.join(''); - * }); - * ``` - * - * A `Readable` stream in object mode will always return a single item from - * a call to `readable.read(size)`, regardless of the value of the`size` argument. - * - * If the `readable.read()` method returns a chunk of data, a `'data'` event will - * also be emitted. - * - * Calling {@link read} after the `'end'` event has - * been emitted will return `null`. No runtime error will be raised. - * @since v0.9.4 - * @param size Optional argument to specify how much data to read. - */ - read(size?: number): any; - /** - * The `readable.setEncoding()` method sets the character encoding for - * data read from the `Readable` stream. - * - * By default, no encoding is assigned and stream data will be returned as`Buffer` objects. Setting an encoding causes the stream data - * to be returned as strings of the specified encoding rather than as `Buffer`objects. For instance, calling `readable.setEncoding('utf8')` will cause the - * output data to be interpreted as UTF-8 data, and passed as strings. Calling`readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal - * string format. - * - * The `Readable` stream will properly handle multi-byte characters delivered - * through the stream that would otherwise become improperly decoded if simply - * pulled from the stream as `Buffer` objects. - * - * ```js - * const readable = getReadableStreamSomehow(); - * readable.setEncoding('utf8'); - * readable.on('data', (chunk) => { - * assert.equal(typeof chunk, 'string'); - * console.log('Got %d characters of string data:', chunk.length); - * }); - * ``` - * @since v0.9.4 - * @param encoding The encoding to use. - */ - setEncoding(encoding: BufferEncoding): this; - /** - * The `readable.pause()` method will cause a stream in flowing mode to stop - * emitting `'data'` events, switching out of flowing mode. Any data that - * becomes available will remain in the internal buffer. - * - * ```js - * const readable = getReadableStreamSomehow(); - * readable.on('data', (chunk) => { - * console.log(`Received ${chunk.length} bytes of data.`); - * readable.pause(); - * console.log('There will be no additional data for 1 second.'); - * setTimeout(() => { - * console.log('Now data will start flowing again.'); - * readable.resume(); - * }, 1000); - * }); - * ``` - * - * The `readable.pause()` method has no effect if there is a `'readable'`event listener. - * @since v0.9.4 - */ - pause(): this; - /** - * The `readable.resume()` method causes an explicitly paused `Readable` stream to - * resume emitting `'data'` events, switching the stream into flowing mode. - * - * The `readable.resume()` method can be used to fully consume the data from a - * stream without actually processing any of that data: - * - * ```js - * getReadableStreamSomehow() - * .resume() - * .on('end', () => { - * console.log('Reached the end, but did not read anything.'); - * }); - * ``` - * - * The `readable.resume()` method has no effect if there is a `'readable'`event listener. - * @since v0.9.4 - */ - resume(): this; - /** - * The `readable.isPaused()` method returns the current operating state of the`Readable`. This is used primarily by the mechanism that underlies the`readable.pipe()` method. In most - * typical cases, there will be no reason to - * use this method directly. - * - * ```js - * const readable = new stream.Readable(); - * - * readable.isPaused(); // === false - * readable.pause(); - * readable.isPaused(); // === true - * readable.resume(); - * readable.isPaused(); // === false - * ``` - * @since v0.11.14 - */ - isPaused(): boolean; - /** - * The `readable.unpipe()` method detaches a `Writable` stream previously attached - * using the {@link pipe} method. - * - * If the `destination` is not specified, then _all_ pipes are detached. - * - * If the `destination` is specified, but no pipe is set up for it, then - * the method does nothing. - * - * ```js - * const fs = require('fs'); - * const readable = getReadableStreamSomehow(); - * const writable = fs.createWriteStream('file.txt'); - * // All the data from readable goes into 'file.txt', - * // but only for the first second. - * readable.pipe(writable); - * setTimeout(() => { - * console.log('Stop writing to file.txt.'); - * readable.unpipe(writable); - * console.log('Manually close the file stream.'); - * writable.end(); - * }, 1000); - * ``` - * @since v0.9.4 - * @param destination Optional specific stream to unpipe - */ - unpipe(destination?: NodeJS.WritableStream): this; - /** - * Passing `chunk` as `null` signals the end of the stream (EOF) and behaves the - * same as `readable.push(null)`, after which no more data can be written. The EOF - * signal is put at the end of the buffer and any buffered data will still be - * flushed. - * - * The `readable.unshift()` method pushes a chunk of data back into the internal - * buffer. This is useful in certain situations where a stream is being consumed by - * code that needs to "un-consume" some amount of data that it has optimistically - * pulled out of the source, so that the data can be passed on to some other party. - * - * The `stream.unshift(chunk)` method cannot be called after the `'end'` event - * has been emitted or a runtime error will be thrown. - * - * Developers using `stream.unshift()` often should consider switching to - * use of a `Transform` stream instead. See the `API for stream implementers` section for more information. - * - * ```js - * // Pull off a header delimited by \n\n. - * // Use unshift() if we get too much. - * // Call the callback with (error, header, stream). - * const { StringDecoder } = require('string_decoder'); - * function parseHeader(stream, callback) { - * stream.on('error', callback); - * stream.on('readable', onReadable); - * const decoder = new StringDecoder('utf8'); - * let header = ''; - * function onReadable() { - * let chunk; - * while (null !== (chunk = stream.read())) { - * const str = decoder.write(chunk); - * if (str.match(/\n\n/)) { - * // Found the header boundary. - * const split = str.split(/\n\n/); - * header += split.shift(); - * const remaining = split.join('\n\n'); - * const buf = Buffer.from(remaining, 'utf8'); - * stream.removeListener('error', callback); - * // Remove the 'readable' listener before unshifting. - * stream.removeListener('readable', onReadable); - * if (buf.length) - * stream.unshift(buf); - * // Now the body of the message can be read from the stream. - * callback(null, header, stream); - * } else { - * // Still reading the header. - * header += str; - * } - * } - * } - * } - * ``` - * - * Unlike {@link push}, `stream.unshift(chunk)` will not - * end the reading process by resetting the internal reading state of the stream. - * This can cause unexpected results if `readable.unshift()` is called during a - * read (i.e. from within a {@link _read} implementation on a - * custom stream). Following the call to `readable.unshift()` with an immediate {@link push} will reset the reading state appropriately, - * however it is best to simply avoid calling `readable.unshift()` while in the - * process of performing a read. - * @since v0.9.11 - * @param chunk Chunk of data to unshift onto the read queue. For streams not operating in object mode, `chunk` must be a string, `Buffer`, `Uint8Array` or `null`. For object mode - * streams, `chunk` may be any JavaScript value. - * @param encoding Encoding of string chunks. Must be a valid `Buffer` encoding, such as `'utf8'` or `'ascii'`. - */ - unshift(chunk: any, encoding?: BufferEncoding): void; - /** - * Prior to Node.js 0.10, streams did not implement the entire `stream` module API - * as it is currently defined. (See `Compatibility` for more information.) - * - * When using an older Node.js library that emits `'data'` events and has a {@link pause} method that is advisory only, the`readable.wrap()` method can be used to create a `Readable` - * stream that uses - * the old stream as its data source. - * - * It will rarely be necessary to use `readable.wrap()` but the method has been - * provided as a convenience for interacting with older Node.js applications and - * libraries. - * - * ```js - * const { OldReader } = require('./old-api-module.js'); - * const { Readable } = require('stream'); - * const oreader = new OldReader(); - * const myReader = new Readable().wrap(oreader); - * - * myReader.on('readable', () => { - * myReader.read(); // etc. - * }); - * ``` - * @since v0.9.4 - * @param stream An "old style" readable stream - */ - wrap(stream: NodeJS.ReadableStream): this; - push(chunk: any, encoding?: BufferEncoding): boolean; - _destroy(error: Error | null, callback: (error?: Error | null) => void): void; - /** - * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'`event (unless `emitClose` is set to `false`). After this call, the readable - * stream will release any internal resources and subsequent calls to `push()`will be ignored. - * - * Once `destroy()` has been called any further calls will be a no-op and no - * further errors except from `_destroy()` may be emitted as `'error'`. - * - * Implementors should not override this method, but instead implement `readable._destroy()`. - * @since v8.0.0 - * @param error Error which will be passed as payload in `'error'` event - */ - destroy(error?: Error): this; - /** - * Event emitter - * The defined events on documents including: - * 1. close - * 2. data - * 3. end - * 4. error - * 5. pause - * 6. readable - * 7. resume - */ - addListener(event: 'close', listener: () => void): this; - addListener(event: 'data', listener: (chunk: any) => void): this; - addListener(event: 'end', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'pause', listener: () => void): this; - addListener(event: 'readable', listener: () => void): this; - addListener(event: 'resume', listener: () => void): this; - addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'close'): boolean; - emit(event: 'data', chunk: any): boolean; - emit(event: 'end'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'pause'): boolean; - emit(event: 'readable'): boolean; - emit(event: 'resume'): boolean; - emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'close', listener: () => void): this; - on(event: 'data', listener: (chunk: any) => void): this; - on(event: 'end', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'pause', listener: () => void): this; - on(event: 'readable', listener: () => void): this; - on(event: 'resume', listener: () => void): this; - on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'data', listener: (chunk: any) => void): this; - once(event: 'end', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'pause', listener: () => void): this; - once(event: 'readable', listener: () => void): this; - once(event: 'resume', listener: () => void): this; - once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'data', listener: (chunk: any) => void): this; - prependListener(event: 'end', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'pause', listener: () => void): this; - prependListener(event: 'readable', listener: () => void): this; - prependListener(event: 'resume', listener: () => void): this; - prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'data', listener: (chunk: any) => void): this; - prependOnceListener(event: 'end', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'pause', listener: () => void): this; - prependOnceListener(event: 'readable', listener: () => void): this; - prependOnceListener(event: 'resume', listener: () => void): this; - prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; - removeListener(event: 'close', listener: () => void): this; - removeListener(event: 'data', listener: (chunk: any) => void): this; - removeListener(event: 'end', listener: () => void): this; - removeListener(event: 'error', listener: (err: Error) => void): this; - removeListener(event: 'pause', listener: () => void): this; - removeListener(event: 'readable', listener: () => void): this; - removeListener(event: 'resume', listener: () => void): this; - removeListener(event: string | symbol, listener: (...args: any[]) => void): this; - [Symbol.asyncIterator](): AsyncIterableIterator; + static toWeb(streamReadable: Readable): streamWeb.ReadableStream; } interface WritableOptions extends StreamOptions { decodeStrings?: boolean | undefined; defaultEncoding?: BufferEncoding | undefined; - write?(this: Writable, chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; + write?( + this: Writable, + chunk: any, + encoding: BufferEncoding, + callback: (error?: Error | null) => void, + ): void; writev?( this: Writable, chunks: Array<{ chunk: any; encoding: BufferEncoding; }>, - callback: (error?: Error | null) => void + callback: (error?: Error | null) => void, ): void; final?(this: Writable, callback: (error?: Error | null) => void): void; } /** * @since v0.9.4 */ - class Writable extends Stream implements NodeJS.WritableStream { + class Writable extends WritableBase { /** - * Is `true` if it is safe to call `writable.write()`, which means - * the stream has not been destroyed, errored or ended. - * @since v11.4.0 + * A utility method for creating a `Writable` from a web `WritableStream`. + * @since v17.0.0 + * @experimental */ - readonly writable: boolean; + static fromWeb( + writableStream: streamWeb.WritableStream, + options?: Pick, + ): Writable; /** - * Is `true` after `writable.end()` has been called. This property - * does not indicate whether the data has been flushed, for this use `writable.writableFinished` instead. - * @since v12.9.0 + * A utility method for creating a web `WritableStream` from a `Writable`. + * @since v17.0.0 + * @experimental */ - readonly writableEnded: boolean; - /** - * Is set to `true` immediately before the `'finish'` event is emitted. - * @since v12.6.0 - */ - readonly writableFinished: boolean; - /** - * Return the value of `highWaterMark` passed when creating this `Writable`. - * @since v9.3.0 - */ - readonly writableHighWaterMark: number; - /** - * This property contains the number of bytes (or objects) in the queue - * ready to be written. The value provides introspection data regarding - * the status of the `highWaterMark`. - * @since v9.4.0 - */ - readonly writableLength: number; - /** - * Getter for the property `objectMode` of a given `Writable` stream. - * @since v12.3.0 - */ - readonly writableObjectMode: boolean; - /** - * Number of times `writable.uncork()` needs to be - * called in order to fully uncork the stream. - * @since v13.2.0, v12.16.0 - */ - readonly writableCorked: number; - /** - * Is `true` after `writable.destroy()` has been called. - * @since v8.0.0 - */ - destroyed: boolean; - constructor(opts?: WritableOptions); - _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; - _writev?( - chunks: Array<{ - chunk: any; - encoding: BufferEncoding; - }>, - callback: (error?: Error | null) => void - ): void; - _construct?(callback: (error?: Error | null) => void): void; - _destroy(error: Error | null, callback: (error?: Error | null) => void): void; - _final(callback: (error?: Error | null) => void): void; - /** - * The `writable.write()` method writes some data to the stream, and calls the - * supplied `callback` once the data has been fully handled. If an error - * occurs, the `callback` will be called with the error as its - * first argument. The `callback` is called asynchronously and before `'error'` is - * emitted. - * - * The return value is `true` if the internal buffer is less than the`highWaterMark` configured when the stream was created after admitting `chunk`. - * If `false` is returned, further attempts to write data to the stream should - * stop until the `'drain'` event is emitted. - * - * While a stream is not draining, calls to `write()` will buffer `chunk`, and - * return false. Once all currently buffered chunks are drained (accepted for - * delivery by the operating system), the `'drain'` event will be emitted. - * It is recommended that once `write()` returns false, no more chunks be written - * until the `'drain'` event is emitted. While calling `write()` on a stream that - * is not draining is allowed, Node.js will buffer all written chunks until - * maximum memory usage occurs, at which point it will abort unconditionally. - * Even before it aborts, high memory usage will cause poor garbage collector - * performance and high RSS (which is not typically released back to the system, - * even after the memory is no longer required). Since TCP sockets may never - * drain if the remote peer does not read the data, writing a socket that is - * not draining may lead to a remotely exploitable vulnerability. - * - * Writing data while the stream is not draining is particularly - * problematic for a `Transform`, because the `Transform` streams are paused - * by default until they are piped or a `'data'` or `'readable'` event handler - * is added. - * - * If the data to be written can be generated or fetched on demand, it is - * recommended to encapsulate the logic into a `Readable` and use {@link pipe}. However, if calling `write()` is preferred, it is - * possible to respect backpressure and avoid memory issues using the `'drain'` event: - * - * ```js - * function write(data, cb) { - * if (!stream.write(data)) { - * stream.once('drain', cb); - * } else { - * process.nextTick(cb); - * } - * } - * - * // Wait for cb to be called before doing any other write. - * write('hello', () => { - * console.log('Write completed, do more writes now.'); - * }); - * ``` - * - * A `Writable` stream in object mode will always ignore the `encoding` argument. - * @since v0.9.4 - * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a string, `Buffer` or `Uint8Array`. For object mode streams, `chunk` may be any - * JavaScript value other than `null`. - * @param [encoding='utf8'] The encoding, if `chunk` is a string. - * @param callback Callback for when this chunk of data is flushed. - * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. - */ - write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean; - write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean; - /** - * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream. - * @since v0.11.15 - * @param encoding The new default encoding - */ - setDefaultEncoding(encoding: BufferEncoding): this; - /** - * Calling the `writable.end()` method signals that no more data will be written - * to the `Writable`. The optional `chunk` and `encoding` arguments allow one - * final additional chunk of data to be written immediately before closing the - * stream. - * - * Calling the {@link write} method after calling {@link end} will raise an error. - * - * ```js - * // Write 'hello, ' and then end with 'world!'. - * const fs = require('fs'); - * const file = fs.createWriteStream('example.txt'); - * file.write('hello, '); - * file.end('world!'); - * // Writing more now is not allowed! - * ``` - * @since v0.9.4 - * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a string, `Buffer` or `Uint8Array`. For object mode streams, `chunk` may be any - * JavaScript value other than `null`. - * @param encoding The encoding if `chunk` is a string - * @param callback Callback for when the stream is finished. - */ - end(cb?: () => void): this; - end(chunk: any, cb?: () => void): this; - end(chunk: any, encoding: BufferEncoding, cb?: () => void): this; - /** - * The `writable.cork()` method forces all written data to be buffered in memory. - * The buffered data will be flushed when either the {@link uncork} or {@link end} methods are called. - * - * The primary intent of `writable.cork()` is to accommodate a situation in which - * several small chunks are written to the stream in rapid succession. Instead of - * immediately forwarding them to the underlying destination, `writable.cork()`buffers all the chunks until `writable.uncork()` is called, which will pass them - * all to `writable._writev()`, if present. This prevents a head-of-line blocking - * situation where data is being buffered while waiting for the first small chunk - * to be processed. However, use of `writable.cork()` without implementing`writable._writev()` may have an adverse effect on throughput. - * - * See also: `writable.uncork()`, `writable._writev()`. - * @since v0.11.2 - */ - cork(): void; - /** - * The `writable.uncork()` method flushes all data buffered since {@link cork} was called. - * - * When using `writable.cork()` and `writable.uncork()` to manage the buffering - * of writes to a stream, it is recommended that calls to `writable.uncork()` be - * deferred using `process.nextTick()`. Doing so allows batching of all`writable.write()` calls that occur within a given Node.js event loop phase. - * - * ```js - * stream.cork(); - * stream.write('some '); - * stream.write('data '); - * process.nextTick(() => stream.uncork()); - * ``` - * - * If the `writable.cork()` method is called multiple times on a stream, the - * same number of calls to `writable.uncork()` must be called to flush the buffered - * data. - * - * ```js - * stream.cork(); - * stream.write('some '); - * stream.cork(); - * stream.write('data '); - * process.nextTick(() => { - * stream.uncork(); - * // The data will not be flushed until uncork() is called a second time. - * stream.uncork(); - * }); - * ``` - * - * See also: `writable.cork()`. - * @since v0.11.2 - */ - uncork(): void; - /** - * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'`event (unless `emitClose` is set to `false`). After this call, the writable - * stream has ended and subsequent calls to `write()` or `end()` will result in - * an `ERR_STREAM_DESTROYED` error. - * This is a destructive and immediate way to destroy a stream. Previous calls to`write()` may not have drained, and may trigger an `ERR_STREAM_DESTROYED` error. - * Use `end()` instead of destroy if data should flush before close, or wait for - * the `'drain'` event before destroying the stream. - * - * Once `destroy()` has been called any further calls will be a no-op and no - * further errors except from `_destroy()` may be emitted as `'error'`. - * - * Implementors should not override this method, - * but instead implement `writable._destroy()`. - * @since v8.0.0 - * @param error Optional, an error to emit with `'error'` event. - */ - destroy(error?: Error): this; - /** - * Event emitter - * The defined events on documents including: - * 1. close - * 2. drain - * 3. error - * 4. finish - * 5. pipe - * 6. unpipe - */ - addListener(event: 'close', listener: () => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'finish', listener: () => void): this; - addListener(event: 'pipe', listener: (src: Readable) => void): this; - addListener(event: 'unpipe', listener: (src: Readable) => void): this; - addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'close'): boolean; - emit(event: 'drain'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'finish'): boolean; - emit(event: 'pipe', src: Readable): boolean; - emit(event: 'unpipe', src: Readable): boolean; - emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'close', listener: () => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'finish', listener: () => void): this; - on(event: 'pipe', listener: (src: Readable) => void): this; - on(event: 'unpipe', listener: (src: Readable) => void): this; - on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'finish', listener: () => void): this; - once(event: 'pipe', listener: (src: Readable) => void): this; - once(event: 'unpipe', listener: (src: Readable) => void): this; - once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'finish', listener: () => void): this; - prependListener(event: 'pipe', listener: (src: Readable) => void): this; - prependListener(event: 'unpipe', listener: (src: Readable) => void): this; - prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'finish', listener: () => void): this; - prependOnceListener(event: 'pipe', listener: (src: Readable) => void): this; - prependOnceListener(event: 'unpipe', listener: (src: Readable) => void): this; - prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; - removeListener(event: 'close', listener: () => void): this; - removeListener(event: 'drain', listener: () => void): this; - removeListener(event: 'error', listener: (err: Error) => void): this; - removeListener(event: 'finish', listener: () => void): this; - removeListener(event: 'pipe', listener: (src: Readable) => void): this; - removeListener(event: 'unpipe', listener: (src: Readable) => void): this; - removeListener(event: string | symbol, listener: (...args: any[]) => void): this; + static toWeb(streamWritable: Writable): streamWeb.WritableStream; } interface DuplexOptions extends ReadableOptions, WritableOptions { allowHalfOpen?: boolean | undefined; @@ -784,10 +1030,10 @@ declare module 'stream' { chunk: any; encoding: BufferEncoding; }>, - callback: (error?: Error | null) => void + callback: (error?: Error | null) => void, ): void; final?(this: Duplex, callback: (error?: Error | null) => void): void; - destroy?(this: Duplex, error: Error | null, callback: (error: Error | null) => void): void; + destroy?(this: Duplex, error: Error | null, callback: (error?: Error | null) => void): void; } /** * Duplex streams are streams that implement both the `Readable` and `Writable` interfaces. @@ -799,7 +1045,7 @@ declare module 'stream' { * * `crypto streams` * @since v0.9.4 */ - class Duplex extends Readable implements Writable { + class Duplex extends ReadableBase implements WritableBase { readonly writable: boolean; readonly writableEnded: boolean; readonly writableFinished: boolean; @@ -807,10 +1053,13 @@ declare module 'stream' { readonly writableLength: number; readonly writableObjectMode: boolean; readonly writableCorked: number; + readonly writableNeedDrain: boolean; + readonly closed: boolean; + readonly errored: Error | null; /** * If `false` then the stream will automatically end the writable side when the * readable side ends. Set initially by the `allowHalfOpen` constructor option, - * which defaults to `false`. + * which defaults to `true`. * * This can be changed manually to change the half-open behavior of an existing`Duplex` stream instance, but must be changed before the `'end'` event is * emitted. @@ -839,16 +1088,27 @@ declare module 'stream' { * * @since v16.8.0 */ - static from(src: Stream | Blob | ArrayBuffer | string | Iterable | AsyncIterable | AsyncGeneratorFunction | Promise | Object): Duplex; + static from( + src: + | Stream + | NodeBlob + | ArrayBuffer + | string + | Iterable + | AsyncIterable + | AsyncGeneratorFunction + | Promise + | Object, + ): Duplex; _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; _writev?( chunks: Array<{ chunk: any; encoding: BufferEncoding; }>, - callback: (error?: Error | null) => void + callback: (error?: Error | null) => void, ): void; - _destroy(error: Error | null, callback: (error: Error | null) => void): void; + _destroy(error: Error | null, callback: (error?: Error | null) => void): void; _final(callback: (error?: Error | null) => void): void; write(chunk: any, encoding?: BufferEncoding, cb?: (error: Error | null | undefined) => void): boolean; write(chunk: any, cb?: (error: Error | null | undefined) => void): boolean; @@ -858,22 +1118,150 @@ declare module 'stream' { end(chunk: any, encoding?: BufferEncoding, cb?: () => void): this; cork(): void; uncork(): void; + /** + * A utility method for creating a web `ReadableStream` and `WritableStream` from a `Duplex`. + * @since v17.0.0 + * @experimental + */ + static toWeb(streamDuplex: Duplex): { + readable: streamWeb.ReadableStream; + writable: streamWeb.WritableStream; + }; + /** + * A utility method for creating a `Duplex` from a web `ReadableStream` and `WritableStream`. + * @since v17.0.0 + * @experimental + */ + static fromWeb( + duplexStream: { + readable: streamWeb.ReadableStream; + writable: streamWeb.WritableStream; + }, + options?: Pick< + DuplexOptions, + "allowHalfOpen" | "decodeStrings" | "encoding" | "highWaterMark" | "objectMode" | "signal" + >, + ): Duplex; + /** + * Event emitter + * The defined events on documents including: + * 1. close + * 2. data + * 3. drain + * 4. end + * 5. error + * 6. finish + * 7. pause + * 8. pipe + * 9. readable + * 10. resume + * 11. unpipe + */ + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: any) => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "pipe", listener: (src: Readable) => void): this; + addListener(event: "readable", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; + addListener(event: "unpipe", listener: (src: Readable) => void): this; + addListener(event: string | symbol, listener: (...args: any[]) => void): this; + emit(event: "close"): boolean; + emit(event: "data", chunk: any): boolean; + emit(event: "drain"): boolean; + emit(event: "end"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "finish"): boolean; + emit(event: "pause"): boolean; + emit(event: "pipe", src: Readable): boolean; + emit(event: "readable"): boolean; + emit(event: "resume"): boolean; + emit(event: "unpipe", src: Readable): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: any) => void): this; + on(event: "drain", listener: () => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "pause", listener: () => void): this; + on(event: "pipe", listener: (src: Readable) => void): this; + on(event: "readable", listener: () => void): this; + on(event: "resume", listener: () => void): this; + on(event: "unpipe", listener: (src: Readable) => void): this; + on(event: string | symbol, listener: (...args: any[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: any) => void): this; + once(event: "drain", listener: () => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "pause", listener: () => void): this; + once(event: "pipe", listener: (src: Readable) => void): this; + once(event: "readable", listener: () => void): this; + once(event: "resume", listener: () => void): this; + once(event: "unpipe", listener: (src: Readable) => void): this; + once(event: string | symbol, listener: (...args: any[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: any) => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "pipe", listener: (src: Readable) => void): this; + prependListener(event: "readable", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; + prependListener(event: "unpipe", listener: (src: Readable) => void): this; + prependListener(event: string | symbol, listener: (...args: any[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: any) => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "pipe", listener: (src: Readable) => void): this; + prependOnceListener(event: "readable", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; + prependOnceListener(event: "unpipe", listener: (src: Readable) => void): this; + prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "data", listener: (chunk: any) => void): this; + removeListener(event: "drain", listener: () => void): this; + removeListener(event: "end", listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "finish", listener: () => void): this; + removeListener(event: "pause", listener: () => void): this; + removeListener(event: "pipe", listener: (src: Readable) => void): this; + removeListener(event: "readable", listener: () => void): this; + removeListener(event: "resume", listener: () => void): this; + removeListener(event: "unpipe", listener: (src: Readable) => void): this; + removeListener(event: string | symbol, listener: (...args: any[]) => void): this; } type TransformCallback = (error?: Error | null, data?: any) => void; interface TransformOptions extends DuplexOptions { construct?(this: Transform, callback: (error?: Error | null) => void): void; read?(this: Transform, size: number): void; - write?(this: Transform, chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; + write?( + this: Transform, + chunk: any, + encoding: BufferEncoding, + callback: (error?: Error | null) => void, + ): void; writev?( this: Transform, chunks: Array<{ chunk: any; encoding: BufferEncoding; }>, - callback: (error?: Error | null) => void + callback: (error?: Error | null) => void, ): void; final?(this: Transform, callback: (error?: Error | null) => void): void; - destroy?(this: Transform, error: Error | null, callback: (error: Error | null) => void): void; + destroy?(this: Transform, error: Error | null, callback: (error?: Error | null) => void): void; transform?(this: Transform, chunk: any, encoding: BufferEncoding, callback: TransformCallback): void; flush?(this: Transform, callback: TransformCallback): void; } @@ -899,18 +1287,21 @@ declare module 'stream' { */ class PassThrough extends Transform {} /** + * A stream to attach a signal to. + * * Attaches an AbortSignal to a readable or writeable stream. This lets code * control stream destruction using an `AbortController`. * - * Calling `abort` on the `AbortController` corresponding to the passed`AbortSignal` will behave the same way as calling `.destroy(new AbortError())`on the stream. + * Calling `abort` on the `AbortController` corresponding to the passed`AbortSignal` will behave the same way as calling `.destroy(new AbortError())`on the stream, and `controller.error(new + * AbortError())` for webstreams. * * ```js - * const fs = require('fs'); + * const fs = require('node:fs'); * * const controller = new AbortController(); * const read = addAbortSignal( * controller.signal, - * fs.createReadStream(('object.json')) + * fs.createReadStream(('object.json')), * ); * // Later, abort the operation closing the stream * controller.abort(); @@ -923,7 +1314,7 @@ declare module 'stream' { * setTimeout(() => controller.abort(), 10_000); // set a timeout * const stream = addAbortSignal( * controller.signal, - * fs.createReadStream(('object.json')) + * fs.createReadStream(('object.json')), * ); * (async () => { * try { @@ -939,22 +1330,70 @@ declare module 'stream' { * } * })(); * ``` + * + * Or using an `AbortSignal` with a ReadableStream: + * + * ```js + * const controller = new AbortController(); + * const rs = new ReadableStream({ + * start(controller) { + * controller.enqueue('hello'); + * controller.enqueue('world'); + * controller.close(); + * }, + * }); + * + * addAbortSignal(controller.signal, rs); + * + * finished(rs, (err) => { + * if (err) { + * if (err.name === 'AbortError') { + * // The operation was cancelled + * } + * } + * }); + * + * const reader = rs.getReader(); + * + * reader.read().then(({ value, done }) => { + * console.log(value); // hello + * console.log(done); // false + * controller.abort(); + * }); + * ``` * @since v15.4.0 * @param signal A signal representing possible cancellation * @param stream a stream to attach a signal to */ function addAbortSignal(signal: AbortSignal, stream: T): T; + /** + * Returns the default highWaterMark used by streams. + * Defaults to `16384` (16 KiB), or `16` for `objectMode`. + * @since v19.9.0 + * @param objectMode + */ + function getDefaultHighWaterMark(objectMode: boolean): number; + /** + * Sets the default highWaterMark used by streams. + * @since v19.9.0 + * @param objectMode + * @param value highWaterMark value + */ + function setDefaultHighWaterMark(objectMode: boolean, value: number): void; interface FinishedOptions extends Abortable { error?: boolean | undefined; readable?: boolean | undefined; writable?: boolean | undefined; } /** + * A readable and/or writable stream/webstream. + * * A function to get notified when a stream is no longer readable, writable * or has experienced an error or a premature close event. * * ```js - * const { finished } = require('stream'); + * const { finished } = require('node:stream'); + * const fs = require('node:fs'); * * const rs = fs.createReadStream('archive.tar'); * @@ -972,21 +1411,7 @@ declare module 'stream' { * Especially useful in error handling scenarios where a stream is destroyed * prematurely (like an aborted HTTP request), and will not emit `'end'`or `'finish'`. * - * The `finished` API provides promise version: - * - * ```js - * const { finished } = require('stream/promises'); - * - * const rs = fs.createReadStream('archive.tar'); - * - * async function run() { - * await finished(rs); - * console.log('Stream is done reading.'); - * } - * - * run().catch(console.error); - * rs.resume(); // Drain the stream. - * ``` + * The `finished` API provides `promise version`. * * `stream.finished()` leaves dangling event listeners (in particular`'error'`, `'end'`, `'finish'` and `'close'`) after `callback` has been * invoked. The reason for this is so that unexpected `'error'` events (due to @@ -1005,37 +1430,55 @@ declare module 'stream' { * @param callback A callback function that takes an optional error argument. * @return A cleanup function which removes all registered listeners. */ - function finished(stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, options: FinishedOptions, callback: (err?: NodeJS.ErrnoException | null) => void): () => void; - function finished(stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, callback: (err?: NodeJS.ErrnoException | null) => void): () => void; + function finished( + stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, + options: FinishedOptions, + callback: (err?: NodeJS.ErrnoException | null) => void, + ): () => void; + function finished( + stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, + callback: (err?: NodeJS.ErrnoException | null) => void, + ): () => void; namespace finished { - function __promisify__(stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, options?: FinishedOptions): Promise; + function __promisify__( + stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, + options?: FinishedOptions, + ): Promise; } type PipelineSourceFunction = () => Iterable | AsyncIterable; type PipelineSource = Iterable | AsyncIterable | NodeJS.ReadableStream | PipelineSourceFunction; type PipelineTransform, U> = | NodeJS.ReadWriteStream - | ((source: S extends (...args: any[]) => Iterable | AsyncIterable ? AsyncIterable : S) => AsyncIterable); + | (( + source: S extends (...args: any[]) => Iterable | AsyncIterable ? AsyncIterable + : S, + ) => AsyncIterable); type PipelineTransformSource = PipelineSource | PipelineTransform; type PipelineDestinationIterableFunction = (source: AsyncIterable) => AsyncIterable; type PipelineDestinationPromiseFunction = (source: AsyncIterable) => Promise

; - type PipelineDestination, P> = S extends PipelineTransformSource - ? NodeJS.WritableStream | PipelineDestinationIterableFunction | PipelineDestinationPromiseFunction + type PipelineDestination, P> = S extends + PipelineTransformSource ? + | NodeJS.WritableStream + | PipelineDestinationIterableFunction + | PipelineDestinationPromiseFunction : never; - type PipelineCallback> = S extends PipelineDestinationPromiseFunction - ? (err: NodeJS.ErrnoException | null, value: P) => void + type PipelineCallback> = S extends + PipelineDestinationPromiseFunction ? (err: NodeJS.ErrnoException | null, value: P) => void : (err: NodeJS.ErrnoException | null) => void; - type PipelinePromise> = S extends PipelineDestinationPromiseFunction ? Promise

: Promise; + type PipelinePromise> = S extends + PipelineDestinationPromiseFunction ? Promise

: Promise; interface PipelineOptions { - signal: AbortSignal; + signal?: AbortSignal | undefined; + end?: boolean | undefined; } /** * A module method to pipe between streams and generators forwarding errors and * properly cleaning up and provide a callback when the pipeline is complete. * * ```js - * const { pipeline } = require('stream'); - * const fs = require('fs'); - * const zlib = require('zlib'); + * const { pipeline } = require('node:stream'); + * const fs = require('node:fs'); + * const zlib = require('node:zlib'); * * // Use the pipeline API to easily pipe a series of streams * // together and get notified when the pipeline is fully done. @@ -1052,95 +1495,11 @@ declare module 'stream' { * } else { * console.log('Pipeline succeeded.'); * } - * } + * }, * ); * ``` * - * The `pipeline` API provides a promise version, which can also - * receive an options argument as the last parameter with a`signal` `AbortSignal` property. When the signal is aborted,`destroy` will be called on the underlying pipeline, with - * an`AbortError`. - * - * ```js - * const { pipeline } = require('stream/promises'); - * - * async function run() { - * await pipeline( - * fs.createReadStream('archive.tar'), - * zlib.createGzip(), - * fs.createWriteStream('archive.tar.gz') - * ); - * console.log('Pipeline succeeded.'); - * } - * - * run().catch(console.error); - * ``` - * - * To use an `AbortSignal`, pass it inside an options object, - * as the last argument: - * - * ```js - * const { pipeline } = require('stream/promises'); - * - * async function run() { - * const ac = new AbortController(); - * const signal = ac.signal; - * - * setTimeout(() => ac.abort(), 1); - * await pipeline( - * fs.createReadStream('archive.tar'), - * zlib.createGzip(), - * fs.createWriteStream('archive.tar.gz'), - * { signal }, - * ); - * } - * - * run().catch(console.error); // AbortError - * ``` - * - * The `pipeline` API also supports async generators: - * - * ```js - * const { pipeline } = require('stream/promises'); - * const fs = require('fs'); - * - * async function run() { - * await pipeline( - * fs.createReadStream('lowercase.txt'), - * async function* (source, signal) { - * source.setEncoding('utf8'); // Work with strings rather than `Buffer`s. - * for await (const chunk of source) { - * yield await processChunk(chunk, { signal }); - * } - * }, - * fs.createWriteStream('uppercase.txt') - * ); - * console.log('Pipeline succeeded.'); - * } - * - * run().catch(console.error); - * ``` - * - * Remember to handle the `signal` argument passed into the async generator. - * Especially in the case where the async generator is the source for the - * pipeline (i.e. first argument) or the pipeline will never complete. - * - * ```js - * const { pipeline } = require('stream/promises'); - * const fs = require('fs'); - * - * async function run() { - * await pipeline( - * async function * (signal) { - * await someLongRunningfn({ signal }); - * yield 'asd'; - * }, - * fs.createWriteStream('uppercase.txt') - * ); - * console.log('Pipeline succeeded.'); - * } - * - * run().catch(console.error); - * ``` + * The `pipeline` API provides a `promise version`. * * `stream.pipeline()` will call `stream.destroy(err)` on all streams except: * @@ -1149,83 +1508,164 @@ declare module 'stream' { * * `stream.pipeline()` leaves dangling event listeners on the streams * after the `callback` has been invoked. In the case of reuse of streams after - * failure, this can cause event listener leaks and swallowed errors. + * failure, this can cause event listener leaks and swallowed errors. If the last + * stream is readable, dangling event listeners will be removed so that the last + * stream can be consumed later. + * + * `stream.pipeline()` closes all the streams when an error is raised. + * The `IncomingRequest` usage with `pipeline` could lead to an unexpected behavior + * once it would destroy the socket without sending the expected response. + * See the example below: + * + * ```js + * const fs = require('node:fs'); + * const http = require('node:http'); + * const { pipeline } = require('node:stream'); + * + * const server = http.createServer((req, res) => { + * const fileStream = fs.createReadStream('./fileNotExist.txt'); + * pipeline(fileStream, res, (err) => { + * if (err) { + * console.log(err); // No such file + * // this message can't be sent once `pipeline` already destroyed the socket + * return res.end('error!!!'); + * } + * }); + * }); + * ``` * @since v10.0.0 * @param callback Called when the pipeline is fully done. */ function pipeline, B extends PipelineDestination>( source: A, destination: B, - callback?: PipelineCallback + callback?: PipelineCallback, ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; - function pipeline, T1 extends PipelineTransform, B extends PipelineDestination>( + function pipeline< + A extends PipelineSource, + T1 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, destination: B, - callback?: PipelineCallback + callback?: PipelineCallback, ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; - function pipeline, T1 extends PipelineTransform, T2 extends PipelineTransform, B extends PipelineDestination>( + function pipeline< + A extends PipelineSource, + T1 extends PipelineTransform, + T2 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, transform2: T2, destination: B, - callback?: PipelineCallback + callback?: PipelineCallback, ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; function pipeline< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, destination: B, callback?: PipelineCallback): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + destination: B, + callback?: PipelineCallback, + ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; function pipeline< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, T4 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, transform4: T4, destination: B, callback?: PipelineCallback): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + transform4: T4, + destination: B, + callback?: PipelineCallback, + ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; function pipeline( streams: ReadonlyArray, - callback?: (err: NodeJS.ErrnoException | null) => void + callback?: (err: NodeJS.ErrnoException | null) => void, ): NodeJS.WritableStream; function pipeline( stream1: NodeJS.ReadableStream, stream2: NodeJS.ReadWriteStream | NodeJS.WritableStream, - ...streams: Array void)> + ...streams: Array< + NodeJS.ReadWriteStream | NodeJS.WritableStream | ((err: NodeJS.ErrnoException | null) => void) + > ): NodeJS.WritableStream; namespace pipeline { - function __promisify__, B extends PipelineDestination>(source: A, destination: B, options?: PipelineOptions): PipelinePromise; - function __promisify__, T1 extends PipelineTransform, B extends PipelineDestination>( + function __promisify__, B extends PipelineDestination>( + source: A, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; + function __promisify__< + A extends PipelineSource, + T1 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, destination: B, - options?: PipelineOptions + options?: PipelineOptions, ): PipelinePromise; - function __promisify__, T1 extends PipelineTransform, T2 extends PipelineTransform, B extends PipelineDestination>( + function __promisify__< + A extends PipelineSource, + T1 extends PipelineTransform, + T2 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, transform2: T2, destination: B, - options?: PipelineOptions + options?: PipelineOptions, ): PipelinePromise; function __promisify__< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, destination: B, options?: PipelineOptions): PipelinePromise; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; function __promisify__< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, T4 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, transform4: T4, destination: B, options?: PipelineOptions): PipelinePromise; - function __promisify__(streams: ReadonlyArray, options?: PipelineOptions): Promise; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + transform4: T4, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; + function __promisify__( + streams: ReadonlyArray, + options?: PipelineOptions, + ): Promise; function __promisify__( stream1: NodeJS.ReadableStream, stream2: NodeJS.ReadWriteStream | NodeJS.WritableStream, @@ -1238,25 +1678,24 @@ declare module 'stream' { ref(): void; unref(): void; } - /** * Returns whether the stream has encountered an error. - * @since v16.14.0 + * @since v17.3.0, v16.14.0 + * @experimental */ function isErrored(stream: Readable | Writable | NodeJS.ReadableStream | NodeJS.WritableStream): boolean; - /** * Returns whether the stream is readable. - * @since v16.14.0 + * @since v17.4.0, v16.14.0 + * @experimental */ function isReadable(stream: Readable | NodeJS.ReadableStream): boolean; - const promises: typeof streamPromises; const consumers: typeof streamConsumers; } export = internal; } -declare module 'node:stream' { - import stream = require('stream'); +declare module "node:stream" { + import stream = require("stream"); export = stream; } diff --git a/node_modules/@types/node/stream/consumers.d.ts b/node_modules/@types/node/stream/consumers.d.ts old mode 100755 new mode 100644 index 1667c24..5ad9cba --- a/node_modules/@types/node/stream/consumers.d.ts +++ b/node_modules/@types/node/stream/consumers.d.ts @@ -1,12 +1,12 @@ -declare module 'stream/consumers' { - import { Readable } from 'node:stream'; +declare module "stream/consumers" { import { Blob as NodeBlob } from "node:buffer"; - function buffer(stream: NodeJS.ReadableStream | Readable | AsyncIterator): Promise; - function text(stream: NodeJS.ReadableStream | Readable | AsyncIterator): Promise; - function arrayBuffer(stream: NodeJS.ReadableStream | Readable | AsyncIterator): Promise; - function blob(stream: NodeJS.ReadableStream | Readable | AsyncIterator): Promise; - function json(stream: NodeJS.ReadableStream | Readable | AsyncIterator): Promise; + import { Readable } from "node:stream"; + function buffer(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; + function text(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; + function arrayBuffer(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; + function blob(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; + function json(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; } -declare module 'node:stream/consumers' { - export * from 'stream/consumers'; +declare module "node:stream/consumers" { + export * from "stream/consumers"; } diff --git a/node_modules/@types/node/stream/promises.d.ts b/node_modules/@types/node/stream/promises.d.ts old mode 100755 new mode 100644 index b427073..6eac5b7 --- a/node_modules/@types/node/stream/promises.d.ts +++ b/node_modules/@types/node/stream/promises.d.ts @@ -1,42 +1,83 @@ -declare module 'stream/promises' { - import { FinishedOptions, PipelineSource, PipelineTransform, PipelineDestination, PipelinePromise, PipelineOptions } from 'node:stream'; - function finished(stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, options?: FinishedOptions): Promise; - function pipeline, B extends PipelineDestination>(source: A, destination: B, options?: PipelineOptions): PipelinePromise; - function pipeline, T1 extends PipelineTransform, B extends PipelineDestination>( +declare module "stream/promises" { + import { + FinishedOptions, + PipelineDestination, + PipelineOptions, + PipelinePromise, + PipelineSource, + PipelineTransform, + } from "node:stream"; + function finished( + stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, + options?: FinishedOptions, + ): Promise; + function pipeline, B extends PipelineDestination>( + source: A, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; + function pipeline< + A extends PipelineSource, + T1 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, destination: B, - options?: PipelineOptions + options?: PipelineOptions, ): PipelinePromise; - function pipeline, T1 extends PipelineTransform, T2 extends PipelineTransform, B extends PipelineDestination>( + function pipeline< + A extends PipelineSource, + T1 extends PipelineTransform, + T2 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, transform2: T2, destination: B, - options?: PipelineOptions + options?: PipelineOptions, ): PipelinePromise; function pipeline< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, destination: B, options?: PipelineOptions): PipelinePromise; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; function pipeline< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, T4 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, transform4: T4, destination: B, options?: PipelineOptions): PipelinePromise; - function pipeline(streams: ReadonlyArray, options?: PipelineOptions): Promise; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + transform4: T4, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; + function pipeline( + streams: ReadonlyArray, + options?: PipelineOptions, + ): Promise; function pipeline( stream1: NodeJS.ReadableStream, stream2: NodeJS.ReadWriteStream | NodeJS.WritableStream, ...streams: Array ): Promise; } -declare module 'node:stream/promises' { - export * from 'stream/promises'; +declare module "node:stream/promises" { + export * from "stream/promises"; } diff --git a/node_modules/@types/node/stream/web.d.ts b/node_modules/@types/node/stream/web.d.ts old mode 100755 new mode 100644 index 666eed6..361594d --- a/node_modules/@types/node/stream/web.d.ts +++ b/node_modules/@types/node/stream/web.d.ts @@ -1,7 +1,6 @@ -declare module 'stream/web' { +declare module "stream/web" { // stub module, pending copy&paste from .d.ts or manual impl // copy from lib.dom.d.ts - interface ReadableWritablePair { readable: ReadableStream; /** @@ -15,7 +14,6 @@ declare module 'stream/web' { */ writable: WritableStream; } - interface StreamPipeOptions { preventAbort?: boolean; preventCancel?: boolean; @@ -63,17 +61,14 @@ declare module 'stream/web' { preventClose?: boolean; signal?: AbortSignal; } - interface ReadableStreamGenericReader { readonly closed: Promise; cancel(reason?: any): Promise; } - interface ReadableStreamDefaultReadValueResult { done: false; value: T; } - interface ReadableStreamDefaultReadDoneResult { done: true; value?: undefined; @@ -82,66 +77,61 @@ declare module 'stream/web' { type ReadableStreamDefaultReadResult = | ReadableStreamDefaultReadValueResult | ReadableStreamDefaultReadDoneResult; - + interface ReadableStreamReadValueResult { + done: false; + value: T; + } + interface ReadableStreamReadDoneResult { + done: true; + value?: T; + } + type ReadableStreamReadResult = ReadableStreamReadValueResult | ReadableStreamReadDoneResult; interface ReadableByteStreamControllerCallback { (controller: ReadableByteStreamController): void | PromiseLike; } - interface UnderlyingSinkAbortCallback { (reason?: any): void | PromiseLike; } - interface UnderlyingSinkCloseCallback { (): void | PromiseLike; } - interface UnderlyingSinkStartCallback { (controller: WritableStreamDefaultController): any; } - interface UnderlyingSinkWriteCallback { (chunk: W, controller: WritableStreamDefaultController): void | PromiseLike; } - interface UnderlyingSourceCancelCallback { (reason?: any): void | PromiseLike; } - interface UnderlyingSourcePullCallback { (controller: ReadableStreamController): void | PromiseLike; } - interface UnderlyingSourceStartCallback { (controller: ReadableStreamController): any; } - interface TransformerFlushCallback { (controller: TransformStreamDefaultController): void | PromiseLike; } - interface TransformerStartCallback { (controller: TransformStreamDefaultController): any; } - interface TransformerTransformCallback { (chunk: I, controller: TransformStreamDefaultController): void | PromiseLike; } - interface UnderlyingByteSource { autoAllocateChunkSize?: number; cancel?: ReadableStreamErrorCallback; pull?: ReadableByteStreamControllerCallback; start?: ReadableByteStreamControllerCallback; - type: 'bytes'; + type: "bytes"; } - interface UnderlyingSource { cancel?: UnderlyingSourceCancelCallback; pull?: UnderlyingSourcePullCallback; start?: UnderlyingSourceStartCallback; type?: undefined; } - interface UnderlyingSink { abort?: UnderlyingSinkAbortCallback; close?: UnderlyingSinkCloseCallback; @@ -149,45 +139,40 @@ declare module 'stream/web' { type?: undefined; write?: UnderlyingSinkWriteCallback; } - interface ReadableStreamErrorCallback { (reason: any): void | PromiseLike; } - /** This Streams API interface represents a readable stream of byte data. */ interface ReadableStream { readonly locked: boolean; cancel(reason?: any): Promise; getReader(): ReadableStreamDefaultReader; + getReader(options: { mode: "byob" }): ReadableStreamBYOBReader; pipeThrough(transform: ReadableWritablePair, options?: StreamPipeOptions): ReadableStream; pipeTo(destination: WritableStream, options?: StreamPipeOptions): Promise; tee(): [ReadableStream, ReadableStream]; values(options?: { preventCancel?: boolean }): AsyncIterableIterator; [Symbol.asyncIterator](): AsyncIterableIterator; } - const ReadableStream: { prototype: ReadableStream; - new ( - underlyingSource: UnderlyingByteSource, - strategy?: QueuingStrategy, - ): ReadableStream; - new (underlyingSource?: UnderlyingSource, strategy?: QueuingStrategy): ReadableStream; + new(underlyingSource: UnderlyingByteSource, strategy?: QueuingStrategy): ReadableStream; + new(underlyingSource?: UnderlyingSource, strategy?: QueuingStrategy): ReadableStream; }; - interface ReadableStreamDefaultReader extends ReadableStreamGenericReader { read(): Promise>; releaseLock(): void; } - + interface ReadableStreamBYOBReader extends ReadableStreamGenericReader { + read(view: T): Promise>; + releaseLock(): void; + } const ReadableStreamDefaultReader: { prototype: ReadableStreamDefaultReader; - new (stream: ReadableStream): ReadableStreamDefaultReader; + new(stream: ReadableStream): ReadableStreamDefaultReader; }; - const ReadableStreamBYOBReader: any; const ReadableStreamBYOBRequest: any; - interface ReadableByteStreamController { readonly byobRequest: undefined; readonly desiredSize: number | null; @@ -195,24 +180,20 @@ declare module 'stream/web' { enqueue(chunk: ArrayBufferView): void; error(error?: any): void; } - const ReadableByteStreamController: { prototype: ReadableByteStreamController; - new (): ReadableByteStreamController; + new(): ReadableByteStreamController; }; - interface ReadableStreamDefaultController { readonly desiredSize: number | null; close(): void; enqueue(chunk?: R): void; error(e?: any): void; } - const ReadableStreamDefaultController: { prototype: ReadableStreamDefaultController; - new (): ReadableStreamDefaultController; + new(): ReadableStreamDefaultController; }; - interface Transformer { flush?: TransformerFlushCallback; readableType?: undefined; @@ -220,33 +201,28 @@ declare module 'stream/web' { transform?: TransformerTransformCallback; writableType?: undefined; } - interface TransformStream { readonly readable: ReadableStream; readonly writable: WritableStream; } - const TransformStream: { prototype: TransformStream; - new ( + new( transformer?: Transformer, writableStrategy?: QueuingStrategy, readableStrategy?: QueuingStrategy, ): TransformStream; }; - interface TransformStreamDefaultController { readonly desiredSize: number | null; enqueue(chunk?: O): void; error(reason?: any): void; terminate(): void; } - const TransformStreamDefaultController: { prototype: TransformStreamDefaultController; - new (): TransformStreamDefaultController; + new(): TransformStreamDefaultController; }; - /** * This Streams API interface provides a standard abstraction for writing * streaming data to a destination, known as a sink. This object comes with @@ -258,12 +234,10 @@ declare module 'stream/web' { close(): Promise; getWriter(): WritableStreamDefaultWriter; } - const WritableStream: { prototype: WritableStream; - new (underlyingSink?: UnderlyingSink, strategy?: QueuingStrategy): WritableStream; + new(underlyingSink?: UnderlyingSink, strategy?: QueuingStrategy): WritableStream; }; - /** * This Streams API interface is the object returned by * WritableStream.getWriter() and once created locks the < writer to the @@ -279,12 +253,10 @@ declare module 'stream/web' { releaseLock(): void; write(chunk?: W): Promise; } - const WritableStreamDefaultWriter: { prototype: WritableStreamDefaultWriter; - new (stream: WritableStream): WritableStreamDefaultWriter; + new(stream: WritableStream): WritableStreamDefaultWriter; }; - /** * This Streams API interface represents a controller allowing control of a * WritableStream's state. When constructing a WritableStream, the @@ -294,21 +266,17 @@ declare module 'stream/web' { interface WritableStreamDefaultController { error(e?: any): void; } - const WritableStreamDefaultController: { prototype: WritableStreamDefaultController; - new (): WritableStreamDefaultController; + new(): WritableStreamDefaultController; }; - interface QueuingStrategy { highWaterMark?: number; size?: QueuingStrategySize; } - interface QueuingStrategySize { (chunk?: T): number; } - interface QueuingStrategyInit { /** * Creates a new ByteLengthQueuingStrategy with the provided high water @@ -321,7 +289,6 @@ declare module 'stream/web' { */ highWaterMark: number; } - /** * This Streams API interface provides a built-in byte length queuing * strategy that can be used when constructing streams. @@ -330,12 +297,10 @@ declare module 'stream/web' { readonly highWaterMark: number; readonly size: QueuingStrategySize; } - const ByteLengthQueuingStrategy: { prototype: ByteLengthQueuingStrategy; - new (init: QueuingStrategyInit): ByteLengthQueuingStrategy; + new(init: QueuingStrategyInit): ByteLengthQueuingStrategy; }; - /** * This Streams API interface provides a built-in byte length queuing * strategy that can be used when constructing streams. @@ -344,32 +309,26 @@ declare module 'stream/web' { readonly highWaterMark: number; readonly size: QueuingStrategySize; } - const CountQueuingStrategy: { prototype: CountQueuingStrategy; - new (init: QueuingStrategyInit): CountQueuingStrategy; + new(init: QueuingStrategyInit): CountQueuingStrategy; }; - interface TextEncoderStream { /** Returns "utf-8". */ - readonly encoding: 'utf-8'; + readonly encoding: "utf-8"; readonly readable: ReadableStream; readonly writable: WritableStream; readonly [Symbol.toStringTag]: string; } - const TextEncoderStream: { prototype: TextEncoderStream; - new (): TextEncoderStream; + new(): TextEncoderStream; }; - interface TextDecoderOptions { fatal?: boolean; ignoreBOM?: boolean; } - type BufferSource = ArrayBufferView | ArrayBuffer; - interface TextDecoderStream { /** Returns encoding's name, lower cased. */ readonly encoding: string; @@ -381,12 +340,27 @@ declare module 'stream/web' { readonly writable: WritableStream; readonly [Symbol.toStringTag]: string; } - const TextDecoderStream: { prototype: TextDecoderStream; - new (label?: string, options?: TextDecoderOptions): TextDecoderStream; + new(encoding?: string, options?: TextDecoderOptions): TextDecoderStream; + }; + interface CompressionStream { + readonly readable: ReadableStream; + readonly writable: WritableStream; + } + const CompressionStream: { + prototype: CompressionStream; + new(format: string): CompressionStream; + }; + interface DecompressionStream { + readonly readable: ReadableStream; + readonly writable: WritableStream; + } + const DecompressionStream: { + prototype: DecompressionStream; + new(format: string): DecompressionStream; }; } -declare module 'node:stream/web' { - export * from 'stream/web'; +declare module "node:stream/web" { + export * from "stream/web"; } diff --git a/node_modules/@types/node/string_decoder.d.ts b/node_modules/@types/node/string_decoder.d.ts old mode 100755 new mode 100644 index 584e0c5..b8691e1 --- a/node_modules/@types/node/string_decoder.d.ts +++ b/node_modules/@types/node/string_decoder.d.ts @@ -1,23 +1,23 @@ /** - * The `string_decoder` module provides an API for decoding `Buffer` objects into - * strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16 + * The `node:string_decoder` module provides an API for decoding `Buffer` objects + * into strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16 * characters. It can be accessed using: * * ```js - * const { StringDecoder } = require('string_decoder'); + * const { StringDecoder } = require('node:string_decoder'); * ``` * * The following example shows the basic use of the `StringDecoder` class. * * ```js - * const { StringDecoder } = require('string_decoder'); + * const { StringDecoder } = require('node:string_decoder'); * const decoder = new StringDecoder('utf8'); * * const cent = Buffer.from([0xC2, 0xA2]); - * console.log(decoder.write(cent)); + * console.log(decoder.write(cent)); // Prints: ¢ * * const euro = Buffer.from([0xE2, 0x82, 0xAC]); - * console.log(decoder.write(euro)); + * console.log(decoder.write(euro)); // Prints: € * ``` * * When a `Buffer` instance is written to the `StringDecoder` instance, an @@ -29,16 +29,16 @@ * symbol (`€`) are written over three separate operations: * * ```js - * const { StringDecoder } = require('string_decoder'); + * const { StringDecoder } = require('node:string_decoder'); * const decoder = new StringDecoder('utf8'); * * decoder.write(Buffer.from([0xE2])); * decoder.write(Buffer.from([0x82])); - * console.log(decoder.end(Buffer.from([0xAC]))); + * console.log(decoder.end(Buffer.from([0xAC]))); // Prints: € * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/string_decoder.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/string_decoder.js) */ -declare module 'string_decoder' { +declare module "string_decoder" { class StringDecoder { constructor(encoding?: BufferEncoding); /** @@ -46,7 +46,7 @@ declare module 'string_decoder' { * the end of the `Buffer`, or `TypedArray`, or `DataView` are omitted from the * returned string and stored in an internal buffer for the next call to`stringDecoder.write()` or `stringDecoder.end()`. * @since v0.1.99 - * @param buffer A `Buffer`, or `TypedArray`, or `DataView` containing the bytes to decode. + * @param buffer The bytes to decode. */ write(buffer: Buffer): string; /** @@ -57,11 +57,11 @@ declare module 'string_decoder' { * If the `buffer` argument is provided, one final call to `stringDecoder.write()`is performed before returning the remaining input. * After `end()` is called, the `stringDecoder` object can be reused for new input. * @since v0.9.3 - * @param buffer A `Buffer`, or `TypedArray`, or `DataView` containing the bytes to decode. + * @param buffer The bytes to decode. */ end(buffer?: Buffer): string; } } -declare module 'node:string_decoder' { - export * from 'string_decoder'; +declare module "node:string_decoder" { + export * from "string_decoder"; } diff --git a/node_modules/@types/node/test.d.ts b/node_modules/@types/node/test.d.ts old mode 100755 new mode 100644 index 1b870b9..149c9e0 --- a/node_modules/@types/node/test.d.ts +++ b/node_modules/@types/node/test.d.ts @@ -1,20 +1,120 @@ /** - * The `node:test` module provides a standalone testing module. - * @see [source](https://github.com/nodejs/node/blob/v16.17.0/lib/test.js) + * The `node:test` module facilitates the creation of JavaScript tests. + * To access it: + * + * ```js + * import test from 'node:test'; + * ``` + * + * This module is only available under the `node:` scheme. The following will not + * work: + * + * ```js + * import test from 'test'; + * ``` + * + * Tests created via the `test` module consist of a single function that is + * processed in one of three ways: + * + * 1. A synchronous function that is considered failing if it throws an exception, + * and is considered passing otherwise. + * 2. A function that returns a `Promise` that is considered failing if the`Promise` rejects, and is considered passing if the `Promise` fulfills. + * 3. A function that receives a callback function. If the callback receives any + * truthy value as its first argument, the test is considered failing. If a + * falsy value is passed as the first argument to the callback, the test is + * considered passing. If the test function receives a callback function and + * also returns a `Promise`, the test will fail. + * + * The following example illustrates how tests are written using the`test` module. + * + * ```js + * test('synchronous passing test', (t) => { + * // This test passes because it does not throw an exception. + * assert.strictEqual(1, 1); + * }); + * + * test('synchronous failing test', (t) => { + * // This test fails because it throws an exception. + * assert.strictEqual(1, 2); + * }); + * + * test('asynchronous passing test', async (t) => { + * // This test passes because the Promise returned by the async + * // function is settled and not rejected. + * assert.strictEqual(1, 1); + * }); + * + * test('asynchronous failing test', async (t) => { + * // This test fails because the Promise returned by the async + * // function is rejected. + * assert.strictEqual(1, 2); + * }); + * + * test('failing test using Promises', (t) => { + * // Promises can be used directly as well. + * return new Promise((resolve, reject) => { + * setImmediate(() => { + * reject(new Error('this will cause the test to fail')); + * }); + * }); + * }); + * + * test('callback passing test', (t, done) => { + * // done() is the callback function. When the setImmediate() runs, it invokes + * // done() with no arguments. + * setImmediate(done); + * }); + * + * test('callback failing test', (t, done) => { + * // When the setImmediate() runs, done() is invoked with an Error object and + * // the test fails. + * setImmediate(() => { + * done(new Error('callback failure')); + * }); + * }); + * ``` + * + * If any tests fail, the process exit code is set to `1`. + * @since v18.0.0, v16.17.0 + * @see [source](https://github.com/nodejs/node/blob/v20.4.0/lib/test.js) */ -declare module 'node:test' { +declare module "node:test" { + import { Readable } from "node:stream"; + import { AsyncResource } from "node:async_hooks"; /** - * The `test()` function is the value imported from the test module. Each invocation of this - * function results in the creation of a test point in the TAP output. + * **Note:**`shard` is used to horizontally parallelize test running across + * machines or processes, ideal for large-scale executions across varied + * environments. It's incompatible with `watch` mode, tailored for rapid + * code iteration by automatically rerunning tests on file changes. * - * The {@link TestContext} object passed to the fn argument can be used to perform actions - * related to the current test. Examples include skipping the test, adding additional TAP - * diagnostic information, or creating subtests. + * ```js + * import { tap } from 'node:test/reporters'; + * import { run } from 'node:test'; + * import process from 'node:process'; + * import path from 'node:path'; * - * `test()` returns a {@link Promise} that resolves once the test completes. The return value - * can usually be discarded for top level tests. However, the return value from subtests should - * be used to prevent the parent test from finishing first and cancelling the subtest as shown - * in the following example. + * run({ files: [path.resolve('./tests/test.js')] }) + * .compose(tap) + * .pipe(process.stdout); + * ``` + * @since v18.9.0, v16.19.0 + * @param options Configuration options for running tests. The following properties are supported: + */ + function run(options?: RunOptions): TestsStream; + /** + * The `test()` function is the value imported from the `test` module. Each + * invocation of this function results in reporting the test to the `TestsStream`. + * + * The `TestContext` object passed to the `fn` argument can be used to perform + * actions related to the current test. Examples include skipping the test, adding + * additional diagnostic information, or creating subtests. + * + * `test()` returns a `Promise` that fulfills once the test completes. + * if `test()` is called within a `describe()` block, it fulfills immediately. + * The return value can usually be discarded for top level tests. + * However, the return value from subtests should be used to prevent the parent + * test from finishing first and cancelling the subtest + * as shown in the following example. * * ```js * test('top level test', async (t) => { @@ -28,109 +128,381 @@ declare module 'node:test' { * }); * }); * ``` - * @since v16.17.0 - * @param name The name of the test, which is displayed when reporting test results. - * Default: The `name` property of fn, or `''` if `fn` does not have a name. - * @param options Configuration options for the test - * @param fn The function under test. The first argument to this function is a - * {@link TestContext} object. If the test uses callbacks, the callback function is - * passed as the second argument. Default: A no-op function. - * @returns A {@link Promise} resolved with `undefined` once the test completes. + * + * The `timeout` option can be used to fail the test if it takes longer than`timeout` milliseconds to complete. However, it is not a reliable mechanism for + * canceling tests because a running test might block the application thread and + * thus prevent the scheduled cancellation. + * @since v18.0.0, v16.17.0 + * @param [name='The name'] The name of the test, which is displayed when reporting test results. + * @param options Configuration options for the test. The following properties are supported: + * @param [fn='A no-op function'] The function under test. The first argument to this function is a {@link TestContext} object. If the test uses callbacks, the callback function is passed as the + * second argument. + * @return Fulfilled with `undefined` once the test completes, or immediately if the test runs within {@link describe}. */ function test(name?: string, fn?: TestFn): Promise; function test(name?: string, options?: TestOptions, fn?: TestFn): Promise; function test(options?: TestOptions, fn?: TestFn): Promise; function test(fn?: TestFn): Promise; - - /* - * @since v16.17.0 - * @param name The name of the suite, which is displayed when reporting suite results. - * Default: The `name` property of fn, or `''` if `fn` does not have a name. - * @param options Configuration options for the suite - * @param fn The function under suite. Default: A no-op function. + namespace test { + export { after, afterEach, before, beforeEach, describe, it, mock, only, run, skip, test, todo }; + } + /** + * The `describe()` function imported from the `node:test` module. Each + * invocation of this function results in the creation of a Subtest. + * After invocation of top level `describe` functions, + * all top level tests and suites will execute. + * @param [name='The name'] The name of the suite, which is displayed when reporting test results. + * @param options Configuration options for the suite. supports the same options as `test([name][, options][, fn])`. + * @param [fn='A no-op function'] The function under suite declaring all subtests and subsuites. The first argument to this function is a {@link SuiteContext} object. + * @return Immediately fulfilled with `undefined`. */ - function describe(name?: string, options?: TestOptions, fn?: SuiteFn): void; - function describe(name?: string, fn?: SuiteFn): void; - function describe(options?: TestOptions, fn?: SuiteFn): void; - function describe(fn?: SuiteFn): void; - - /* - * @since v16.17.0 - * @param name The name of the test, which is displayed when reporting test results. - * Default: The `name` property of fn, or `''` if `fn` does not have a name. - * @param options Configuration options for the test - * @param fn The function under test. If the test uses callbacks, the callback function is - * passed as the second argument. Default: A no-op function. + function describe(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function describe(name?: string, fn?: SuiteFn): Promise; + function describe(options?: TestOptions, fn?: SuiteFn): Promise; + function describe(fn?: SuiteFn): Promise; + namespace describe { + /** + * Shorthand for skipping a suite, same as `describe([name], { skip: true }[, fn])`. + */ + function skip(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function skip(name?: string, fn?: SuiteFn): Promise; + function skip(options?: TestOptions, fn?: SuiteFn): Promise; + function skip(fn?: SuiteFn): Promise; + /** + * Shorthand for marking a suite as `TODO`, same as `describe([name], { todo: true }[, fn])`. + */ + function todo(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function todo(name?: string, fn?: SuiteFn): Promise; + function todo(options?: TestOptions, fn?: SuiteFn): Promise; + function todo(fn?: SuiteFn): Promise; + /** + * Shorthand for marking a suite as `only`, same as `describe([name], { only: true }[, fn])`. + * @since v18.15.0 + */ + function only(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function only(name?: string, fn?: SuiteFn): Promise; + function only(options?: TestOptions, fn?: SuiteFn): Promise; + function only(fn?: SuiteFn): Promise; + } + /** + * Shorthand for `test()`. + * + * The `it()` function is imported from the `node:test` module. + * @since v18.6.0, v16.17.0 */ - function it(name?: string, options?: TestOptions, fn?: ItFn): void; - function it(name?: string, fn?: ItFn): void; - function it(options?: TestOptions, fn?: ItFn): void; - function it(fn?: ItFn): void; - + function it(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function it(name?: string, fn?: TestFn): Promise; + function it(options?: TestOptions, fn?: TestFn): Promise; + function it(fn?: TestFn): Promise; + namespace it { + /** + * Shorthand for skipping a test, same as `it([name], { skip: true }[, fn])`. + */ + function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function skip(name?: string, fn?: TestFn): Promise; + function skip(options?: TestOptions, fn?: TestFn): Promise; + function skip(fn?: TestFn): Promise; + /** + * Shorthand for marking a test as `TODO`, same as `it([name], { todo: true }[, fn])`. + */ + function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function todo(name?: string, fn?: TestFn): Promise; + function todo(options?: TestOptions, fn?: TestFn): Promise; + function todo(fn?: TestFn): Promise; + /** + * Shorthand for marking a test as `only`, same as `it([name], { only: true }[, fn])`. + * @since v18.15.0 + */ + function only(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function only(name?: string, fn?: TestFn): Promise; + function only(options?: TestOptions, fn?: TestFn): Promise; + function only(fn?: TestFn): Promise; + } + /** + * Shorthand for skipping a test, same as `test([name], { skip: true }[, fn])`. + * @since v20.2.0 + */ + function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function skip(name?: string, fn?: TestFn): Promise; + function skip(options?: TestOptions, fn?: TestFn): Promise; + function skip(fn?: TestFn): Promise; + /** + * Shorthand for marking a test as `TODO`, same as `test([name], { todo: true }[, fn])`. + * @since v20.2.0 + */ + function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function todo(name?: string, fn?: TestFn): Promise; + function todo(options?: TestOptions, fn?: TestFn): Promise; + function todo(fn?: TestFn): Promise; + /** + * Shorthand for marking a test as `only`, same as `test([name], { only: true }[, fn])`. + * @since v20.2.0 + */ + function only(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function only(name?: string, fn?: TestFn): Promise; + function only(options?: TestOptions, fn?: TestFn): Promise; + function only(fn?: TestFn): Promise; /** * The type of a function under test. The first argument to this function is a * {@link TestContext} object. If the test uses callbacks, the callback function is passed as * the second argument. */ - type TestFn = (t: TestContext, done: (result?: any) => void) => any; - + type TestFn = (t: TestContext, done: (result?: any) => void) => void | Promise; /** * The type of a function under Suite. - * If the test uses callbacks, the callback function is passed as an argument */ - type SuiteFn = (done: (result?: any) => void) => void; - - /** - * The type of a function under test. - * If the test uses callbacks, the callback function is passed as an argument - */ - type ItFn = (done: (result?: any) => void) => any; - - /** - * An instance of `TestContext` is passed to each test function in order to interact with the - * test runner. However, the `TestContext` constructor is not exposed as part of the API. - * @since v16.17.0 - */ - interface TestContext { + type SuiteFn = (s: SuiteContext) => void | Promise; + interface TestShard { /** - * This function is used to write TAP diagnostics to the output. Any diagnostic information is - * included at the end of the test's results. This function does not return a value. - * @param message Message to be displayed as a TAP diagnostic. - * @since v16.17.0 + * A positive integer between 1 and `` that specifies the index of the shard to run. + */ + index: number; + /** + * A positive integer that specifies the total number of shards to split the test files to. + */ + total: number; + } + interface RunOptions { + /** + * If a number is provided, then that many files would run in parallel. + * If truthy, it would run (number of cpu cores - 1) files in parallel. + * If falsy, it would only run one file at a time. + * If unspecified, subtests inherit this value from their parent. + * @default true + */ + concurrency?: number | boolean | undefined; + /** + * An array containing the list of files to run. + * If unspecified, the test runner execution model will be used. + */ + files?: readonly string[] | undefined; + /** + * Allows aborting an in-progress test execution. + * @default undefined + */ + signal?: AbortSignal | undefined; + /** + * A number of milliseconds the test will fail after. + * If unspecified, subtests inherit this value from their parent. + * @default Infinity + */ + timeout?: number | undefined; + /** + * Sets inspector port of test child process. + * If a nullish value is provided, each process gets its own port, + * incremented from the primary's `process.debugPort`. + */ + inspectPort?: number | (() => number) | undefined; + /** + * That can be used to only run tests whose name matches the provided pattern. + * Test name patterns are interpreted as JavaScript regular expressions. + * For each test that is executed, any corresponding test hooks, such as `beforeEach()`, are also run. + */ + testNamePatterns?: string | RegExp | string[] | RegExp[]; + /** + * If truthy, the test context will only run tests that have the `only` option set + */ + only?: boolean; + /** + * A function that accepts the TestsStream instance and can be used to setup listeners before any tests are run. + */ + setup?: (root: Test) => void | Promise; + /** + * Whether to run in watch mode or not. + * @default false + */ + watch?: boolean | undefined; + /** + * Running tests in a specific shard. + * @default undefined + */ + shard?: TestShard | undefined; + } + class Test extends AsyncResource { + concurrency: number; + nesting: number; + only: boolean; + reporter: TestsStream; + runOnlySubtests: boolean; + testNumber: number; + timeout: number | null; + } + /** + * A successful call to `run()` method will return a new `TestsStream` object, streaming a series of events representing the execution of the tests.`TestsStream` will emit events, in the + * order of the tests definition + * @since v18.9.0, v16.19.0 + */ + class TestsStream extends Readable implements NodeJS.ReadableStream { + addListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; + addListener(event: "test:fail", listener: (data: TestFail) => void): this; + addListener(event: "test:pass", listener: (data: TestPass) => void): this; + addListener(event: "test:plan", listener: (data: TestPlan) => void): this; + addListener(event: "test:start", listener: (data: TestStart) => void): this; + addListener(event: "test:stderr", listener: (data: TestStderr) => void): this; + addListener(event: "test:stdout", listener: (data: TestStdout) => void): this; + addListener(event: string, listener: (...args: any[]) => void): this; + emit(event: "test:diagnostic", data: DiagnosticData): boolean; + emit(event: "test:fail", data: TestFail): boolean; + emit(event: "test:pass", data: TestPass): boolean; + emit(event: "test:plan", data: TestPlan): boolean; + emit(event: "test:start", data: TestStart): boolean; + emit(event: "test:stderr", data: TestStderr): boolean; + emit(event: "test:stdout", data: TestStdout): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; + on(event: "test:fail", listener: (data: TestFail) => void): this; + on(event: "test:pass", listener: (data: TestPass) => void): this; + on(event: "test:plan", listener: (data: TestPlan) => void): this; + on(event: "test:start", listener: (data: TestStart) => void): this; + on(event: "test:stderr", listener: (data: TestStderr) => void): this; + on(event: "test:stdout", listener: (data: TestStdout) => void): this; + on(event: string, listener: (...args: any[]) => void): this; + once(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; + once(event: "test:fail", listener: (data: TestFail) => void): this; + once(event: "test:pass", listener: (data: TestPass) => void): this; + once(event: "test:plan", listener: (data: TestPlan) => void): this; + once(event: "test:start", listener: (data: TestStart) => void): this; + once(event: "test:stderr", listener: (data: TestStderr) => void): this; + once(event: "test:stdout", listener: (data: TestStdout) => void): this; + once(event: string, listener: (...args: any[]) => void): this; + prependListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; + prependListener(event: "test:fail", listener: (data: TestFail) => void): this; + prependListener(event: "test:pass", listener: (data: TestPass) => void): this; + prependListener(event: "test:plan", listener: (data: TestPlan) => void): this; + prependListener(event: "test:start", listener: (data: TestStart) => void): this; + prependListener(event: "test:stderr", listener: (data: TestStderr) => void): this; + prependListener(event: "test:stdout", listener: (data: TestStdout) => void): this; + prependListener(event: string, listener: (...args: any[]) => void): this; + prependOnceListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; + prependOnceListener(event: "test:fail", listener: (data: TestFail) => void): this; + prependOnceListener(event: "test:pass", listener: (data: TestPass) => void): this; + prependOnceListener(event: "test:plan", listener: (data: TestPlan) => void): this; + prependOnceListener(event: "test:start", listener: (data: TestStart) => void): this; + prependOnceListener(event: "test:stderr", listener: (data: TestStderr) => void): this; + prependOnceListener(event: "test:stdout", listener: (data: TestStdout) => void): this; + prependOnceListener(event: string, listener: (...args: any[]) => void): this; + } + /** + * An instance of `TestContext` is passed to each test function in order to + * interact with the test runner. However, the `TestContext` constructor is not + * exposed as part of the API. + * @since v18.0.0, v16.17.0 + */ + class TestContext { + /** + * This function is used to create a hook running before subtest of the current test. + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as + * the second argument. Default: A no-op function. + * @param options Configuration options for the hook. + * @since v20.1.0 + */ + before: typeof before; + /** + * This function is used to create a hook running before each subtest of the current test. + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as + * the second argument. Default: A no-op function. + * @param options Configuration options for the hook. + * @since v18.8.0 + */ + beforeEach: typeof beforeEach; + /** + * This function is used to create a hook that runs after the current test finishes. + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as + * the second argument. Default: A no-op function. + * @param options Configuration options for the hook. + * @since v18.13.0 + */ + after: typeof after; + /** + * This function is used to create a hook running after each subtest of the current test. + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as + * the second argument. Default: A no-op function. + * @param options Configuration options for the hook. + * @since v18.8.0 + */ + afterEach: typeof afterEach; + /** + * This function is used to write diagnostics to the output. Any diagnostic + * information is included at the end of the test's results. This function does + * not return a value. + * + * ```js + * test('top level test', (t) => { + * t.diagnostic('A diagnostic message'); + * }); + * ``` + * @since v18.0.0, v16.17.0 + * @param message Message to be reported. */ diagnostic(message: string): void; - /** - * If `shouldRunOnlyTests` is truthy, the test context will only run tests that have the `only` - * option set. Otherwise, all tests are run. If Node.js was not started with the `--test-only` - * command-line option, this function is a no-op. + * The name of the test. + * @since v18.8.0, v16.18.0 + */ + readonly name: string; + /** + * If `shouldRunOnlyTests` is truthy, the test context will only run tests that + * have the `only` option set. Otherwise, all tests are run. If Node.js was not + * started with the `--test-only` command-line option, this function is a + * no-op. + * + * ```js + * test('top level test', (t) => { + * // The test context can be set to run subtests with the 'only' option. + * t.runOnly(true); + * return Promise.all([ + * t.test('this subtest is now skipped'), + * t.test('this subtest is run', { only: true }), + * ]); + * }); + * ``` + * @since v18.0.0, v16.17.0 * @param shouldRunOnlyTests Whether or not to run `only` tests. - * @since v16.17.0 */ runOnly(shouldRunOnlyTests: boolean): void; - /** - * This function causes the test's output to indicate the test as skipped. If `message` is - * provided, it is included in the TAP output. Calling `skip()` does not terminate execution of - * the test function. This function does not return a value. - * @param message Optional skip message to be displayed in TAP output. - * @since v16.17.0 + * ```js + * test('top level test', async (t) => { + * await fetch('some/uri', { signal: t.signal }); + * }); + * ``` + * @since v18.7.0, v16.17.0 + */ + readonly signal: AbortSignal; + /** + * This function causes the test's output to indicate the test as skipped. If`message` is provided, it is included in the output. Calling `skip()` does + * not terminate execution of the test function. This function does not return a + * value. + * + * ```js + * test('top level test', (t) => { + * // Make sure to return here as well if the test contains additional logic. + * t.skip('this is skipped'); + * }); + * ``` + * @since v18.0.0, v16.17.0 + * @param message Optional skip message. */ skip(message?: string): void; - /** - * This function adds a `TODO` directive to the test's output. If `message` is provided, it is - * included in the TAP output. Calling `todo()` does not terminate execution of the test - * function. This function does not return a value. - * @param message Optional `TODO` message to be displayed in TAP output. - * @since v16.17.0 + * This function adds a `TODO` directive to the test's output. If `message` is + * provided, it is included in the output. Calling `todo()` does not terminate + * execution of the test function. This function does not return a value. + * + * ```js + * test('top level test', (t) => { + * // This test is marked as `TODO` + * t.todo('this is a todo'); + * }); + * ``` + * @since v18.0.0, v16.17.0 + * @param message Optional `TODO` message. */ todo(message?: string): void; - /** * This function is used to create subtests under the current test. This function behaves in * the same fashion as the top level {@link test} function. - * @since v16.17.0 + * @since v18.0.0 * @param name The name of the test, which is displayed when reporting test results. * Default: The `name` property of fn, or `''` if `fn` does not have a name. * @param options Configuration options for the test @@ -140,51 +512,954 @@ declare module 'node:test' { * @returns A {@link Promise} resolved with `undefined` once the test completes. */ test: typeof test; + /** + * Each test provides its own MockTracker instance. + */ + readonly mock: MockTracker; + } + /** + * An instance of `SuiteContext` is passed to each suite function in order to + * interact with the test runner. However, the `SuiteContext` constructor is not + * exposed as part of the API. + * @since v18.7.0, v16.17.0 + */ + class SuiteContext { + /** + * The name of the suite. + * @since v18.8.0, v16.18.0 + */ + readonly name: string; + /** + * Can be used to abort test subtasks when the test has been aborted. + * @since v18.7.0, v16.17.0 + */ + readonly signal: AbortSignal; } - interface TestOptions { /** - * The number of tests that can be run at the same time. If unspecified, subtests inherit this - * value from their parent. - * @default 1 + * If a number is provided, then that many tests would run in parallel. + * If truthy, it would run (number of cpu cores - 1) tests in parallel. + * For subtests, it will be `Infinity` tests in parallel. + * If falsy, it would only run one test at a time. + * If unspecified, subtests inherit this value from their parent. + * @default false */ - concurrency?: number; - + concurrency?: number | boolean | undefined; /** * If truthy, and the test context is configured to run `only` tests, then this test will be * run. Otherwise, the test is skipped. * @default false */ - only?: boolean; - + only?: boolean | undefined; /** * Allows aborting an in-progress test. - * @since v16.17.0 + * @since v18.8.0 */ - signal?: AbortSignal; - + signal?: AbortSignal | undefined; /** * If truthy, the test is skipped. If a string is provided, that string is displayed in the * test results as the reason for skipping the test. * @default false */ - skip?: boolean | string; - + skip?: boolean | string | undefined; /** * A number of milliseconds the test will fail after. If unspecified, subtests inherit this * value from their parent. * @default Infinity - * @since v16.17.0 + * @since v18.7.0 */ - timeout?: number; - + timeout?: number | undefined; /** * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in * the test results as the reason why the test is `TODO`. * @default false */ - todo?: boolean | string; + todo?: boolean | string | undefined; } + /** + * This function is used to create a hook running before running a suite. + * + * ```js + * describe('tests', async () => { + * before(() => console.log('about to run some test')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); + * }); + * ``` + * @since v18.8.0, v16.18.0 + * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. The following properties are supported: + */ + function before(fn?: HookFn, options?: HookOptions): void; + /** + * This function is used to create a hook running after running a suite. + * + * ```js + * describe('tests', async () => { + * after(() => console.log('finished running tests')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); + * }); + * ``` + * @since v18.8.0, v16.18.0 + * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. The following properties are supported: + */ + function after(fn?: HookFn, options?: HookOptions): void; + /** + * This function is used to create a hook running + * before each subtest of the current suite. + * + * ```js + * describe('tests', async () => { + * beforeEach(() => console.log('about to run a test')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); + * }); + * ``` + * @since v18.8.0, v16.18.0 + * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. The following properties are supported: + */ + function beforeEach(fn?: HookFn, options?: HookOptions): void; + /** + * This function is used to create a hook running + * after each subtest of the current test. + * + * ```js + * describe('tests', async () => { + * afterEach(() => console.log('finished running a test')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); + * }); + * ``` + * @since v18.8.0, v16.18.0 + * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. The following properties are supported: + */ + function afterEach(fn?: HookFn, options?: HookOptions): void; + /** + * The hook function. If the hook uses callbacks, the callback function is passed as the + * second argument. + */ + type HookFn = (s: SuiteContext, done: (result?: any) => void) => any; + /** + * Configuration options for hooks. + * @since v18.8.0 + */ + interface HookOptions { + /** + * Allows aborting an in-progress hook. + */ + signal?: AbortSignal | undefined; + /** + * A number of milliseconds the hook will fail after. If unspecified, subtests inherit this + * value from their parent. + * @default Infinity + */ + timeout?: number | undefined; + } + interface MockFunctionOptions { + /** + * The number of times that the mock will use the behavior of `implementation`. + * Once the mock function has been called `times` times, + * it will automatically restore the behavior of `original`. + * This value must be an integer greater than zero. + * @default Infinity + */ + times?: number | undefined; + } + interface MockMethodOptions extends MockFunctionOptions { + /** + * If `true`, `object[methodName]` is treated as a getter. + * This option cannot be used with the `setter` option. + */ + getter?: boolean | undefined; + /** + * If `true`, `object[methodName]` is treated as a setter. + * This option cannot be used with the `getter` option. + */ + setter?: boolean | undefined; + } + type Mock = F & { + mock: MockFunctionContext; + }; + type NoOpFunction = (...args: any[]) => undefined; + type FunctionPropertyNames = { + [K in keyof T]: T[K] extends Function ? K : never; + }[keyof T]; + /** + * The `MockTracker` class is used to manage mocking functionality. The test runner + * module provides a top level `mock` export which is a `MockTracker` instance. + * Each test also provides its own `MockTracker` instance via the test context's`mock` property. + * @since v19.1.0, v18.13.0 + */ + class MockTracker { + /** + * This function is used to create a mock function. + * + * The following example creates a mock function that increments a counter by one + * on each invocation. The `times` option is used to modify the mock behavior such + * that the first two invocations add two to the counter instead of one. + * + * ```js + * test('mocks a counting function', (t) => { + * let cnt = 0; + * + * function addOne() { + * cnt++; + * return cnt; + * } + * + * function addTwo() { + * cnt += 2; + * return cnt; + * } + * + * const fn = t.mock.fn(addOne, addTwo, { times: 2 }); + * + * assert.strictEqual(fn(), 2); + * assert.strictEqual(fn(), 4); + * assert.strictEqual(fn(), 5); + * assert.strictEqual(fn(), 6); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param [original='A no-op function'] An optional function to create a mock on. + * @param implementation An optional function used as the mock implementation for `original`. This is useful for creating mocks that exhibit one behavior for a specified number of calls and + * then restore the behavior of `original`. + * @param options Optional configuration options for the mock function. The following properties are supported: + * @return The mocked function. The mocked function contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the + * behavior of the mocked function. + */ + fn(original?: F, options?: MockFunctionOptions): Mock; + fn( + original?: F, + implementation?: Implementation, + options?: MockFunctionOptions, + ): Mock; + /** + * This function is used to create a mock on an existing object method. The + * following example demonstrates how a mock is created on an existing object + * method. + * + * ```js + * test('spies on an object method', (t) => { + * const number = { + * value: 5, + * subtract(a) { + * return this.value - a; + * }, + * }; + * + * t.mock.method(number, 'subtract'); + * assert.strictEqual(number.subtract.mock.calls.length, 0); + * assert.strictEqual(number.subtract(3), 2); + * assert.strictEqual(number.subtract.mock.calls.length, 1); + * + * const call = number.subtract.mock.calls[0]; + * + * assert.deepStrictEqual(call.arguments, [3]); + * assert.strictEqual(call.result, 2); + * assert.strictEqual(call.error, undefined); + * assert.strictEqual(call.target, undefined); + * assert.strictEqual(call.this, number); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param object The object whose method is being mocked. + * @param methodName The identifier of the method on `object` to mock. If `object[methodName]` is not a function, an error is thrown. + * @param implementation An optional function used as the mock implementation for `object[methodName]`. + * @param options Optional configuration options for the mock method. The following properties are supported: + * @return The mocked method. The mocked method contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the + * behavior of the mocked method. + */ + method< + MockedObject extends object, + MethodName extends FunctionPropertyNames, + >( + object: MockedObject, + methodName: MethodName, + options?: MockFunctionOptions, + ): MockedObject[MethodName] extends Function ? Mock + : never; + method< + MockedObject extends object, + MethodName extends FunctionPropertyNames, + Implementation extends Function, + >( + object: MockedObject, + methodName: MethodName, + implementation: Implementation, + options?: MockFunctionOptions, + ): MockedObject[MethodName] extends Function ? Mock + : never; + method( + object: MockedObject, + methodName: keyof MockedObject, + options: MockMethodOptions, + ): Mock; + method( + object: MockedObject, + methodName: keyof MockedObject, + implementation: Function, + options: MockMethodOptions, + ): Mock; - export { test as default, test, describe, it }; + /** + * This function is syntax sugar for `MockTracker.method` with `options.getter`set to `true`. + * @since v19.3.0, v18.13.0 + */ + getter< + MockedObject extends object, + MethodName extends keyof MockedObject, + >( + object: MockedObject, + methodName: MethodName, + options?: MockFunctionOptions, + ): Mock<() => MockedObject[MethodName]>; + getter< + MockedObject extends object, + MethodName extends keyof MockedObject, + Implementation extends Function, + >( + object: MockedObject, + methodName: MethodName, + implementation?: Implementation, + options?: MockFunctionOptions, + ): Mock<(() => MockedObject[MethodName]) | Implementation>; + /** + * This function is syntax sugar for `MockTracker.method` with `options.setter`set to `true`. + * @since v19.3.0, v18.13.0 + */ + setter< + MockedObject extends object, + MethodName extends keyof MockedObject, + >( + object: MockedObject, + methodName: MethodName, + options?: MockFunctionOptions, + ): Mock<(value: MockedObject[MethodName]) => void>; + setter< + MockedObject extends object, + MethodName extends keyof MockedObject, + Implementation extends Function, + >( + object: MockedObject, + methodName: MethodName, + implementation?: Implementation, + options?: MockFunctionOptions, + ): Mock<((value: MockedObject[MethodName]) => void) | Implementation>; + /** + * This function restores the default behavior of all mocks that were previously + * created by this `MockTracker` and disassociates the mocks from the`MockTracker` instance. Once disassociated, the mocks can still be used, but the`MockTracker` instance can no longer be + * used to reset their behavior or + * otherwise interact with them. + * + * After each test completes, this function is called on the test context's`MockTracker`. If the global `MockTracker` is used extensively, calling this + * function manually is recommended. + * @since v19.1.0, v18.13.0 + */ + reset(): void; + /** + * This function restores the default behavior of all mocks that were previously + * created by this `MockTracker`. Unlike `mock.reset()`, `mock.restoreAll()` does + * not disassociate the mocks from the `MockTracker` instance. + * @since v19.1.0, v18.13.0 + */ + restoreAll(): void; + timers: MockTimers; + } + const mock: MockTracker; + interface MockFunctionCall< + F extends Function, + ReturnType = F extends (...args: any) => infer T ? T + : F extends abstract new(...args: any) => infer T ? T + : unknown, + Args = F extends (...args: infer Y) => any ? Y + : F extends abstract new(...args: infer Y) => any ? Y + : unknown[], + > { + /** + * An array of the arguments passed to the mock function. + */ + arguments: Args; + /** + * If the mocked function threw then this property contains the thrown value. + */ + error: unknown | undefined; + /** + * The value returned by the mocked function. + * + * If the mocked function threw, it will be `undefined`. + */ + result: ReturnType | undefined; + /** + * An `Error` object whose stack can be used to determine the callsite of the mocked function invocation. + */ + stack: Error; + /** + * If the mocked function is a constructor, this field contains the class being constructed. + * Otherwise this will be `undefined`. + */ + target: F extends abstract new(...args: any) => any ? F : undefined; + /** + * The mocked function's `this` value. + */ + this: unknown; + } + /** + * The `MockFunctionContext` class is used to inspect or manipulate the behavior of + * mocks created via the `MockTracker` APIs. + * @since v19.1.0, v18.13.0 + */ + class MockFunctionContext { + /** + * A getter that returns a copy of the internal array used to track calls to the + * mock. Each entry in the array is an object with the following properties. + * @since v19.1.0, v18.13.0 + */ + readonly calls: Array>; + /** + * This function returns the number of times that this mock has been invoked. This + * function is more efficient than checking `ctx.calls.length` because `ctx.calls`is a getter that creates a copy of the internal call tracking array. + * @since v19.1.0, v18.13.0 + * @return The number of times that this mock has been invoked. + */ + callCount(): number; + /** + * This function is used to change the behavior of an existing mock. + * + * The following example creates a mock function using `t.mock.fn()`, calls the + * mock function, and then changes the mock implementation to a different function. + * + * ```js + * test('changes a mock behavior', (t) => { + * let cnt = 0; + * + * function addOne() { + * cnt++; + * return cnt; + * } + * + * function addTwo() { + * cnt += 2; + * return cnt; + * } + * + * const fn = t.mock.fn(addOne); + * + * assert.strictEqual(fn(), 1); + * fn.mock.mockImplementation(addTwo); + * assert.strictEqual(fn(), 3); + * assert.strictEqual(fn(), 5); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param implementation The function to be used as the mock's new implementation. + */ + mockImplementation(implementation: Function): void; + /** + * This function is used to change the behavior of an existing mock for a single + * invocation. Once invocation `onCall` has occurred, the mock will revert to + * whatever behavior it would have used had `mockImplementationOnce()` not been + * called. + * + * The following example creates a mock function using `t.mock.fn()`, calls the + * mock function, changes the mock implementation to a different function for the + * next invocation, and then resumes its previous behavior. + * + * ```js + * test('changes a mock behavior once', (t) => { + * let cnt = 0; + * + * function addOne() { + * cnt++; + * return cnt; + * } + * + * function addTwo() { + * cnt += 2; + * return cnt; + * } + * + * const fn = t.mock.fn(addOne); + * + * assert.strictEqual(fn(), 1); + * fn.mock.mockImplementationOnce(addTwo); + * assert.strictEqual(fn(), 3); + * assert.strictEqual(fn(), 4); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param implementation The function to be used as the mock's implementation for the invocation number specified by `onCall`. + * @param onCall The invocation number that will use `implementation`. If the specified invocation has already occurred then an exception is thrown. + */ + mockImplementationOnce(implementation: Function, onCall?: number): void; + /** + * Resets the call history of the mock function. + * @since v19.3.0, v18.13.0 + */ + resetCalls(): void; + /** + * Resets the implementation of the mock function to its original behavior. The + * mock can still be used after calling this function. + * @since v19.1.0, v18.13.0 + */ + restore(): void; + } + type Timer = "setInterval" | "setTimeout" | "setImmediate" | "Date"; + + interface MockTimersOptions { + apis: Timer[]; + now?: number | Date; + } + /** + * Mocking timers is a technique commonly used in software testing to simulate and + * control the behavior of timers, such as `setInterval` and `setTimeout`, + * without actually waiting for the specified time intervals. + * + * The MockTimers API also allows for mocking of the `Date` constructor and + * `setImmediate`/`clearImmediate` functions. + * + * The `MockTracker` provides a top-level `timers` export + * which is a `MockTimers` instance. + * @since v20.4.0 + * @experimental + */ + class MockTimers { + /** + * Enables timer mocking for the specified timers. + * + * **Note:** When you enable mocking for a specific timer, its associated + * clear function will also be implicitly mocked. + * + * **Note:** Mocking `Date` will affect the behavior of the mocked timers + * as they use the same internal clock. + * + * Example usage without setting initial time: + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.enable({ apis: ['setInterval', 'Date'], now: 1234 }); + * ``` + * + * The above example enables mocking for the `Date` constructor, `setInterval` timer and + * implicitly mocks the `clearInterval` function. Only the `Date` constructor from `globalThis`, + * `setInterval` and `clearInterval` functions from `node:timers`,`node:timers/promises`, and `globalThis` will be mocked. + * + * Example usage with initial time set + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.enable({ apis: ['Date'], now: 1000 }); + * ``` + * + * Example usage with initial Date object as time set + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.enable({ apis: ['Date'], now: new Date() }); + * ``` + * + * Alternatively, if you call `mock.timers.enable()` without any parameters: + * + * All timers (`'setInterval'`, `'clearInterval'`, `'Date'`, `'setImmediate'`, `'clearImmediate'`, `'setTimeout'`, and `'clearTimeout'`) + * will be mocked. + * + * The `setInterval`, `clearInterval`, `setTimeout`, and `clearTimeout` functions from `node:timers`, `node:timers/promises`, + * and `globalThis` will be mocked. + * The `Date` constructor from `globalThis` will be mocked. + * + * If there is no initial epoch set, the initial date will be based on 0 in the Unix epoch. This is `January 1st, 1970, 00:00:00 UTC`. You can set an initial date by passing a now property to the `.enable()` method. This value will be used as the initial date for the mocked Date object. It can either be a positive integer, or another Date object. + * @since v20.4.0 + */ + enable(options?: MockTimersOptions): void; + /** + * You can use the `.setTime()` method to manually move the mocked date to another time. This method only accepts a positive integer. + * Note: This method will execute any mocked timers that are in the past from the new time. + * In the below example we are setting a new time for the mocked date. + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * test('sets the time of a date object', (context) => { + * // Optionally choose what to mock + * context.mock.timers.enable({ apis: ['Date'], now: 100 }); + * assert.strictEqual(Date.now(), 100); + * // Advance in time will also advance the date + * context.mock.timers.setTime(1000); + * context.mock.timers.tick(200); + * assert.strictEqual(Date.now(), 1200); + * }); + * ``` + */ + setTime(time: number): void; + /** + * This function restores the default behavior of all mocks that were previously + * created by this `MockTimers` instance and disassociates the mocks + * from the `MockTracker` instance. + * + * **Note:** After each test completes, this function is called on + * the test context's `MockTracker`. + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.reset(); + * ``` + * @since v20.4.0 + */ + reset(): void; + /** + * Advances time for all mocked timers. + * + * **Note:** This diverges from how `setTimeout` in Node.js behaves and accepts + * only positive numbers. In Node.js, `setTimeout` with negative numbers is + * only supported for web compatibility reasons. + * + * The following example mocks a `setTimeout` function and + * by using `.tick` advances in + * time triggering all pending timers. + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { + * const fn = context.mock.fn(); + * + * context.mock.timers.enable({ apis: ['setTimeout'] }); + * + * setTimeout(fn, 9999); + * + * assert.strictEqual(fn.mock.callCount(), 0); + * + * // Advance in time + * context.mock.timers.tick(9999); + * + * assert.strictEqual(fn.mock.callCount(), 1); + * }); + * ``` + * + * Alternativelly, the `.tick` function can be called many times + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { + * const fn = context.mock.fn(); + * context.mock.timers.enable({ apis: ['setTimeout'] }); + * const nineSecs = 9000; + * setTimeout(fn, nineSecs); + * + * const twoSeconds = 3000; + * context.mock.timers.tick(twoSeconds); + * context.mock.timers.tick(twoSeconds); + * context.mock.timers.tick(twoSeconds); + * + * assert.strictEqual(fn.mock.callCount(), 1); + * }); + * ``` + * + * Advancing time using `.tick` will also advance the time for any `Date` object + * created after the mock was enabled (if `Date` was also set to be mocked). + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { + * const fn = context.mock.fn(); + * + * context.mock.timers.enable({ apis: ['setTimeout', 'Date'] }); + * setTimeout(fn, 9999); + * + * assert.strictEqual(fn.mock.callCount(), 0); + * assert.strictEqual(Date.now(), 0); + * + * // Advance in time + * context.mock.timers.tick(9999); + * assert.strictEqual(fn.mock.callCount(), 1); + * assert.strictEqual(Date.now(), 9999); + * }); + * ``` + * @since v20.4.0 + */ + tick(milliseconds: number): void; + /** + * Triggers all pending mocked timers immediately. If the `Date` object is also + * mocked, it will also advance the `Date` object to the furthest timer's time. + * + * The example below triggers all pending timers immediately, + * causing them to execute without any delay. + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('runAll functions following the given order', (context) => { + * context.mock.timers.enable({ apis: ['setTimeout', 'Date'] }); + * const results = []; + * setTimeout(() => results.push(1), 9999); + * + * // Notice that if both timers have the same timeout, + * // the order of execution is guaranteed + * setTimeout(() => results.push(3), 8888); + * setTimeout(() => results.push(2), 8888); + * + * assert.deepStrictEqual(results, []); + * + * context.mock.timers.runAll(); + * assert.deepStrictEqual(results, [3, 2, 1]); + * // The Date object is also advanced to the furthest timer's time + * assert.strictEqual(Date.now(), 9999); + * }); + * ``` + * + * **Note:** The `runAll()` function is specifically designed for + * triggering timers in the context of timer mocking. + * It does not have any effect on real-time system + * clocks or actual timers outside of the mocking environment. + * @since v20.4.0 + */ + runAll(): void; + /** + * Calls {@link MockTimers.reset()}. + */ + [Symbol.dispose](): void; + } + export { + after, + afterEach, + before, + beforeEach, + describe, + it, + Mock, + mock, + only, + run, + skip, + test, + test as default, + todo, + }; +} + +interface TestLocationInfo { + /** + * The column number where the test is defined, or + * `undefined` if the test was run through the REPL. + */ + column?: number; + /** + * The path of the test file, `undefined` if test is not ran through a file. + */ + file?: string; + /** + * The line number where the test is defined, or + * `undefined` if the test was run through the REPL. + */ + line?: number; +} +interface DiagnosticData extends TestLocationInfo { + /** + * The diagnostic message. + */ + message: string; + /** + * The nesting level of the test. + */ + nesting: number; +} +interface TestFail extends TestLocationInfo { + /** + * Additional execution metadata. + */ + details: { + /** + * The duration of the test in milliseconds. + */ + duration_ms: number; + /** + * The error thrown by the test. + */ + error: Error; + /** + * The type of the test, used to denote whether this is a suite. + * @since 20.0.0, 19.9.0, 18.17.0 + */ + type?: "suite"; + }; + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The ordinal number of the test. + */ + testNumber: number; + /** + * Present if `context.todo` is called. + */ + todo?: string | boolean; + /** + * Present if `context.skip` is called. + */ + skip?: string | boolean; +} +interface TestPass extends TestLocationInfo { + /** + * Additional execution metadata. + */ + details: { + /** + * The duration of the test in milliseconds. + */ + duration_ms: number; + /** + * The type of the test, used to denote whether this is a suite. + * @since 20.0.0, 19.9.0, 18.17.0 + */ + type?: "suite"; + }; + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The ordinal number of the test. + */ + testNumber: number; + /** + * Present if `context.todo` is called. + */ + todo?: string | boolean; + /** + * Present if `context.skip` is called. + */ + skip?: string | boolean; +} +interface TestPlan extends TestLocationInfo { + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The number of subtests that have ran. + */ + count: number; +} +interface TestStart extends TestLocationInfo { + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; +} +interface TestStderr extends TestLocationInfo { + /** + * The message written to `stderr` + */ + message: string; +} +interface TestStdout extends TestLocationInfo { + /** + * The message written to `stdout` + */ + message: string; +} +interface TestEnqueue extends TestLocationInfo { + /** + * The test name + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; +} +interface TestDequeue extends TestLocationInfo { + /** + * The test name + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; +} + +/** + * The `node:test/reporters` module exposes the builtin-reporters for `node:test`. + * To access it: + * + * ```js + * import test from 'node:test/reporters'; + * ``` + * + * This module is only available under the `node:` scheme. The following will not + * work: + * + * ```js + * import test from 'test/reporters'; + * ``` + * @since v19.9.0 + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/test/reporters.js) + */ +declare module "node:test/reporters" { + import { Transform, TransformOptions } from "node:stream"; + + type TestEvent = + | { type: "test:diagnostic"; data: DiagnosticData } + | { type: "test:fail"; data: TestFail } + | { type: "test:pass"; data: TestPass } + | { type: "test:plan"; data: TestPlan } + | { type: "test:start"; data: TestStart } + | { type: "test:stderr"; data: TestStderr } + | { type: "test:stdout"; data: TestStdout } + | { type: "test:enqueue"; data: TestEnqueue } + | { type: "test:dequeue"; data: TestDequeue } + | { type: "test:watch:drained" }; + type TestEventGenerator = AsyncGenerator; + + /** + * The `dot` reporter outputs the test results in a compact format, + * where each passing test is represented by a `.`, + * and each failing test is represented by a `X`. + */ + function dot(source: TestEventGenerator): AsyncGenerator<"\n" | "." | "X", void>; + /** + * The `tap` reporter outputs the test results in the [TAP](https://testanything.org/) format. + */ + function tap(source: TestEventGenerator): AsyncGenerator; + /** + * The `spec` reporter outputs the test results in a human-readable format. + */ + class Spec extends Transform { + constructor(); + } + /** + * The `junit` reporter outputs test results in a jUnit XML format + */ + function junit(source: TestEventGenerator): AsyncGenerator; + class Lcov extends Transform { + constructor(opts?: TransformOptions); + } + export { dot, junit, Lcov as lcov, Spec as spec, tap, TestEvent }; } diff --git a/node_modules/@types/node/timers.d.ts b/node_modules/@types/node/timers.d.ts old mode 100755 new mode 100644 index 4d14758..039f31f --- a/node_modules/@types/node/timers.d.ts +++ b/node_modules/@types/node/timers.d.ts @@ -1,16 +1,20 @@ /** * The `timer` module exposes a global API for scheduling functions to * be called at some future period of time. Because the timer functions are - * globals, there is no need to call `require('timers')` to use the API. + * globals, there is no need to call `require('node:timers')` to use the API. * * The timer functions within Node.js implement a similar API as the timers API * provided by Web Browsers but use a different internal implementation that is * built around the Node.js [Event Loop](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/#setimmediate-vs-settimeout). - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/timers.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/timers.js) */ -declare module 'timers' { - import { Abortable } from 'node:events'; - import { setTimeout as setTimeoutPromise, setImmediate as setImmediatePromise, setInterval as setIntervalPromise } from 'node:timers/promises'; +declare module "timers" { + import { Abortable } from "node:events"; + import { + setImmediate as setImmediatePromise, + setInterval as setIntervalPromise, + setTimeout as setTimeoutPromise, + } from "node:timers/promises"; interface TimerOptions extends Abortable { /** * Set to `false` to indicate that the scheduled `Timeout` @@ -33,15 +37,74 @@ declare module 'timers' { refresh(): this; [Symbol.toPrimitive](): number; } - interface Immediate extends RefCounted { + /** + * This object is created internally and is returned from `setImmediate()`. It + * can be passed to `clearImmediate()` in order to cancel the scheduled + * actions. + * + * By default, when an immediate is scheduled, the Node.js event loop will continue + * running as long as the immediate is active. The `Immediate` object returned by `setImmediate()` exports both `immediate.ref()` and `immediate.unref()`functions that can be used to + * control this default behavior. + */ + class Immediate implements RefCounted { + /** + * When called, requests that the Node.js event loop _not_ exit so long as the`Immediate` is active. Calling `immediate.ref()` multiple times will have no + * effect. + * + * By default, all `Immediate` objects are "ref'ed", making it normally unnecessary + * to call `immediate.ref()` unless `immediate.unref()` had been called previously. + * @since v9.7.0 + * @return a reference to `immediate` + */ + ref(): this; + /** + * When called, the active `Immediate` object will not require the Node.js event + * loop to remain active. If there is no other activity keeping the event loop + * running, the process may exit before the `Immediate` object's callback is + * invoked. Calling `immediate.unref()` multiple times will have no effect. + * @since v9.7.0 + * @return a reference to `immediate` + */ + unref(): this; /** * If true, the `Immediate` object will keep the Node.js event loop active. * @since v11.0.0 */ hasRef(): boolean; _onImmediate: Function; // to distinguish it from the Timeout class + /** + * Cancels the immediate. This is similar to calling `clearImmediate()`. + * @since v20.5.0 + */ + [Symbol.dispose](): void; } - interface Timeout extends Timer { + /** + * This object is created internally and is returned from `setTimeout()` and `setInterval()`. It can be passed to either `clearTimeout()` or `clearInterval()` in order to cancel the + * scheduled actions. + * + * By default, when a timer is scheduled using either `setTimeout()` or `setInterval()`, the Node.js event loop will continue running as long as the + * timer is active. Each of the `Timeout` objects returned by these functions + * export both `timeout.ref()` and `timeout.unref()` functions that can be used to + * control this default behavior. + */ + class Timeout implements Timer { + /** + * When called, requests that the Node.js event loop _not_ exit so long as the`Timeout` is active. Calling `timeout.ref()` multiple times will have no effect. + * + * By default, all `Timeout` objects are "ref'ed", making it normally unnecessary + * to call `timeout.ref()` unless `timeout.unref()` had been called previously. + * @since v0.9.1 + * @return a reference to `timeout` + */ + ref(): this; + /** + * When called, the active `Timeout` object will not require the Node.js event loop + * to remain active. If there is no other activity keeping the event loop running, + * the process may exit before the `Timeout` object's callback is invoked. Calling`timeout.unref()` multiple times will have no effect. + * @since v0.9.1 + * @return a reference to `timeout` + */ + unref(): this; /** * If true, the `Timeout` object will keep the Node.js event loop active. * @since v11.0.0 @@ -60,35 +123,118 @@ declare module 'timers' { */ refresh(): this; [Symbol.toPrimitive](): number; + /** + * Cancels the timeout. + * @since v20.5.0 + */ + [Symbol.dispose](): void; } } - function setTimeout(callback: (...args: TArgs) => void, ms?: number, ...args: TArgs): NodeJS.Timeout; + /** + * Schedules execution of a one-time `callback` after `delay` milliseconds. + * + * The `callback` will likely not be invoked in precisely `delay` milliseconds. + * Node.js makes no guarantees about the exact timing of when callbacks will fire, + * nor of their ordering. The callback will be called as close as possible to the + * time specified. + * + * When `delay` is larger than `2147483647` or less than `1`, the `delay`will be set to `1`. Non-integer delays are truncated to an integer. + * + * If `callback` is not a function, a `TypeError` will be thrown. + * + * This method has a custom variant for promises that is available using `timersPromises.setTimeout()`. + * @since v0.0.1 + * @param callback The function to call when the timer elapses. + * @param [delay=1] The number of milliseconds to wait before calling the `callback`. + * @param args Optional arguments to pass when the `callback` is called. + * @return for use with {@link clearTimeout} + */ + function setTimeout( + callback: (...args: TArgs) => void, + ms?: number, + ...args: TArgs + ): NodeJS.Timeout; // util.promisify no rest args compability - // tslint:disable-next-line void-return + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type function setTimeout(callback: (args: void) => void, ms?: number): NodeJS.Timeout; namespace setTimeout { const __promisify__: typeof setTimeoutPromise; } + /** + * Cancels a `Timeout` object created by `setTimeout()`. + * @since v0.0.1 + * @param timeout A `Timeout` object as returned by {@link setTimeout} or the `primitive` of the `Timeout` object as a string or a number. + */ function clearTimeout(timeoutId: NodeJS.Timeout | string | number | undefined): void; - function setInterval(callback: (...args: TArgs) => void, ms?: number, ...args: TArgs): NodeJS.Timer; + /** + * Schedules repeated execution of `callback` every `delay` milliseconds. + * + * When `delay` is larger than `2147483647` or less than `1`, the `delay` will be + * set to `1`. Non-integer delays are truncated to an integer. + * + * If `callback` is not a function, a `TypeError` will be thrown. + * + * This method has a custom variant for promises that is available using `timersPromises.setInterval()`. + * @since v0.0.1 + * @param callback The function to call when the timer elapses. + * @param [delay=1] The number of milliseconds to wait before calling the `callback`. + * @param args Optional arguments to pass when the `callback` is called. + * @return for use with {@link clearInterval} + */ + function setInterval( + callback: (...args: TArgs) => void, + ms?: number, + ...args: TArgs + ): NodeJS.Timeout; // util.promisify no rest args compability - // tslint:disable-next-line void-return - function setInterval(callback: (args: void) => void, ms?: number): NodeJS.Timer; + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type + function setInterval(callback: (args: void) => void, ms?: number): NodeJS.Timeout; namespace setInterval { const __promisify__: typeof setIntervalPromise; } + /** + * Cancels a `Timeout` object created by `setInterval()`. + * @since v0.0.1 + * @param timeout A `Timeout` object as returned by {@link setInterval} or the `primitive` of the `Timeout` object as a string or a number. + */ function clearInterval(intervalId: NodeJS.Timeout | string | number | undefined): void; - function setImmediate(callback: (...args: TArgs) => void, ...args: TArgs): NodeJS.Immediate; + /** + * Schedules the "immediate" execution of the `callback` after I/O events' + * callbacks. + * + * When multiple calls to `setImmediate()` are made, the `callback` functions are + * queued for execution in the order in which they are created. The entire callback + * queue is processed every event loop iteration. If an immediate timer is queued + * from inside an executing callback, that timer will not be triggered until the + * next event loop iteration. + * + * If `callback` is not a function, a `TypeError` will be thrown. + * + * This method has a custom variant for promises that is available using `timersPromises.setImmediate()`. + * @since v0.9.1 + * @param callback The function to call at the end of this turn of the Node.js `Event Loop` + * @param args Optional arguments to pass when the `callback` is called. + * @return for use with {@link clearImmediate} + */ + function setImmediate( + callback: (...args: TArgs) => void, + ...args: TArgs + ): NodeJS.Immediate; // util.promisify no rest args compability - // tslint:disable-next-line void-return + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type function setImmediate(callback: (args: void) => void): NodeJS.Immediate; namespace setImmediate { const __promisify__: typeof setImmediatePromise; } + /** + * Cancels an `Immediate` object created by `setImmediate()`. + * @since v0.9.1 + * @param immediate An `Immediate` object as returned by {@link setImmediate}. + */ function clearImmediate(immediateId: NodeJS.Immediate | undefined): void; function queueMicrotask(callback: () => void): void; } } -declare module 'node:timers' { - export * from 'timers'; +declare module "node:timers" { + export * from "timers"; } diff --git a/node_modules/@types/node/timers/promises.d.ts b/node_modules/@types/node/timers/promises.d.ts old mode 100755 new mode 100644 index fd77888..5a54dc7 --- a/node_modules/@types/node/timers/promises.d.ts +++ b/node_modules/@types/node/timers/promises.d.ts @@ -1,6 +1,6 @@ /** * The `timers/promises` API provides an alternative set of timer functions - * that return `Promise` objects. The API is accessible via`require('timers/promises')`. + * that return `Promise` objects. The API is accessible via`require('node:timers/promises')`. * * ```js * import { @@ -11,8 +11,8 @@ * ``` * @since v15.0.0 */ -declare module 'timers/promises' { - import { TimerOptions } from 'node:timers'; +declare module "timers/promises" { + import { TimerOptions } from "node:timers"; /** * ```js * import { @@ -44,6 +44,8 @@ declare module 'timers/promises' { function setImmediate(value?: T, options?: TimerOptions): Promise; /** * Returns an async iterator that generates values in an interval of `delay` ms. + * If `ref` is `true`, you need to call `next()` of async iterator explicitly + * or implicitly to keep the event loop alive. * * ```js * import { @@ -62,7 +64,30 @@ declare module 'timers/promises' { * @since v15.9.0 */ function setInterval(delay?: number, value?: T, options?: TimerOptions): AsyncIterable; + interface Scheduler { + /** + * ```js + * import { scheduler } from 'node:timers/promises'; + * + * await scheduler.wait(1000); // Wait one second before continuing + * ``` + * An experimental API defined by the Scheduling APIs draft specification being developed as a standard Web Platform API. + * Calling timersPromises.scheduler.wait(delay, options) is roughly equivalent to calling timersPromises.setTimeout(delay, undefined, options) except that the ref option is not supported. + * @since v16.14.0 + * @experimental + * @param [delay=1] The number of milliseconds to wait before fulfilling the promise. + */ + wait: (delay?: number, options?: TimerOptions) => Promise; + /** + * An experimental API defined by the Scheduling APIs draft specification being developed as a standard Web Platform API. + * Calling timersPromises.scheduler.yield() is equivalent to calling timersPromises.setImmediate() with no arguments. + * @since v16.14.0 + * @experimental + */ + yield: () => Promise; + } + const scheduler: Scheduler; } -declare module 'node:timers/promises' { - export * from 'timers/promises'; +declare module "node:timers/promises" { + export * from "timers/promises"; } diff --git a/node_modules/@types/node/tls.d.ts b/node_modules/@types/node/tls.d.ts old mode 100755 new mode 100644 index b013b26..b289e84 --- a/node_modules/@types/node/tls.d.ts +++ b/node_modules/@types/node/tls.d.ts @@ -1,16 +1,17 @@ /** - * The `tls` module provides an implementation of the Transport Layer Security + * The `node:tls` module provides an implementation of the Transport Layer Security * (TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL. * The module can be accessed using: * * ```js - * const tls = require('tls'); + * const tls = require('node:tls'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/tls.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/tls.js) */ -declare module 'tls' { - import { X509Certificate } from 'node:crypto'; - import * as net from 'node:net'; +declare module "tls" { + import { X509Certificate } from "node:crypto"; + import * as net from "node:net"; + import * as stream from "stream"; const CLIENT_RENEG_LIMIT: number; const CLIENT_RENEG_WINDOW: number; interface Certificate { @@ -40,21 +41,100 @@ declare module 'tls' { CN: string; } interface PeerCertificate { - subject: Certificate; - issuer: Certificate; - subjectaltname: string; - infoAccess: NodeJS.Dict; - modulus: string; - exponent: string; - valid_from: string; - valid_to: string; - fingerprint: string; - fingerprint256: string; - ext_key_usage: string[]; - serialNumber: string; + /** + * `true` if a Certificate Authority (CA), `false` otherwise. + * @since v18.13.0 + */ + ca: boolean; + /** + * The DER encoded X.509 certificate data. + */ raw: Buffer; + /** + * The certificate subject. + */ + subject: Certificate; + /** + * The certificate issuer, described in the same terms as the `subject`. + */ + issuer: Certificate; + /** + * The date-time the certificate is valid from. + */ + valid_from: string; + /** + * The date-time the certificate is valid to. + */ + valid_to: string; + /** + * The certificate serial number, as a hex string. + */ + serialNumber: string; + /** + * The SHA-1 digest of the DER encoded certificate. + * It is returned as a `:` separated hexadecimal string. + */ + fingerprint: string; + /** + * The SHA-256 digest of the DER encoded certificate. + * It is returned as a `:` separated hexadecimal string. + */ + fingerprint256: string; + /** + * The SHA-512 digest of the DER encoded certificate. + * It is returned as a `:` separated hexadecimal string. + */ + fingerprint512: string; + /** + * The extended key usage, a set of OIDs. + */ + ext_key_usage?: string[]; + /** + * A string containing concatenated names for the subject, + * an alternative to the `subject` names. + */ + subjectaltname?: string; + /** + * An array describing the AuthorityInfoAccess, used with OCSP. + */ + infoAccess?: NodeJS.Dict; + /** + * For RSA keys: The RSA bit size. + * + * For EC keys: The key size in bits. + */ + bits?: number; + /** + * The RSA exponent, as a string in hexadecimal number notation. + */ + exponent?: string; + /** + * The RSA modulus, as a hexadecimal string. + */ + modulus?: string; + /** + * The public key. + */ + pubkey?: Buffer; + /** + * The ASN.1 name of the OID of the elliptic curve. + * Well-known curves are identified by an OID. + * While it is unusual, it is possible that the curve + * is identified by its mathematical properties, + * in which case it will not have an OID. + */ + asn1Curve?: string; + /** + * The NIST name for the elliptic curve,if it has one + * (not all well-known curves have been assigned names by NIST). + */ + nistCurve?: string; } interface DetailedPeerCertificate extends PeerCertificate { + /** + * The issuer certificate object. + * For self-signed certificates, this may be a circular reference. + */ issuerCertificate: DetailedPeerCertificate; } interface CipherNameAndProtocol { @@ -132,7 +212,7 @@ declare module 'tls' { * * Instances of `tls.TLSSocket` implement the duplex `Stream` interface. * - * Methods that return TLS connection metadata (e.g.{@link TLSSocket.getPeerCertificate} will only return data while the + * Methods that return TLS connection metadata (e.g.{@link TLSSocket.getPeerCertificate}) will only return data while the * connection is open. * @since v0.11.4 */ @@ -142,8 +222,8 @@ declare module 'tls' { */ constructor(socket: net.Socket, options?: TLSSocketOptions); /** - * Returns `true` if the peer certificate was signed by one of the CAs specified - * when creating the `tls.TLSSocket` instance, otherwise `false`. + * This property is `true` if the peer certificate was signed by one of the CAs + * specified when creating the `tls.TLSSocket` instance, otherwise `false`. * @since v0.11.4 */ authorized: boolean; @@ -179,13 +259,13 @@ declare module 'tls' { /** * Returns an object containing information on the negotiated cipher suite. * - * For example: + * For example, a TLSv1.2 protocol with AES256-SHA cipher: * * ```json * { - * "name": "AES128-SHA256", - * "standardName": "TLS_RSA_WITH_AES_128_CBC_SHA256", - * "version": "TLSv1.2" + * "name": "AES256-SHA", + * "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA", + * "version": "SSLv3" * } * ``` * @@ -316,7 +396,7 @@ declare module 'tls' { rejectUnauthorized?: boolean | undefined; requestCert?: boolean | undefined; }, - callback: (err: Error | null) => void + callback: (err: Error | null) => void, ): undefined | boolean; /** * The `tlsSocket.setMaxSendFragment()` method sets the maximum TLS fragment size. @@ -342,9 +422,9 @@ declare module 'tls' { * When enabled, TLS packet trace information is written to `stderr`. This can be * used to debug TLS connection problems. * - * Note: The format of the output is identical to the output of `openssl s_client -trace` or `openssl s_server -trace`. While it is produced by OpenSSL's`SSL_trace()` function, the format is - * undocumented, can change without notice, - * and should not be relied on. + * The format of the output is identical to the output of`openssl s_client -trace` or `openssl s_server -trace`. While it is produced by + * OpenSSL's `SSL_trace()` function, the format is undocumented, can change + * without notice, and should not be relied on. * @since v12.2.0 */ enableTrace(): void; @@ -373,7 +453,7 @@ declare module 'tls' { * 128, * 'client finished'); * - * + * /* * Example return value of keyingMaterial: * void): this; - addListener(event: 'OCSPResponse', listener: (response: Buffer) => void): this; - addListener(event: 'secureConnect', listener: () => void): this; - addListener(event: 'session', listener: (session: Buffer) => void): this; - addListener(event: 'keylog', listener: (line: Buffer) => void): this; + addListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; + addListener(event: "secureConnect", listener: () => void): this; + addListener(event: "session", listener: (session: Buffer) => void): this; + addListener(event: "keylog", listener: (line: Buffer) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'OCSPResponse', response: Buffer): boolean; - emit(event: 'secureConnect'): boolean; - emit(event: 'session', session: Buffer): boolean; - emit(event: 'keylog', line: Buffer): boolean; + emit(event: "OCSPResponse", response: Buffer): boolean; + emit(event: "secureConnect"): boolean; + emit(event: "session", session: Buffer): boolean; + emit(event: "keylog", line: Buffer): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'OCSPResponse', listener: (response: Buffer) => void): this; - on(event: 'secureConnect', listener: () => void): this; - on(event: 'session', listener: (session: Buffer) => void): this; - on(event: 'keylog', listener: (line: Buffer) => void): this; + on(event: "OCSPResponse", listener: (response: Buffer) => void): this; + on(event: "secureConnect", listener: () => void): this; + on(event: "session", listener: (session: Buffer) => void): this; + on(event: "keylog", listener: (line: Buffer) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'OCSPResponse', listener: (response: Buffer) => void): this; - once(event: 'secureConnect', listener: () => void): this; - once(event: 'session', listener: (session: Buffer) => void): this; - once(event: 'keylog', listener: (line: Buffer) => void): this; + once(event: "OCSPResponse", listener: (response: Buffer) => void): this; + once(event: "secureConnect", listener: () => void): this; + once(event: "session", listener: (session: Buffer) => void): this; + once(event: "keylog", listener: (line: Buffer) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'OCSPResponse', listener: (response: Buffer) => void): this; - prependListener(event: 'secureConnect', listener: () => void): this; - prependListener(event: 'session', listener: (session: Buffer) => void): this; - prependListener(event: 'keylog', listener: (line: Buffer) => void): this; + prependListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; + prependListener(event: "secureConnect", listener: () => void): this; + prependListener(event: "session", listener: (session: Buffer) => void): this; + prependListener(event: "keylog", listener: (line: Buffer) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'OCSPResponse', listener: (response: Buffer) => void): this; - prependOnceListener(event: 'secureConnect', listener: () => void): this; - prependOnceListener(event: 'session', listener: (session: Buffer) => void): this; - prependOnceListener(event: 'keylog', listener: (line: Buffer) => void): this; + prependOnceListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; + prependOnceListener(event: "secureConnect", listener: () => void): this; + prependOnceListener(event: "session", listener: (session: Buffer) => void): this; + prependOnceListener(event: "keylog", listener: (line: Buffer) => void): this; } interface CommonConnectionOptions { /** @@ -481,7 +561,6 @@ declare module 'tls' { */ ticketKeys?: Buffer | undefined; /** - * * @param socket * @param identity identity parameter sent from the client. * @return pre-shared key that must either be @@ -516,7 +595,7 @@ declare module 'tls' { host?: string | undefined; port?: number | undefined; path?: string | undefined; // Creates unix socket connection to path. If this option is specified, `host` and `port` are ignored. - socket?: net.Socket | undefined; // Establish secure connection on a given socket rather than creating a new socket + socket?: stream.Duplex | undefined; // Establish secure connection on a given socket rather than creating a new socket checkServerIdentity?: typeof checkServerIdentity | undefined; servername?: string | undefined; // SNI TLS Extension session?: Buffer | undefined; @@ -557,7 +636,8 @@ declare module 'tls' { * used. * @since v0.5.3 * @param hostname A SNI host name or wildcard (e.g. `'*'`) - * @param context An object containing any of the possible properties from the {@link createSecureContext} `options` arguments (e.g. `key`, `cert`, `ca`, etc). + * @param context An object containing any of the possible properties from the {@link createSecureContext} `options` arguments (e.g. `key`, `cert`, `ca`, etc), or a TLS context object created + * with {@link createSecureContext} itself. */ addContext(hostname: string, context: SecureContextOptions): void; /** @@ -596,47 +676,118 @@ declare module 'tls' { * 6. keylog */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: TLSSocket) => void): this; - addListener(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; - addListener(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; - addListener(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void): this; - addListener(event: 'secureConnection', listener: (tlsSocket: TLSSocket) => void): this; - addListener(event: 'keylog', listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; + addListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; + addListener( + event: "newSession", + listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void, + ): this; + addListener( + event: "OCSPRequest", + listener: ( + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ) => void, + ): this; + addListener( + event: "resumeSession", + listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void, + ): this; + addListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; + addListener(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'tlsClientError', err: Error, tlsSocket: TLSSocket): boolean; - emit(event: 'newSession', sessionId: Buffer, sessionData: Buffer, callback: () => void): boolean; - emit(event: 'OCSPRequest', certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void): boolean; - emit(event: 'resumeSession', sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void): boolean; - emit(event: 'secureConnection', tlsSocket: TLSSocket): boolean; - emit(event: 'keylog', line: Buffer, tlsSocket: TLSSocket): boolean; + emit(event: "tlsClientError", err: Error, tlsSocket: TLSSocket): boolean; + emit(event: "newSession", sessionId: Buffer, sessionData: Buffer, callback: () => void): boolean; + emit( + event: "OCSPRequest", + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ): boolean; + emit( + event: "resumeSession", + sessionId: Buffer, + callback: (err: Error | null, sessionData: Buffer | null) => void, + ): boolean; + emit(event: "secureConnection", tlsSocket: TLSSocket): boolean; + emit(event: "keylog", line: Buffer, tlsSocket: TLSSocket): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'tlsClientError', listener: (err: Error, tlsSocket: TLSSocket) => void): this; - on(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; - on(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; - on(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void): this; - on(event: 'secureConnection', listener: (tlsSocket: TLSSocket) => void): this; - on(event: 'keylog', listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; + on(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; + on(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; + on( + event: "OCSPRequest", + listener: ( + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ) => void, + ): this; + on( + event: "resumeSession", + listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void, + ): this; + on(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; + on(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'tlsClientError', listener: (err: Error, tlsSocket: TLSSocket) => void): this; - once(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; - once(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; - once(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void): this; - once(event: 'secureConnection', listener: (tlsSocket: TLSSocket) => void): this; - once(event: 'keylog', listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; + once(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; + once( + event: "newSession", + listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void, + ): this; + once( + event: "OCSPRequest", + listener: ( + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ) => void, + ): this; + once( + event: "resumeSession", + listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void, + ): this; + once(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; + once(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: TLSSocket) => void): this; - prependListener(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; - prependListener(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; - prependListener(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void): this; - prependListener(event: 'secureConnection', listener: (tlsSocket: TLSSocket) => void): this; - prependListener(event: 'keylog', listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; + prependListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; + prependListener( + event: "newSession", + listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void, + ): this; + prependListener( + event: "OCSPRequest", + listener: ( + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ) => void, + ): this; + prependListener( + event: "resumeSession", + listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void, + ): this; + prependListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; + prependListener(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: TLSSocket) => void): this; - prependOnceListener(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; - prependOnceListener(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; - prependOnceListener(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void): this; - prependOnceListener(event: 'secureConnection', listener: (tlsSocket: TLSSocket) => void): this; - prependOnceListener(event: 'keylog', listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; + prependOnceListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; + prependOnceListener( + event: "newSession", + listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void, + ): this; + prependOnceListener( + event: "OCSPRequest", + listener: ( + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ) => void, + ): this; + prependOnceListener( + event: "resumeSession", + listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void, + ): this; + prependOnceListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; + prependOnceListener(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; } /** * @deprecated since v0.11.3 Use `tls.TLSSocket` instead. @@ -645,8 +796,19 @@ declare module 'tls' { encrypted: TLSSocket; cleartext: TLSSocket; } - type SecureVersion = 'TLSv1.3' | 'TLSv1.2' | 'TLSv1.1' | 'TLSv1'; + type SecureVersion = "TLSv1.3" | "TLSv1.2" | "TLSv1.1" | "TLSv1"; interface SecureContextOptions { + /** + * If set, this will be called when a client opens a connection using the ALPN extension. + * One argument will be passed to the callback: an object containing `servername` and `protocols` fields, + * respectively containing the server name from the SNI extension (if any) and an array of + * ALPN protocol name strings. The callback must return either one of the strings listed in `protocols`, + * which will be returned to the client as the selected ALPN protocol, or `undefined`, + * to reject the connection with a fatal alert. If a string is returned that does not match one of + * the client's ALPN protocols, an error will be thrown. + * This option cannot be used with the `ALPNProtocols` option, and setting both options will throw an error. + */ + ALPNCallback?: ((arg: { servername: string; protocols: string[] }) => string | undefined) | undefined; /** * Optionally override the trusted CA certificates. Default is to trust * the well-known CAs curated by Mozilla. Mozilla's CAs are completely @@ -688,12 +850,9 @@ declare module 'tls' { */ crl?: string | Buffer | Array | undefined; /** - * Diffie Hellman parameters, required for Perfect Forward Secrecy. Use - * openssl dhparam to create the parameters. The key length must be - * greater than or equal to 1024 bits or else an error will be thrown. - * Although 1024 bits is permissible, use 2048 bits or larger for - * stronger security. If omitted or invalid, the parameters are - * silently discarded and DHE ciphers will not be available. + * `'auto'` or custom Diffie-Hellman parameters, required for non-ECDHE perfect forward secrecy. + * If omitted or invalid, the parameters are silently discarded and DHE ciphers will not be available. + * ECDHE-based perfect forward secrecy will still be available. */ dhparam?: string | Buffer | undefined; /** @@ -722,7 +881,7 @@ declare module 'tls' { * object.passphrase is optional. Encrypted keys will be decrypted with * object.passphrase if provided, or options.passphrase if it is not. */ - key?: string | Buffer | Array | undefined; + key?: string | Buffer | Array | undefined; /** * Name of an OpenSSL engine to get private key from. Should be used * together with privateKeyIdentifier. @@ -813,13 +972,19 @@ declare module 'tls' { * Returns [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object, populating it with `reason`, `host`, and `cert` on * failure. On success, returns [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type). * - * This function can be overwritten by providing alternative function as part of - * the `options.checkServerIdentity` option passed to `tls.connect()`. The + * This function is intended to be used in combination with the`checkServerIdentity` option that can be passed to {@link connect} and as + * such operates on a `certificate object`. For other purposes, consider using `x509.checkHost()` instead. + * + * This function can be overwritten by providing an alternative function as the`options.checkServerIdentity` option that is passed to `tls.connect()`. The * overwriting function can call `tls.checkServerIdentity()` of course, to augment * the checks done with additional verification. * * This function is only called if the certificate passed all other checks, such as * being issued by trusted CA (`options.ca`). + * + * Earlier versions of Node.js incorrectly accepted certificates for a given`hostname` if a matching `uniformResourceIdentifier` subject alternative name + * was present (see [CVE-2021-44531](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44531)). Applications that wish to accept`uniformResourceIdentifier` subject alternative names can use + * a custom`options.checkServerIdentity` function that implements the desired behavior. * @since v0.8.4 * @param hostname The host name or IP address to verify the certificate against. * @param cert A `certificate object` representing the peer's certificate. @@ -829,14 +994,14 @@ declare module 'tls' { * Creates a new {@link Server}. The `secureConnectionListener`, if provided, is * automatically set as a listener for the `'secureConnection'` event. * - * The `ticketKeys` options is automatically shared between `cluster` module + * The `ticketKeys` options is automatically shared between `node:cluster` module * workers. * * The following illustrates a simple echo server: * * ```js - * const tls = require('tls'); - * const fs = require('fs'); + * const tls = require('node:tls'); + * const fs = require('node:fs'); * * const options = { * key: fs.readFileSync('server-key.pem'), @@ -846,7 +1011,7 @@ declare module 'tls' { * requestCert: true, * * // This is necessary only if the client uses a self-signed certificate. - * ca: [ fs.readFileSync('client-cert.pem') ] + * ca: [ fs.readFileSync('client-cert.pem') ], * }; * * const server = tls.createServer(options, (socket) => { @@ -881,8 +1046,8 @@ declare module 'tls' { * * ```js * // Assumes an echo server that is listening on port 8000. - * const tls = require('tls'); - * const fs = require('fs'); + * const tls = require('node:tls'); + * const fs = require('node:fs'); * * const options = { * // Necessary only if the server requires client certificate authentication. @@ -913,7 +1078,12 @@ declare module 'tls' { * @since v0.11.3 */ function connect(options: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; - function connect(port: number, host?: string, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; + function connect( + port: number, + host?: string, + options?: ConnectionOptions, + secureConnectListener?: () => void, + ): TLSSocket; function connect(port: number, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; /** * Creates a new secure pair object with two streams, one of which reads and writes @@ -948,7 +1118,12 @@ declare module 'tls' { * @param requestCert `true` to specify whether a server should request a certificate from a connecting client. Only applies when `isServer` is `true`. * @param rejectUnauthorized If not `false` a server automatically reject clients with invalid certificates. Only applies when `isServer` is `true`. */ - function createSecurePair(context?: SecureContext, isServer?: boolean, requestCert?: boolean, rejectUnauthorized?: boolean): SecurePair; + function createSecurePair( + context?: SecureContext, + isServer?: boolean, + requestCert?: boolean, + rejectUnauthorized?: boolean, + ): SecurePair; /** * {@link createServer} sets the default value of the `honorCipherOrder` option * to `true`, other APIs that create secure contexts leave it unset. @@ -958,12 +1133,19 @@ declare module 'tls' { * APIs that create secure contexts have no default value. * * The `tls.createSecureContext()` method creates a `SecureContext` object. It is - * usable as an argument to several `tls` APIs, such as {@link createServer} and `server.addContext()`, but has no public methods. + * usable as an argument to several `tls` APIs, such as `server.addContext()`, + * but has no public methods. The {@link Server} constructor and the {@link createServer} method do not support the `secureContext` option. * * A key is _required_ for ciphers that use certificates. Either `key` or`pfx` can be used to provide it. * * If the `ca` option is not given, then Node.js will default to using [Mozilla's publicly trusted list of * CAs](https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt). + * + * Custom DHE parameters are discouraged in favor of the new `dhparam: 'auto'`option. When set to `'auto'`, well-known DHE parameters of sufficient strength + * will be selected automatically. Otherwise, if necessary, `openssl dhparam` can + * be used to create custom parameters. The key length must be greater than or + * equal to 1024 bits or else an error will be thrown. Although 1024 bits is + * permissible, use 2048 bits or larger for stronger security. * @since v0.11.13 */ function createSecureContext(options?: SecureContextOptions): SecureContext; @@ -972,6 +1154,8 @@ declare module 'tls' { * lower-case for historical reasons, but must be uppercased to be used in * the `ciphers` option of {@link createSecureContext}. * + * Not all supported ciphers are enabled by default. See `Modifying the default TLS cipher suite`. + * * Cipher names that start with `'tls_'` are for TLSv1.3, all the others are for * TLSv1.2 and below. * @@ -1007,13 +1191,20 @@ declare module 'tls' { * are provided, the lowest minimum is used. */ let DEFAULT_MIN_VERSION: SecureVersion; + /** + * The default value of the ciphers option of tls.createSecureContext(). + * It can be assigned any of the supported OpenSSL ciphers. + * Defaults to the content of crypto.constants.defaultCoreCipherList, unless + * changed using CLI options using --tls-default-ciphers. + */ + let DEFAULT_CIPHERS: string; /** * An immutable array of strings representing the root certificates (in PEM * format) used for verifying peer certificates. This is the default value * of the ca option to tls.createSecureContext(). */ - const rootCertificates: ReadonlyArray; + const rootCertificates: readonly string[]; } -declare module 'node:tls' { - export * from 'tls'; +declare module "node:tls" { + export * from "tls"; } diff --git a/node_modules/@types/node/trace_events.d.ts b/node_modules/@types/node/trace_events.d.ts old mode 100755 new mode 100644 index 2976eb6..3361359 --- a/node_modules/@types/node/trace_events.d.ts +++ b/node_modules/@types/node/trace_events.d.ts @@ -1,9 +1,9 @@ /** - * The `trace_events` module provides a mechanism to centralize tracing information - * generated by V8, Node.js core, and userspace code. + * The `node:trace_events` module provides a mechanism to centralize tracing + * information generated by V8, Node.js core, and userspace code. * * Tracing can be enabled with the `--trace-event-categories` command-line flag - * or by using the `trace_events` module. The `--trace-event-categories` flag + * or by using the `node:trace_events` module. The `--trace-event-categories` flag * accepts a list of comma-separated category names. * * The available categories are: @@ -13,9 +13,19 @@ * The `async_hooks` events have a unique `asyncId` and a special `triggerId` `triggerAsyncId` property. * * `node.bootstrap`: Enables capture of Node.js bootstrap milestones. * * `node.console`: Enables capture of `console.time()` and `console.count()`output. + * * `node.threadpoolwork.sync`: Enables capture of trace data for threadpool + * synchronous operations, such as `blob`, `zlib`, `crypto` and `node_api`. + * * `node.threadpoolwork.async`: Enables capture of trace data for threadpool + * asynchronous operations, such as `blob`, `zlib`, `crypto` and `node_api`. * * `node.dns.native`: Enables capture of trace data for DNS queries. + * * `node.net.native`: Enables capture of trace data for network. * * `node.environment`: Enables capture of Node.js Environment milestones. * * `node.fs.sync`: Enables capture of trace data for file system sync methods. + * * `node.fs_dir.sync`: Enables capture of trace data for file system sync + * directory methods. + * * `node.fs.async`: Enables capture of trace data for file system async methods. + * * `node.fs_dir.async`: Enables capture of trace data for file system async + * directory methods. * * `node.perf`: Enables capture of `Performance API` measurements. * * `node.perf.usertiming`: Enables capture of only Performance API User Timing * measures and marks. @@ -23,8 +33,9 @@ * measurements. * * `node.promises.rejections`: Enables capture of trace data tracking the number * of unhandled Promise rejections and handled-after-rejections. - * * `node.vm.script`: Enables capture of trace data for the `vm` module's`runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. + * * `node.vm.script`: Enables capture of trace data for the `node:vm` module's`runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. * * `v8`: The `V8` events are GC, compiling, and execution related. + * * `node.http`: Enables capture of trace data for http request / response. * * By default the `node`, `node.async_hooks`, and `v8` categories are enabled. * @@ -43,10 +54,10 @@ * node --trace-event-categories v8,node,node.async_hooks * ``` * - * Alternatively, trace events may be enabled using the `trace_events` module: + * Alternatively, trace events may be enabled using the `node:trace_events` module: * * ```js - * const trace_events = require('trace_events'); + * const trace_events = require('node:trace_events'); * const tracing = trace_events.createTracing({ categories: ['node.perf'] }); * tracing.enable(); // Enable trace event capture for the 'node.perf' category * @@ -66,6 +77,16 @@ * node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js * ``` * + * To guarantee that the log file is properly generated after signal events like`SIGINT`, `SIGTERM`, or `SIGBREAK`, make sure to have the appropriate handlers + * in your code, such as: + * + * ```js + * process.on('SIGINT', function onSigint() { + * console.info('Received SIGINT.'); + * process.exit(130); // Or applicable exit code depending on OS and signal + * }); + * ``` + * * The tracing system uses the same time source * as the one used by `process.hrtime()`. * However the trace-event timestamps are expressed in microseconds, @@ -73,9 +94,9 @@ * * The features from this module are not available in `Worker` threads. * @experimental - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/trace_events.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/trace_events.js) */ -declare module 'trace_events' { +declare module "trace_events" { /** * The `Tracing` object is used to enable or disable tracing for sets of * categories. Instances are created using the @@ -122,7 +143,7 @@ declare module 'trace_events' { * Creates and returns a `Tracing` object for the given set of `categories`. * * ```js - * const trace_events = require('trace_events'); + * const trace_events = require('node:trace_events'); * const categories = ['node.perf', 'node.async_hooks']; * const tracing = trace_events.createTracing({ categories }); * tracing.enable(); @@ -142,7 +163,7 @@ declare module 'trace_events' { * Given the file `test.js` below, the command`node --trace-event-categories node.perf test.js` will print`'node.async_hooks,node.perf'` to the console. * * ```js - * const trace_events = require('trace_events'); + * const trace_events = require('node:trace_events'); * const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] }); * const t2 = trace_events.createTracing({ categories: ['node.perf'] }); * const t3 = trace_events.createTracing({ categories: ['v8'] }); @@ -156,6 +177,6 @@ declare module 'trace_events' { */ function getEnabledCategories(): string | undefined; } -declare module 'node:trace_events' { - export * from 'trace_events'; +declare module "node:trace_events" { + export * from "trace_events"; } diff --git a/node_modules/@types/node/ts4.8/assert.d.ts b/node_modules/@types/node/ts4.8/assert.d.ts old mode 100755 new mode 100644 index 9f916c1..cd82143 --- a/node_modules/@types/node/ts4.8/assert.d.ts +++ b/node_modules/@types/node/ts4.8/assert.d.ts @@ -1,9 +1,9 @@ /** - * The `assert` module provides a set of assertion functions for verifying + * The `node:assert` module provides a set of assertion functions for verifying * invariants. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/assert.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/assert.js) */ -declare module 'assert' { +declare module "assert" { /** * An alias of {@link ok}. * @since v0.5.9 @@ -12,15 +12,29 @@ declare module 'assert' { function assert(value: unknown, message?: string | Error): asserts value; namespace assert { /** - * Indicates the failure of an assertion. All errors thrown by the `assert` module - * will be instances of the `AssertionError` class. + * Indicates the failure of an assertion. All errors thrown by the `node:assert`module will be instances of the `AssertionError` class. */ class AssertionError extends Error { + /** + * Set to the `actual` argument for methods such as {@link assert.strictEqual()}. + */ actual: unknown; + /** + * Set to the `expected` argument for methods such as {@link assert.strictEqual()}. + */ expected: unknown; + /** + * Set to the passed in operator value. + */ operator: string; + /** + * Indicates if the message was auto-generated (`true`) or not. + */ generatedMessage: boolean; - code: 'ERR_ASSERTION'; + /** + * Value is always `ERR_ASSERTION` to show that the error is an assertion error. + */ + code: "ERR_ASSERTION"; constructor(options?: { /** If provided, the error message is set to this value. */ message?: string | undefined; @@ -31,14 +45,15 @@ declare module 'assert' { /** The `operator` property on the error instance. */ operator?: string | undefined; /** If provided, the generated stack trace omits frames before this function. */ - // tslint:disable-next-line:ban-types + // eslint-disable-next-line @typescript-eslint/ban-types stackStartFn?: Function | undefined; }); } /** - * This feature is currently experimental and behavior might still change. + * This feature is deprecated and will be removed in a future version. + * Please consider using alternatives such as the `mock` helper function. * @since v14.2.0, v12.19.0 - * @experimental + * @deprecated Deprecated */ class CallTracker { /** @@ -47,7 +62,7 @@ declare module 'assert' { * error. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * // Creates call tracker. * const tracker = new assert.CallTracker(); @@ -65,26 +80,44 @@ declare module 'assert' { */ calls(exact?: number): () => void; calls any>(fn?: Func, exact?: number): Func; + /** + * Example: + * + * ```js + * import assert from 'node:assert'; + * + * const tracker = new assert.CallTracker(); + * + * function func() {} + * const callsfunc = tracker.calls(func); + * callsfunc(1, 2, 3); + * + * assert.deepStrictEqual(tracker.getCalls(callsfunc), + * [{ thisArg: undefined, arguments: [1, 2, 3] }]); + * ``` + * @since v18.8.0, v16.18.0 + * @param fn + * @return An Array with all the calls to a tracked function. + */ + getCalls(fn: Function): CallTrackerCall[]; /** * The arrays contains information about the expected and actual number of calls of * the functions that have not been called the expected number of times. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * // Creates call tracker. * const tracker = new assert.CallTracker(); * * function func() {} * - * function foo() {} - * * // Returns a function that wraps func() that must be called exact times * // before tracker.verify(). * const callsfunc = tracker.calls(func, 2); * * // Returns an array containing information on callsfunc() - * tracker.report(); + * console.log(tracker.report()); * // [ * // { * // message: 'Expected the func function to be executed 2 time(s) but was @@ -97,15 +130,39 @@ declare module 'assert' { * // ] * ``` * @since v14.2.0, v12.19.0 - * @return of objects containing information about the wrapper functions returned by `calls`. + * @return An Array of objects containing information about the wrapper functions returned by `calls`. */ report(): CallTrackerReportInformation[]; + /** + * Reset calls of the call tracker. + * If a tracked function is passed as an argument, the calls will be reset for it. + * If no arguments are passed, all tracked functions will be reset. + * + * ```js + * import assert from 'node:assert'; + * + * const tracker = new assert.CallTracker(); + * + * function func() {} + * const callsfunc = tracker.calls(func); + * + * callsfunc(); + * // Tracker was called once + * assert.strictEqual(tracker.getCalls(callsfunc).length, 1); + * + * tracker.reset(callsfunc); + * assert.strictEqual(tracker.getCalls(callsfunc).length, 0); + * ``` + * @since v18.8.0, v16.18.0 + * @param fn a tracked function to reset. + */ + reset(fn?: Function): void; /** * Iterates through the list of functions passed to `tracker.calls()` and will throw an error for functions that * have not been called the expected number of times. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * // Creates call tracker. * const tracker = new assert.CallTracker(); @@ -125,6 +182,10 @@ declare module 'assert' { */ verify(): void; } + interface CallTrackerCall { + thisArg: object; + arguments: unknown[]; + } interface CallTrackerReportInformation { message: string; /** The actual number of times the function was called. */ @@ -136,14 +197,14 @@ declare module 'assert' { /** A stack trace of the function. */ stack: object; } - type AssertPredicate = RegExp | (new () => object) | ((thrown: unknown) => boolean) | object | Error; + type AssertPredicate = RegExp | (new() => object) | ((thrown: unknown) => boolean) | object | Error; /** * Throws an `AssertionError` with the provided error message or a default * error message. If the `message` parameter is an instance of an `Error` then * it will be thrown instead of the `AssertionError`. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.fail(); * // AssertionError [ERR_ASSERTION]: Failed @@ -167,8 +228,8 @@ declare module 'assert' { expected: unknown, message?: string | Error, operator?: string, - // tslint:disable-next-line:ban-types - stackStartFn?: Function + // eslint-disable-next-line @typescript-eslint/ban-types + stackStartFn?: Function, ): never; /** * Tests if `value` is truthy. It is equivalent to`assert.equal(!!value, true, message)`. @@ -181,7 +242,7 @@ declare module 'assert' { * thrown in a file! See below for further details. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.ok(true); * // OK @@ -216,7 +277,7 @@ declare module 'assert' { * ``` * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * // Using `assert()` works the same: * assert(0); @@ -237,11 +298,11 @@ declare module 'assert' { * > Stability: 3 - Legacy: Use {@link strictEqual} instead. * * Tests shallow, coercive equality between the `actual` and `expected` parameters - * using the [Abstract Equality Comparison](https://tc39.github.io/ecma262/#sec-abstract-equality-comparison) ( `==` ). `NaN` is special handled - * and treated as being identical in case both sides are `NaN`. + * using the [`==` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality). `NaN` is specially handled + * and treated as being identical if both sides are `NaN`. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * assert.equal(1, 1); * // OK, 1 == 1 @@ -270,12 +331,11 @@ declare module 'assert' { * * > Stability: 3 - Legacy: Use {@link notStrictEqual} instead. * - * Tests shallow, coercive inequality with the [Abstract Equality Comparison](https://tc39.github.io/ecma262/#sec-abstract-equality-comparison)(`!=` ). `NaN` is special handled and treated as - * being identical in case both - * sides are `NaN`. + * Tests shallow, coercive inequality with the [`!=` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Inequality). `NaN` is + * specially handled and treated as being identical if both sides are `NaN`. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * assert.notEqual(1, 2); * // OK @@ -322,24 +382,24 @@ declare module 'assert' { * Tests for any deep inequality. Opposite of {@link deepEqual}. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * const obj1 = { * a: { - * b: 1 - * } + * b: 1, + * }, * }; * const obj2 = { * a: { - * b: 2 - * } + * b: 2, + * }, * }; * const obj3 = { * a: { - * b: 1 - * } + * b: 1, + * }, * }; - * const obj4 = Object.create(obj1); + * const obj4 = { __proto__: obj1 }; * * assert.notDeepEqual(obj1, obj1); * // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } @@ -362,10 +422,10 @@ declare module 'assert' { function notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void; /** * Tests strict equality between the `actual` and `expected` parameters as - * determined by the [SameValue Comparison](https://tc39.github.io/ecma262/#sec-samevalue). + * determined by [`Object.is()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is). * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.strictEqual(1, 2); * // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal: @@ -400,10 +460,10 @@ declare module 'assert' { function strictEqual(actual: unknown, expected: T, message?: string | Error): asserts actual is T; /** * Tests strict inequality between the `actual` and `expected` parameters as - * determined by the [SameValue Comparison](https://tc39.github.io/ecma262/#sec-samevalue). + * determined by [`Object.is()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is). * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.notStrictEqual(1, 2); * // OK @@ -434,7 +494,7 @@ declare module 'assert' { * Tests for deep strict inequality. Opposite of {@link deepStrictEqual}. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.notDeepStrictEqual({ a: 1 }, { a: '1' }); * // OK @@ -465,14 +525,14 @@ declare module 'assert' { * Custom validation object/error instance: * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * const err = new TypeError('Wrong value'); * err.code = 404; * err.foo = 'bar'; * err.info = { * nested: true, - * baz: 'text' + * baz: 'text', * }; * err.reg = /abc/i; * @@ -485,16 +545,16 @@ declare module 'assert' { * message: 'Wrong value', * info: { * nested: true, - * baz: 'text' - * } + * baz: 'text', + * }, * // Only properties on the validation object will be tested for. * // Using nested objects requires all properties to be present. Otherwise * // the validation is going to fail. - * } + * }, * ); * * // Using regular expressions to validate error properties: - * throws( + * assert.throws( * () => { * throw err; * }, @@ -508,17 +568,17 @@ declare module 'assert' { * info: { * nested: true, * // It is not possible to use regular expressions for nested properties! - * baz: 'text' + * baz: 'text', * }, * // The `reg` property contains a regular expression and only if the * // validation object contains an identical regular expression, it is going * // to pass. - * reg: /abc/i - * } + * reg: /abc/i, + * }, * ); * * // Fails due to the different `message` and `name` properties: - * throws( + * assert.throws( * () => { * const otherErr = new Error('Not found'); * // Copy all enumerable properties from `err` to `otherErr`. @@ -529,20 +589,20 @@ declare module 'assert' { * }, * // The error's `message` and `name` properties will also be checked when using * // an error as validation object. - * err + * err, * ); * ``` * * Validate instanceof using constructor: * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.throws( * () => { * throw new Error('Wrong value'); * }, - * Error + * Error, * ); * ``` * @@ -552,13 +612,13 @@ declare module 'assert' { * therefore also include the error name. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.throws( * () => { * throw new Error('Wrong value'); * }, - * /^Error: Wrong value$/ + * /^Error: Wrong value$/, * ); * ``` * @@ -568,7 +628,7 @@ declare module 'assert' { * It will otherwise fail with an `AssertionError`. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.throws( * () => { @@ -584,7 +644,7 @@ declare module 'assert' { * // possible. * return true; * }, - * 'unexpected error' + * 'unexpected error', * ); * ``` * @@ -594,7 +654,7 @@ declare module 'assert' { * a string as the second argument gets considered: * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * function throwingFirst() { * throw new Error('First'); @@ -650,20 +710,20 @@ declare module 'assert' { * propagated back to the caller. * * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), - * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) or a validation + * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions), or a validation * function. See {@link throws} for more details. * * The following, for instance, will throw the `TypeError` because there is no * matching error type in the assertion: * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.doesNotThrow( * () => { * throw new TypeError('Wrong value'); * }, - * SyntaxError + * SyntaxError, * ); * ``` * @@ -671,27 +731,27 @@ declare module 'assert' { * 'Got unwanted exception...': * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.doesNotThrow( * () => { * throw new TypeError('Wrong value'); * }, - * TypeError + * TypeError, * ); * ``` * * If an `AssertionError` is thrown and a value is provided for the `message`parameter, the value of `message` will be appended to the `AssertionError` message: * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.doesNotThrow( * () => { * throw new TypeError('Wrong value'); * }, * /Wrong value/, - * 'Whoops' + * 'Whoops', * ); * // Throws: AssertionError: Got unwanted exception: Whoops * ``` @@ -705,7 +765,7 @@ declare module 'assert' { * from the error passed to `ifError()` including the potential new frames for`ifError()` itself. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.ifError(null); * // OK @@ -751,7 +811,7 @@ declare module 'assert' { * If specified, `message` will be the message provided by the `AssertionError` if the `asyncFn` fails to reject. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * await assert.rejects( * async () => { @@ -759,13 +819,13 @@ declare module 'assert' { * }, * { * name: 'TypeError', - * message: 'Wrong value' - * } + * message: 'Wrong value', + * }, * ); * ``` * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * await assert.rejects( * async () => { @@ -775,16 +835,16 @@ declare module 'assert' { * assert.strictEqual(err.name, 'TypeError'); * assert.strictEqual(err.message, 'Wrong value'); * return true; - * } + * }, * ); * ``` * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.rejects( * Promise.reject(new Error('Wrong value')), - * Error + * Error, * ).then(() => { * // ... * }); @@ -797,7 +857,11 @@ declare module 'assert' { * @since v10.0.0 */ function rejects(block: (() => Promise) | Promise, message?: string | Error): Promise; - function rejects(block: (() => Promise) | Promise, error: AssertPredicate, message?: string | Error): Promise; + function rejects( + block: (() => Promise) | Promise, + error: AssertPredicate, + message?: string | Error, + ): Promise; /** * Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately * calls the function and awaits the returned promise to complete. It will then @@ -814,24 +878,24 @@ declare module 'assert' { * error messages as expressive as possible. * * If specified, `error` can be a [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), - * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) or a validation + * [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions), or a validation * function. See {@link throws} for more details. * * Besides the async nature to await the completion behaves identically to {@link doesNotThrow}. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * await assert.doesNotReject( * async () => { * throw new TypeError('Wrong value'); * }, - * SyntaxError + * SyntaxError, * ); * ``` * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.doesNotReject(Promise.reject(new TypeError('Wrong value'))) * .then(() => { @@ -840,13 +904,20 @@ declare module 'assert' { * ``` * @since v10.0.0 */ - function doesNotReject(block: (() => Promise) | Promise, message?: string | Error): Promise; - function doesNotReject(block: (() => Promise) | Promise, error: AssertPredicate, message?: string | Error): Promise; + function doesNotReject( + block: (() => Promise) | Promise, + message?: string | Error, + ): Promise; + function doesNotReject( + block: (() => Promise) | Promise, + error: AssertPredicate, + message?: string | Error, + ): Promise; /** * Expects the `string` input to match the regular expression. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.match('I will fail', /pass/); * // AssertionError [ERR_ASSERTION]: The input did not match the regular ... @@ -869,7 +940,7 @@ declare module 'assert' { * Expects the `string` input not to match the regular expression. * * ```js - * import assert from 'assert/strict'; + * import assert from 'node:assert/strict'; * * assert.doesNotMatch('I will fail', /fail/); * // AssertionError [ERR_ASSERTION]: The input was expected to not match the ... @@ -888,25 +959,38 @@ declare module 'assert' { * @since v13.6.0, v12.16.0 */ function doesNotMatch(value: string, regExp: RegExp, message?: string | Error): void; - const strict: Omit & { - (value: unknown, message?: string | Error): asserts value; - equal: typeof strictEqual; - notEqual: typeof notStrictEqual; - deepEqual: typeof deepStrictEqual; - notDeepEqual: typeof notDeepStrictEqual; - // Mapped types and assertion functions are incompatible? - // TS2775: Assertions require every name in the call target - // to be declared with an explicit type annotation. - ok: typeof ok; - strictEqual: typeof strictEqual; - deepStrictEqual: typeof deepStrictEqual; - ifError: typeof ifError; - strict: typeof strict; - }; + const strict: + & Omit< + typeof assert, + | "equal" + | "notEqual" + | "deepEqual" + | "notDeepEqual" + | "ok" + | "strictEqual" + | "deepStrictEqual" + | "ifError" + | "strict" + > + & { + (value: unknown, message?: string | Error): asserts value; + equal: typeof strictEqual; + notEqual: typeof notStrictEqual; + deepEqual: typeof deepStrictEqual; + notDeepEqual: typeof notDeepStrictEqual; + // Mapped types and assertion functions are incompatible? + // TS2775: Assertions require every name in the call target + // to be declared with an explicit type annotation. + ok: typeof ok; + strictEqual: typeof strictEqual; + deepStrictEqual: typeof deepStrictEqual; + ifError: typeof ifError; + strict: typeof strict; + }; } export = assert; } -declare module 'node:assert' { - import assert = require('assert'); +declare module "node:assert" { + import assert = require("assert"); export = assert; } diff --git a/node_modules/@types/node/ts4.8/assert/strict.d.ts b/node_modules/@types/node/ts4.8/assert/strict.d.ts old mode 100755 new mode 100644 index b4319b9..f333913 --- a/node_modules/@types/node/ts4.8/assert/strict.d.ts +++ b/node_modules/@types/node/ts4.8/assert/strict.d.ts @@ -1,8 +1,8 @@ -declare module 'assert/strict' { - import { strict } from 'node:assert'; +declare module "assert/strict" { + import { strict } from "node:assert"; export = strict; } -declare module 'node:assert/strict' { - import { strict } from 'node:assert'; +declare module "node:assert/strict" { + import { strict } from "node:assert"; export = strict; } diff --git a/node_modules/@types/node/ts4.8/async_hooks.d.ts b/node_modules/@types/node/ts4.8/async_hooks.d.ts old mode 100755 new mode 100644 index ed294eb..0667a61 --- a/node_modules/@types/node/ts4.8/async_hooks.d.ts +++ b/node_modules/@types/node/ts4.8/async_hooks.d.ts @@ -1,19 +1,27 @@ /** - * The `async_hooks` module provides an API to track asynchronous resources. It - * can be accessed using: + * We strongly discourage the use of the `async_hooks` API. + * Other APIs that can cover most of its use cases include: + * + * * `AsyncLocalStorage` tracks async context + * * `process.getActiveResourcesInfo()` tracks active resources + * + * The `node:async_hooks` module provides an API to track asynchronous resources. + * It can be accessed using: * * ```js - * import async_hooks from 'async_hooks'; + * import async_hooks from 'node:async_hooks'; * ``` * @experimental - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/async_hooks.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/async_hooks.js) */ -declare module 'async_hooks' { +declare module "async_hooks" { /** * ```js - * import { executionAsyncId } from 'async_hooks'; + * import { executionAsyncId } from 'node:async_hooks'; + * import fs from 'node:fs'; * * console.log(executionAsyncId()); // 1 - bootstrap + * const path = '.'; * fs.open(path, 'r', (err, fd) => { * console.log(executionAsyncId()); // 6 - open() * }); @@ -51,8 +59,8 @@ declare module 'async_hooks' { * but having an object representing the top-level can be helpful. * * ```js - * import { open } from 'fs'; - * import { executionAsyncId, executionAsyncResource } from 'async_hooks'; + * import { open } from 'node:fs'; + * import { executionAsyncId, executionAsyncResource } from 'node:async_hooks'; * * console.log(executionAsyncId(), executionAsyncResource()); // 1 {} * open(new URL(import.meta.url), 'r', (err, fd) => { @@ -64,11 +72,11 @@ declare module 'async_hooks' { * use of a tracking `Map` to store the metadata: * * ```js - * import { createServer } from 'http'; + * import { createServer } from 'node:http'; * import { * executionAsyncId, * executionAsyncResource, - * createHook + * createHook, * } from 'async_hooks'; * const sym = Symbol('state'); // Private symbol to avoid pollution * @@ -78,7 +86,7 @@ declare module 'async_hooks' { * if (cr) { * resource[sym] = cr[sym]; * } - * } + * }, * }).enable(); * * const server = createServer((req, res) => { @@ -167,11 +175,11 @@ declare module 'async_hooks' { * specifics of all functions that can be passed to `callbacks` is in the `Hook Callbacks` section. * * ```js - * import { createHook } from 'async_hooks'; + * import { createHook } from 'node:async_hooks'; * * const asyncHook = createHook({ * init(asyncId, type, triggerAsyncId, resource) { }, - * destroy(asyncId) { } + * destroy(asyncId) { }, * }); * ``` * @@ -223,13 +231,13 @@ declare module 'async_hooks' { * The following is an overview of the `AsyncResource` API. * * ```js - * import { AsyncResource, executionAsyncId } from 'async_hooks'; + * import { AsyncResource, executionAsyncId } from 'node:async_hooks'; * * // AsyncResource() is meant to be extended. Instantiating a * // new AsyncResource() also triggers init. If triggerAsyncId is omitted then * // async_hook.executionAsyncId() is used. * const asyncResource = new AsyncResource( - * type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false } + * type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false }, * ); * * // Run a function in the execution context of the resource. This will @@ -263,9 +271,6 @@ declare module 'async_hooks' { constructor(type: string, triggerAsyncId?: number | AsyncResourceOptions); /** * Binds the given function to the current execution context. - * - * The returned function will have an `asyncResource` property referencing - * the `AsyncResource` to which the function is bound. * @since v14.8.0, v12.19.0 * @param fn The function to bind to the current execution context. * @param type An optional name to associate with the underlying `AsyncResource`. @@ -273,23 +278,14 @@ declare module 'async_hooks' { static bind any, ThisArg>( fn: Func, type?: string, - thisArg?: ThisArg - ): Func & { - asyncResource: AsyncResource; - }; + thisArg?: ThisArg, + ): Func; /** * Binds the given function to execute to this `AsyncResource`'s scope. - * - * The returned function will have an `asyncResource` property referencing - * the `AsyncResource` to which the function is bound. * @since v14.8.0, v12.19.0 * @param fn The function to bind to the current `AsyncResource`. */ - bind any>( - fn: Func - ): Func & { - asyncResource: AsyncResource; - }; + bind any>(fn: Func): Func; /** * Call the provided function with the provided arguments in the execution context * of the async resource. This will establish the context, trigger the AsyncHooks @@ -300,7 +296,11 @@ declare module 'async_hooks' { * @param thisArg The receiver to be used for the function call. * @param args Optional arguments to pass to the function. */ - runInAsyncScope(fn: (this: This, ...args: any[]) => Result, thisArg?: This, ...args: any[]): Result; + runInAsyncScope( + fn: (this: This, ...args: any[]) => Result, + thisArg?: This, + ...args: any[] + ): Result; /** * Call all `destroy` hooks. This should only ever be called once. An error will * be thrown if it is called more than once. This **must** be manually called. If @@ -314,7 +314,6 @@ declare module 'async_hooks' { */ asyncId(): number; /** - * * @return The same `triggerAsyncId` that is passed to the `AsyncResource` constructor. */ triggerAsyncId(): number; @@ -322,17 +321,17 @@ declare module 'async_hooks' { /** * This class creates stores that stay coherent through asynchronous operations. * - * While you can create your own implementation on top of the `async_hooks` module,`AsyncLocalStorage` should be preferred as it is a performant and memory safe - * implementation that involves significant optimizations that are non-obvious to - * implement. + * While you can create your own implementation on top of the `node:async_hooks`module, `AsyncLocalStorage` should be preferred as it is a performant and memory + * safe implementation that involves significant optimizations that are non-obvious + * to implement. * * The following example uses `AsyncLocalStorage` to build a simple logger * that assigns IDs to incoming HTTP requests and includes them in messages * logged within each request. * * ```js - * import http from 'http'; - * import { AsyncLocalStorage } from 'async_hooks'; + * import http from 'node:http'; + * import { AsyncLocalStorage } from 'node:async_hooks'; * * const asyncLocalStorage = new AsyncLocalStorage(); * @@ -364,10 +363,48 @@ declare module 'async_hooks' { * * Each instance of `AsyncLocalStorage` maintains an independent storage context. * Multiple instances can safely exist simultaneously without risk of interfering - * with each other data. + * with each other's data. * @since v13.10.0, v12.17.0 */ class AsyncLocalStorage { + /** + * Binds the given function to the current execution context. + * @since v19.8.0 + * @experimental + * @param fn The function to bind to the current execution context. + * @return A new function that calls `fn` within the captured execution context. + */ + static bind any>(fn: Func): Func; + /** + * Captures the current execution context and returns a function that accepts a + * function as an argument. Whenever the returned function is called, it + * calls the function passed to it within the captured context. + * + * ```js + * const asyncLocalStorage = new AsyncLocalStorage(); + * const runInAsyncScope = asyncLocalStorage.run(123, () => AsyncLocalStorage.snapshot()); + * const result = asyncLocalStorage.run(321, () => runInAsyncScope(() => asyncLocalStorage.getStore())); + * console.log(result); // returns 123 + * ``` + * + * AsyncLocalStorage.snapshot() can replace the use of AsyncResource for simple + * async context tracking purposes, for example: + * + * ```js + * class Foo { + * #runInAsyncScope = AsyncLocalStorage.snapshot(); + * + * get() { return this.#runInAsyncScope(() => asyncLocalStorage.getStore()); } + * } + * + * const foo = asyncLocalStorage.run(123, () => new Foo()); + * console.log(asyncLocalStorage.run(321, () => foo.get())); // returns 123 + * ``` + * @since v19.8.0 + * @experimental + * @return A new function with the signature `(fn: (...args) : R, ...args) : R`. + */ + static snapshot(): (fn: (...args: TArgs) => R, ...args: TArgs) => R; /** * Disables the instance of `AsyncLocalStorage`. All subsequent calls * to `asyncLocalStorage.getStore()` will return `undefined` until`asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()` is called again. @@ -395,8 +432,9 @@ declare module 'async_hooks' { getStore(): T | undefined; /** * Runs a function synchronously within a context and returns its - * return value. The store is not accessible outside of the callback function or - * the asynchronous operations created within the callback. + * return value. The store is not accessible outside of the callback function. + * The store is accessible to any asynchronous operations created within the + * callback. * * The optional `args` are passed to the callback function. * @@ -410,6 +448,9 @@ declare module 'async_hooks' { * try { * asyncLocalStorage.run(store, () => { * asyncLocalStorage.getStore(); // Returns the store object + * setTimeout(() => { + * asyncLocalStorage.getStore(); // Returns the store object + * }, 200); * throw new Error(); * }); * } catch (e) { @@ -419,6 +460,7 @@ declare module 'async_hooks' { * ``` * @since v13.10.0, v12.17.0 */ + run(store: T, callback: () => R): R; run(store: T, callback: (...args: TArgs) => R, ...args: TArgs): R; /** * Runs a function synchronously outside of a context and returns its @@ -492,6 +534,6 @@ declare module 'async_hooks' { enterWith(store: T): void; } } -declare module 'node:async_hooks' { - export * from 'async_hooks'; +declare module "node:async_hooks" { + export * from "async_hooks"; } diff --git a/node_modules/@types/node/ts4.8/buffer.d.ts b/node_modules/@types/node/ts4.8/buffer.d.ts old mode 100755 new mode 100644 index f3f44ee..2fa2e74 --- a/node_modules/@types/node/ts4.8/buffer.d.ts +++ b/node_modules/@types/node/ts4.8/buffer.d.ts @@ -10,7 +10,7 @@ * recommended to explicitly reference it via an import or require statement. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Creates a zero-filled Buffer of length 10. * const buf1 = Buffer.alloc(10); @@ -41,10 +41,29 @@ * // Creates a Buffer containing the Latin-1 bytes [0x74, 0xe9, 0x73, 0x74]. * const buf7 = Buffer.from('tést', 'latin1'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/buffer.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/buffer.js) */ -declare module 'buffer' { - import { BinaryLike } from 'node:crypto'; +declare module "buffer" { + import { BinaryLike } from "node:crypto"; + import { ReadableStream as WebReadableStream } from "node:stream/web"; + /** + * This function returns `true` if `input` contains only valid UTF-8-encoded data, + * including the case in which `input` is empty. + * + * Throws if the `input` is a detached array buffer. + * @since v19.4.0, v18.14.0 + * @param input The input to validate. + */ + export function isUtf8(input: Buffer | ArrayBuffer | NodeJS.TypedArray): boolean; + /** + * This function returns `true` if `input` contains only valid ASCII-encoded data, + * including the case in which `input` is empty. + * + * Throws if the `input` is a detached array buffer. + * @since v19.6.0, v18.15.0 + * @param input The input to validate. + */ + export function isAscii(input: Buffer | ArrayBuffer | NodeJS.TypedArray): boolean; export const INSPECT_MAX_BYTES: number; export const kMaxLength: number; export const kStringMaxLength: number; @@ -52,7 +71,16 @@ declare module 'buffer' { MAX_LENGTH: number; MAX_STRING_LENGTH: number; }; - export type TranscodeEncoding = 'ascii' | 'utf8' | 'utf16le' | 'ucs2' | 'latin1' | 'binary'; + export type TranscodeEncoding = + | "ascii" + | "utf8" + | "utf-8" + | "utf16le" + | "utf-16le" + | "ucs2" + | "ucs-2" + | "latin1" + | "binary"; /** * Re-encodes the given `Buffer` or `Uint8Array` instance from one character * encoding to another. Returns a new `Buffer` instance. @@ -66,7 +94,7 @@ declare module 'buffer' { * sequence cannot be adequately represented in the target encoding. For instance: * * ```js - * import { Buffer, transcode } from 'buffer'; + * import { Buffer, transcode } from 'node:buffer'; * * const newBuf = transcode(Buffer.from('€'), 'utf8', 'ascii'); * console.log(newBuf.toString('ascii')); @@ -83,7 +111,7 @@ declare module 'buffer' { export function transcode(source: Uint8Array, fromEnc: TranscodeEncoding, toEnc: TranscodeEncoding): Buffer; export const SlowBuffer: { /** @deprecated since v6.0.0, use `Buffer.allocUnsafeSlow()` */ - new (size: number): Buffer; + new(size: number): Buffer; prototype: Buffer; }; /** @@ -113,18 +141,17 @@ declare module 'buffer' { /** * A [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) encapsulates immutable, raw data that can be safely shared across * multiple worker threads. - * @since v15.7.0 - * @experimental + * @since v15.7.0, v14.18.0 */ export class Blob { /** * The total size of the `Blob` in bytes. - * @since v15.7.0 + * @since v15.7.0, v14.18.0 */ readonly size: number; /** * The content-type of the `Blob`. - * @since v15.7.0 + * @since v15.7.0, v14.18.0 */ readonly type: string; /** @@ -139,13 +166,13 @@ declare module 'buffer' { /** * Returns a promise that fulfills with an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) containing a copy of * the `Blob` data. - * @since v15.7.0 + * @since v15.7.0, v14.18.0 */ arrayBuffer(): Promise; /** * Creates and returns a new `Blob` containing a subset of this `Blob` objects * data. The original `Blob` is not altered. - * @since v15.7.0 + * @since v15.7.0, v14.18.0 * @param start The starting index. * @param end The ending index. * @param type The content-type for the new `Blob` @@ -154,25 +181,72 @@ declare module 'buffer' { /** * Returns a promise that fulfills with the contents of the `Blob` decoded as a * UTF-8 string. - * @since v15.7.0 + * @since v15.7.0, v14.18.0 */ text(): Promise; /** * Returns a new `ReadableStream` that allows the content of the `Blob` to be read. * @since v16.7.0 */ - stream(): unknown; // pending web streams types + stream(): WebReadableStream; + } + export interface FileOptions { + /** + * One of either `'transparent'` or `'native'`. When set to `'native'`, line endings in string source parts will be + * converted to the platform native line-ending as specified by `require('node:os').EOL`. + */ + endings?: "native" | "transparent"; + /** The File content-type. */ + type?: string; + /** The last modified date of the file. `Default`: Date.now(). */ + lastModified?: number; + } + /** + * A [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) provides information about files. + * @since v19.2.0, v18.13.0 + */ + export class File extends Blob { + constructor(sources: Array, fileName: string, options?: FileOptions); + /** + * The name of the `File`. + * @since v19.2.0, v18.13.0 + */ + readonly name: string; + /** + * The last modified date of the `File`. + * @since v19.2.0, v18.13.0 + */ + readonly lastModified: number; } export import atob = globalThis.atob; export import btoa = globalThis.btoa; + import { Blob as NodeBlob } from "buffer"; + // This conditional type will be the existing global Blob in a browser, or + // the copy below in a Node environment. + type __Blob = typeof globalThis extends { onmessage: any; Blob: any } ? {} : NodeBlob; global { + namespace NodeJS { + export { BufferEncoding }; + } // Buffer class - type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex'; + type BufferEncoding = + | "ascii" + | "utf8" + | "utf-8" + | "utf16le" + | "utf-16le" + | "ucs2" + | "ucs-2" + | "base64" + | "base64url" + | "latin1" + | "binary" + | "hex"; type WithImplicitCoercion = | T | { - valueOf(): T; - }; + valueOf(): T; + }; /** * Raw data is stored in instances of the Buffer class. * A Buffer is similar to an array of integers but corresponds to a raw memory allocation outside the V8 heap. A Buffer cannot be resized. @@ -186,68 +260,75 @@ declare module 'buffer' { * @param encoding encoding to use, optional. Default is 'utf8' * @deprecated since v10.0.0 - Use `Buffer.from(string[, encoding])` instead. */ - new (str: string, encoding?: BufferEncoding): Buffer; + new(str: string, encoding?: BufferEncoding): Buffer; /** * Allocates a new buffer of {size} octets. * * @param size count of octets to allocate. * @deprecated since v10.0.0 - Use `Buffer.alloc()` instead (also see `Buffer.allocUnsafe()`). */ - new (size: number): Buffer; + new(size: number): Buffer; /** * Allocates a new buffer containing the given {array} of octets. * * @param array The octets to store. * @deprecated since v10.0.0 - Use `Buffer.from(array)` instead. */ - new (array: Uint8Array): Buffer; + new(array: Uint8Array): Buffer; /** * Produces a Buffer backed by the same allocated memory as * the given {ArrayBuffer}/{SharedArrayBuffer}. * - * * @param arrayBuffer The ArrayBuffer with which to share memory. * @deprecated since v10.0.0 - Use `Buffer.from(arrayBuffer[, byteOffset[, length]])` instead. */ - new (arrayBuffer: ArrayBuffer | SharedArrayBuffer): Buffer; + new(arrayBuffer: ArrayBuffer | SharedArrayBuffer): Buffer; /** * Allocates a new buffer containing the given {array} of octets. * * @param array The octets to store. * @deprecated since v10.0.0 - Use `Buffer.from(array)` instead. */ - new (array: ReadonlyArray): Buffer; + new(array: readonly any[]): Buffer; /** * Copies the passed {buffer} data onto a new {Buffer} instance. * * @param buffer The buffer to copy. * @deprecated since v10.0.0 - Use `Buffer.from(buffer)` instead. */ - new (buffer: Buffer): Buffer; + new(buffer: Buffer): Buffer; /** * Allocates a new `Buffer` using an `array` of bytes in the range `0` – `255`. * Array entries outside that range will be truncated to fit into it. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'. * const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); * ``` * + * If `array` is an `Array`\-like object (that is, one with a `length` property of + * type `number`), it is treated as if it is an array, unless it is a `Buffer` or + * a `Uint8Array`. This means all other `TypedArray` variants get treated as an`Array`. To create a `Buffer` from the bytes backing a `TypedArray`, use `Buffer.copyBytesFrom()`. + * * A `TypeError` will be thrown if `array` is not an `Array` or another type * appropriate for `Buffer.from()` variants. * * `Buffer.from(array)` and `Buffer.from(string)` may also use the internal`Buffer` pool like `Buffer.allocUnsafe()` does. * @since v5.10.0 */ - from(arrayBuffer: WithImplicitCoercion, byteOffset?: number, length?: number): Buffer; + from( + arrayBuffer: WithImplicitCoercion, + byteOffset?: number, + length?: number, + ): Buffer; /** * Creates a new Buffer using the passed {data} * @param data data to create a new Buffer */ - from(data: Uint8Array | ReadonlyArray): Buffer; - from(data: WithImplicitCoercion | string>): Buffer; + from(data: Uint8Array | readonly number[]): Buffer; + from(data: WithImplicitCoercion): Buffer; /** * Creates a new Buffer containing the given JavaScript string {str}. * If provided, the {encoding} parameter identifies the character encoding. @@ -257,9 +338,9 @@ declare module 'buffer' { str: | WithImplicitCoercion | { - [Symbol.toPrimitive](hint: 'string'): string; - }, - encoding?: BufferEncoding + [Symbol.toPrimitive](hint: "string"): string; + }, + encoding?: BufferEncoding, ): Buffer; /** * Creates a new Buffer using the passed {data} @@ -270,7 +351,7 @@ declare module 'buffer' { * Returns `true` if `obj` is a `Buffer`, `false` otherwise. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * Buffer.isBuffer(Buffer.alloc(10)); // true * Buffer.isBuffer(Buffer.from('foo')); // true @@ -286,7 +367,7 @@ declare module 'buffer' { * or `false` otherwise. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * console.log(Buffer.isEncoding('utf8')); * // Prints: true @@ -315,7 +396,7 @@ declare module 'buffer' { * string. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const str = '\u00bd + \u00bc = \u00be'; * @@ -333,7 +414,10 @@ declare module 'buffer' { * @param [encoding='utf8'] If `string` is a string, this is its encoding. * @return The number of bytes contained within `string`. */ - byteLength(string: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer, encoding?: BufferEncoding): number; + byteLength( + string: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer, + encoding?: BufferEncoding, + ): number; /** * Returns a new `Buffer` which is the result of concatenating all the `Buffer`instances in the `list` together. * @@ -347,7 +431,7 @@ declare module 'buffer' { * truncated to `totalLength`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Create a single `Buffer` from a list of three `Buffer` instances. * @@ -372,12 +456,29 @@ declare module 'buffer' { * @param list List of `Buffer` or {@link Uint8Array} instances to concatenate. * @param totalLength Total length of the `Buffer` instances in `list` when concatenated. */ - concat(list: ReadonlyArray, totalLength?: number): Buffer; + concat(list: readonly Uint8Array[], totalLength?: number): Buffer; + /** + * Copies the underlying memory of `view` into a new `Buffer`. + * + * ```js + * const u16 = new Uint16Array([0, 0xffff]); + * const buf = Buffer.copyBytesFrom(u16, 1, 1); + * u16[1] = 0; + * console.log(buf.length); // 2 + * console.log(buf[0]); // 255 + * console.log(buf[1]); // 255 + * ``` + * @since v19.8.0 + * @param view The {TypedArray} to copy. + * @param [offset=': 0'] The starting offset within `view`. + * @param [length=view.length - offset] The number of elements from `view` to copy. + */ + copyBytesFrom(view: NodeJS.TypedArray, offset?: number, length?: number): Buffer; /** * Compares `buf1` to `buf2`, typically for the purpose of sorting arrays of`Buffer` instances. This is equivalent to calling `buf1.compare(buf2)`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from('1234'); * const buf2 = Buffer.from('0123'); @@ -390,12 +491,12 @@ declare module 'buffer' { * @since v0.11.13 * @return Either `-1`, `0`, or `1`, depending on the result of the comparison. See `compare` for details. */ - compare(buf1: Uint8Array, buf2: Uint8Array): number; + compare(buf1: Uint8Array, buf2: Uint8Array): -1 | 0 | 1; /** * Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the`Buffer` will be zero-filled. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.alloc(5); * @@ -403,12 +504,12 @@ declare module 'buffer' { * // Prints: * ``` * - * If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_INVALID_ARG_VALUE` is thrown. + * If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_OUT_OF_RANGE` is thrown. * * If `fill` is specified, the allocated `Buffer` will be initialized by calling `buf.fill(fill)`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.alloc(5, 'a'); * @@ -420,7 +521,7 @@ declare module 'buffer' { * initialized by calling `buf.fill(fill, encoding)`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64'); * @@ -438,15 +539,15 @@ declare module 'buffer' { * @param [fill=0] A value to pre-fill the new `Buffer` with. * @param [encoding='utf8'] If `fill` is a string, this is its encoding. */ - alloc(size: number, fill?: string | Buffer | number, encoding?: BufferEncoding): Buffer; + alloc(size: number, fill?: string | Uint8Array | number, encoding?: BufferEncoding): Buffer; /** - * Allocates a new `Buffer` of `size` bytes. If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_INVALID_ARG_VALUE` is thrown. + * Allocates a new `Buffer` of `size` bytes. If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_OUT_OF_RANGE` is thrown. * * The underlying memory for `Buffer` instances created in this way is _not_ - * _initialized_. The contents of the newly created `Buffer` are unknown and_may contain sensitive data_. Use `Buffer.alloc()` instead to initialize`Buffer` instances with zeroes. + * _initialized_. The contents of the newly created `Buffer` are unknown and _may contain sensitive data_. Use `Buffer.alloc()` instead to initialize`Buffer` instances with zeroes. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(10); * @@ -462,9 +563,8 @@ declare module 'buffer' { * A `TypeError` will be thrown if `size` is not a number. * * The `Buffer` module pre-allocates an internal `Buffer` instance of - * size `Buffer.poolSize` that is used as a pool for the fast allocation of new`Buffer` instances created using `Buffer.allocUnsafe()`,`Buffer.from(array)`, `Buffer.concat()`, and the - * deprecated`new Buffer(size)` constructor only when `size` is less than or equal - * to `Buffer.poolSize >> 1` (floor of `Buffer.poolSize` divided by two). + * size `Buffer.poolSize` that is used as a pool for the fast allocation of new`Buffer` instances created using `Buffer.allocUnsafe()`, `Buffer.from(array)`, + * and `Buffer.concat()` only when `size` is less than`Buffer.poolSize >>> 1` (floor of `Buffer.poolSize` divided by two). * * Use of this pre-allocated internal memory pool is a key difference between * calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)`. @@ -477,15 +577,15 @@ declare module 'buffer' { */ allocUnsafe(size: number): Buffer; /** - * Allocates a new `Buffer` of `size` bytes. If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_INVALID_ARG_VALUE` is thrown. A zero-length `Buffer` is created - * if `size` is 0. + * Allocates a new `Buffer` of `size` bytes. If `size` is larger than {@link constants.MAX_LENGTH} or smaller than 0, `ERR_OUT_OF_RANGE` is thrown. A zero-length `Buffer` is created if + * `size` is 0. * * The underlying memory for `Buffer` instances created in this way is _not_ - * _initialized_. The contents of the newly created `Buffer` are unknown and_may contain sensitive data_. Use `buf.fill(0)` to initialize + * _initialized_. The contents of the newly created `Buffer` are unknown and _may contain sensitive data_. Use `buf.fill(0)` to initialize * such `Buffer` instances with zeroes. * * When using `Buffer.allocUnsafe()` to allocate new `Buffer` instances, - * allocations under 4 KB are sliced from a single pre-allocated `Buffer`. This + * allocations under 4 KiB are sliced from a single pre-allocated `Buffer`. This * allows applications to avoid the garbage collection overhead of creating many * individually allocated `Buffer` instances. This approach improves both * performance and memory usage by eliminating the need to track and clean up as @@ -497,7 +597,7 @@ declare module 'buffer' { * then copying out the relevant bits. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Need to keep around a few small chunks of memory. * const store = []; @@ -535,7 +635,7 @@ declare module 'buffer' { * written. However, partially encoded characters will not be written. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.alloc(256); * @@ -571,7 +671,7 @@ declare module 'buffer' { * as {@link constants.MAX_STRING_LENGTH}. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.allocUnsafe(26); * @@ -608,7 +708,7 @@ declare module 'buffer' { * In particular, `Buffer.from(buf.toJSON())` works like `Buffer.from(buf)`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]); * const json = JSON.stringify(buf); @@ -628,14 +728,14 @@ declare module 'buffer' { * @since v0.9.2 */ toJSON(): { - type: 'Buffer'; + type: "Buffer"; data: number[]; }; /** * Returns `true` if both `buf` and `otherBuffer` have exactly the same bytes,`false` otherwise. Equivalent to `buf.compare(otherBuffer) === 0`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from('ABC'); * const buf2 = Buffer.from('414243', 'hex'); @@ -659,7 +759,7 @@ declare module 'buffer' { * * `-1` is returned if `target` should come _after_`buf` when sorted. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from('ABC'); * const buf2 = Buffer.from('BCD'); @@ -683,7 +783,7 @@ declare module 'buffer' { * The optional `targetStart`, `targetEnd`, `sourceStart`, and `sourceEnd`arguments can be used to limit the comparison to specific ranges within `target`and `buf` respectively. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9]); * const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4]); @@ -704,7 +804,13 @@ declare module 'buffer' { * @param [sourceStart=0] The offset within `buf` at which to begin comparison. * @param [sourceEnd=buf.length] The offset within `buf` at which to end comparison (not inclusive). */ - compare(target: Uint8Array, targetStart?: number, targetEnd?: number, sourceStart?: number, sourceEnd?: number): number; + compare( + target: Uint8Array, + targetStart?: number, + targetEnd?: number, + sourceStart?: number, + sourceEnd?: number, + ): -1 | 0 | 1; /** * Copies data from a region of `buf` to a region in `target`, even if the `target`memory region overlaps with `buf`. * @@ -713,7 +819,7 @@ declare module 'buffer' { * different function arguments. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Create two `Buffer` instances. * const buf1 = Buffer.allocUnsafe(26); @@ -734,7 +840,7 @@ declare module 'buffer' { * ``` * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Create a `Buffer` and copy data from one region to an overlapping region * // within the same `Buffer`. @@ -763,13 +869,11 @@ declare module 'buffer' { * Returns a new `Buffer` that references the same memory as the original, but * offset and cropped by the `start` and `end` indices. * - * This is the same behavior as `buf.subarray()`. - * * This method is not compatible with the `Uint8Array.prototype.slice()`, * which is a superclass of `Buffer`. To copy the slice, use`Uint8Array.prototype.slice()`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('buffer'); * @@ -780,8 +884,17 @@ declare module 'buffer' { * * console.log(buf.toString()); * // Prints: buffer + * + * // With buf.slice(), the original buffer is modified. + * const notReallyCopiedBuf = buf.slice(); + * notReallyCopiedBuf[0]++; + * console.log(notReallyCopiedBuf.toString()); + * // Prints: cuffer + * console.log(buf.toString()); + * // Also prints: cuffer (!) * ``` * @since v0.3.0 + * @deprecated Use `subarray` instead. * @param [start=0] Where the new `Buffer` will start. * @param [end=buf.length] Where the new `Buffer` will end (not inclusive). */ @@ -798,7 +911,7 @@ declare module 'buffer' { * Modifying the new `Buffer` slice will modify the memory in the original `Buffer`because the allocated memory of the two objects overlap. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Create a `Buffer` with the ASCII alphabet, take a slice, and modify one byte * // from the original `Buffer`. @@ -825,7 +938,7 @@ declare module 'buffer' { * end of `buf` rather than the beginning. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('buffer'); * @@ -852,7 +965,7 @@ declare module 'buffer' { * `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -873,7 +986,7 @@ declare module 'buffer' { * `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -894,7 +1007,7 @@ declare module 'buffer' { * This function is also available under the `writeBigUint64BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -918,7 +1031,7 @@ declare module 'buffer' { * Writes `value` to `buf` at the specified `offset` as little-endian * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -947,7 +1060,7 @@ declare module 'buffer' { * This function is also available under the `writeUintLE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(6); * @@ -975,7 +1088,7 @@ declare module 'buffer' { * This function is also available under the `writeUintBE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(6); * @@ -1001,7 +1114,7 @@ declare module 'buffer' { * when `value` is anything other than a signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(6); * @@ -1022,7 +1135,7 @@ declare module 'buffer' { * signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(6); * @@ -1044,7 +1157,7 @@ declare module 'buffer' { * This function is also available under the `readBigUint64BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]); * @@ -1066,7 +1179,7 @@ declare module 'buffer' { * This function is also available under the `readBigUint64LE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]); * @@ -1107,7 +1220,7 @@ declare module 'buffer' { * This function is also available under the `readUintLE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]); * @@ -1131,7 +1244,7 @@ declare module 'buffer' { * This function is also available under the `readUintBE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]); * @@ -1155,7 +1268,7 @@ declare module 'buffer' { * supporting up to 48 bits of accuracy. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]); * @@ -1172,7 +1285,7 @@ declare module 'buffer' { * supporting up to 48 bits of accuracy. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]); * @@ -1194,7 +1307,7 @@ declare module 'buffer' { * This function is also available under the `readUint8` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([1, -2]); * @@ -1220,7 +1333,7 @@ declare module 'buffer' { * This function is also available under the `readUint16LE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56]); * @@ -1246,7 +1359,7 @@ declare module 'buffer' { * This function is also available under the `readUint16BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56]); * @@ -1270,7 +1383,7 @@ declare module 'buffer' { * This function is also available under the `readUint32LE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]); * @@ -1294,7 +1407,7 @@ declare module 'buffer' { * This function is also available under the `readUint32BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]); * @@ -1316,7 +1429,7 @@ declare module 'buffer' { * Integers read from a `Buffer` are interpreted as two's complement signed values. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([-1, 5]); * @@ -1337,7 +1450,7 @@ declare module 'buffer' { * Integers read from a `Buffer` are interpreted as two's complement signed values. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0, 5]); * @@ -1356,7 +1469,7 @@ declare module 'buffer' { * Integers read from a `Buffer` are interpreted as two's complement signed values. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0, 5]); * @@ -1373,7 +1486,7 @@ declare module 'buffer' { * Integers read from a `Buffer` are interpreted as two's complement signed values. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0, 0, 0, 5]); * @@ -1392,7 +1505,7 @@ declare module 'buffer' { * Integers read from a `Buffer` are interpreted as two's complement signed values. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([0, 0, 0, 5]); * @@ -1407,7 +1520,7 @@ declare module 'buffer' { * Reads a 32-bit, little-endian float from `buf` at the specified `offset`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([1, 2, 3, 4]); * @@ -1424,7 +1537,7 @@ declare module 'buffer' { * Reads a 32-bit, big-endian float from `buf` at the specified `offset`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([1, 2, 3, 4]); * @@ -1439,7 +1552,7 @@ declare module 'buffer' { * Reads a 64-bit, little-endian double from `buf` at the specified `offset`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]); * @@ -1456,7 +1569,7 @@ declare module 'buffer' { * Reads a 64-bit, big-endian double from `buf` at the specified `offset`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]); * @@ -1473,7 +1586,7 @@ declare module 'buffer' { * byte order _in-place_. Throws `ERR_INVALID_BUFFER_SIZE` if `buf.length` is not a multiple of 2. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); * @@ -1495,7 +1608,7 @@ declare module 'buffer' { * between UTF-16 little-endian and UTF-16 big-endian: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('This is little-endian UTF-16', 'utf16le'); * buf.swap16(); // Convert to big-endian UTF-16 text. @@ -1509,7 +1622,7 @@ declare module 'buffer' { * byte order _in-place_. Throws `ERR_INVALID_BUFFER_SIZE` if `buf.length` is not a multiple of 4. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); * @@ -1535,7 +1648,7 @@ declare module 'buffer' { * Throws `ERR_INVALID_BUFFER_SIZE` if `buf.length` is not a multiple of 8. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); * @@ -1564,7 +1677,7 @@ declare module 'buffer' { * This function is also available under the `writeUint8` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1594,7 +1707,7 @@ declare module 'buffer' { * This function is also available under the `writeUint16LE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1622,7 +1735,7 @@ declare module 'buffer' { * This function is also available under the `writeUint16BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1650,7 +1763,7 @@ declare module 'buffer' { * This function is also available under the `writeUint32LE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1677,7 +1790,7 @@ declare module 'buffer' { * This function is also available under the `writeUint32BE` alias. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1705,7 +1818,7 @@ declare module 'buffer' { * `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(2); * @@ -1728,7 +1841,7 @@ declare module 'buffer' { * The `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(2); * @@ -1750,7 +1863,7 @@ declare module 'buffer' { * The `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(2); * @@ -1772,7 +1885,7 @@ declare module 'buffer' { * The `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1794,7 +1907,7 @@ declare module 'buffer' { * The `value` is interpreted and written as a two's complement signed integer. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1814,7 +1927,7 @@ declare module 'buffer' { * undefined when `value` is anything other than a JavaScript number. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1834,7 +1947,7 @@ declare module 'buffer' { * undefined when `value` is anything other than a JavaScript number. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(4); * @@ -1854,7 +1967,7 @@ declare module 'buffer' { * other than a JavaScript number. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -1874,7 +1987,7 @@ declare module 'buffer' { * other than a JavaScript number. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(8); * @@ -1894,7 +2007,7 @@ declare module 'buffer' { * the entire `buf` will be filled: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Fill a `Buffer` with the ASCII character 'h'. * @@ -1902,6 +2015,12 @@ declare module 'buffer' { * * console.log(b.toString()); * // Prints: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh + * + * // Fill a buffer with empty string + * const c = Buffer.allocUnsafe(5).fill(''); + * + * console.log(c.fill('')); + * // Prints: * ``` * * `value` is coerced to a `uint32` value if it is not a string, `Buffer`, or @@ -1912,7 +2031,7 @@ declare module 'buffer' { * then only the bytes of that character that fit into `buf` are written: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Fill a `Buffer` with character that takes up two bytes in UTF-8. * @@ -1924,7 +2043,7 @@ declare module 'buffer' { * fill data remains, an exception is thrown: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.allocUnsafe(5); * @@ -1936,7 +2055,7 @@ declare module 'buffer' { * // Throws an exception. * ``` * @since v0.5.0 - * @param value The value with which to fill `buf`. + * @param value The value with which to fill `buf`. Empty value (string, Uint8Array, Buffer) is coerced to `0`. * @param [offset=0] Number of bytes to skip before starting to fill `buf`. * @param [end=buf.length] Where to stop filling `buf` (not inclusive). * @param [encoding='utf8'] The encoding for `value` if `value` is a string. @@ -1948,12 +2067,12 @@ declare module 'buffer' { * * * a string, `value` is interpreted according to the character encoding in`encoding`. * * a `Buffer` or [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array), `value` will be used in its entirety. - * To compare a partial `Buffer`, use `buf.slice()`. + * To compare a partial `Buffer`, use `buf.subarray`. * * a number, `value` will be interpreted as an unsigned 8-bit integer * value between `0` and `255`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('this is a buffer'); * @@ -1986,7 +2105,7 @@ declare module 'buffer' { * behavior matches [`String.prototype.indexOf()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf). * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const b = Buffer.from('abcdef'); * @@ -2017,7 +2136,7 @@ declare module 'buffer' { * rather than the first occurrence. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('this buffer is a buffer'); * @@ -2052,7 +2171,7 @@ declare module 'buffer' { * This behavior matches [`String.prototype.lastIndexOf()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/lastIndexOf). * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const b = Buffer.from('abcdef'); * @@ -2085,7 +2204,7 @@ declare module 'buffer' { * of `buf`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * // Log the entire contents of a `Buffer`. * @@ -2109,7 +2228,7 @@ declare module 'buffer' { * Equivalent to `buf.indexOf() !== -1`. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('this is a buffer'); * @@ -2139,7 +2258,7 @@ declare module 'buffer' { * Creates and returns an [iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) of `buf` keys (indices). * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('buffer'); * @@ -2162,7 +2281,7 @@ declare module 'buffer' { * called automatically when a `Buffer` is used in a `for..of` statement. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * * const buf = Buffer.from('buffer'); * @@ -2204,8 +2323,8 @@ declare module 'buffer' { * **binary data and predate the introduction of typed arrays in JavaScript.** * **For code running using Node.js APIs, converting between base64-encoded strings** * **and binary data should be performed using `Buffer.from(str, 'base64')` and`buf.toString('base64')`.** - * @since v15.13.0 - * @deprecated Use `Buffer.from(data, 'base64')` instead. + * @since v15.13.0, v14.17.0 + * @legacy Use `Buffer.from(data, 'base64')` instead. * @param data The Base64-encoded input string. */ function atob(data: string): string; @@ -2220,13 +2339,24 @@ declare module 'buffer' { * **binary data and predate the introduction of typed arrays in JavaScript.** * **For code running using Node.js APIs, converting between base64-encoded strings** * **and binary data should be performed using `Buffer.from(str, 'base64')` and`buf.toString('base64')`.** - * @since v15.13.0 - * @deprecated Use `buf.toString('base64')` instead. + * @since v15.13.0, v14.17.0 + * @legacy Use `buf.toString('base64')` instead. * @param data An ASCII (Latin1) string. */ function btoa(data: string): string; + interface Blob extends __Blob {} + /** + * `Blob` class is a global reference for `require('node:buffer').Blob` + * https://nodejs.org/api/buffer.html#class-blob + * @since v18.0.0 + */ + var Blob: typeof globalThis extends { + onmessage: any; + Blob: infer T; + } ? T + : typeof NodeBlob; } } -declare module 'node:buffer' { - export * from 'buffer'; +declare module "node:buffer" { + export * from "buffer"; } diff --git a/node_modules/@types/node/ts4.8/child_process.d.ts b/node_modules/@types/node/ts4.8/child_process.d.ts old mode 100755 new mode 100644 index d383145..a97532b --- a/node_modules/@types/node/ts4.8/child_process.d.ts +++ b/node_modules/@types/node/ts4.8/child_process.d.ts @@ -1,10 +1,10 @@ /** - * The `child_process` module provides the ability to spawn subprocesses in + * The `node:child_process` module provides the ability to spawn subprocesses in * a manner that is similar, but not identical, to [`popen(3)`](http://man7.org/linux/man-pages/man3/popen.3.html). This capability * is primarily provided by the {@link spawn} function: * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const ls = spawn('ls', ['-lh', '/usr']); * * ls.stdout.on('data', (data) => { @@ -28,8 +28,11 @@ * identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }`option if the output will not be consumed. * * The command lookup is performed using the `options.env.PATH` environment - * variable if it is in the `options` object. Otherwise, `process.env.PATH` is - * used. + * variable if `env` is in the `options` object. Otherwise, `process.env.PATH` is + * used. If `options.env` is set without `PATH`, lookup on Unix is performed + * on a default search path search of `/usr/bin:/bin` (see your operating system's + * manual for execvpe/execvp), on Windows the current processes environment + * variable `PATH` is used. * * On Windows, environment variables are case-insensitive. Node.js * lexicographically sorts the `env` keys and uses the first one that @@ -41,8 +44,8 @@ * without blocking the Node.js event loop. The {@link spawnSync} function provides equivalent functionality in a synchronous manner that blocks * the event loop until the spawned process either exits or is terminated. * - * For convenience, the `child_process` module provides a handful of synchronous - * and asynchronous alternatives to {@link spawn} and {@link spawnSync}. Each of these alternatives are implemented on + * For convenience, the `node:child_process` module provides a handful of + * synchronous and asynchronous alternatives to {@link spawn} and {@link spawnSync}. Each of these alternatives are implemented on * top of {@link spawn} or {@link spawnSync}. * * * {@link exec}: spawns a shell and runs a command within that @@ -60,14 +63,14 @@ * For certain use cases, such as automating shell scripts, the `synchronous counterparts` may be more convenient. In many cases, however, * the synchronous methods can have significant impact on performance due to * stalling the event loop while spawned processes complete. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/child_process.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/child_process.js) */ -declare module 'child_process' { - import { ObjectEncodingOptions } from 'node:fs'; - import { EventEmitter, Abortable } from 'node:events'; - import * as net from 'node:net'; - import { Writable, Readable, Stream, Pipe } from 'node:stream'; - import { URL } from 'node:url'; +declare module "child_process" { + import { ObjectEncodingOptions } from "node:fs"; + import { Abortable, EventEmitter } from "node:events"; + import * as net from "node:net"; + import { Pipe, Readable, Stream, Writable } from "node:stream"; + import { URL } from "node:url"; type Serializable = string | object | number | boolean | bigint; type SendHandle = net.Socket | net.Server; /** @@ -91,8 +94,7 @@ declare module 'child_process' { * `subprocess.stdin` is an alias for `subprocess.stdio[0]`. Both properties will * refer to the same value. * - * The `subprocess.stdin` property can be `undefined` if the child process could - * not be successfully spawned. + * The `subprocess.stdin` property can be `null` or `undefined`if the child process could not be successfully spawned. * @since v0.1.90 */ stdin: Writable | null; @@ -106,7 +108,7 @@ declare module 'child_process' { * refer to the same value. * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * * const subprocess = spawn('ls'); * @@ -115,8 +117,7 @@ declare module 'child_process' { * }); * ``` * - * The `subprocess.stdout` property can be `null` if the child process could - * not be successfully spawned. + * The `subprocess.stdout` property can be `null` or `undefined`if the child process could not be successfully spawned. * @since v0.1.90 */ stdout: Readable | null; @@ -129,14 +130,13 @@ declare module 'child_process' { * `subprocess.stderr` is an alias for `subprocess.stdio[2]`. Both properties will * refer to the same value. * - * The `subprocess.stderr` property can be `null` if the child process could - * not be successfully spawned. + * The `subprocess.stderr` property can be `null` or `undefined`if the child process could not be successfully spawned. * @since v0.1.90 */ stderr: Readable | null; /** * The `subprocess.channel` property is a reference to the child's IPC channel. If - * no IPC channel currently exists, this property is `undefined`. + * no IPC channel exists, this property is `undefined`. * @since v7.1.0 */ readonly channel?: Pipe | null | undefined; @@ -151,16 +151,16 @@ declare module 'child_process' { * in the array are `null`. * * ```js - * const assert = require('assert'); - * const fs = require('fs'); - * const child_process = require('child_process'); + * const assert = require('node:assert'); + * const fs = require('node:fs'); + * const child_process = require('node:child_process'); * * const subprocess = child_process.spawn('ls', { * stdio: [ * 0, // Use parent's stdin for child. * 'pipe', // Pipe child's stdout to parent. * fs.openSync('err.out', 'w'), // Direct child's stderr to a file. - * ] + * ], * }); * * assert.strictEqual(subprocess.stdio[0], null); @@ -186,7 +186,7 @@ declare module 'child_process' { // stderr Readable | Writable | null | undefined, // extra - Readable | Writable | null | undefined // extra + Readable | Writable | null | undefined, // extra ]; /** * The `subprocess.killed` property indicates whether the child process @@ -201,7 +201,7 @@ declare module 'child_process' { * emitted. * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const grep = spawn('grep', ['ssh']); * * console.log(`Spawned child pid: ${grep.pid}`); @@ -248,7 +248,7 @@ declare module 'child_process' { * returns `true` if [`kill(2)`](http://man7.org/linux/man-pages/man2/kill.2.html) succeeds, and `false` otherwise. * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const grep = spawn('grep', ['ssh']); * * grep.on('close', (code, signal) => { @@ -281,7 +281,7 @@ declare module 'child_process' { * * ```js * 'use strict'; - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * * const subprocess = spawn( * 'sh', @@ -291,8 +291,8 @@ declare module 'child_process' { * console.log(process.pid, 'is alive') * }, 500);"`, * ], { - * stdio: ['inherit', 'inherit', 'inherit'] - * } + * stdio: ['inherit', 'inherit', 'inherit'], + * }, * ); * * setTimeout(() => { @@ -302,6 +302,11 @@ declare module 'child_process' { * @since v0.1.90 */ kill(signal?: NodeJS.Signals | number): boolean; + /** + * Calls {@link ChildProcess.kill} with `'SIGTERM'`. + * @since v20.5.0 + */ + [Symbol.dispose](): void; /** * When an IPC channel has been established between the parent and child ( * i.e. when using {@link fork}), the `subprocess.send()` method can @@ -314,7 +319,7 @@ declare module 'child_process' { * For example, in the parent script: * * ```js - * const cp = require('child_process'); + * const cp = require('node:child_process'); * const n = cp.fork(`${__dirname}/sub.js`); * * n.on('message', (m) => { @@ -368,10 +373,10 @@ declare module 'child_process' { * a TCP server object to the child process as illustrated in the example below: * * ```js - * const subprocess = require('child_process').fork('subprocess.js'); + * const subprocess = require('node:child_process').fork('subprocess.js'); * * // Open up the server object and send the handle. - * const server = require('net').createServer(); + * const server = require('node:net').createServer(); * server.on('connection', (socket) => { * socket.end('handled by parent'); * }); @@ -395,10 +400,9 @@ declare module 'child_process' { * Once the server is now shared between the parent and child, some connections * can be handled by the parent and some by the child. * - * While the example above uses a server created using the `net` module, `dgram`module servers use exactly the same workflow with the exceptions of listening on - * a `'message'` event instead of `'connection'` and using `server.bind()` instead - * of `server.listen()`. This is, however, currently only supported on Unix - * platforms. + * While the example above uses a server created using the `node:net` module,`node:dgram` module servers use exactly the same workflow with the exceptions of + * listening on a `'message'` event instead of `'connection'` and using`server.bind()` instead of `server.listen()`. This is, however, only + * supported on Unix platforms. * * #### Example: sending a socket object * @@ -407,13 +411,13 @@ declare module 'child_process' { * handle connections with "normal" or "special" priority: * * ```js - * const { fork } = require('child_process'); + * const { fork } = require('node:child_process'); * const normal = fork('subprocess.js', ['normal']); * const special = fork('subprocess.js', ['special']); * * // Open up the server and send sockets to child. Use pauseOnConnect to prevent * // the sockets from being read before they are sent to the child process. - * const server = require('net').createServer({ pauseOnConnect: true }); + * const server = require('node:net').createServer({ pauseOnConnect: true }); * server.on('connection', (socket) => { * * // If this is special priority... @@ -454,7 +458,12 @@ declare module 'child_process' { */ send(message: Serializable, callback?: (error: Error | null) => void): boolean; send(message: Serializable, sendHandle?: SendHandle, callback?: (error: Error | null) => void): boolean; - send(message: Serializable, sendHandle?: SendHandle, options?: MessageOptions, callback?: (error: Error | null) => void): boolean; + send( + message: Serializable, + sendHandle?: SendHandle, + options?: MessageOptions, + callback?: (error: Error | null) => void, + ): boolean; /** * Closes the IPC channel between parent and child, allowing the child to exit * gracefully once there are no other connections keeping it alive. After calling @@ -479,11 +488,11 @@ declare module 'child_process' { * the child and the parent. * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * * const subprocess = spawn(process.argv[0], ['child_program.js'], { * detached: true, - * stdio: 'ignore' + * stdio: 'ignore', * }); * * subprocess.unref(); @@ -497,11 +506,11 @@ declare module 'child_process' { * to wait for the child to exit before exiting itself. * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * * const subprocess = spawn(process.argv[0], ['child_program.js'], { * detached: true, - * stdio: 'ignore' + * stdio: 'ignore', * }); * * subprocess.unref(); @@ -520,47 +529,53 @@ declare module 'child_process' { * 6. spawn */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - addListener(event: 'disconnect', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - addListener(event: 'message', listener: (message: Serializable, sendHandle: SendHandle) => void): this; - addListener(event: 'spawn', listener: () => void): this; + addListener(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + addListener(event: "disconnect", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + addListener(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this; + addListener(event: "spawn", listener: () => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close', code: number | null, signal: NodeJS.Signals | null): boolean; - emit(event: 'disconnect'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'exit', code: number | null, signal: NodeJS.Signals | null): boolean; - emit(event: 'message', message: Serializable, sendHandle: SendHandle): boolean; - emit(event: 'spawn', listener: () => void): boolean; + emit(event: "close", code: number | null, signal: NodeJS.Signals | null): boolean; + emit(event: "disconnect"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "exit", code: number | null, signal: NodeJS.Signals | null): boolean; + emit(event: "message", message: Serializable, sendHandle: SendHandle): boolean; + emit(event: "spawn", listener: () => void): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - on(event: 'disconnect', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - on(event: 'message', listener: (message: Serializable, sendHandle: SendHandle) => void): this; - on(event: 'spawn', listener: () => void): this; + on(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + on(event: "disconnect", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + on(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this; + on(event: "spawn", listener: () => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - once(event: 'disconnect', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - once(event: 'message', listener: (message: Serializable, sendHandle: SendHandle) => void): this; - once(event: 'spawn', listener: () => void): this; + once(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + once(event: "disconnect", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + once(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this; + once(event: "spawn", listener: () => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - prependListener(event: 'disconnect', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - prependListener(event: 'message', listener: (message: Serializable, sendHandle: SendHandle) => void): this; - prependListener(event: 'spawn', listener: () => void): this; + prependListener(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + prependListener(event: "disconnect", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; + prependListener(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this; + prependListener(event: "spawn", listener: () => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - prependOnceListener(event: 'disconnect', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this; - prependOnceListener(event: 'message', listener: (message: Serializable, sendHandle: SendHandle) => void): this; - prependOnceListener(event: 'spawn', listener: () => void): this; + prependOnceListener( + event: "close", + listener: (code: number | null, signal: NodeJS.Signals | null) => void, + ): this; + prependOnceListener(event: "disconnect", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener( + event: "exit", + listener: (code: number | null, signal: NodeJS.Signals | null) => void, + ): this; + prependOnceListener(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this; + prependOnceListener(event: "spawn", listener: () => void): this; } // return this object when stdio option is undefined or not specified interface ChildProcessWithoutNullStreams extends ChildProcess { @@ -574,11 +589,13 @@ declare module 'child_process' { // stderr Readable | Writable | null | undefined, // extra, no modification - Readable | Writable | null | undefined // extra, no modification + Readable | Writable | null | undefined, // extra, no modification ]; } // return this object when stdio option is a tuple of 3 - interface ChildProcessByStdio extends ChildProcess { + interface ChildProcessByStdio + extends ChildProcess + { stdin: I; stdout: O; stderr: E; @@ -588,15 +605,15 @@ declare module 'child_process' { E, Readable | Writable | null | undefined, // extra, no modification - Readable | Writable | null | undefined // extra, no modification + Readable | Writable | null | undefined, // extra, no modification ]; } interface MessageOptions { keepOpen?: boolean | undefined; } - type IOType = 'overlapped' | 'pipe' | 'ignore' | 'inherit'; - type StdioOptions = IOType | Array; - type SerializationType = 'json' | 'advanced'; + type IOType = "overlapped" | "pipe" | "ignore" | "inherit"; + type StdioOptions = IOType | Array; + type SerializationType = "json" | "advanced"; interface MessagingOptions extends Abortable { /** * Specify the kind of serialization used for sending messages between processes. @@ -621,7 +638,7 @@ declare module 'child_process' { } interface CommonOptions extends ProcessEnvOptions { /** - * @default true + * @default false */ windowsHide?: boolean | undefined; /** @@ -631,6 +648,15 @@ declare module 'child_process' { } interface CommonSpawnOptions extends CommonOptions, MessagingOptions, Abortable { argv0?: string | undefined; + /** + * Can be set to 'pipe', 'inherit', 'overlapped', or 'ignore', or an array of these strings. + * If passed as an array, the first element is used for `stdin`, the second for + * `stdout`, and the third for `stderr`. A fourth element can be used to + * specify the `stdio` behavior beyond the standard streams. See + * {@link ChildProcess.stdio} for more information. + * + * @default 'pipe' + */ stdio?: StdioOptions | undefined; shell?: boolean | string | undefined; windowsVerbatimArguments?: boolean | undefined; @@ -641,10 +667,14 @@ declare module 'child_process' { interface SpawnOptionsWithoutStdio extends SpawnOptions { stdio?: StdioPipeNamed | StdioPipe[] | undefined; } - type StdioNull = 'inherit' | 'ignore' | Stream; - type StdioPipeNamed = 'pipe' | 'overlapped'; + type StdioNull = "inherit" | "ignore" | Stream; + type StdioPipeNamed = "pipe" | "overlapped"; type StdioPipe = undefined | null | StdioPipeNamed; - interface SpawnOptionsWithStdioTuple extends SpawnOptions { + interface SpawnOptionsWithStdioTuple< + Stdin extends StdioNull | StdioPipe, + Stdout extends StdioNull | StdioPipe, + Stderr extends StdioNull | StdioPipe, + > extends SpawnOptions { stdio: [Stdin, Stdout, Stderr]; } /** @@ -660,7 +690,7 @@ declare module 'child_process' { * ```js * const defaults = { * cwd: undefined, - * env: process.env + * env: process.env, * }; * ``` * @@ -679,7 +709,7 @@ declare module 'child_process' { * exit code: * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const ls = spawn('ls', ['-lh', '/usr']); * * ls.stdout.on('data', (data) => { @@ -698,7 +728,7 @@ declare module 'child_process' { * Example: A very elaborate way to run `ps ax | grep ssh` * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const ps = spawn('ps', ['ax']); * const grep = spawn('grep', ['ssh']); * @@ -735,7 +765,7 @@ declare module 'child_process' { * Example of checking for failed `spawn`: * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const subprocess = spawn('bad_command'); * * subprocess.on('error', (err) => { @@ -746,14 +776,14 @@ declare module 'child_process' { * Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process * title while others (Windows, SunOS) will use `command`. * - * Node.js currently overwrites `argv[0]` with `process.execPath` on startup, so`process.argv[0]` in a Node.js child process will not match the `argv0`parameter passed to `spawn` from the parent, - * retrieve it with the`process.argv0` property instead. + * Node.js overwrites `argv[0]` with `process.execPath` on startup, so`process.argv[0]` in a Node.js child process will not match the `argv0`parameter passed to `spawn` from the parent. Retrieve + * it with the`process.argv0` property instead. * * If the `signal` option is enabled, calling `.abort()` on the corresponding`AbortController` is similar to calling `.kill()` on the child process except * the error passed to the callback will be an `AbortError`: * * ```js - * const { spawn } = require('child_process'); + * const { spawn } = require('node:child_process'); * const controller = new AbortController(); * const { signal } = controller; * const grep = spawn('grep', ['ssh'], { signal }); @@ -767,26 +797,86 @@ declare module 'child_process' { * @param args List of string arguments. */ function spawn(command: string, options?: SpawnOptionsWithoutStdio): ChildProcessWithoutNullStreams; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; function spawn(command: string, options: SpawnOptions): ChildProcess; // overloads of spawn with 'args' - function spawn(command: string, args?: ReadonlyArray, options?: SpawnOptionsWithoutStdio): ChildProcessWithoutNullStreams; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptionsWithStdioTuple): ChildProcessByStdio; - function spawn(command: string, args: ReadonlyArray, options: SpawnOptions): ChildProcess; + function spawn( + command: string, + args?: readonly string[], + options?: SpawnOptionsWithoutStdio, + ): ChildProcessWithoutNullStreams; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn( + command: string, + args: readonly string[], + options: SpawnOptionsWithStdioTuple, + ): ChildProcessByStdio; + function spawn(command: string, args: readonly string[], options: SpawnOptions): ChildProcess; interface ExecOptions extends CommonOptions { shell?: string | undefined; signal?: AbortSignal | undefined; @@ -812,7 +902,7 @@ declare module 'child_process' { * need to be dealt with accordingly: * * ```js - * const { exec } = require('child_process'); + * const { exec } = require('node:child_process'); * * exec('"/path/to/test file/test.sh" arg1 arg2'); * // Double quotes are used so that the space in the path is not interpreted as @@ -838,7 +928,7 @@ declare module 'child_process' { * encoding, `Buffer` objects will be passed to the callback instead. * * ```js - * const { exec } = require('child_process'); + * const { exec } = require('node:child_process'); * exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => { * if (error) { * console.error(`exec error: ${error}`); @@ -863,8 +953,8 @@ declare module 'child_process' { * callback, but with two additional properties `stdout` and `stderr`. * * ```js - * const util = require('util'); - * const exec = util.promisify(require('child_process').exec); + * const util = require('node:util'); + * const exec = util.promisify(require('node:child_process').exec); * * async function lsExample() { * const { stdout, stderr } = await exec('ls'); @@ -878,11 +968,11 @@ declare module 'child_process' { * the error passed to the callback will be an `AbortError`: * * ```js - * const { exec } = require('child_process'); + * const { exec } = require('node:child_process'); * const controller = new AbortController(); * const { signal } = controller; * const child = exec('grep ssh', { signal }, (error) => { - * console.log(error); // an AbortError + * console.error(error); // an AbortError * }); * controller.abort(); * ``` @@ -890,14 +980,17 @@ declare module 'child_process' { * @param command The command to run, with space-separated arguments. * @param callback called with the output when process terminates. */ - function exec(command: string, callback?: (error: ExecException | null, stdout: string, stderr: string) => void): ChildProcess; + function exec( + command: string, + callback?: (error: ExecException | null, stdout: string, stderr: string) => void, + ): ChildProcess; // `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`. function exec( command: string, options: { - encoding: 'buffer' | null; + encoding: "buffer" | null; } & ExecOptions, - callback?: (error: ExecException | null, stdout: Buffer, stderr: Buffer) => void + callback?: (error: ExecException | null, stdout: Buffer, stderr: Buffer) => void, ): ChildProcess; // `options` with well known `encoding` means stdout/stderr are definitely `string`. function exec( @@ -905,7 +998,7 @@ declare module 'child_process' { options: { encoding: BufferEncoding; } & ExecOptions, - callback?: (error: ExecException | null, stdout: string, stderr: string) => void + callback?: (error: ExecException | null, stdout: string, stderr: string) => void, ): ChildProcess; // `options` with an `encoding` whose type is `string` means stdout/stderr could either be `Buffer` or `string`. // There is no guarantee the `encoding` is unknown as `string` is a superset of `BufferEncoding`. @@ -914,15 +1007,19 @@ declare module 'child_process' { options: { encoding: BufferEncoding; } & ExecOptions, - callback?: (error: ExecException | null, stdout: string | Buffer, stderr: string | Buffer) => void + callback?: (error: ExecException | null, stdout: string | Buffer, stderr: string | Buffer) => void, ): ChildProcess; // `options` without an `encoding` means stdout/stderr are definitely `string`. - function exec(command: string, options: ExecOptions, callback?: (error: ExecException | null, stdout: string, stderr: string) => void): ChildProcess; + function exec( + command: string, + options: ExecOptions, + callback?: (error: ExecException | null, stdout: string, stderr: string) => void, + ): ChildProcess; // fallback if nothing else matches. Worst case is always `string | Buffer`. function exec( command: string, options: (ObjectEncodingOptions & ExecOptions) | undefined | null, - callback?: (error: ExecException | null, stdout: string | Buffer, stderr: string | Buffer) => void + callback?: (error: ExecException | null, stdout: string | Buffer, stderr: string | Buffer) => void, ): ChildProcess; interface PromiseWithChild extends Promise { child: ChildProcess; @@ -935,8 +1032,8 @@ declare module 'child_process' { function __promisify__( command: string, options: { - encoding: 'buffer' | null; - } & ExecOptions + encoding: "buffer" | null; + } & ExecOptions, ): PromiseWithChild<{ stdout: Buffer; stderr: Buffer; @@ -945,21 +1042,21 @@ declare module 'child_process' { command: string, options: { encoding: BufferEncoding; - } & ExecOptions + } & ExecOptions, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( command: string, - options: ExecOptions + options: ExecOptions, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( command: string, - options?: (ObjectEncodingOptions & ExecOptions) | null + options?: (ObjectEncodingOptions & ExecOptions) | null, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; @@ -976,12 +1073,15 @@ declare module 'child_process' { encoding: BufferEncoding; } interface ExecFileOptionsWithBufferEncoding extends ExecFileOptions { - encoding: 'buffer' | null; + encoding: "buffer" | null; } interface ExecFileOptionsWithOtherEncoding extends ExecFileOptions { encoding: BufferEncoding; } - type ExecFileException = ExecException & NodeJS.ErrnoException; + type ExecFileException = + & Omit + & Omit + & { code?: string | number | undefined | null }; /** * The `child_process.execFile()` function is similar to {@link exec} except that it does not spawn a shell by default. Rather, the specified * executable `file` is spawned directly as a new process making it slightly more @@ -992,7 +1092,7 @@ declare module 'child_process' { * supported. * * ```js - * const { execFile } = require('child_process'); + * const { execFile } = require('node:child_process'); * const child = execFile('node', ['--version'], (error, stdout, stderr) => { * if (error) { * throw error; @@ -1015,8 +1115,8 @@ declare module 'child_process' { * callback, but with two additional properties `stdout` and `stderr`. * * ```js - * const util = require('util'); - * const execFile = util.promisify(require('child_process').execFile); + * const util = require('node:util'); + * const execFile = util.promisify(require('node:child_process').execFile); * async function getVersion() { * const { stdout } = await execFile('node', ['--version']); * console.log(stdout); @@ -1032,11 +1132,11 @@ declare module 'child_process' { * the error passed to the callback will be an `AbortError`: * * ```js - * const { execFile } = require('child_process'); + * const { execFile } = require('node:child_process'); * const controller = new AbortController(); * const { signal } = controller; * const child = execFile('node', ['--version'], { signal }, (error) => { - * console.log(error); // an AbortError + * console.error(error); // an AbortError * }); * controller.abort(); * ``` @@ -1046,56 +1146,92 @@ declare module 'child_process' { * @param callback Called with the output when process terminates. */ function execFile(file: string): ChildProcess; - function execFile(file: string, options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null): ChildProcess; - function execFile(file: string, args?: ReadonlyArray | null): ChildProcess; - function execFile(file: string, args: ReadonlyArray | undefined | null, options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null): ChildProcess; - // no `options` definitely means stdout/stderr are `string`. - function execFile(file: string, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void): ChildProcess; - function execFile(file: string, args: ReadonlyArray | undefined | null, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void): ChildProcess; - // `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`. - function execFile(file: string, options: ExecFileOptionsWithBufferEncoding, callback: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void): ChildProcess; function execFile( file: string, - args: ReadonlyArray | undefined | null, + options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, + ): ChildProcess; + function execFile(file: string, args?: readonly string[] | null): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, + ): ChildProcess; + // no `options` definitely means stdout/stderr are `string`. + function execFile( + file: string, + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + ): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + ): ChildProcess; + // `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`. + function execFile( + file: string, options: ExecFileOptionsWithBufferEncoding, - callback: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void + callback: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void, + ): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithBufferEncoding, + callback: (error: ExecFileException | null, stdout: Buffer, stderr: Buffer) => void, ): ChildProcess; // `options` with well known `encoding` means stdout/stderr are definitely `string`. - function execFile(file: string, options: ExecFileOptionsWithStringEncoding, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void): ChildProcess; function execFile( file: string, - args: ReadonlyArray | undefined | null, options: ExecFileOptionsWithStringEncoding, - callback: (error: ExecFileException | null, stdout: string, stderr: string) => void + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + ): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithStringEncoding, + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, ): ChildProcess; // `options` with an `encoding` whose type is `string` means stdout/stderr could either be `Buffer` or `string`. // There is no guarantee the `encoding` is unknown as `string` is a superset of `BufferEncoding`. - function execFile(file: string, options: ExecFileOptionsWithOtherEncoding, callback: (error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void): ChildProcess; function execFile( file: string, - args: ReadonlyArray | undefined | null, options: ExecFileOptionsWithOtherEncoding, - callback: (error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void + callback: (error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void, + ): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithOtherEncoding, + callback: (error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void, ): ChildProcess; // `options` without an `encoding` means stdout/stderr are definitely `string`. - function execFile(file: string, options: ExecFileOptions, callback: (error: ExecFileException | null, stdout: string, stderr: string) => void): ChildProcess; function execFile( file: string, - args: ReadonlyArray | undefined | null, options: ExecFileOptions, - callback: (error: ExecFileException | null, stdout: string, stderr: string) => void + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, + ): ChildProcess; + function execFile( + file: string, + args: readonly string[] | undefined | null, + options: ExecFileOptions, + callback: (error: ExecFileException | null, stdout: string, stderr: string) => void, ): ChildProcess; // fallback if nothing else matches. Worst case is always `string | Buffer`. function execFile( file: string, options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, - callback: ((error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void) | undefined | null + callback: + | ((error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void) + | undefined + | null, ): ChildProcess; function execFile( file: string, - args: ReadonlyArray | undefined | null, + args: readonly string[] | undefined | null, options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, - callback: ((error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void) | undefined | null + callback: + | ((error: ExecFileException | null, stdout: string | Buffer, stderr: string | Buffer) => void) + | undefined + | null, ): ChildProcess; namespace execFile { function __promisify__(file: string): PromiseWithChild<{ @@ -1104,82 +1240,82 @@ declare module 'child_process' { }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null + args: readonly string[] | undefined | null, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( file: string, - options: ExecFileOptionsWithBufferEncoding + options: ExecFileOptionsWithBufferEncoding, ): PromiseWithChild<{ stdout: Buffer; stderr: Buffer; }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null, - options: ExecFileOptionsWithBufferEncoding + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithBufferEncoding, ): PromiseWithChild<{ stdout: Buffer; stderr: Buffer; }>; function __promisify__( file: string, - options: ExecFileOptionsWithStringEncoding + options: ExecFileOptionsWithStringEncoding, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null, - options: ExecFileOptionsWithStringEncoding + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithStringEncoding, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( file: string, - options: ExecFileOptionsWithOtherEncoding + options: ExecFileOptionsWithOtherEncoding, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null, - options: ExecFileOptionsWithOtherEncoding + args: readonly string[] | undefined | null, + options: ExecFileOptionsWithOtherEncoding, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; }>; function __promisify__( file: string, - options: ExecFileOptions + options: ExecFileOptions, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null, - options: ExecFileOptions + args: readonly string[] | undefined | null, + options: ExecFileOptions, ): PromiseWithChild<{ stdout: string; stderr: string; }>; function __promisify__( file: string, - options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null + options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; }>; function __promisify__( file: string, - args: ReadonlyArray | undefined | null, - options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null + args: readonly string[] | undefined | null, + options: (ObjectEncodingOptions & ExecFileOptions) | undefined | null, ): PromiseWithChild<{ stdout: string | Buffer; stderr: string | Buffer; @@ -1189,6 +1325,15 @@ declare module 'child_process' { execPath?: string | undefined; execArgv?: string[] | undefined; silent?: boolean | undefined; + /** + * Can be set to 'pipe', 'inherit', 'overlapped', or 'ignore', or an array of these strings. + * If passed as an array, the first element is used for `stdin`, the second for + * `stdout`, and the third for `stderr`. A fourth element can be used to + * specify the `stdio` behavior beyond the standard streams. See + * {@link ChildProcess.stdio} for more information. + * + * @default 'pipe' + */ stdio?: StdioOptions | undefined; detached?: boolean | undefined; windowsVerbatimArguments?: boolean | undefined; @@ -1228,7 +1373,7 @@ declare module 'child_process' { * console.log(`Hello from ${process.argv[2]}!`); * }, 1_000); * } else { - * const { fork } = require('child_process'); + * const { fork } = require('node:child_process'); * const controller = new AbortController(); * const { signal } = controller; * const child = fork(__filename, ['child'], { signal }); @@ -1243,17 +1388,17 @@ declare module 'child_process' { * @param args List of string arguments. */ function fork(modulePath: string, options?: ForkOptions): ChildProcess; - function fork(modulePath: string, args?: ReadonlyArray, options?: ForkOptions): ChildProcess; + function fork(modulePath: string, args?: readonly string[], options?: ForkOptions): ChildProcess; interface SpawnSyncOptions extends CommonSpawnOptions { input?: string | NodeJS.ArrayBufferView | undefined; maxBuffer?: number | undefined; - encoding?: BufferEncoding | 'buffer' | null | undefined; + encoding?: BufferEncoding | "buffer" | null | undefined; } interface SpawnSyncOptionsWithStringEncoding extends SpawnSyncOptions { encoding: BufferEncoding; } interface SpawnSyncOptionsWithBufferEncoding extends SpawnSyncOptions { - encoding?: 'buffer' | null | undefined; + encoding?: "buffer" | null | undefined; } interface SpawnSyncReturns { pid: number; @@ -1283,16 +1428,37 @@ declare module 'child_process' { function spawnSync(command: string, options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns; function spawnSync(command: string, options: SpawnSyncOptionsWithBufferEncoding): SpawnSyncReturns; function spawnSync(command: string, options?: SpawnSyncOptions): SpawnSyncReturns; - function spawnSync(command: string, args: ReadonlyArray): SpawnSyncReturns; - function spawnSync(command: string, args: ReadonlyArray, options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns; - function spawnSync(command: string, args: ReadonlyArray, options: SpawnSyncOptionsWithBufferEncoding): SpawnSyncReturns; - function spawnSync(command: string, args?: ReadonlyArray, options?: SpawnSyncOptions): SpawnSyncReturns; + function spawnSync(command: string, args: readonly string[]): SpawnSyncReturns; + function spawnSync( + command: string, + args: readonly string[], + options: SpawnSyncOptionsWithStringEncoding, + ): SpawnSyncReturns; + function spawnSync( + command: string, + args: readonly string[], + options: SpawnSyncOptionsWithBufferEncoding, + ): SpawnSyncReturns; + function spawnSync( + command: string, + args?: readonly string[], + options?: SpawnSyncOptions, + ): SpawnSyncReturns; interface CommonExecOptions extends CommonOptions { input?: string | NodeJS.ArrayBufferView | undefined; + /** + * Can be set to 'pipe', 'inherit, or 'ignore', or an array of these strings. + * If passed as an array, the first element is used for `stdin`, the second for + * `stdout`, and the third for `stderr`. A fourth element can be used to + * specify the `stdio` behavior beyond the standard streams. See + * {@link ChildProcess.stdio} for more information. + * + * @default 'pipe' + */ stdio?: StdioOptions | undefined; killSignal?: NodeJS.Signals | number | undefined; maxBuffer?: number | undefined; - encoding?: BufferEncoding | 'buffer' | null | undefined; + encoding?: BufferEncoding | "buffer" | null | undefined; } interface ExecSyncOptions extends CommonExecOptions { shell?: string | undefined; @@ -1301,7 +1467,7 @@ declare module 'child_process' { encoding: BufferEncoding; } interface ExecSyncOptionsWithBufferEncoding extends ExecSyncOptions { - encoding?: 'buffer' | null | undefined; + encoding?: "buffer" | null | undefined; } /** * The `child_process.execSync()` method is generally identical to {@link exec} with the exception that the method will not return @@ -1330,7 +1496,7 @@ declare module 'child_process' { encoding: BufferEncoding; } interface ExecFileSyncOptionsWithBufferEncoding extends ExecFileSyncOptions { - encoding?: 'buffer' | null; // specify `null`. + encoding?: "buffer" | null; // specify `null`. } /** * The `child_process.execFileSync()` method is generally identical to {@link execFile} with the exception that the method will not @@ -1356,11 +1522,19 @@ declare module 'child_process' { function execFileSync(file: string, options: ExecFileSyncOptionsWithStringEncoding): string; function execFileSync(file: string, options: ExecFileSyncOptionsWithBufferEncoding): Buffer; function execFileSync(file: string, options?: ExecFileSyncOptions): string | Buffer; - function execFileSync(file: string, args: ReadonlyArray): Buffer; - function execFileSync(file: string, args: ReadonlyArray, options: ExecFileSyncOptionsWithStringEncoding): string; - function execFileSync(file: string, args: ReadonlyArray, options: ExecFileSyncOptionsWithBufferEncoding): Buffer; - function execFileSync(file: string, args?: ReadonlyArray, options?: ExecFileSyncOptions): string | Buffer; + function execFileSync(file: string, args: readonly string[]): Buffer; + function execFileSync( + file: string, + args: readonly string[], + options: ExecFileSyncOptionsWithStringEncoding, + ): string; + function execFileSync( + file: string, + args: readonly string[], + options: ExecFileSyncOptionsWithBufferEncoding, + ): Buffer; + function execFileSync(file: string, args?: readonly string[], options?: ExecFileSyncOptions): string | Buffer; } -declare module 'node:child_process' { - export * from 'child_process'; +declare module "node:child_process" { + export * from "child_process"; } diff --git a/node_modules/@types/node/ts4.8/cluster.d.ts b/node_modules/@types/node/ts4.8/cluster.d.ts old mode 100755 new mode 100644 index 7f16141..39cd56a --- a/node_modules/@types/node/ts4.8/cluster.d.ts +++ b/node_modules/@types/node/ts4.8/cluster.d.ts @@ -1,18 +1,19 @@ /** - * A single instance of Node.js runs in a single thread. To take advantage of - * multi-core systems, the user will sometimes want to launch a cluster of Node.js - * processes to handle the load. + * Clusters of Node.js processes can be used to run multiple instances of Node.js + * that can distribute workloads among their application threads. When process + * isolation is not needed, use the `worker_threads` module instead, which + * allows running multiple application threads within a single Node.js instance. * * The cluster module allows easy creation of child processes that all share * server ports. * * ```js - * import cluster from 'cluster'; - * import http from 'http'; - * import { cpus } from 'os'; - * import process from 'process'; + * import cluster from 'node:cluster'; + * import http from 'node:http'; + * import { availableParallelism } from 'node:os'; + * import process from 'node:process'; * - * const numCPUs = cpus().length; + * const numCPUs = availableParallelism(); * * if (cluster.isPrimary) { * console.log(`Primary ${process.pid} is running`); @@ -49,12 +50,13 @@ * ``` * * On Windows, it is not yet possible to set up a named pipe server in a worker. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/cluster.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/cluster.js) */ -declare module 'cluster' { - import * as child from 'node:child_process'; - import EventEmitter = require('node:events'); - import * as net from 'node:net'; +declare module "cluster" { + import * as child from "node:child_process"; + import EventEmitter = require("node:events"); + import * as net from "node:net"; + type SerializationType = "json" | "advanced"; export interface ClusterSettings { execArgv?: string[] | undefined; // default: process.execArgv exec?: string | undefined; @@ -64,11 +66,14 @@ declare module 'cluster' { uid?: number | undefined; gid?: number | undefined; inspectPort?: number | (() => number) | undefined; + serialization?: SerializationType | undefined; + cwd?: string | undefined; + windowsHide?: boolean | undefined; } export interface Address { address: string; port: number; - addressType: number | 'udp4' | 'udp6'; // 4, 6, -1, "udp4", "udp6" + addressType: number | "udp4" | "udp6"; // 4, 6, -1, "udp4", "udp6" } /** * A `Worker` object contains all public information and method about a worker. @@ -99,9 +104,9 @@ declare module 'cluster' { /** * Send a message to a worker or primary, optionally with a handle. * - * In the primary this sends a message to a specific worker. It is identical to `ChildProcess.send()`. + * In the primary, this sends a message to a specific worker. It is identical to `ChildProcess.send()`. * - * In a worker this sends a message to the primary. It is identical to`process.send()`. + * In a worker, this sends a message to the primary. It is identical to`process.send()`. * * This example will echo back all messages from the primary: * @@ -120,22 +125,25 @@ declare module 'cluster' { * @param options The `options` argument, if present, is an object used to parameterize the sending of certain types of handles. `options` supports the following properties: */ send(message: child.Serializable, callback?: (error: Error | null) => void): boolean; - send(message: child.Serializable, sendHandle: child.SendHandle, callback?: (error: Error | null) => void): boolean; - send(message: child.Serializable, sendHandle: child.SendHandle, options?: child.MessageOptions, callback?: (error: Error | null) => void): boolean; + send( + message: child.Serializable, + sendHandle: child.SendHandle, + callback?: (error: Error | null) => void, + ): boolean; + send( + message: child.Serializable, + sendHandle: child.SendHandle, + options?: child.MessageOptions, + callback?: (error: Error | null) => void, + ): boolean; /** - * This function will kill the worker. In the primary, it does this - * by disconnecting the `worker.process`, and once disconnected, killing - * with `signal`. In the worker, it does it by disconnecting the channel, - * and then exiting with code `0`. + * This function will kill the worker. In the primary worker, it does this by + * disconnecting the `worker.process`, and once disconnected, killing with`signal`. In the worker, it does it by killing the process with `signal`. * - * Because `kill()` attempts to gracefully disconnect the worker process, it is - * susceptible to waiting indefinitely for the disconnect to complete. For example, - * if the worker enters an infinite loop, a graceful disconnect will never occur. - * If the graceful disconnect behavior is not needed, use `worker.process.kill()`. + * The `kill()` function kills the worker process without waiting for a graceful + * disconnect, it has the same behavior as `worker.process.kill()`. * - * Causes `.exitedAfterDisconnect` to be set. - * - * This method is aliased as `worker.destroy()` for backward compatibility. + * This method is aliased as `worker.destroy()` for backwards compatibility. * * In a worker, `process.kill()` exists, but it is not this function; * it is `kill()`. @@ -188,7 +196,7 @@ declare module 'cluster' { * }); * * } else if (cluster.isWorker) { - * const net = require('net'); + * const net = require('node:net'); * const server = net.createServer((socket) => { * // Connections never end * }); @@ -218,12 +226,12 @@ declare module 'cluster' { * because of exiting or being signaled). Otherwise, it returns `false`. * * ```js - * import cluster from 'cluster'; - * import http from 'http'; - * import { cpus } from 'os'; - * import process from 'process'; + * import cluster from 'node:cluster'; + * import http from 'node:http'; + * import { availableParallelism } from 'node:os'; + * import process from 'node:process'; * - * const numCPUs = cpus().length; + * const numCPUs = availableParallelism(); * * if (cluster.isPrimary) { * console.log(`Primary ${process.pid} is running`); @@ -253,7 +261,8 @@ declare module 'cluster' { */ isDead(): boolean; /** - * This property is `true` if the worker exited due to `.kill()` or`.disconnect()`. If the worker exited any other way, it is `false`. If the + * This property is `true` if the worker exited due to `.disconnect()`. + * If the worker exited any other way, it is `false`. If the * worker has not exited, it is `undefined`. * * The boolean `worker.exitedAfterDisconnect` allows distinguishing between @@ -283,47 +292,47 @@ declare module 'cluster' { * 6. online */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'disconnect', listener: () => void): this; - addListener(event: 'error', listener: (error: Error) => void): this; - addListener(event: 'exit', listener: (code: number, signal: string) => void): this; - addListener(event: 'listening', listener: (address: Address) => void): this; - addListener(event: 'message', listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - addListener(event: 'online', listener: () => void): this; + addListener(event: "disconnect", listener: () => void): this; + addListener(event: "error", listener: (error: Error) => void): this; + addListener(event: "exit", listener: (code: number, signal: string) => void): this; + addListener(event: "listening", listener: (address: Address) => void): this; + addListener(event: "message", listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + addListener(event: "online", listener: () => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'disconnect'): boolean; - emit(event: 'error', error: Error): boolean; - emit(event: 'exit', code: number, signal: string): boolean; - emit(event: 'listening', address: Address): boolean; - emit(event: 'message', message: any, handle: net.Socket | net.Server): boolean; - emit(event: 'online'): boolean; + emit(event: "disconnect"): boolean; + emit(event: "error", error: Error): boolean; + emit(event: "exit", code: number, signal: string): boolean; + emit(event: "listening", address: Address): boolean; + emit(event: "message", message: any, handle: net.Socket | net.Server): boolean; + emit(event: "online"): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'disconnect', listener: () => void): this; - on(event: 'error', listener: (error: Error) => void): this; - on(event: 'exit', listener: (code: number, signal: string) => void): this; - on(event: 'listening', listener: (address: Address) => void): this; - on(event: 'message', listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - on(event: 'online', listener: () => void): this; + on(event: "disconnect", listener: () => void): this; + on(event: "error", listener: (error: Error) => void): this; + on(event: "exit", listener: (code: number, signal: string) => void): this; + on(event: "listening", listener: (address: Address) => void): this; + on(event: "message", listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + on(event: "online", listener: () => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'disconnect', listener: () => void): this; - once(event: 'error', listener: (error: Error) => void): this; - once(event: 'exit', listener: (code: number, signal: string) => void): this; - once(event: 'listening', listener: (address: Address) => void): this; - once(event: 'message', listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - once(event: 'online', listener: () => void): this; + once(event: "disconnect", listener: () => void): this; + once(event: "error", listener: (error: Error) => void): this; + once(event: "exit", listener: (code: number, signal: string) => void): this; + once(event: "listening", listener: (address: Address) => void): this; + once(event: "message", listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + once(event: "online", listener: () => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'disconnect', listener: () => void): this; - prependListener(event: 'error', listener: (error: Error) => void): this; - prependListener(event: 'exit', listener: (code: number, signal: string) => void): this; - prependListener(event: 'listening', listener: (address: Address) => void): this; - prependListener(event: 'message', listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - prependListener(event: 'online', listener: () => void): this; + prependListener(event: "disconnect", listener: () => void): this; + prependListener(event: "error", listener: (error: Error) => void): this; + prependListener(event: "exit", listener: (code: number, signal: string) => void): this; + prependListener(event: "listening", listener: (address: Address) => void): this; + prependListener(event: "message", listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + prependListener(event: "online", listener: () => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'disconnect', listener: () => void): this; - prependOnceListener(event: 'error', listener: (error: Error) => void): this; - prependOnceListener(event: 'exit', listener: (code: number, signal: string) => void): this; - prependOnceListener(event: 'listening', listener: (address: Address) => void): this; - prependOnceListener(event: 'message', listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - prependOnceListener(event: 'online', listener: () => void): this; + prependOnceListener(event: "disconnect", listener: () => void): this; + prependOnceListener(event: "error", listener: (error: Error) => void): this; + prependOnceListener(event: "exit", listener: (code: number, signal: string) => void): this; + prependOnceListener(event: "listening", listener: (address: Address) => void): this; + prependOnceListener(event: "message", listener: (message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + prependOnceListener(event: "online", listener: () => void): this; } export interface Cluster extends EventEmitter { disconnect(callback?: () => void): void; @@ -355,60 +364,69 @@ declare module 'cluster' { * 7. setup */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'disconnect', listener: (worker: Worker) => void): this; - addListener(event: 'exit', listener: (worker: Worker, code: number, signal: string) => void): this; - addListener(event: 'fork', listener: (worker: Worker) => void): this; - addListener(event: 'listening', listener: (worker: Worker, address: Address) => void): this; - addListener(event: 'message', listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - addListener(event: 'online', listener: (worker: Worker) => void): this; - addListener(event: 'setup', listener: (settings: ClusterSettings) => void): this; + addListener(event: "disconnect", listener: (worker: Worker) => void): this; + addListener(event: "exit", listener: (worker: Worker, code: number, signal: string) => void): this; + addListener(event: "fork", listener: (worker: Worker) => void): this; + addListener(event: "listening", listener: (worker: Worker, address: Address) => void): this; + addListener( + event: "message", + listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void, + ): this; // the handle is a net.Socket or net.Server object, or undefined. + addListener(event: "online", listener: (worker: Worker) => void): this; + addListener(event: "setup", listener: (settings: ClusterSettings) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'disconnect', worker: Worker): boolean; - emit(event: 'exit', worker: Worker, code: number, signal: string): boolean; - emit(event: 'fork', worker: Worker): boolean; - emit(event: 'listening', worker: Worker, address: Address): boolean; - emit(event: 'message', worker: Worker, message: any, handle: net.Socket | net.Server): boolean; - emit(event: 'online', worker: Worker): boolean; - emit(event: 'setup', settings: ClusterSettings): boolean; + emit(event: "disconnect", worker: Worker): boolean; + emit(event: "exit", worker: Worker, code: number, signal: string): boolean; + emit(event: "fork", worker: Worker): boolean; + emit(event: "listening", worker: Worker, address: Address): boolean; + emit(event: "message", worker: Worker, message: any, handle: net.Socket | net.Server): boolean; + emit(event: "online", worker: Worker): boolean; + emit(event: "setup", settings: ClusterSettings): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'disconnect', listener: (worker: Worker) => void): this; - on(event: 'exit', listener: (worker: Worker, code: number, signal: string) => void): this; - on(event: 'fork', listener: (worker: Worker) => void): this; - on(event: 'listening', listener: (worker: Worker, address: Address) => void): this; - on(event: 'message', listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - on(event: 'online', listener: (worker: Worker) => void): this; - on(event: 'setup', listener: (settings: ClusterSettings) => void): this; + on(event: "disconnect", listener: (worker: Worker) => void): this; + on(event: "exit", listener: (worker: Worker, code: number, signal: string) => void): this; + on(event: "fork", listener: (worker: Worker) => void): this; + on(event: "listening", listener: (worker: Worker, address: Address) => void): this; + on(event: "message", listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + on(event: "online", listener: (worker: Worker) => void): this; + on(event: "setup", listener: (settings: ClusterSettings) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'disconnect', listener: (worker: Worker) => void): this; - once(event: 'exit', listener: (worker: Worker, code: number, signal: string) => void): this; - once(event: 'fork', listener: (worker: Worker) => void): this; - once(event: 'listening', listener: (worker: Worker, address: Address) => void): this; - once(event: 'message', listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - once(event: 'online', listener: (worker: Worker) => void): this; - once(event: 'setup', listener: (settings: ClusterSettings) => void): this; + once(event: "disconnect", listener: (worker: Worker) => void): this; + once(event: "exit", listener: (worker: Worker, code: number, signal: string) => void): this; + once(event: "fork", listener: (worker: Worker) => void): this; + once(event: "listening", listener: (worker: Worker, address: Address) => void): this; + once(event: "message", listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; // the handle is a net.Socket or net.Server object, or undefined. + once(event: "online", listener: (worker: Worker) => void): this; + once(event: "setup", listener: (settings: ClusterSettings) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'disconnect', listener: (worker: Worker) => void): this; - prependListener(event: 'exit', listener: (worker: Worker, code: number, signal: string) => void): this; - prependListener(event: 'fork', listener: (worker: Worker) => void): this; - prependListener(event: 'listening', listener: (worker: Worker, address: Address) => void): this; + prependListener(event: "disconnect", listener: (worker: Worker) => void): this; + prependListener(event: "exit", listener: (worker: Worker, code: number, signal: string) => void): this; + prependListener(event: "fork", listener: (worker: Worker) => void): this; + prependListener(event: "listening", listener: (worker: Worker, address: Address) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - prependListener(event: 'message', listener: (worker: Worker, message: any, handle?: net.Socket | net.Server) => void): this; - prependListener(event: 'online', listener: (worker: Worker) => void): this; - prependListener(event: 'setup', listener: (settings: ClusterSettings) => void): this; + prependListener( + event: "message", + listener: (worker: Worker, message: any, handle?: net.Socket | net.Server) => void, + ): this; + prependListener(event: "online", listener: (worker: Worker) => void): this; + prependListener(event: "setup", listener: (settings: ClusterSettings) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'disconnect', listener: (worker: Worker) => void): this; - prependOnceListener(event: 'exit', listener: (worker: Worker, code: number, signal: string) => void): this; - prependOnceListener(event: 'fork', listener: (worker: Worker) => void): this; - prependOnceListener(event: 'listening', listener: (worker: Worker, address: Address) => void): this; + prependOnceListener(event: "disconnect", listener: (worker: Worker) => void): this; + prependOnceListener(event: "exit", listener: (worker: Worker, code: number, signal: string) => void): this; + prependOnceListener(event: "fork", listener: (worker: Worker) => void): this; + prependOnceListener(event: "listening", listener: (worker: Worker, address: Address) => void): this; // the handle is a net.Socket or net.Server object, or undefined. - prependOnceListener(event: 'message', listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void): this; - prependOnceListener(event: 'online', listener: (worker: Worker) => void): this; - prependOnceListener(event: 'setup', listener: (settings: ClusterSettings) => void): this; + prependOnceListener( + event: "message", + listener: (worker: Worker, message: any, handle: net.Socket | net.Server) => void, + ): this; + prependOnceListener(event: "online", listener: (worker: Worker) => void): this; + prependOnceListener(event: "setup", listener: (settings: ClusterSettings) => void): this; } const cluster: Cluster; export default cluster; } -declare module 'node:cluster' { - export * from 'cluster'; - export { default as default } from 'cluster'; +declare module "node:cluster" { + export * from "cluster"; + export { default as default } from "cluster"; } diff --git a/node_modules/@types/node/ts4.8/console.d.ts b/node_modules/@types/node/ts4.8/console.d.ts old mode 100755 new mode 100644 index ede7a53..bcc3450 --- a/node_modules/@types/node/ts4.8/console.d.ts +++ b/node_modules/@types/node/ts4.8/console.d.ts @@ -1,11 +1,11 @@ /** - * The `console` module provides a simple debugging console that is similar to the - * JavaScript console mechanism provided by web browsers. + * The `node:console` module provides a simple debugging console that is similar to + * the JavaScript console mechanism provided by web browsers. * * The module exports two specific components: * - * * A `Console` class with methods such as `console.log()`, `console.error()` and`console.warn()` that can be used to write to any Node.js stream. - * * A global `console` instance configured to write to `process.stdout` and `process.stderr`. The global `console` can be used without calling`require('console')`. + * * A `Console` class with methods such as `console.log()`, `console.error()`, and`console.warn()` that can be used to write to any Node.js stream. + * * A global `console` instance configured to write to `process.stdout` and `process.stderr`. The global `console` can be used without calling`require('node:console')`. * * _**Warning**_: The global console object's methods are neither consistently * synchronous like the browser APIs they resemble, nor are they consistently @@ -53,14 +53,14 @@ * myConsole.warn(`Danger ${name}! Danger!`); * // Prints: Danger Will Robinson! Danger!, to err * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/console.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/console.js) */ -declare module 'console' { - import console = require('node:console'); +declare module "console" { + import console = require("node:console"); export = console; } -declare module 'node:console' { - import { InspectOptions } from 'node:util'; +declare module "node:console" { + import { InspectOptions } from "node:util"; global { // This needs to be global to avoid TS2403 in case lib.dom.d.ts is present in the same build interface Console { @@ -123,7 +123,7 @@ declare module 'node:console' { * > * ``` * @since v8.3.0 - * @param label The display label for the counter. + * @param [label='default'] The display label for the counter. */ count(label?: string): void; /** @@ -141,7 +141,7 @@ declare module 'node:console' { * > * ``` * @since v8.3.0 - * @param label The display label for the counter. + * @param [label='default'] The display label for the counter. */ countReset(label?: string): void; /** @@ -221,7 +221,7 @@ declare module 'node:console' { log(message?: any, ...optionalParams: any[]): void; /** * Try to construct a table with the columns of the properties of `tabularData`(or use `properties`) and rows of `tabularData` and log it. Falls back to just - * logging the argument if it can’t be parsed as tabular. + * logging the argument if it can't be parsed as tabular. * * ```js * // These can't be parsed as tabular data @@ -250,13 +250,14 @@ declare module 'node:console' { * @since v10.0.0 * @param properties Alternate properties for constructing the table. */ - table(tabularData: any, properties?: ReadonlyArray): void; + table(tabularData: any, properties?: readonly string[]): void; /** * Starts a timer that can be used to compute the duration of an operation. Timers * are identified by a unique `label`. Use the same `label` when calling {@link timeEnd} to stop the timer and output the elapsed time in * suitable time units to `stdout`. For example, if the elapsed * time is 3869ms, `console.timeEnd()` displays "3.869s". * @since v0.1.104 + * @param [label='default'] */ time(label?: string): void; /** @@ -264,12 +265,13 @@ declare module 'node:console' { * prints the result to `stdout`: * * ```js - * console.time('100-elements'); - * for (let i = 0; i < 100; i++) {} - * console.timeEnd('100-elements'); - * // prints 100-elements: 225.438ms + * console.time('bunch-of-stuff'); + * // Do a bunch of stuff. + * console.timeEnd('bunch-of-stuff'); + * // Prints: bunch-of-stuff: 225.438ms * ``` * @since v0.1.104 + * @param [label='default'] */ timeEnd(label?: string): void; /** @@ -285,6 +287,7 @@ declare module 'node:console' { * console.timeEnd('process'); * ``` * @since v10.7.0 + * @param [label='default'] */ timeLog(label?: string, ...data: any[]): void; /** @@ -392,7 +395,7 @@ declare module 'node:console' { stdout: NodeJS.WritableStream; stderr?: NodeJS.WritableStream | undefined; ignoreErrors?: boolean | undefined; - colorMode?: boolean | 'auto' | undefined; + colorMode?: boolean | "auto" | undefined; inspectOptions?: InspectOptions | undefined; /** * Set group indentation @@ -402,8 +405,8 @@ declare module 'node:console' { } interface ConsoleConstructor { prototype: Console; - new (stdout: NodeJS.WritableStream, stderr?: NodeJS.WritableStream, ignoreErrors?: boolean): Console; - new (options: ConsoleConstructorOptions): Console; + new(stdout: NodeJS.WritableStream, stderr?: NodeJS.WritableStream, ignoreErrors?: boolean): Console; + new(options: ConsoleConstructorOptions): Console; } } var console: Console; diff --git a/node_modules/@types/node/ts4.8/constants.d.ts b/node_modules/@types/node/ts4.8/constants.d.ts old mode 100755 new mode 100644 index 208020d..c3ac2b8 --- a/node_modules/@types/node/ts4.8/constants.d.ts +++ b/node_modules/@types/node/ts4.8/constants.d.ts @@ -1,18 +1,19 @@ /** @deprecated since v6.3.0 - use constants property exposed by the relevant module instead. */ -declare module 'constants' { - import { constants as osConstants, SignalConstants } from 'node:os'; - import { constants as cryptoConstants } from 'node:crypto'; - import { constants as fsConstants } from 'node:fs'; +declare module "constants" { + import { constants as osConstants, SignalConstants } from "node:os"; + import { constants as cryptoConstants } from "node:crypto"; + import { constants as fsConstants } from "node:fs"; - const exp: typeof osConstants.errno & - typeof osConstants.priority & - SignalConstants & - typeof cryptoConstants & - typeof fsConstants; + const exp: + & typeof osConstants.errno + & typeof osConstants.priority + & SignalConstants + & typeof cryptoConstants + & typeof fsConstants; export = exp; } -declare module 'node:constants' { - import constants = require('constants'); +declare module "node:constants" { + import constants = require("constants"); export = constants; } diff --git a/node_modules/@types/node/ts4.8/crypto.d.ts b/node_modules/@types/node/ts4.8/crypto.d.ts old mode 100755 new mode 100644 index 4f6dc9f..f392681 --- a/node_modules/@types/node/ts4.8/crypto.d.ts +++ b/node_modules/@types/node/ts4.8/crypto.d.ts @@ -1,9 +1,10 @@ /** - * The `crypto` module provides cryptographic functionality that includes a set of - * wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify functions. + * The `node:crypto` module provides cryptographic functionality that includes a + * set of wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify + * functions. * * ```js - * const { createHmac } = await import('crypto'); + * const { createHmac } = await import('node:crypto'); * * const secret = 'abcdefg'; * const hash = createHmac('sha256', secret) @@ -13,12 +14,64 @@ * // Prints: * // c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/crypto.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/crypto.js) */ -declare module 'crypto' { - import * as stream from 'node:stream'; - import { PeerCertificate } from 'node:tls'; - interface Certificate { +declare module "crypto" { + import * as stream from "node:stream"; + import { PeerCertificate } from "node:tls"; + /** + * SPKAC is a Certificate Signing Request mechanism originally implemented by + * Netscape and was specified formally as part of HTML5's `keygen` element. + * + * `` is deprecated since [HTML 5.2](https://www.w3.org/TR/html52/changes.html#features-removed) and new projects + * should not use this element anymore. + * + * The `node:crypto` module provides the `Certificate` class for working with SPKAC + * data. The most common usage is handling output generated by the HTML5`` element. Node.js uses [OpenSSL's SPKAC + * implementation](https://www.openssl.org/docs/man3.0/man1/openssl-spkac.html) internally. + * @since v0.11.8 + */ + class Certificate { + /** + * ```js + * const { Certificate } = await import('node:crypto'); + * const spkac = getSpkacSomehow(); + * const challenge = Certificate.exportChallenge(spkac); + * console.log(challenge.toString('utf8')); + * // Prints: the challenge as a UTF8 string + * ``` + * @since v9.0.0 + * @param encoding The `encoding` of the `spkac` string. + * @return The challenge component of the `spkac` data structure, which includes a public key and a challenge. + */ + static exportChallenge(spkac: BinaryLike): Buffer; + /** + * ```js + * const { Certificate } = await import('node:crypto'); + * const spkac = getSpkacSomehow(); + * const publicKey = Certificate.exportPublicKey(spkac); + * console.log(publicKey); + * // Prints: the public key as + * ``` + * @since v9.0.0 + * @param encoding The `encoding` of the `spkac` string. + * @return The public key component of the `spkac` data structure, which includes a public key and a challenge. + */ + static exportPublicKey(spkac: BinaryLike, encoding?: string): Buffer; + /** + * ```js + * import { Buffer } from 'node:buffer'; + * const { Certificate } = await import('node:crypto'); + * + * const spkac = getSpkacSomehow(); + * console.log(Certificate.verifySpkac(Buffer.from(spkac))); + * // Prints: true or false + * ``` + * @since v9.0.0 + * @param encoding The `encoding` of the `spkac` string. + * @return `true` if the given `spkac` data structure is valid, `false` otherwise. + */ + static verifySpkac(spkac: NodeJS.ArrayBufferView): boolean; /** * @deprecated * @param spkac @@ -42,36 +95,13 @@ declare module 'crypto' { */ verifySpkac(spkac: NodeJS.ArrayBufferView): boolean; } - const Certificate: Certificate & { - /** @deprecated since v14.9.0 - Use static methods of `crypto.Certificate` instead. */ - new (): Certificate; - /** @deprecated since v14.9.0 - Use static methods of `crypto.Certificate` instead. */ - (): Certificate; - /** - * @param spkac - * @returns The challenge component of the `spkac` data structure, - * which includes a public key and a challenge. - */ - exportChallenge(spkac: BinaryLike): Buffer; - /** - * @param spkac - * @param encoding The encoding of the spkac string. - * @returns The public key component of the `spkac` data structure, - * which includes a public key and a challenge. - */ - exportPublicKey(spkac: BinaryLike, encoding?: string): Buffer; - /** - * @param spkac - * @returns `true` if the given `spkac` data structure is valid, - * `false` otherwise. - */ - verifySpkac(spkac: NodeJS.ArrayBufferView): boolean; - }; namespace constants { - // https://nodejs.org/dist/latest-v10.x/docs/api/crypto.html#crypto_crypto_constants + // https://nodejs.org/dist/latest-v20.x/docs/api/crypto.html#crypto-constants const OPENSSL_VERSION_NUMBER: number; /** Applies multiple bug workarounds within OpenSSL. See https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html for detail. */ const SSL_OP_ALL: number; + /** Instructs OpenSSL to allow a non-[EC]DHE-based key exchange mode for TLS v1.3 */ + const SSL_OP_ALLOW_NO_DHE_KEX: number; /** Allows legacy insecure renegotiation between OpenSSL and unpatched clients or servers. See https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html. */ const SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION: number; /** Attempts to use the server's preferences instead of the client's when selecting a cipher. See https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html. */ @@ -84,39 +114,33 @@ declare module 'crypto' { const SSL_OP_CRYPTOPRO_TLSEXT_BUG: number; /** Instructs OpenSSL to disable a SSL 3.0/TLS 1.0 vulnerability workaround added in OpenSSL 0.9.6d. */ const SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS: number; - /** Instructs OpenSSL to always use the tmp_rsa key when performing RSA operations. */ - const SSL_OP_EPHEMERAL_RSA: number; /** Allows initial connection to servers that do not support RI. */ const SSL_OP_LEGACY_SERVER_CONNECT: number; - const SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER: number; - const SSL_OP_MICROSOFT_SESS_ID_BUG: number; - /** Instructs OpenSSL to disable the workaround for a man-in-the-middle protocol-version vulnerability in the SSL 2.0 server implementation. */ - const SSL_OP_MSIE_SSLV2_RSA_PADDING: number; - const SSL_OP_NETSCAPE_CA_DN_BUG: number; - const SSL_OP_NETSCAPE_CHALLENGE_BUG: number; - const SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG: number; - const SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG: number; /** Instructs OpenSSL to disable support for SSL/TLS compression. */ const SSL_OP_NO_COMPRESSION: number; + /** Instructs OpenSSL to disable encrypt-then-MAC. */ + const SSL_OP_NO_ENCRYPT_THEN_MAC: number; const SSL_OP_NO_QUERY_MTU: number; + /** Instructs OpenSSL to disable renegotiation. */ + const SSL_OP_NO_RENEGOTIATION: number; /** Instructs OpenSSL to always start a new session when performing renegotiation. */ const SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION: number; + /** Instructs OpenSSL to turn off SSL v2 */ const SSL_OP_NO_SSLv2: number; + /** Instructs OpenSSL to turn off SSL v3 */ const SSL_OP_NO_SSLv3: number; + /** Instructs OpenSSL to disable use of RFC4507bis tickets. */ const SSL_OP_NO_TICKET: number; + /** Instructs OpenSSL to turn off TLS v1 */ const SSL_OP_NO_TLSv1: number; + /** Instructs OpenSSL to turn off TLS v1.1 */ const SSL_OP_NO_TLSv1_1: number; + /** Instructs OpenSSL to turn off TLS v1.2 */ const SSL_OP_NO_TLSv1_2: number; - const SSL_OP_PKCS1_CHECK_1: number; - const SSL_OP_PKCS1_CHECK_2: number; - /** Instructs OpenSSL to always create a new key when using temporary/ephemeral DH parameters. */ - const SSL_OP_SINGLE_DH_USE: number; - /** Instructs OpenSSL to always create a new key when using temporary/ephemeral ECDH parameters. */ - const SSL_OP_SINGLE_ECDH_USE: number; - const SSL_OP_SSLEAY_080_CLIENT_DH_BUG: number; - const SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG: number; - const SSL_OP_TLS_BLOCK_PADDING_BUG: number; - const SSL_OP_TLS_D5_BUG: number; + /** Instructs OpenSSL to turn off TLS v1.3 */ + const SSL_OP_NO_TLSv1_3: number; + /** Instructs OpenSSL server to prioritize ChaCha20-Poly1305 when the client does. This option has no effect if `SSL_OP_CIPHER_SERVER_PREFERENCE` is not enabled. */ + const SSL_OP_PRIORITIZE_CHACHA: number; /** Instructs OpenSSL to disable version rollback attack detection. */ const SSL_OP_TLS_ROLLBACK_BUG: number; const ENGINE_METHOD_RSA: number; @@ -134,7 +158,6 @@ declare module 'crypto' { const DH_CHECK_P_NOT_PRIME: number; const DH_UNABLE_TO_CHECK_GENERATOR: number; const DH_NOT_SUITABLE_GENERATOR: number; - const ALPN_ENABLED: number; const RSA_PKCS1_PADDING: number; const RSA_SSLV23_PADDING: number; const RSA_NO_PADDING: number; @@ -172,19 +195,19 @@ declare module 'crypto' { * * The `algorithm` is dependent on the available algorithms supported by the * version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc. - * On recent releases of OpenSSL, `openssl list -digest-algorithms`(`openssl list-message-digest-algorithms` for older versions of OpenSSL) will + * On recent releases of OpenSSL, `openssl list -digest-algorithms` will * display the available digest algorithms. * * Example: generating the sha256 sum of a file * * ```js * import { - * createReadStream - * } from 'fs'; - * import { argv } from 'process'; + * createReadStream, + * } from 'node:fs'; + * import { argv } from 'node:process'; * const { - * createHash - * } = await import('crypto'); + * createHash, + * } = await import('node:crypto'); * * const filename = argv[2]; * @@ -212,22 +235,24 @@ declare module 'crypto' { * * The `algorithm` is dependent on the available algorithms supported by the * version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc. - * On recent releases of OpenSSL, `openssl list -digest-algorithms`(`openssl list-message-digest-algorithms` for older versions of OpenSSL) will + * On recent releases of OpenSSL, `openssl list -digest-algorithms` will * display the available digest algorithms. * * The `key` is the HMAC key used to generate the cryptographic HMAC hash. If it is - * a `KeyObject`, its type must be `secret`. + * a `KeyObject`, its type must be `secret`. If it is a string, please consider `caveats when using strings as inputs to cryptographic APIs`. If it was + * obtained from a cryptographically secure source of entropy, such as {@link randomBytes} or {@link generateKey}, its length should not + * exceed the block size of `algorithm` (e.g., 512 bits for SHA-256). * * Example: generating the sha256 HMAC of a file * * ```js * import { - * createReadStream - * } from 'fs'; - * import { argv } from 'process'; + * createReadStream, + * } from 'node:fs'; + * import { argv } from 'node:process'; * const { - * createHmac - * } = await import('crypto'); + * createHmac, + * } = await import('node:crypto'); * * const filename = argv[2]; * @@ -250,11 +275,11 @@ declare module 'crypto' { */ function createHmac(algorithm: string, key: BinaryLike | KeyObject, options?: stream.TransformOptions): Hmac; // https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings - type BinaryToTextEncoding = 'base64' | 'base64url' | 'hex'; - type CharacterEncoding = 'utf8' | 'utf-8' | 'utf16le' | 'latin1'; - type LegacyCharacterEncoding = 'ascii' | 'binary' | 'ucs2' | 'ucs-2'; + type BinaryToTextEncoding = "base64" | "base64url" | "hex" | "binary"; + type CharacterEncoding = "utf8" | "utf-8" | "utf16le" | "utf-16le" | "latin1"; + type LegacyCharacterEncoding = "ascii" | "binary" | "ucs2" | "ucs-2"; type Encoding = BinaryToTextEncoding | CharacterEncoding | LegacyCharacterEncoding; - type ECDHKeyFormat = 'compressed' | 'uncompressed' | 'hybrid'; + type ECDHKeyFormat = "compressed" | "uncompressed" | "hybrid"; /** * The `Hash` class is a utility for creating hash digests of data. It can be * used in one of two ways: @@ -270,8 +295,8 @@ declare module 'crypto' { * * ```js * const { - * createHash - * } = await import('crypto'); + * createHash, + * } = await import('node:crypto'); * * const hash = createHash('sha256'); * @@ -293,9 +318,9 @@ declare module 'crypto' { * Example: Using `Hash` and piped streams: * * ```js - * import { createReadStream } from 'fs'; - * import { stdout } from 'process'; - * const { createHash } = await import('crypto'); + * import { createReadStream } from 'node:fs'; + * import { stdout } from 'node:process'; + * const { createHash } = await import('node:crypto'); * * const hash = createHash('sha256'); * @@ -307,8 +332,8 @@ declare module 'crypto' { * * ```js * const { - * createHash - * } = await import('crypto'); + * createHash, + * } = await import('node:crypto'); * * const hash = createHash('sha256'); * @@ -335,8 +360,8 @@ declare module 'crypto' { * ```js * // Calculate a rolling hash. * const { - * createHash - * } = await import('crypto'); + * createHash, + * } = await import('node:crypto'); * * const hash = createHash('sha256'); * @@ -354,7 +379,7 @@ declare module 'crypto' { * @since v13.1.0 * @param options `stream.transform` options */ - copy(options?: stream.TransformOptions): Hash; + copy(options?: HashOptions): Hash; /** * Updates the hash content with the given `data`, the encoding of which * is given in `inputEncoding`. @@ -395,8 +420,8 @@ declare module 'crypto' { * * ```js * const { - * createHmac - * } = await import('crypto'); + * createHmac, + * } = await import('node:crypto'); * * const hmac = createHmac('sha256', 'a secret'); * @@ -418,11 +443,11 @@ declare module 'crypto' { * Example: Using `Hmac` and piped streams: * * ```js - * import { createReadStream } from 'fs'; - * import { stdout } from 'process'; + * import { createReadStream } from 'node:fs'; + * import { stdout } from 'node:process'; * const { - * createHmac - * } = await import('crypto'); + * createHmac, + * } = await import('node:crypto'); * * const hmac = createHmac('sha256', 'a secret'); * @@ -434,8 +459,8 @@ declare module 'crypto' { * * ```js * const { - * createHmac - * } = await import('crypto'); + * createHmac, + * } = await import('node:crypto'); * * const hmac = createHmac('sha256', 'a secret'); * @@ -473,15 +498,15 @@ declare module 'crypto' { digest(): Buffer; digest(encoding: BinaryToTextEncoding): string; } - type KeyObjectType = 'secret' | 'public' | 'private'; + type KeyObjectType = "secret" | "public" | "private"; interface KeyExportOptions { - type: 'pkcs1' | 'spki' | 'pkcs8' | 'sec1'; + type: "pkcs1" | "spki" | "pkcs8" | "sec1"; format: T; cipher?: string | undefined; passphrase?: string | Buffer | undefined; } interface JwkKeyExportOptions { - format: 'jwk'; + format: "jwk"; } interface JsonWebKey { crv?: string | undefined; @@ -548,13 +573,13 @@ declare module 'crypto' { * Example: Converting a `CryptoKey` instance to a `KeyObject`: * * ```js - * const { webcrypto, KeyObject } = await import('crypto'); - * const { subtle } = webcrypto; + * const { KeyObject } = await import('node:crypto'); + * const { subtle } = globalThis.crypto; * * const key = await subtle.generateKey({ * name: 'HMAC', * hash: 'SHA-256', - * length: 256 + * length: 256, * }, true, ['sign', 'verify']); * * const keyObject = KeyObject.from(key); @@ -625,9 +650,16 @@ declare module 'crypto' { * PKCS#1 and SEC1 encryption. * @since v11.6.0 */ - export(options: KeyExportOptions<'pem'>): string | Buffer; - export(options?: KeyExportOptions<'der'>): Buffer; + export(options: KeyExportOptions<"pem">): string | Buffer; + export(options?: KeyExportOptions<"der">): Buffer; export(options?: JwkKeyExportOptions): JsonWebKey; + /** + * Returns `true` or `false` depending on whether the keys have exactly the same + * type, value, and parameters. This method is not [constant time](https://en.wikipedia.org/wiki/Timing_attack). + * @since v17.7.0, v16.15.0 + * @param otherKeyObject A `KeyObject` with which to compare `keyObject`. + */ + equals(otherKeyObject: KeyObject): boolean; /** * For secret keys, this property represents the size of the key in bytes. This * property is `undefined` for asymmetric keys. @@ -641,9 +673,9 @@ declare module 'crypto' { */ type: KeyObjectType; } - type CipherCCMTypes = 'aes-128-ccm' | 'aes-192-ccm' | 'aes-256-ccm' | 'chacha20-poly1305'; - type CipherGCMTypes = 'aes-128-gcm' | 'aes-192-gcm' | 'aes-256-gcm'; - type CipherOCBTypes = 'aes-128-ocb' | 'aes-192-ocb' | 'aes-256-ocb'; + type CipherCCMTypes = "aes-128-ccm" | "aes-192-ccm" | "aes-256-ccm" | "chacha20-poly1305"; + type CipherGCMTypes = "aes-128-gcm" | "aes-192-gcm" | "aes-256-gcm"; + type CipherOCBTypes = "aes-128-ocb" | "aes-192-ocb" | "aes-256-ocb"; type BinaryLike = string | NodeJS.ArrayBufferView; type CipherKey = BinaryLike | KeyObject; interface CipherCCMOptions extends stream.TransformOptions { @@ -659,25 +691,30 @@ declare module 'crypto' { * Creates and returns a `Cipher` object that uses the given `algorithm` and`password`. * * The `options` argument controls stream behavior and is optional except when a - * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the + * cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the * authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication * tag that will be returned by `getAuthTag()` and defaults to 16 bytes. + * For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes. * * The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On - * recent OpenSSL releases, `openssl list -cipher-algorithms`(`openssl list-cipher-algorithms` for older versions of OpenSSL) will + * recent OpenSSL releases, `openssl list -cipher-algorithms` will * display the available cipher algorithms. * * The `password` is used to derive the cipher key and initialization vector (IV). * The value must be either a `'latin1'` encoded string, a `Buffer`, a`TypedArray`, or a `DataView`. * + * **This function is semantically insecure for all** + * **supported ciphers and fatally flawed for ciphers in counter mode (such as CTR,** + * **GCM, or CCM).** + * * The implementation of `crypto.createCipher()` derives keys using the OpenSSL - * function [`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) with the digest algorithm set to MD5, one + * function [`EVP_BytesToKey`](https://www.openssl.org/docs/man3.0/man3/EVP_BytesToKey.html) with the digest algorithm set to MD5, one * iteration, and no salt. The lack of salt allows dictionary attacks as the same * password always creates the same key. The low iteration count and * non-cryptographically secure hash algorithm allow passwords to be tested very * rapidly. * - * In line with OpenSSL's recommendation to use a more modern algorithm instead of [`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) it is recommended that + * In line with OpenSSL's recommendation to use a more modern algorithm instead of [`EVP_BytesToKey`](https://www.openssl.org/docs/man3.0/man3/EVP_BytesToKey.html) it is recommended that * developers derive a key and IV on * their own using {@link scrypt} and to use {@link createCipheriv} to create the `Cipher` object. Users should not use ciphers with counter mode * (e.g. CTR, GCM, or CCM) in `crypto.createCipher()`. A warning is emitted when @@ -697,12 +734,13 @@ declare module 'crypto' { * initialization vector (`iv`). * * The `options` argument controls stream behavior and is optional except when a - * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the + * cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the * authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication * tag that will be returned by `getAuthTag()` and defaults to 16 bytes. + * For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes. * * The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On - * recent OpenSSL releases, `openssl list -cipher-algorithms`(`openssl list-cipher-algorithms` for older versions of OpenSSL) will + * recent OpenSSL releases, `openssl list -cipher-algorithms` will * display the available cipher algorithms. * * The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded @@ -721,10 +759,30 @@ declare module 'crypto' { * @since v0.1.94 * @param options `stream.transform` options */ - function createCipheriv(algorithm: CipherCCMTypes, key: CipherKey, iv: BinaryLike, options: CipherCCMOptions): CipherCCM; - function createCipheriv(algorithm: CipherOCBTypes, key: CipherKey, iv: BinaryLike, options: CipherOCBOptions): CipherOCB; - function createCipheriv(algorithm: CipherGCMTypes, key: CipherKey, iv: BinaryLike, options?: CipherGCMOptions): CipherGCM; - function createCipheriv(algorithm: string, key: CipherKey, iv: BinaryLike | null, options?: stream.TransformOptions): Cipher; + function createCipheriv( + algorithm: CipherCCMTypes, + key: CipherKey, + iv: BinaryLike, + options: CipherCCMOptions, + ): CipherCCM; + function createCipheriv( + algorithm: CipherOCBTypes, + key: CipherKey, + iv: BinaryLike, + options: CipherOCBOptions, + ): CipherOCB; + function createCipheriv( + algorithm: CipherGCMTypes, + key: CipherKey, + iv: BinaryLike, + options?: CipherGCMOptions, + ): CipherGCM; + function createCipheriv( + algorithm: string, + key: CipherKey, + iv: BinaryLike | null, + options?: stream.TransformOptions, + ): Cipher; /** * Instances of the `Cipher` class are used to encrypt data. The class can be * used in one of two ways: @@ -744,8 +802,8 @@ declare module 'crypto' { * const { * scrypt, * randomFill, - * createCipheriv - * } = await import('crypto'); + * createCipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -779,17 +837,17 @@ declare module 'crypto' { * import { * createReadStream, * createWriteStream, - * } from 'fs'; + * } from 'node:fs'; * * import { - * pipeline - * } from 'stream'; + * pipeline, + * } from 'node:stream'; * * const { * scrypt, * randomFill, - * createCipheriv - * } = await import('crypto'); + * createCipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -820,8 +878,8 @@ declare module 'crypto' { * const { * scrypt, * randomFill, - * createCipheriv - * } = await import('crypto'); + * createCipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -896,7 +954,7 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options: { plaintextLength: number; - } + }, ): this; getAuthTag(): Buffer; } @@ -905,7 +963,7 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options?: { plaintextLength: number; - } + }, ): this; getAuthTag(): Buffer; } @@ -914,7 +972,7 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options?: { plaintextLength: number; - } + }, ): this; getAuthTag(): Buffer; } @@ -922,17 +980,22 @@ declare module 'crypto' { * Creates and returns a `Decipher` object that uses the given `algorithm` and`password` (key). * * The `options` argument controls stream behavior and is optional except when a - * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the + * cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the * authentication tag in bytes, see `CCM mode`. + * For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes. + * + * **This function is semantically insecure for all** + * **supported ciphers and fatally flawed for ciphers in counter mode (such as CTR,** + * **GCM, or CCM).** * * The implementation of `crypto.createDecipher()` derives keys using the OpenSSL - * function [`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) with the digest algorithm set to MD5, one + * function [`EVP_BytesToKey`](https://www.openssl.org/docs/man3.0/man3/EVP_BytesToKey.html) with the digest algorithm set to MD5, one * iteration, and no salt. The lack of salt allows dictionary attacks as the same * password always creates the same key. The low iteration count and * non-cryptographically secure hash algorithm allow passwords to be tested very * rapidly. * - * In line with OpenSSL's recommendation to use a more modern algorithm instead of [`EVP_BytesToKey`](https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html) it is recommended that + * In line with OpenSSL's recommendation to use a more modern algorithm instead of [`EVP_BytesToKey`](https://www.openssl.org/docs/man3.0/man3/EVP_BytesToKey.html) it is recommended that * developers derive a key and IV on * their own using {@link scrypt} and to use {@link createDecipheriv} to create the `Decipher` object. * @since v0.1.94 @@ -948,12 +1011,13 @@ declare module 'crypto' { * Creates and returns a `Decipher` object that uses the given `algorithm`, `key`and initialization vector (`iv`). * * The `options` argument controls stream behavior and is optional except when a - * cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the`authTagLength` option is required and specifies the length of the + * cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the * authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to restrict accepted authentication tags * to those with the specified length. + * For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes. * * The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On - * recent OpenSSL releases, `openssl list -cipher-algorithms`(`openssl list-cipher-algorithms` for older versions of OpenSSL) will + * recent OpenSSL releases, `openssl list -cipher-algorithms` will * display the available cipher algorithms. * * The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded @@ -972,10 +1036,30 @@ declare module 'crypto' { * @since v0.1.94 * @param options `stream.transform` options */ - function createDecipheriv(algorithm: CipherCCMTypes, key: CipherKey, iv: BinaryLike, options: CipherCCMOptions): DecipherCCM; - function createDecipheriv(algorithm: CipherOCBTypes, key: CipherKey, iv: BinaryLike, options: CipherOCBOptions): DecipherOCB; - function createDecipheriv(algorithm: CipherGCMTypes, key: CipherKey, iv: BinaryLike, options?: CipherGCMOptions): DecipherGCM; - function createDecipheriv(algorithm: string, key: CipherKey, iv: BinaryLike | null, options?: stream.TransformOptions): Decipher; + function createDecipheriv( + algorithm: CipherCCMTypes, + key: CipherKey, + iv: BinaryLike, + options: CipherCCMOptions, + ): DecipherCCM; + function createDecipheriv( + algorithm: CipherOCBTypes, + key: CipherKey, + iv: BinaryLike, + options: CipherOCBOptions, + ): DecipherOCB; + function createDecipheriv( + algorithm: CipherGCMTypes, + key: CipherKey, + iv: BinaryLike, + options?: CipherGCMOptions, + ): DecipherGCM; + function createDecipheriv( + algorithm: string, + key: CipherKey, + iv: BinaryLike | null, + options?: stream.TransformOptions, + ): Decipher; /** * Instances of the `Decipher` class are used to decrypt data. The class can be * used in one of two ways: @@ -992,11 +1076,11 @@ declare module 'crypto' { * Example: Using `Decipher` objects as streams: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * const { * scryptSync, - * createDecipheriv - * } = await import('crypto'); + * createDecipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -1011,6 +1095,7 @@ declare module 'crypto' { * * let decrypted = ''; * decipher.on('readable', () => { + * let chunk; * while (null !== (chunk = decipher.read())) { * decrypted += chunk.toString('utf8'); * } @@ -1033,12 +1118,12 @@ declare module 'crypto' { * import { * createReadStream, * createWriteStream, - * } from 'fs'; - * import { Buffer } from 'buffer'; + * } from 'node:fs'; + * import { Buffer } from 'node:buffer'; * const { * scryptSync, - * createDecipheriv - * } = await import('crypto'); + * createDecipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -1058,11 +1143,11 @@ declare module 'crypto' { * Example: Using the `decipher.update()` and `decipher.final()` methods: * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * const { * scryptSync, - * createDecipheriv - * } = await import('crypto'); + * createDecipheriv, + * } = await import('node:crypto'); * * const algorithm = 'aes-192-cbc'; * const password = 'Password used to generate key'; @@ -1133,7 +1218,7 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options: { plaintextLength: number; - } + }, ): this; } interface DecipherGCM extends Decipher { @@ -1142,7 +1227,7 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options?: { plaintextLength: number; - } + }, ): this; } interface DecipherOCB extends Decipher { @@ -1151,66 +1236,74 @@ declare module 'crypto' { buffer: NodeJS.ArrayBufferView, options?: { plaintextLength: number; - } + }, ): this; } interface PrivateKeyInput { key: string | Buffer; format?: KeyFormat | undefined; - type?: 'pkcs1' | 'pkcs8' | 'sec1' | undefined; + type?: "pkcs1" | "pkcs8" | "sec1" | undefined; passphrase?: string | Buffer | undefined; + encoding?: string | undefined; } interface PublicKeyInput { key: string | Buffer; format?: KeyFormat | undefined; - type?: 'pkcs1' | 'spki' | undefined; + type?: "pkcs1" | "spki" | undefined; + encoding?: string | undefined; } /** * Asynchronously generates a new random secret key of the given `length`. The`type` will determine which validations will be performed on the `length`. * * ```js * const { - * generateKey - * } = await import('crypto'); + * generateKey, + * } = await import('node:crypto'); * - * generateKey('hmac', { length: 64 }, (err, key) => { + * generateKey('hmac', { length: 512 }, (err, key) => { * if (err) throw err; * console.log(key.export().toString('hex')); // 46e..........620 * }); * ``` + * + * The size of a generated HMAC key should not exceed the block size of the + * underlying hash function. See {@link createHmac} for more information. * @since v15.0.0 * @param type The intended use of the generated secret key. Currently accepted values are `'hmac'` and `'aes'`. */ function generateKey( - type: 'hmac' | 'aes', + type: "hmac" | "aes", options: { length: number; }, - callback: (err: Error | null, key: KeyObject) => void + callback: (err: Error | null, key: KeyObject) => void, ): void; /** * Synchronously generates a new random secret key of the given `length`. The`type` will determine which validations will be performed on the `length`. * * ```js * const { - * generateKeySync - * } = await import('crypto'); + * generateKeySync, + * } = await import('node:crypto'); * - * const key = generateKeySync('hmac', { length: 64 }); + * const key = generateKeySync('hmac', { length: 512 }); * console.log(key.export().toString('hex')); // e89..........41e * ``` + * + * The size of a generated HMAC key should not exceed the block size of the + * underlying hash function. See {@link createHmac} for more information. * @since v15.0.0 * @param type The intended use of the generated secret key. Currently accepted values are `'hmac'` and `'aes'`. */ function generateKeySync( - type: 'hmac' | 'aes', + type: "hmac" | "aes", options: { length: number; - } + }, ): KeyObject; interface JsonWebKeyInput { key: JsonWebKey; - format: 'jwk'; + format: "jwk"; } /** * Creates and returns a new key object containing a private key. If `key` is a @@ -1257,10 +1350,10 @@ declare module 'crypto' { * @param options `stream.Writable` options */ function createSign(algorithm: string, options?: stream.WritableOptions): Sign; - type DSAEncoding = 'der' | 'ieee-p1363'; + type DSAEncoding = "der" | "ieee-p1363"; interface SigningOptions { /** - * @See crypto.constants.RSA_PKCS1_PADDING + * @see crypto.constants.RSA_PKCS1_PADDING */ padding?: number | undefined; saltLength?: number | undefined; @@ -1274,6 +1367,7 @@ declare module 'crypto' { interface VerifyKeyObjectInput extends SigningOptions { key: KeyObject; } + interface VerifyJsonWebKeyInput extends JsonWebKeyInput, SigningOptions {} type KeyLike = string | Buffer | KeyObject; /** * The `Sign` class is a utility for generating signatures. It can be used in one @@ -1293,11 +1387,11 @@ declare module 'crypto' { * const { * generateKeyPairSync, * createSign, - * createVerify - * } = await import('crypto'); + * createVerify, + * } = await import('node:crypto'); * * const { privateKey, publicKey } = generateKeyPairSync('ec', { - * namedCurve: 'sect239k1' + * namedCurve: 'sect239k1', * }); * * const sign = createSign('SHA256'); @@ -1318,8 +1412,8 @@ declare module 'crypto' { * const { * generateKeyPairSync, * createSign, - * createVerify - * } = await import('crypto'); + * createVerify, + * } = await import('node:crypto'); * * const { privateKey, publicKey } = generateKeyPairSync('rsa', { * modulusLength: 2048, @@ -1365,7 +1459,10 @@ declare module 'crypto' { * @since v0.1.92 */ sign(privateKey: KeyLike | SignKeyObjectInput | SignPrivateKeyInput): Buffer; - sign(privateKey: KeyLike | SignKeyObjectInput | SignPrivateKeyInput, outputFormat: BinaryToTextEncoding): string; + sign( + privateKey: KeyLike | SignKeyObjectInput | SignPrivateKeyInput, + outputFormat: BinaryToTextEncoding, + ): string; } /** * Creates and returns a `Verify` object that uses the given algorithm. @@ -1428,8 +1525,15 @@ declare module 'crypto' { * be passed instead of a public key. * @since v0.1.92 */ - verify(object: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, signature: NodeJS.ArrayBufferView): boolean; - verify(object: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, signature: string, signature_format?: BinaryToTextEncoding): boolean; + verify( + object: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput | VerifyJsonWebKeyInput, + signature: NodeJS.ArrayBufferView, + ): boolean; + verify( + object: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput | VerifyJsonWebKeyInput, + signature: string, + signature_format?: BinaryToTextEncoding, + ): boolean; } /** * Creates a `DiffieHellman` key exchange object using the supplied `prime` and an @@ -1447,11 +1551,27 @@ declare module 'crypto' { * @param [generator=2] * @param generatorEncoding The `encoding` of the `generator` string. */ - function createDiffieHellman(primeLength: number, generator?: number | NodeJS.ArrayBufferView): DiffieHellman; - function createDiffieHellman(prime: NodeJS.ArrayBufferView): DiffieHellman; - function createDiffieHellman(prime: string, primeEncoding: BinaryToTextEncoding): DiffieHellman; - function createDiffieHellman(prime: string, primeEncoding: BinaryToTextEncoding, generator: number | NodeJS.ArrayBufferView): DiffieHellman; - function createDiffieHellman(prime: string, primeEncoding: BinaryToTextEncoding, generator: string, generatorEncoding: BinaryToTextEncoding): DiffieHellman; + function createDiffieHellman(primeLength: number, generator?: number): DiffieHellman; + function createDiffieHellman( + prime: ArrayBuffer | NodeJS.ArrayBufferView, + generator?: number | ArrayBuffer | NodeJS.ArrayBufferView, + ): DiffieHellman; + function createDiffieHellman( + prime: ArrayBuffer | NodeJS.ArrayBufferView, + generator: string, + generatorEncoding: BinaryToTextEncoding, + ): DiffieHellman; + function createDiffieHellman( + prime: string, + primeEncoding: BinaryToTextEncoding, + generator?: number | ArrayBuffer | NodeJS.ArrayBufferView, + ): DiffieHellman; + function createDiffieHellman( + prime: string, + primeEncoding: BinaryToTextEncoding, + generator: string, + generatorEncoding: BinaryToTextEncoding, + ): DiffieHellman; /** * The `DiffieHellman` class is a utility for creating Diffie-Hellman key * exchanges. @@ -1459,11 +1579,11 @@ declare module 'crypto' { * Instances of the `DiffieHellman` class can be created using the {@link createDiffieHellman} function. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * const { - * createDiffieHellman - * } = await import('crypto'); + * createDiffieHellman, + * } = await import('node:crypto'); * * // Generate Alice's keys... * const alice = createDiffieHellman(2048); @@ -1485,10 +1605,15 @@ declare module 'crypto' { class DiffieHellman { private constructor(); /** - * Generates private and public Diffie-Hellman key values, and returns + * Generates private and public Diffie-Hellman key values unless they have been + * generated or computed already, and returns * the public key in the specified `encoding`. This key should be * transferred to the other party. * If `encoding` is provided a string is returned; otherwise a `Buffer` is returned. + * + * This function is a thin wrapper around [`DH_generate_key()`](https://www.openssl.org/docs/man3.0/man3/DH_generate_key.html). In particular, + * once a private key has been generated or set, calling this function only updates + * the public key but does not generate a new private key. * @since v0.5.0 * @param encoding The `encoding` of the return value. */ @@ -1509,8 +1634,16 @@ declare module 'crypto' { */ computeSecret(otherPublicKey: NodeJS.ArrayBufferView, inputEncoding?: null, outputEncoding?: null): Buffer; computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding, outputEncoding?: null): Buffer; - computeSecret(otherPublicKey: NodeJS.ArrayBufferView, inputEncoding: null, outputEncoding: BinaryToTextEncoding): string; - computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding, outputEncoding: BinaryToTextEncoding): string; + computeSecret( + otherPublicKey: NodeJS.ArrayBufferView, + inputEncoding: null, + outputEncoding: BinaryToTextEncoding, + ): string; + computeSecret( + otherPublicKey: string, + inputEncoding: BinaryToTextEncoding, + outputEncoding: BinaryToTextEncoding, + ): string; /** * Returns the Diffie-Hellman prime in the specified `encoding`. * If `encoding` is provided a string is @@ -1560,6 +1693,9 @@ declare module 'crypto' { * Sets the Diffie-Hellman private key. If the `encoding` argument is provided,`privateKey` is expected * to be a string. If no `encoding` is provided, `privateKey` is expected * to be a `Buffer`, `TypedArray`, or `DataView`. + * + * This function does not automatically compute the associated public key. Either `diffieHellman.setPublicKey()` or `diffieHellman.generateKeys()` can be + * used to manually provide the public key or to automatically derive it. * @since v0.5.0 * @param encoding The `encoding` of the `privateKey` string. */ @@ -1569,7 +1705,7 @@ declare module 'crypto' { * A bit field containing any warnings and/or errors resulting from a check * performed during initialization of the `DiffieHellman` object. * - * The following values are valid for this property (as defined in `constants`module): + * The following values are valid for this property (as defined in `node:constants` module): * * * `DH_CHECK_P_NOT_SAFE_PRIME` * * `DH_CHECK_P_NOT_PRIME` @@ -1608,12 +1744,12 @@ declare module 'crypto' { (name: string): DiffieHellmanGroup; readonly prototype: DiffieHellmanGroup; } - type DiffieHellmanGroup = Omit; + type DiffieHellmanGroup = Omit; /** * Creates a predefined `DiffieHellmanGroup` key exchange object. The - * supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in [RFC 2412](https://www.rfc-editor.org/rfc/rfc2412.txt), but see `Caveats`) and `'modp14'`, `'modp15'`,`'modp16'`, `'modp17'`, - * `'modp18'` (defined in [RFC 3526](https://www.rfc-editor.org/rfc/rfc3526.txt)). The - * returned object mimics the interface of objects created by {@link createDiffieHellman}, but will not allow changing + * supported groups are listed in the documentation for `DiffieHellmanGroup`. + * + * The returned object mimics the interface of objects created by {@link createDiffieHellman}, but will not allow changing * the keys (with `diffieHellman.setPublicKey()`, for example). The * advantage of using this method is that the parties do not have to * generate nor exchange a group modulus beforehand, saving both processor @@ -1623,8 +1759,8 @@ declare module 'crypto' { * * ```js * const { - * getDiffieHellman - * } = await import('crypto'); + * getDiffieHellman, + * } = await import('node:crypto'); * const alice = getDiffieHellman('modp14'); * const bob = getDiffieHellman('modp14'); * @@ -1654,9 +1790,6 @@ declare module 'crypto' { * otherwise `err` will be `null`. By default, the successfully generated`derivedKey` will be passed to the callback as a `Buffer`. An error will be * thrown if any of the input arguments specify invalid values or types. * - * If `digest` is `null`, `'sha1'` will be used. This behavior is deprecated, - * please specify a `digest` explicitly. - * * The `iterations` argument must be a number set as high as possible. The * higher the number of iterations, the more secure the derived key will be, * but will take a longer amount of time to complete. @@ -1668,8 +1801,8 @@ declare module 'crypto' { * * ```js * const { - * pbkdf2 - * } = await import('crypto'); + * pbkdf2, + * } = await import('node:crypto'); * * pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => { * if (err) throw err; @@ -1677,25 +1810,20 @@ declare module 'crypto' { * }); * ``` * - * The `crypto.DEFAULT_ENCODING` property can be used to change the way the`derivedKey` is passed to the callback. This property, however, has been - * deprecated and use should be avoided. - * - * ```js - * import crypto from 'crypto'; - * crypto.DEFAULT_ENCODING = 'hex'; - * crypto.pbkdf2('secret', 'salt', 100000, 512, 'sha512', (err, derivedKey) => { - * if (err) throw err; - * console.log(derivedKey); // '3745e48...aa39b34' - * }); - * ``` - * * An array of supported digest functions can be retrieved using {@link getHashes}. * * This API uses libuv's threadpool, which can have surprising and * negative performance implications for some applications; see the `UV_THREADPOOL_SIZE` documentation for more information. * @since v0.5.5 */ - function pbkdf2(password: BinaryLike, salt: BinaryLike, iterations: number, keylen: number, digest: string, callback: (err: Error | null, derivedKey: Buffer) => void): void; + function pbkdf2( + password: BinaryLike, + salt: BinaryLike, + iterations: number, + keylen: number, + digest: string, + callback: (err: Error | null, derivedKey: Buffer) => void, + ): void; /** * Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2) * implementation. A selected HMAC digest algorithm specified by `digest` is @@ -1704,9 +1832,6 @@ declare module 'crypto' { * If an error occurs an `Error` will be thrown, otherwise the derived key will be * returned as a `Buffer`. * - * If `digest` is `null`, `'sha1'` will be used. This behavior is deprecated, - * please specify a `digest` explicitly. - * * The `iterations` argument must be a number set as high as possible. The * higher the number of iterations, the more secure the derived key will be, * but will take a longer amount of time to complete. @@ -1718,27 +1843,23 @@ declare module 'crypto' { * * ```js * const { - * pbkdf2Sync - * } = await import('crypto'); + * pbkdf2Sync, + * } = await import('node:crypto'); * * const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512'); * console.log(key.toString('hex')); // '3745e48...08d59ae' * ``` * - * The `crypto.DEFAULT_ENCODING` property may be used to change the way the`derivedKey` is returned. This property, however, is deprecated and use - * should be avoided. - * - * ```js - * import crypto from 'crypto'; - * crypto.DEFAULT_ENCODING = 'hex'; - * const key = crypto.pbkdf2Sync('secret', 'salt', 100000, 512, 'sha512'); - * console.log(key); // '3745e48...aa39b34' - * ``` - * * An array of supported digest functions can be retrieved using {@link getHashes}. * @since v0.9.3 */ - function pbkdf2Sync(password: BinaryLike, salt: BinaryLike, iterations: number, keylen: number, digest: string): Buffer; + function pbkdf2Sync( + password: BinaryLike, + salt: BinaryLike, + iterations: number, + keylen: number, + digest: string, + ): Buffer; /** * Generates cryptographically strong pseudorandom data. The `size` argument * is a number indicating the number of bytes to generate. @@ -1750,8 +1871,8 @@ declare module 'crypto' { * ```js * // Asynchronous * const { - * randomBytes - * } = await import('crypto'); + * randomBytes, + * } = await import('node:crypto'); * * randomBytes(256, (err, buf) => { * if (err) throw err; @@ -1766,8 +1887,8 @@ declare module 'crypto' { * ```js * // Synchronous * const { - * randomBytes - * } = await import('crypto'); + * randomBytes, + * } = await import('node:crypto'); * * const buf = randomBytes(256); * console.log( @@ -1808,8 +1929,8 @@ declare module 'crypto' { * ```js * // Asynchronous * const { - * randomInt - * } = await import('crypto'); + * randomInt, + * } = await import('node:crypto'); * * randomInt(3, (err, n) => { * if (err) throw err; @@ -1820,8 +1941,8 @@ declare module 'crypto' { * ```js * // Synchronous * const { - * randomInt - * } = await import('crypto'); + * randomInt, + * } = await import('node:crypto'); * * const n = randomInt(3); * console.log(`Random number chosen from (0, 1, 2): ${n}`); @@ -1830,8 +1951,8 @@ declare module 'crypto' { * ```js * // With `min` argument * const { - * randomInt - * } = await import('crypto'); + * randomInt, + * } = await import('node:crypto'); * * const n = randomInt(1, 7); * console.log(`The dice rolled: ${n}`); @@ -1849,8 +1970,8 @@ declare module 'crypto' { * Synchronous version of {@link randomFill}. * * ```js - * import { Buffer } from 'buffer'; - * const { randomFillSync } = await import('crypto'); + * import { Buffer } from 'node:buffer'; + * const { randomFillSync } = await import('node:crypto'); * * const buf = Buffer.alloc(10); * console.log(randomFillSync(buf).toString('hex')); @@ -1866,8 +1987,8 @@ declare module 'crypto' { * Any `ArrayBuffer`, `TypedArray` or `DataView` instance may be passed as`buffer`. * * ```js - * import { Buffer } from 'buffer'; - * const { randomFillSync } = await import('crypto'); + * import { Buffer } from 'node:buffer'; + * const { randomFillSync } = await import('node:crypto'); * * const a = new Uint32Array(10); * console.log(Buffer.from(randomFillSync(a).buffer, @@ -1895,8 +2016,8 @@ declare module 'crypto' { * If the `callback` function is not provided, an error will be thrown. * * ```js - * import { Buffer } from 'buffer'; - * const { randomFill } = await import('crypto'); + * import { Buffer } from 'node:buffer'; + * const { randomFill } = await import('node:crypto'); * * const buf = Buffer.alloc(10); * randomFill(buf, (err, buf) => { @@ -1925,8 +2046,8 @@ declare module 'crypto' { * distribution and have no meaningful lower or upper bounds. * * ```js - * import { Buffer } from 'buffer'; - * const { randomFill } = await import('crypto'); + * import { Buffer } from 'node:buffer'; + * const { randomFill } = await import('node:crypto'); * * const a = new Uint32Array(10); * randomFill(a, (err, buf) => { @@ -1962,9 +2083,21 @@ declare module 'crypto' { * @param [size=buffer.length - offset] * @param callback `function(err, buf) {}`. */ - function randomFill(buffer: T, callback: (err: Error | null, buf: T) => void): void; - function randomFill(buffer: T, offset: number, callback: (err: Error | null, buf: T) => void): void; - function randomFill(buffer: T, offset: number, size: number, callback: (err: Error | null, buf: T) => void): void; + function randomFill( + buffer: T, + callback: (err: Error | null, buf: T) => void, + ): void; + function randomFill( + buffer: T, + offset: number, + callback: (err: Error | null, buf: T) => void, + ): void; + function randomFill( + buffer: T, + offset: number, + size: number, + callback: (err: Error | null, buf: T) => void, + ): void; interface ScryptOptions { cost?: number | undefined; blockSize?: number | undefined; @@ -1992,8 +2125,8 @@ declare module 'crypto' { * * ```js * const { - * scrypt - * } = await import('crypto'); + * scrypt, + * } = await import('node:crypto'); * * // Using the factory defaults. * scrypt('password', 'salt', 64, (err, derivedKey) => { @@ -2008,8 +2141,19 @@ declare module 'crypto' { * ``` * @since v10.5.0 */ - function scrypt(password: BinaryLike, salt: BinaryLike, keylen: number, callback: (err: Error | null, derivedKey: Buffer) => void): void; - function scrypt(password: BinaryLike, salt: BinaryLike, keylen: number, options: ScryptOptions, callback: (err: Error | null, derivedKey: Buffer) => void): void; + function scrypt( + password: BinaryLike, + salt: BinaryLike, + keylen: number, + callback: (err: Error | null, derivedKey: Buffer) => void, + ): void; + function scrypt( + password: BinaryLike, + salt: BinaryLike, + keylen: number, + options: ScryptOptions, + callback: (err: Error | null, derivedKey: Buffer) => void, + ): void; /** * Provides a synchronous [scrypt](https://en.wikipedia.org/wiki/Scrypt) implementation. Scrypt is a password-based * key derivation function that is designed to be expensive computationally and @@ -2028,8 +2172,8 @@ declare module 'crypto' { * * ```js * const { - * scryptSync - * } = await import('crypto'); + * scryptSync, + * } = await import('node:crypto'); * // Using the factory defaults. * * const key1 = scryptSync('password', 'salt', 64); @@ -2100,8 +2244,8 @@ declare module 'crypto' { /** * ```js * const { - * getCiphers - * } = await import('crypto'); + * getCiphers, + * } = await import('node:crypto'); * * console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...] * ``` @@ -2112,8 +2256,8 @@ declare module 'crypto' { /** * ```js * const { - * getCurves - * } = await import('crypto'); + * getCurves, + * } = await import('node:crypto'); * * console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...] * ``` @@ -2127,7 +2271,8 @@ declare module 'crypto' { */ function getFips(): 1 | 0; /** - * Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build. Throws an error if FIPS mode is not available. + * Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build. + * Throws an error if FIPS mode is not available. * @since v10.0.0 * @param bool `true` to enable FIPS mode. */ @@ -2135,8 +2280,8 @@ declare module 'crypto' { /** * ```js * const { - * getHashes - * } = await import('crypto'); + * getHashes, + * } = await import('node:crypto'); * * console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...] * ``` @@ -2151,11 +2296,11 @@ declare module 'crypto' { * Instances of the `ECDH` class can be created using the {@link createECDH} function. * * ```js - * import assert from 'assert'; + * import assert from 'node:assert'; * * const { - * createECDH - * } = await import('crypto'); + * createECDH, + * } = await import('node:crypto'); * * // Generate Alice's keys... * const alice = createECDH('secp521r1'); @@ -2196,8 +2341,8 @@ declare module 'crypto' { * ```js * const { * createECDH, - * ECDH - * } = await import('crypto'); + * ECDH, + * } = await import('node:crypto'); * * const ecdh = createECDH('secp256k1'); * ecdh.generateKeys(); @@ -2222,8 +2367,8 @@ declare module 'crypto' { key: BinaryLike, curve: string, inputEncoding?: BinaryToTextEncoding, - outputEncoding?: 'latin1' | 'hex' | 'base64' | 'base64url', - format?: 'uncompressed' | 'compressed' | 'hybrid' + outputEncoding?: "latin1" | "hex" | "base64" | "base64url", + format?: "uncompressed" | "compressed" | "hybrid", ): Buffer | string; /** * Generates private and public EC Diffie-Hellman key values, and returns @@ -2259,7 +2404,11 @@ declare module 'crypto' { computeSecret(otherPublicKey: NodeJS.ArrayBufferView): Buffer; computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding): Buffer; computeSecret(otherPublicKey: NodeJS.ArrayBufferView, outputEncoding: BinaryToTextEncoding): string; - computeSecret(otherPublicKey: string, inputEncoding: BinaryToTextEncoding, outputEncoding: BinaryToTextEncoding): string; + computeSecret( + otherPublicKey: string, + inputEncoding: BinaryToTextEncoding, + outputEncoding: BinaryToTextEncoding, + ): string; /** * If `encoding` is specified, a string is returned; otherwise a `Buffer` is * returned. @@ -2279,7 +2428,7 @@ declare module 'crypto' { * @param [format='uncompressed'] * @return The EC Diffie-Hellman public key in the specified `encoding` and `format`. */ - getPublicKey(): Buffer; + getPublicKey(encoding?: null, format?: ECDHKeyFormat): Buffer; getPublicKey(encoding: BinaryToTextEncoding, format?: ECDHKeyFormat): string; /** * Sets the EC Diffie-Hellman private key. @@ -2304,28 +2453,33 @@ declare module 'crypto' { */ function createECDH(curveName: string): ECDH; /** - * This function is based on a constant-time algorithm. - * Returns true if `a` is equal to `b`, without leaking timing information that + * This function compares the underlying bytes that represent the given`ArrayBuffer`, `TypedArray`, or `DataView` instances using a constant-time + * algorithm. + * + * This function does not leak timing information that * would allow an attacker to guess one of the values. This is suitable for * comparing HMAC digests or secret values like authentication cookies or [capability urls](https://www.w3.org/TR/capability-urls/). * * `a` and `b` must both be `Buffer`s, `TypedArray`s, or `DataView`s, and they - * must have the same byte length. + * must have the same byte length. An error is thrown if `a` and `b` have + * different byte lengths. * * If at least one of `a` and `b` is a `TypedArray` with more than one byte per * entry, such as `Uint16Array`, the result will be computed using the platform * byte order. * + * **When both of the inputs are `Float32Array`s or`Float64Array`s, this function might return unexpected results due to IEEE 754** + * **encoding of floating-point numbers. In particular, neither `x === y` nor`Object.is(x, y)` implies that the byte representations of two floating-point** + * **numbers `x` and `y` are equal.** + * * Use of `crypto.timingSafeEqual` does not guarantee that the _surrounding_ code * is timing-safe. Care should be taken to ensure that the surrounding code does * not introduce timing vulnerabilities. * @since v6.6.0 */ function timingSafeEqual(a: NodeJS.ArrayBufferView, b: NodeJS.ArrayBufferView): boolean; - /** @deprecated since v10.0.0 */ - const DEFAULT_ENCODING: BufferEncoding; - type KeyType = 'rsa' | 'rsa-pss' | 'dsa' | 'ec' | 'ed25519' | 'ed448' | 'x25519' | 'x448'; - type KeyFormat = 'pem' | 'der'; + type KeyType = "rsa" | "rsa-pss" | "dsa" | "ec" | "ed25519" | "ed448" | "x25519" | "x448"; + type KeyFormat = "pem" | "der" | "jwk"; interface BasePrivateKeyEncodingOptions { format: T; cipher?: string | undefined; @@ -2344,6 +2498,10 @@ declare module 'crypto' { * Name of the curve to use */ namedCurve: string; + /** + * Must be `'named'` or `'explicit'`. Default: `'named'`. + */ + paramEncoding?: "explicit" | "named" | undefined; } interface RSAKeyPairKeyObjectOptions { /** @@ -2400,11 +2558,11 @@ declare module 'crypto' { */ publicExponent?: number | undefined; publicKeyEncoding: { - type: 'pkcs1' | 'spki'; + type: "pkcs1" | "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs1' | 'pkcs8'; + type: "pkcs1" | "pkcs8"; }; } interface RSAPSSKeyPairOptions { @@ -2430,11 +2588,11 @@ declare module 'crypto' { */ saltLength?: string; publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } interface DSAKeyPairOptions { @@ -2447,60 +2605,56 @@ declare module 'crypto' { */ divisorLength: number; publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } - interface ECKeyPairOptions { - /** - * Name of the curve to use. - */ - namedCurve: string; + interface ECKeyPairOptions extends ECKeyPairKeyObjectOptions { publicKeyEncoding: { - type: 'pkcs1' | 'spki'; + type: "pkcs1" | "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'sec1' | 'pkcs8'; + type: "sec1" | "pkcs8"; }; } interface ED25519KeyPairOptions { publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } interface ED448KeyPairOptions { publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } interface X25519KeyPairOptions { publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } interface X448KeyPairOptions { publicKeyEncoding: { - type: 'spki'; + type: "spki"; format: PubF; }; privateKeyEncoding: BasePrivateKeyEncodingOptions & { - type: 'pkcs8'; + type: "pkcs8"; }; } interface KeyPairSyncResult { @@ -2521,8 +2675,8 @@ declare module 'crypto' { * * ```js * const { - * generateKeyPairSync - * } = await import('crypto'); + * generateKeyPairSync, + * } = await import('node:crypto'); * * const { * publicKey, @@ -2531,14 +2685,14 @@ declare module 'crypto' { * modulusLength: 4096, * publicKeyEncoding: { * type: 'spki', - * format: 'pem' + * format: 'pem', * }, * privateKeyEncoding: { * type: 'pkcs8', * format: 'pem', * cipher: 'aes-256-cbc', - * passphrase: 'top secret' - * } + * passphrase: 'top secret', + * }, * }); * ``` * @@ -2548,46 +2702,142 @@ declare module 'crypto' { * @since v10.12.0 * @param type Must be `'rsa'`, `'rsa-pss'`, `'dsa'`, `'ec'`, `'ed25519'`, `'ed448'`, `'x25519'`, `'x448'`, or `'dh'`. */ - function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa', options: RSAKeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa', options: RSAKeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'rsa-pss', options: RSAPSSKeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'dsa', options: DSAKeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'dsa', options: DSAKeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ec', options: ECKeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ec', options: ECKeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed25519', options?: ED25519KeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed448', options: ED448KeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'ed448', options?: ED448KeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x25519', options: X25519KeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x25519', options?: X25519KeyPairKeyObjectOptions): KeyPairKeyObjectResult; - function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'pem', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'pem', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'der', 'pem'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x448', options: X448KeyPairOptions<'der', 'der'>): KeyPairSyncResult; - function generateKeyPairSync(type: 'x448', options?: X448KeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "rsa", + options: RSAKeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa", + options: RSAKeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa", + options: RSAKeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa", + options: RSAKeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "rsa", options: RSAKeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "rsa-pss", options: RSAPSSKeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "dsa", + options: DSAKeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "dsa", + options: DSAKeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "dsa", + options: DSAKeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "dsa", + options: DSAKeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "dsa", options: DSAKeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "ec", + options: ECKeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ec", + options: ECKeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ec", + options: ECKeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ec", + options: ECKeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "ec", options: ECKeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed25519", + options: ED25519KeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed25519", + options: ED25519KeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "ed25519", options?: ED25519KeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "ed448", + options: ED448KeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed448", + options: ED448KeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed448", + options: ED448KeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "ed448", + options: ED448KeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "ed448", options?: ED448KeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "x25519", + options: X25519KeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x25519", + options: X25519KeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x25519", + options: X25519KeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x25519", + options: X25519KeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "x25519", options?: X25519KeyPairKeyObjectOptions): KeyPairKeyObjectResult; + function generateKeyPairSync( + type: "x448", + options: X448KeyPairOptions<"pem", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x448", + options: X448KeyPairOptions<"pem", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x448", + options: X448KeyPairOptions<"der", "pem">, + ): KeyPairSyncResult; + function generateKeyPairSync( + type: "x448", + options: X448KeyPairOptions<"der", "der">, + ): KeyPairSyncResult; + function generateKeyPairSync(type: "x448", options?: X448KeyPairKeyObjectOptions): KeyPairKeyObjectResult; /** * Generates a new asymmetric key pair of the given `type`. RSA, RSA-PSS, DSA, EC, * Ed25519, Ed448, X25519, X448, and DH are currently supported. @@ -2600,21 +2850,21 @@ declare module 'crypto' { * * ```js * const { - * generateKeyPair - * } = await import('crypto'); + * generateKeyPair, + * } = await import('node:crypto'); * * generateKeyPair('rsa', { * modulusLength: 4096, * publicKeyEncoding: { * type: 'spki', - * format: 'pem' + * format: 'pem', * }, * privateKeyEncoding: { * type: 'pkcs8', * format: 'pem', * cipher: 'aes-256-cbc', - * passphrase: 'top secret' - * } + * passphrase: 'top secret', + * }, * }, (err, publicKey, privateKey) => { * // Handle errors and use the generated key pair. * }); @@ -2627,279 +2877,448 @@ declare module 'crypto' { * @since v10.12.0 * @param type Must be `'rsa'`, `'rsa-pss'`, `'dsa'`, `'ec'`, `'ed25519'`, `'ed448'`, `'x25519'`, `'x448'`, or `'dh'`. */ - function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'rsa', options: RSAKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'rsa', options: RSAKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'rsa-pss', options: RSAPSSKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'rsa-pss', options: RSAPSSKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'dsa', options: DSAKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'dsa', options: DSAKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'ec', options: ECKeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ec', options: ECKeyPairKeyObjectOptions, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'ed25519', options: ED25519KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ed25519', options: ED25519KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'ed448', options: ED448KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'ed448', options: ED448KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'x25519', options: X25519KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'x25519', options: X25519KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; - function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'pem', 'pem'>, callback: (err: Error | null, publicKey: string, privateKey: string) => void): void; - function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'pem', 'der'>, callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'der', 'pem'>, callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void): void; - function generateKeyPair(type: 'x448', options: X448KeyPairOptions<'der', 'der'>, callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void): void; - function generateKeyPair(type: 'x448', options: X448KeyPairKeyObjectOptions | undefined, callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void): void; + function generateKeyPair( + type: "rsa", + options: RSAKeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "rsa", + options: RSAKeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "rsa", + options: RSAKeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "rsa", + options: RSAKeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "rsa", + options: RSAKeyPairKeyObjectOptions, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "rsa-pss", + options: RSAPSSKeyPairKeyObjectOptions, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "dsa", + options: DSAKeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "dsa", + options: DSAKeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "dsa", + options: DSAKeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "dsa", + options: DSAKeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "dsa", + options: DSAKeyPairKeyObjectOptions, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "ec", + options: ECKeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ec", + options: ECKeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ec", + options: ECKeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ec", + options: ECKeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ec", + options: ECKeyPairKeyObjectOptions, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ed25519", + options: ED25519KeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ed25519", + options: ED25519KeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ed25519", + options: ED25519KeyPairKeyObjectOptions | undefined, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "ed448", + options: ED448KeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ed448", + options: ED448KeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ed448", + options: ED448KeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "ed448", + options: ED448KeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "ed448", + options: ED448KeyPairKeyObjectOptions | undefined, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "x25519", + options: X25519KeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "x25519", + options: X25519KeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "x25519", + options: X25519KeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "x25519", + options: X25519KeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "x25519", + options: X25519KeyPairKeyObjectOptions | undefined, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; + function generateKeyPair( + type: "x448", + options: X448KeyPairOptions<"pem", "pem">, + callback: (err: Error | null, publicKey: string, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "x448", + options: X448KeyPairOptions<"pem", "der">, + callback: (err: Error | null, publicKey: string, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "x448", + options: X448KeyPairOptions<"der", "pem">, + callback: (err: Error | null, publicKey: Buffer, privateKey: string) => void, + ): void; + function generateKeyPair( + type: "x448", + options: X448KeyPairOptions<"der", "der">, + callback: (err: Error | null, publicKey: Buffer, privateKey: Buffer) => void, + ): void; + function generateKeyPair( + type: "x448", + options: X448KeyPairKeyObjectOptions | undefined, + callback: (err: Error | null, publicKey: KeyObject, privateKey: KeyObject) => void, + ): void; namespace generateKeyPair { function __promisify__( - type: 'rsa', - options: RSAKeyPairOptions<'pem', 'pem'> + type: "rsa", + options: RSAKeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'rsa', - options: RSAKeyPairOptions<'pem', 'der'> + type: "rsa", + options: RSAKeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'rsa', - options: RSAKeyPairOptions<'der', 'pem'> + type: "rsa", + options: RSAKeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'rsa', - options: RSAKeyPairOptions<'der', 'der'> + type: "rsa", + options: RSAKeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'rsa', options: RSAKeyPairKeyObjectOptions): Promise; + function __promisify__(type: "rsa", options: RSAKeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'rsa-pss', - options: RSAPSSKeyPairOptions<'pem', 'pem'> + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'rsa-pss', - options: RSAPSSKeyPairOptions<'pem', 'der'> + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'rsa-pss', - options: RSAPSSKeyPairOptions<'der', 'pem'> + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'rsa-pss', - options: RSAPSSKeyPairOptions<'der', 'der'> + type: "rsa-pss", + options: RSAPSSKeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'rsa-pss', options: RSAPSSKeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'dsa', - options: DSAKeyPairOptions<'pem', 'pem'> + type: "rsa-pss", + options: RSAPSSKeyPairKeyObjectOptions, + ): Promise; + function __promisify__( + type: "dsa", + options: DSAKeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'dsa', - options: DSAKeyPairOptions<'pem', 'der'> + type: "dsa", + options: DSAKeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'dsa', - options: DSAKeyPairOptions<'der', 'pem'> + type: "dsa", + options: DSAKeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'dsa', - options: DSAKeyPairOptions<'der', 'der'> + type: "dsa", + options: DSAKeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'dsa', options: DSAKeyPairKeyObjectOptions): Promise; + function __promisify__(type: "dsa", options: DSAKeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'ec', - options: ECKeyPairOptions<'pem', 'pem'> + type: "ec", + options: ECKeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'ec', - options: ECKeyPairOptions<'pem', 'der'> + type: "ec", + options: ECKeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'ec', - options: ECKeyPairOptions<'der', 'pem'> + type: "ec", + options: ECKeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'ec', - options: ECKeyPairOptions<'der', 'der'> + type: "ec", + options: ECKeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'ec', options: ECKeyPairKeyObjectOptions): Promise; + function __promisify__(type: "ec", options: ECKeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'ed25519', - options: ED25519KeyPairOptions<'pem', 'pem'> + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'ed25519', - options: ED25519KeyPairOptions<'pem', 'der'> + type: "ed25519", + options: ED25519KeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'ed25519', - options: ED25519KeyPairOptions<'der', 'pem'> + type: "ed25519", + options: ED25519KeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'ed25519', - options: ED25519KeyPairOptions<'der', 'der'> + type: "ed25519", + options: ED25519KeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'ed25519', options?: ED25519KeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'ed448', - options: ED448KeyPairOptions<'pem', 'pem'> + type: "ed25519", + options?: ED25519KeyPairKeyObjectOptions, + ): Promise; + function __promisify__( + type: "ed448", + options: ED448KeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'ed448', - options: ED448KeyPairOptions<'pem', 'der'> + type: "ed448", + options: ED448KeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'ed448', - options: ED448KeyPairOptions<'der', 'pem'> + type: "ed448", + options: ED448KeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'ed448', - options: ED448KeyPairOptions<'der', 'der'> + type: "ed448", + options: ED448KeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'ed448', options?: ED448KeyPairKeyObjectOptions): Promise; + function __promisify__(type: "ed448", options?: ED448KeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'x25519', - options: X25519KeyPairOptions<'pem', 'pem'> + type: "x25519", + options: X25519KeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'x25519', - options: X25519KeyPairOptions<'pem', 'der'> + type: "x25519", + options: X25519KeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'x25519', - options: X25519KeyPairOptions<'der', 'pem'> + type: "x25519", + options: X25519KeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'x25519', - options: X25519KeyPairOptions<'der', 'der'> + type: "x25519", + options: X25519KeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'x25519', options?: X25519KeyPairKeyObjectOptions): Promise; function __promisify__( - type: 'x448', - options: X448KeyPairOptions<'pem', 'pem'> + type: "x25519", + options?: X25519KeyPairKeyObjectOptions, + ): Promise; + function __promisify__( + type: "x448", + options: X448KeyPairOptions<"pem", "pem">, ): Promise<{ publicKey: string; privateKey: string; }>; function __promisify__( - type: 'x448', - options: X448KeyPairOptions<'pem', 'der'> + type: "x448", + options: X448KeyPairOptions<"pem", "der">, ): Promise<{ publicKey: string; privateKey: Buffer; }>; function __promisify__( - type: 'x448', - options: X448KeyPairOptions<'der', 'pem'> + type: "x448", + options: X448KeyPairOptions<"der", "pem">, ): Promise<{ publicKey: Buffer; privateKey: string; }>; function __promisify__( - type: 'x448', - options: X448KeyPairOptions<'der', 'der'> + type: "x448", + options: X448KeyPairOptions<"der", "der">, ): Promise<{ publicKey: Buffer; privateKey: Buffer; }>; - function __promisify__(type: 'x448', options?: X448KeyPairKeyObjectOptions): Promise; + function __promisify__(type: "x448", options?: X448KeyPairKeyObjectOptions): Promise; } /** * Calculates and returns the signature for `data` using the given private key and @@ -2913,12 +3332,16 @@ declare module 'crypto' { * If the `callback` function is provided this function uses libuv's threadpool. * @since v12.0.0 */ - function sign(algorithm: string | null | undefined, data: NodeJS.ArrayBufferView, key: KeyLike | SignKeyObjectInput | SignPrivateKeyInput): Buffer; function sign( algorithm: string | null | undefined, data: NodeJS.ArrayBufferView, key: KeyLike | SignKeyObjectInput | SignPrivateKeyInput, - callback: (error: Error | null, data: Buffer) => void + ): Buffer; + function sign( + algorithm: string | null | undefined, + data: NodeJS.ArrayBufferView, + key: KeyLike | SignKeyObjectInput | SignPrivateKeyInput, + callback: (error: Error | null, data: Buffer) => void, ): void; /** * Verifies the given signature for `data` using the given key and algorithm. If`algorithm` is `null` or `undefined`, then the algorithm is dependent upon the @@ -2936,13 +3359,18 @@ declare module 'crypto' { * If the `callback` function is provided this function uses libuv's threadpool. * @since v12.0.0 */ - function verify(algorithm: string | null | undefined, data: NodeJS.ArrayBufferView, key: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, signature: NodeJS.ArrayBufferView): boolean; function verify( algorithm: string | null | undefined, data: NodeJS.ArrayBufferView, - key: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput, + key: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput | VerifyJsonWebKeyInput, signature: NodeJS.ArrayBufferView, - callback: (error: Error | null, result: boolean) => void + ): boolean; + function verify( + algorithm: string | null | undefined, + data: NodeJS.ArrayBufferView, + key: KeyLike | VerifyKeyObjectInput | VerifyPublicKeyInput | VerifyJsonWebKeyInput, + signature: NodeJS.ArrayBufferView, + callback: (error: Error | null, result: boolean) => void, ): void; /** * Computes the Diffie-Hellman secret based on a `privateKey` and a `publicKey`. @@ -2950,7 +3378,7 @@ declare module 'crypto' { * @since v13.9.0, v12.17.0 */ function diffieHellman(options: { privateKey: KeyObject; publicKey: KeyObject }): Buffer; - type CipherMode = 'cbc' | 'ccm' | 'cfb' | 'ctr' | 'ecb' | 'gcm' | 'ocb' | 'ofb' | 'stream' | 'wrap' | 'xts'; + type CipherMode = "cbc" | "ccm" | "cfb" | "ctr" | "ecb" | "gcm" | "ocb" | "ofb" | "stream" | "wrap" | "xts"; interface CipherInfoOptions { /** * A test key length. @@ -3010,10 +3438,10 @@ declare module 'crypto' { * of the input arguments specify invalid values or types. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * const { - * hkdf - * } = await import('crypto'); + * hkdf, + * } = await import('node:crypto'); * * hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => { * if (err) throw err; @@ -3022,13 +3450,20 @@ declare module 'crypto' { * ``` * @since v15.0.0 * @param digest The digest algorithm to use. - * @param ikm The input keying material. It must be at least one byte in length. + * @param ikm The input keying material. Must be provided but can be zero-length. * @param salt The salt value. Must be provided but can be zero-length. * @param info Additional info value. Must be provided but can be zero-length, and cannot be more than 1024 bytes. * @param keylen The length of the key to generate. Must be greater than 0. The maximum allowable value is `255` times the number of bytes produced by the selected digest function (e.g. `sha512` * generates 64-byte hashes, making the maximum HKDF output 16320 bytes). */ - function hkdf(digest: string, irm: BinaryLike | KeyObject, salt: BinaryLike, info: BinaryLike, keylen: number, callback: (err: Error | null, derivedKey: ArrayBuffer) => void): void; + function hkdf( + digest: string, + irm: BinaryLike | KeyObject, + salt: BinaryLike, + info: BinaryLike, + keylen: number, + callback: (err: Error | null, derivedKey: ArrayBuffer) => void, + ): void; /** * Provides a synchronous HKDF key derivation function as defined in RFC 5869\. The * given `ikm`, `salt` and `info` are used with the `digest` to derive a key of`keylen` bytes. @@ -3039,23 +3474,29 @@ declare module 'crypto' { * types, or if the derived key cannot be generated. * * ```js - * import { Buffer } from 'buffer'; + * import { Buffer } from 'node:buffer'; * const { - * hkdfSync - * } = await import('crypto'); + * hkdfSync, + * } = await import('node:crypto'); * * const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64); * console.log(Buffer.from(derivedKey).toString('hex')); // '24156e2...5391653' * ``` * @since v15.0.0 * @param digest The digest algorithm to use. - * @param ikm The input keying material. It must be at least one byte in length. + * @param ikm The input keying material. Must be provided but can be zero-length. * @param salt The salt value. Must be provided but can be zero-length. * @param info Additional info value. Must be provided but can be zero-length, and cannot be more than 1024 bytes. * @param keylen The length of the key to generate. Must be greater than 0. The maximum allowable value is `255` times the number of bytes produced by the selected digest function (e.g. `sha512` * generates 64-byte hashes, making the maximum HKDF output 16320 bytes). */ - function hkdfSync(digest: string, ikm: BinaryLike | KeyObject, salt: BinaryLike, info: BinaryLike, keylen: number): ArrayBuffer; + function hkdfSync( + digest: string, + ikm: BinaryLike | KeyObject, + salt: BinaryLike, + info: BinaryLike, + keylen: number, + ): ArrayBuffer; interface SecureHeapUsage { /** * The total allocated secure heap size as specified using the `--secure-heap=n` command-line flag. @@ -3092,37 +3533,37 @@ declare module 'crypto' { /** * Generates a random [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122.txt) version 4 UUID. The UUID is generated using a * cryptographic pseudorandom number generator. - * @since v15.6.0 + * @since v15.6.0, v14.17.0 */ function randomUUID(options?: RandomUUIDOptions): string; interface X509CheckOptions { /** * @default 'always' */ - subject: 'always' | 'never'; + subject?: "always" | "default" | "never"; /** * @default true */ - wildcards: boolean; + wildcards?: boolean; /** * @default true */ - partialWildcards: boolean; + partialWildcards?: boolean; /** * @default false */ - multiLabelWildcards: boolean; + multiLabelWildcards?: boolean; /** * @default false */ - singleLabelSubdomains: boolean; + singleLabelSubdomains?: boolean; } /** * Encapsulates an X509 certificate and provides read-only access to * its information. * * ```js - * const { X509Certificate } = await import('crypto'); + * const { X509Certificate } = await import('node:crypto'); * * const x509 = new X509Certificate('{... pem encoded cert ...}'); * @@ -3132,12 +3573,16 @@ declare module 'crypto' { */ class X509Certificate { /** - * Will be \`true\` if this is a Certificate Authority (ca) certificate. + * Will be \`true\` if this is a Certificate Authority (CA) certificate. * @since v15.6.0 */ readonly ca: boolean; /** * The SHA-1 fingerprint of this certificate. + * + * Because SHA-1 is cryptographically broken and because the security of SHA-1 is + * significantly worse than that of algorithms that are commonly used to sign + * certificates, consider using `x509.fingerprint256` instead. * @since v15.6.0 */ readonly fingerprint: string; @@ -3148,23 +3593,53 @@ declare module 'crypto' { readonly fingerprint256: string; /** * The SHA-512 fingerprint of this certificate. - * @since v16.14.0 + * + * Because computing the SHA-256 fingerprint is usually faster and because it is + * only half the size of the SHA-512 fingerprint, `x509.fingerprint256` may be + * a better choice. While SHA-512 presumably provides a higher level of security in + * general, the security of SHA-256 matches that of most algorithms that are + * commonly used to sign certificates. + * @since v17.2.0, v16.14.0 */ - readonly fingerprint512: string; + readonly fingerprint512: string; /** * The complete subject of this certificate. * @since v15.6.0 */ readonly subject: string; /** - * The subject alternative name specified for this certificate or `undefined` - * if not available. + * The subject alternative name specified for this certificate. + * + * This is a comma-separated list of subject alternative names. Each entry begins + * with a string identifying the kind of the subject alternative name followed by + * a colon and the value associated with the entry. + * + * Earlier versions of Node.js incorrectly assumed that it is safe to split this + * property at the two-character sequence `', '` (see [CVE-2021-44532](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44532)). However, + * both malicious and legitimate certificates can contain subject alternative names + * that include this sequence when represented as a string. + * + * After the prefix denoting the type of the entry, the remainder of each entry + * might be enclosed in quotes to indicate that the value is a JSON string literal. + * For backward compatibility, Node.js only uses JSON string literals within this + * property when necessary to avoid ambiguity. Third-party code should be prepared + * to handle both possible entry formats. * @since v15.6.0 */ readonly subjectAltName: string | undefined; /** - * The information access content of this certificate or `undefined` if not - * available. + * A textual representation of the certificate's authority information access + * extension. + * + * This is a line feed separated list of access descriptions. Each line begins with + * the access method and the kind of the access location, followed by a colon and + * the value associated with the access location. + * + * After the prefix denoting the access method and the kind of the access location, + * the remainder of each line might be enclosed in quotes to indicate that the + * value is a JSON string literal. For backward compatibility, Node.js only uses + * JSON string literals within this property when necessary to avoid ambiguity. + * Third-party code should be prepared to handle both possible entry formats. * @since v15.6.0 */ readonly infoAccess: string | undefined; @@ -3196,6 +3671,10 @@ declare module 'crypto' { readonly raw: Buffer; /** * The serial number of this certificate. + * + * Serial numbers are assigned by certificate authorities and do not uniquely + * identify certificates. Consider using `x509.fingerprint256` as a unique + * identifier instead. * @since v15.6.0 */ readonly serialNumber: string; @@ -3212,18 +3691,50 @@ declare module 'crypto' { constructor(buffer: BinaryLike); /** * Checks whether the certificate matches the given email address. + * + * If the `'subject'` option is undefined or set to `'default'`, the certificate + * subject is only considered if the subject alternative name extension either does + * not exist or does not contain any email addresses. + * + * If the `'subject'` option is set to `'always'` and if the subject alternative + * name extension either does not exist or does not contain a matching email + * address, the certificate subject is considered. + * + * If the `'subject'` option is set to `'never'`, the certificate subject is never + * considered, even if the certificate contains no subject alternative names. * @since v15.6.0 * @return Returns `email` if the certificate matches, `undefined` if it does not. */ - checkEmail(email: string, options?: Pick): string | undefined; + checkEmail(email: string, options?: Pick): string | undefined; /** * Checks whether the certificate matches the given host name. + * + * If the certificate matches the given host name, the matching subject name is + * returned. The returned name might be an exact match (e.g., `foo.example.com`) + * or it might contain wildcards (e.g., `*.example.com`). Because host name + * comparisons are case-insensitive, the returned subject name might also differ + * from the given `name` in capitalization. + * + * If the `'subject'` option is undefined or set to `'default'`, the certificate + * subject is only considered if the subject alternative name extension either does + * not exist or does not contain any DNS names. This behavior is consistent with [RFC 2818](https://www.rfc-editor.org/rfc/rfc2818.txt) ("HTTP Over TLS"). + * + * If the `'subject'` option is set to `'always'` and if the subject alternative + * name extension either does not exist or does not contain a matching DNS name, + * the certificate subject is considered. + * + * If the `'subject'` option is set to `'never'`, the certificate subject is never + * considered, even if the certificate contains no subject alternative names. * @since v15.6.0 - * @return Returns `name` if the certificate matches, `undefined` if it does not. + * @return Returns a subject name that matches `name`, or `undefined` if no subject name matches `name`. */ checkHost(name: string, options?: X509CheckOptions): string | undefined; /** * Checks whether the certificate matches the given IP address (IPv4 or IPv6). + * + * Only [RFC 5280](https://www.rfc-editor.org/rfc/rfc5280.txt) `iPAddress` subject alternative names are considered, and they + * must match the given `ip` address exactly. Other subject alternative names as + * well as the subject field of the certificate are ignored. * @since v15.6.0 * @return Returns `ip` if the certificate matches, `undefined` if it does not. */ @@ -3308,9 +3819,21 @@ declare module 'crypto' { * @param size The size (in bits) of the prime to generate. */ function generatePrime(size: number, callback: (err: Error | null, prime: ArrayBuffer) => void): void; - function generatePrime(size: number, options: GeneratePrimeOptionsBigInt, callback: (err: Error | null, prime: bigint) => void): void; - function generatePrime(size: number, options: GeneratePrimeOptionsArrayBuffer, callback: (err: Error | null, prime: ArrayBuffer) => void): void; - function generatePrime(size: number, options: GeneratePrimeOptions, callback: (err: Error | null, prime: ArrayBuffer | bigint) => void): void; + function generatePrime( + size: number, + options: GeneratePrimeOptionsBigInt, + callback: (err: Error | null, prime: bigint) => void, + ): void; + function generatePrime( + size: number, + options: GeneratePrimeOptionsArrayBuffer, + callback: (err: Error | null, prime: ArrayBuffer) => void, + ): void; + function generatePrime( + size: number, + options: GeneratePrimeOptions, + callback: (err: Error | null, prime: ArrayBuffer | bigint) => void, + ): void; /** * Generates a pseudorandom prime of `size` bits. * @@ -3345,7 +3868,7 @@ declare module 'crypto' { interface CheckPrimeOptions { /** * The number of Miller-Rabin probabilistic primality iterations to perform. - * When the value is 0 (zero), a number of checks is used that yields a false positive rate of at most 2-64 for random input. + * When the value is 0 (zero), a number of checks is used that yields a false positive rate of at most `2**-64` for random input. * Care must be used when selecting a number of checks. * Refer to the OpenSSL documentation for the BN_is_prime_ex function nchecks options for more details. * @@ -3359,7 +3882,11 @@ declare module 'crypto' { * @param candidate A possible prime encoded as a sequence of big endian octets of arbitrary length. */ function checkPrime(value: LargeNumberLike, callback: (err: Error | null, result: boolean) => void): void; - function checkPrime(value: LargeNumberLike, options: CheckPrimeOptions, callback: (err: Error | null, result: boolean) => void): void; + function checkPrime( + value: LargeNumberLike, + options: CheckPrimeOptions, + callback: (err: Error | null, result: boolean) => void, + ): void; /** * Checks the primality of the `candidate`. * @since v15.8.0 @@ -3372,30 +3899,36 @@ declare module 'crypto' { * * `engine` could be either an id or a path to the engine's shared library. * - * The optional `flags` argument uses `ENGINE_METHOD_ALL` by default. - * The `flags` is a bit field taking one of or a mix of the following flags (defined in `crypto.constants`): + * The optional `flags` argument uses `ENGINE_METHOD_ALL` by default. The `flags`is a bit field taking one of or a mix of the following flags (defined in`crypto.constants`): * - * - `crypto.constants.ENGINE_METHOD_RSA` - * - `crypto.constants.ENGINE_METHOD_DSA` - * - `crypto.constants.ENGINE_METHOD_DH` - * - `crypto.constants.ENGINE_METHOD_RAND` - * - `crypto.constants.ENGINE_METHOD_EC` - * - `crypto.constants.ENGINE_METHOD_CIPHERS` - * - `crypto.constants.ENGINE_METHOD_DIGESTS` - * - `crypto.constants.ENGINE_METHOD_PKEY_METHS` - * - `crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS` - * - `crypto.constants.ENGINE_METHOD_ALL` - * - `crypto.constants.ENGINE_METHOD_NONE` - * - * The flags below are deprecated in OpenSSL-1.1.0. - * - * - `crypto.constants.ENGINE_METHOD_ECDH` - * - `crypto.constants.ENGINE_METHOD_ECDSA` - * - `crypto.constants.ENGINE_METHOD_STORE` + * * `crypto.constants.ENGINE_METHOD_RSA` + * * `crypto.constants.ENGINE_METHOD_DSA` + * * `crypto.constants.ENGINE_METHOD_DH` + * * `crypto.constants.ENGINE_METHOD_RAND` + * * `crypto.constants.ENGINE_METHOD_EC` + * * `crypto.constants.ENGINE_METHOD_CIPHERS` + * * `crypto.constants.ENGINE_METHOD_DIGESTS` + * * `crypto.constants.ENGINE_METHOD_PKEY_METHS` + * * `crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS` + * * `crypto.constants.ENGINE_METHOD_ALL` + * * `crypto.constants.ENGINE_METHOD_NONE` * @since v0.11.11 - * @param [flags=crypto.constants.ENGINE_METHOD_ALL] + * @param flags */ function setEngine(engine: string, flags?: number): void; + /** + * A convenient alias for {@link webcrypto.getRandomValues}. This + * implementation is not compliant with the Web Crypto spec, to write + * web-compatible code use {@link webcrypto.getRandomValues} instead. + * @since v17.4.0 + * @return Returns `typedArray`. + */ + function getRandomValues(typedArray: T): T; + /** + * A convenient alias for `crypto.webcrypto.subtle`. + * @since v17.4.0 + */ + const subtle: webcrypto.SubtleCrypto; /** * An implementation of the Web Crypto API standard. * @@ -3405,9 +3938,17 @@ declare module 'crypto' { const webcrypto: webcrypto.Crypto; namespace webcrypto { type BufferSource = ArrayBufferView | ArrayBuffer; - type KeyFormat = 'jwk' | 'pkcs8' | 'raw' | 'spki'; - type KeyType = 'private' | 'public' | 'secret'; - type KeyUsage = 'decrypt' | 'deriveBits' | 'deriveKey' | 'encrypt' | 'sign' | 'unwrapKey' | 'verify' | 'wrapKey'; + type KeyFormat = "jwk" | "pkcs8" | "raw" | "spki"; + type KeyType = "private" | "public" | "secret"; + type KeyUsage = + | "decrypt" + | "deriveBits" + | "deriveKey" + | "encrypt" + | "sign" + | "unwrapKey" + | "verify" + | "wrapKey"; type AlgorithmIdentifier = Algorithm | string; type HashAlgorithmIdentifier = AlgorithmIdentifier; type NamedCurve = string; @@ -3561,7 +4102,7 @@ declare module 'crypto' { /** Illegal constructor */ (_: { readonly _: unique symbol }): never; // Allows instanceof to work but not be callable by the user. readonly length: 0; - readonly name: 'CryptoKey'; + readonly name: "CryptoKey"; readonly prototype: CryptoKey; } /** @@ -3634,21 +4175,34 @@ declare module 'crypto' { * - `'AES-GCM'` * @since v15.0.0 */ - decrypt(algorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, key: CryptoKey, data: BufferSource): Promise; + decrypt( + algorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, + key: CryptoKey, + data: BufferSource, + ): Promise; /** * Using the method and parameters specified in `algorithm` and the keying material provided by `baseKey`, * `subtle.deriveBits()` attempts to generate `length` bits. - * The Node.js implementation requires that `length` is a multiple of `8`. + * The Node.js implementation requires that when `length` is a number it must be multiple of `8`. + * When `length` is `null` the maximum number of bits for a given algorithm is generated. This is allowed + * for the `'ECDH'`, `'X25519'`, and `'X448'` algorithms. * If successful, the returned promise will be resolved with an `` containing the generated data. * * The algorithms currently supported include: * * - `'ECDH'` + * - `'X25519'` + * - `'X448'` * - `'HKDF'` * - `'PBKDF2'` * @since v15.0.0 */ - deriveBits(algorithm: AlgorithmIdentifier | EcdhKeyDeriveParams | HkdfParams | Pbkdf2Params, baseKey: CryptoKey, length: number): Promise; + deriveBits(algorithm: EcdhKeyDeriveParams, baseKey: CryptoKey, length: number | null): Promise; + deriveBits( + algorithm: AlgorithmIdentifier | HkdfParams | Pbkdf2Params, + baseKey: CryptoKey, + length: number, + ): Promise; /** * Using the method and parameters specified in `algorithm`, and the keying material provided by `baseKey`, * `subtle.deriveKey()` attempts to generate a new ` based on the method and parameters in `derivedKeyAlgorithm`. @@ -3659,6 +4213,8 @@ declare module 'crypto' { * The algorithms currently supported include: * * - `'ECDH'` + * - `'X25519'` + * - `'X448'` * - `'HKDF'` * - `'PBKDF2'` * @param keyUsages See {@link https://nodejs.org/docs/latest/api/webcrypto.html#cryptokeyusages Key usages}. @@ -3667,9 +4223,14 @@ declare module 'crypto' { deriveKey( algorithm: AlgorithmIdentifier | EcdhKeyDeriveParams | HkdfParams | Pbkdf2Params, baseKey: CryptoKey, - derivedKeyAlgorithm: AlgorithmIdentifier | AesDerivedKeyParams | HmacImportParams | HkdfParams | Pbkdf2Params, + derivedKeyAlgorithm: + | AlgorithmIdentifier + | AesDerivedKeyParams + | HmacImportParams + | HkdfParams + | Pbkdf2Params, extractable: boolean, - keyUsages: ReadonlyArray + keyUsages: readonly KeyUsage[], ): Promise; /** * Using the method identified by `algorithm`, `subtle.digest()` attempts to generate a digest of `data`. @@ -3699,7 +4260,11 @@ declare module 'crypto' { * - `'AES-GCM'` * @since v15.0.0 */ - encrypt(algorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, key: CryptoKey, data: BufferSource): Promise; + encrypt( + algorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, + key: CryptoKey, + data: BufferSource, + ): Promise; /** * Exports the given key into the specified format, if supported. * @@ -3714,8 +4279,8 @@ declare module 'crypto' { * @returns `` containing ``. * @since v15.0.0 */ - exportKey(format: 'jwk', key: CryptoKey): Promise; - exportKey(format: Exclude, key: CryptoKey): Promise; + exportKey(format: "jwk", key: CryptoKey): Promise; + exportKey(format: Exclude, key: CryptoKey): Promise; /** * Using the method and parameters provided in `algorithm`, * `subtle.generateKey()` attempts to generate new keying material. @@ -3727,7 +4292,11 @@ declare module 'crypto' { * - `'RSA-PSS'` * - `'RSA-OAEP'` * - `'ECDSA'` + * - `'Ed25519'` + * - `'Ed448'` * - `'ECDH'` + * - `'X25519'` + * - `'X448'` * The `` (secret key) generating algorithms supported include: * * - `'HMAC'` @@ -3738,9 +4307,21 @@ declare module 'crypto' { * @param keyUsages See {@link https://nodejs.org/docs/latest/api/webcrypto.html#cryptokeyusages Key usages}. * @since v15.0.0 */ - generateKey(algorithm: RsaHashedKeyGenParams | EcKeyGenParams, extractable: boolean, keyUsages: ReadonlyArray): Promise; - generateKey(algorithm: AesKeyGenParams | HmacKeyGenParams | Pbkdf2Params, extractable: boolean, keyUsages: ReadonlyArray): Promise; - generateKey(algorithm: AlgorithmIdentifier, extractable: boolean, keyUsages: KeyUsage[]): Promise; + generateKey( + algorithm: RsaHashedKeyGenParams | EcKeyGenParams, + extractable: boolean, + keyUsages: readonly KeyUsage[], + ): Promise; + generateKey( + algorithm: AesKeyGenParams | HmacKeyGenParams | Pbkdf2Params, + extractable: boolean, + keyUsages: readonly KeyUsage[], + ): Promise; + generateKey( + algorithm: AlgorithmIdentifier, + extractable: boolean, + keyUsages: KeyUsage[], + ): Promise; /** * The `subtle.importKey()` method attempts to interpret the provided `keyData` as the given `format` * to create a `` instance using the provided `algorithm`, `extractable`, and `keyUsages` arguments. @@ -3752,18 +4333,28 @@ declare module 'crypto' { * @since v15.0.0 */ importKey( - format: 'jwk', + format: "jwk", keyData: JsonWebKey, - algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm, + algorithm: + | AlgorithmIdentifier + | RsaHashedImportParams + | EcKeyImportParams + | HmacImportParams + | AesKeyAlgorithm, extractable: boolean, - keyUsages: ReadonlyArray + keyUsages: readonly KeyUsage[], ): Promise; importKey( - format: Exclude, + format: Exclude, keyData: BufferSource, - algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm, + algorithm: + | AlgorithmIdentifier + | RsaHashedImportParams + | EcKeyImportParams + | HmacImportParams + | AesKeyAlgorithm, extractable: boolean, - keyUsages: KeyUsage[] + keyUsages: KeyUsage[], ): Promise; /** * Using the method and parameters given by `algorithm` and the keying material provided by `key`, @@ -3775,10 +4366,16 @@ declare module 'crypto' { * - `'RSASSA-PKCS1-v1_5'` * - `'RSA-PSS'` * - `'ECDSA'` + * - `'Ed25519'` + * - `'Ed448'` * - `'HMAC'` * @since v15.0.0 */ - sign(algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams | Ed448Params, key: CryptoKey, data: BufferSource): Promise; + sign( + algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams | Ed448Params, + key: CryptoKey, + data: BufferSource, + ): Promise; /** * In cryptography, "wrapping a key" refers to exporting and then encrypting the keying material. * The `subtle.unwrapKey()` method attempts to decrypt a wrapped key and create a `` instance. @@ -3800,7 +4397,11 @@ declare module 'crypto' { * - `'RSA-PSS'` * - `'RSA-OAEP'` * - `'ECDSA'` + * - `'Ed25519'` + * - `'Ed448'` * - `'ECDH'` + * - `'X25519'` + * - `'X448'` * - `'HMAC'` * - `'AES-CTR'` * - `'AES-CBC'` @@ -3815,9 +4416,14 @@ declare module 'crypto' { wrappedKey: BufferSource, unwrappingKey: CryptoKey, unwrapAlgorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, - unwrappedKeyAlgorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm, + unwrappedKeyAlgorithm: + | AlgorithmIdentifier + | RsaHashedImportParams + | EcKeyImportParams + | HmacImportParams + | AesKeyAlgorithm, extractable: boolean, - keyUsages: KeyUsage[] + keyUsages: KeyUsage[], ): Promise; /** * Using the method and parameters given in `algorithm` and the keying material provided by `key`, @@ -3829,10 +4435,17 @@ declare module 'crypto' { * - `'RSASSA-PKCS1-v1_5'` * - `'RSA-PSS'` * - `'ECDSA'` + * - `'Ed25519'` + * - `'Ed448'` * - `'HMAC'` * @since v15.0.0 */ - verify(algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams | Ed448Params, key: CryptoKey, signature: BufferSource, data: BufferSource): Promise; + verify( + algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams | Ed448Params, + key: CryptoKey, + signature: BufferSource, + data: BufferSource, + ): Promise; /** * In cryptography, "wrapping a key" refers to exporting and then encrypting the keying material. * The `subtle.wrapKey()` method exports the keying material into the format identified by `format`, @@ -3851,10 +4464,15 @@ declare module 'crypto' { * @param format Must be one of `'raw'`, `'pkcs8'`, `'spki'`, or `'jwk'`. * @since v15.0.0 */ - wrapKey(format: KeyFormat, key: CryptoKey, wrappingKey: CryptoKey, wrapAlgorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams): Promise; + wrapKey( + format: KeyFormat, + key: CryptoKey, + wrappingKey: CryptoKey, + wrapAlgorithm: AlgorithmIdentifier | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams, + ): Promise; } } } -declare module 'node:crypto' { - export * from 'crypto'; +declare module "node:crypto" { + export * from "crypto"; } diff --git a/node_modules/@types/node/ts4.8/dgram.d.ts b/node_modules/@types/node/ts4.8/dgram.d.ts old mode 100755 new mode 100644 index d7b9ee2..0b86ae7 --- a/node_modules/@types/node/ts4.8/dgram.d.ts +++ b/node_modules/@types/node/ts4.8/dgram.d.ts @@ -1,13 +1,13 @@ /** - * The `dgram` module provides an implementation of UDP datagram sockets. + * The `node:dgram` module provides an implementation of UDP datagram sockets. * * ```js - * import dgram from 'dgram'; + * import dgram from 'node:dgram'; * * const server = dgram.createSocket('udp4'); * * server.on('error', (err) => { - * console.log(`server error:\n${err.stack}`); + * console.error(`server error:\n${err.stack}`); * server.close(); * }); * @@ -23,15 +23,15 @@ * server.bind(41234); * // Prints: server listening 0.0.0.0:41234 * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/dgram.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/dgram.js) */ -declare module 'dgram' { - import { AddressInfo } from 'node:net'; - import * as dns from 'node:dns'; - import { EventEmitter, Abortable } from 'node:events'; +declare module "dgram" { + import { AddressInfo } from "node:net"; + import * as dns from "node:dns"; + import { Abortable, EventEmitter } from "node:events"; interface RemoteInfo { address: string; - family: 'IPv4' | 'IPv6'; + family: "IPv4" | "IPv6"; port: number; size: number; } @@ -41,7 +41,7 @@ declare module 'dgram' { exclusive?: boolean | undefined; fd?: number | undefined; } - type SocketType = 'udp4' | 'udp6'; + type SocketType = "udp4" | "udp6"; interface SocketOptions extends Abortable { type: SocketType; reuseAddr?: boolean | undefined; @@ -51,7 +51,13 @@ declare module 'dgram' { ipv6Only?: boolean | undefined; recvBufferSize?: number | undefined; sendBufferSize?: number | undefined; - lookup?: ((hostname: string, options: dns.LookupOneOptions, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void) => void) | undefined; + lookup?: + | (( + hostname: string, + options: dns.LookupOneOptions, + callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, + ) => void) + | undefined; } /** * Creates a `dgram.Socket` object. Once the socket is created, calling `socket.bind()` will instruct the socket to begin listening for datagram @@ -98,8 +104,8 @@ declare module 'dgram' { * When sharing a UDP socket across multiple `cluster` workers, the`socket.addMembership()` function must be called only once or an`EADDRINUSE` error will occur: * * ```js - * import cluster from 'cluster'; - * import dgram from 'dgram'; + * import cluster from 'node:cluster'; + * import dgram from 'node:dgram'; * * if (cluster.isPrimary) { * cluster.fork(); // Works ok. @@ -116,7 +122,7 @@ declare module 'dgram' { addMembership(multicastAddress: string, multicastInterface?: string): void; /** * Returns an object containing the address information for a socket. - * For UDP sockets, this object will contain `address`, `family` and `port`properties. + * For UDP sockets, this object will contain `address`, `family`, and `port`properties. * * This method throws `EBADF` if called on an unbound socket. * @since v0.1.99 @@ -142,12 +148,12 @@ declare module 'dgram' { * Example of a UDP server listening on port 41234: * * ```js - * import dgram from 'dgram'; + * import dgram from 'node:dgram'; * * const server = dgram.createSocket('udp4'); * * server.on('error', (err) => { - * console.log(`server error:\n${err.stack}`); + * console.error(`server error:\n${err.stack}`); * server.close(); * }); * @@ -221,6 +227,16 @@ declare module 'dgram' { * @return the `SO_SNDBUF` socket send buffer size in bytes. */ getSendBufferSize(): number; + /** + * @since v18.8.0, v16.19.0 + * @return Number of bytes queued for sending. + */ + getSendQueueSize(): number; + /** + * @since v18.8.0, v16.19.0 + * @return Number of send requests currently in the queue awaiting to be processed. + */ + getSendQueueCount(): number; /** * By default, binding a socket will cause it to block the Node.js process from * exiting as long as the socket is open. The `socket.unref()` method can be used @@ -260,7 +276,7 @@ declare module 'dgram' { * * The `address` argument is a string. If the value of `address` is a host name, * DNS will be used to resolve the address of the host. If `address` is not - * provided or otherwise falsy, `'127.0.0.1'` (for `udp4` sockets) or `'::1'`(for `udp6` sockets) will be used by default. + * provided or otherwise nullish, `'127.0.0.1'` (for `udp4` sockets) or `'::1'`(for `udp6` sockets) will be used by default. * * If the socket has not been previously bound with a call to `bind`, the socket * is assigned a random port number and is bound to the "all interfaces" address @@ -284,8 +300,8 @@ declare module 'dgram' { * Example of sending a UDP packet to a port on `localhost`; * * ```js - * import dgram from 'dgram'; - * import { Buffer } from 'buffer'; + * import dgram from 'node:dgram'; + * import { Buffer } from 'node:buffer'; * * const message = Buffer.from('Some bytes'); * const client = dgram.createSocket('udp4'); @@ -297,8 +313,8 @@ declare module 'dgram' { * Example of sending a UDP packet composed of multiple buffers to a port on`127.0.0.1`; * * ```js - * import dgram from 'dgram'; - * import { Buffer } from 'buffer'; + * import dgram from 'node:dgram'; + * import { Buffer } from 'node:buffer'; * * const buf1 = Buffer.from('Some '); * const buf2 = Buffer.from('bytes'); @@ -316,8 +332,8 @@ declare module 'dgram' { * Example of sending a UDP packet using a socket connected to a port on`localhost`: * * ```js - * import dgram from 'dgram'; - * import { Buffer } from 'buffer'; + * import dgram from 'node:dgram'; + * import { Buffer } from 'node:buffer'; * * const message = Buffer.from('Some bytes'); * const client = dgram.createSocket('udp4'); @@ -335,12 +351,42 @@ declare module 'dgram' { * @param address Destination host name or IP address. * @param callback Called when the message has been sent. */ - send(msg: string | Uint8Array | ReadonlyArray, port?: number, address?: string, callback?: (error: Error | null, bytes: number) => void): void; - send(msg: string | Uint8Array | ReadonlyArray, port?: number, callback?: (error: Error | null, bytes: number) => void): void; - send(msg: string | Uint8Array | ReadonlyArray, callback?: (error: Error | null, bytes: number) => void): void; - send(msg: string | Uint8Array, offset: number, length: number, port?: number, address?: string, callback?: (error: Error | null, bytes: number) => void): void; - send(msg: string | Uint8Array, offset: number, length: number, port?: number, callback?: (error: Error | null, bytes: number) => void): void; - send(msg: string | Uint8Array, offset: number, length: number, callback?: (error: Error | null, bytes: number) => void): void; + send( + msg: string | Uint8Array | readonly any[], + port?: number, + address?: string, + callback?: (error: Error | null, bytes: number) => void, + ): void; + send( + msg: string | Uint8Array | readonly any[], + port?: number, + callback?: (error: Error | null, bytes: number) => void, + ): void; + send( + msg: string | Uint8Array | readonly any[], + callback?: (error: Error | null, bytes: number) => void, + ): void; + send( + msg: string | Uint8Array, + offset: number, + length: number, + port?: number, + address?: string, + callback?: (error: Error | null, bytes: number) => void, + ): void; + send( + msg: string | Uint8Array, + offset: number, + length: number, + port?: number, + callback?: (error: Error | null, bytes: number) => void, + ): void; + send( + msg: string | Uint8Array, + offset: number, + length: number, + callback?: (error: Error | null, bytes: number) => void, + ): void; /** * Sets or clears the `SO_BROADCAST` socket option. When set to `true`, UDP * packets may be sent to a local interface's broadcast address. @@ -451,7 +497,7 @@ declare module 'dgram' { * TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. * Changing TTL values is typically done for network probes or when multicasting. * - * The `ttl` argument may be between between 1 and 255\. The default on most systems + * The `ttl` argument may be between 1 and 255\. The default on most systems * is 64. * * This method throws `EBADF` if called on an unbound socket. @@ -465,7 +511,7 @@ declare module 'dgram' { * process active, allowing the process to exit even if the socket is still * listening. * - * Calling `socket.unref()` multiple times will have no addition effect. + * Calling `socket.unref()` multiple times will have no additional effect. * * The `socket.unref()` method returns a reference to the socket so calls can be * chained. @@ -503,43 +549,48 @@ declare module 'dgram' { * 5. message */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'connect', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'listening', listener: () => void): this; - addListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "connect", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "listening", listener: () => void): this; + addListener(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close'): boolean; - emit(event: 'connect'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'listening'): boolean; - emit(event: 'message', msg: Buffer, rinfo: RemoteInfo): boolean; + emit(event: "close"): boolean; + emit(event: "connect"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "listening"): boolean; + emit(event: "message", msg: Buffer, rinfo: RemoteInfo): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'connect', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'listening', listener: () => void): this; - on(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + on(event: "close", listener: () => void): this; + on(event: "connect", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "listening", listener: () => void): this; + on(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'connect', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'listening', listener: () => void): this; - once(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + once(event: "close", listener: () => void): this; + once(event: "connect", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "listening", listener: () => void): this; + once(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'connect', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'listening', listener: () => void): this; - prependListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "connect", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "listening", listener: () => void): this; + prependListener(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'connect', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'listening', listener: () => void): this; - prependOnceListener(event: 'message', listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "connect", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "listening", listener: () => void): this; + prependOnceListener(event: "message", listener: (msg: Buffer, rinfo: RemoteInfo) => void): this; + /** + * Calls `socket.close()` and returns a promise that fulfills when the socket has closed. + * @since v20.5.0 + */ + [Symbol.asyncDispose](): Promise; } } -declare module 'node:dgram' { - export * from 'dgram'; +declare module "node:dgram" { + export * from "dgram"; } diff --git a/node_modules/@types/node/ts4.8/diagnostics_channel.d.ts b/node_modules/@types/node/ts4.8/diagnostics_channel.d.ts old mode 100755 new mode 100644 index cb2429e..cd4bd71 --- a/node_modules/@types/node/ts4.8/diagnostics_channel.d.ts +++ b/node_modules/@types/node/ts4.8/diagnostics_channel.d.ts @@ -1,11 +1,11 @@ /** - * The `diagnostics_channel` module provides an API to create named channels + * The `node:diagnostics_channel` module provides an API to create named channels * to report arbitrary message data for diagnostics purposes. * * It can be accessed using: * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * ``` * * It is intended that a module writer wanting to report diagnostics messages @@ -19,10 +19,11 @@ * channels are used along with the shape of the message data. Channel names * should generally include the module name to avoid collisions with data from * other modules. - * @experimental - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/diagnostics_channel.js) + * @since v15.1.0, v14.17.0 + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/diagnostics_channel.js) */ -declare module 'diagnostics_channel' { +declare module "diagnostics_channel" { + import { AsyncLocalStorage } from "node:async_hooks"; /** * Check if there are active subscribers to the named channel. This is helpful if * the message you want to send might be expensive to prepare. @@ -31,7 +32,7 @@ declare module 'diagnostics_channel' { * performance-sensitive code. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * if (diagnostics_channel.hasSubscribers('my-channel')) { * // There are subscribers, prepare and publish message @@ -41,14 +42,14 @@ declare module 'diagnostics_channel' { * @param name The channel name * @return If there are active subscribers */ - function hasSubscribers(name: string): boolean; + function hasSubscribers(name: string | symbol): boolean; /** - * This is the primary entry-point for anyone wanting to interact with a named + * This is the primary entry-point for anyone wanting to publish to a named * channel. It produces a channel object which is optimized to reduce overhead at * publish time as much as possible. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * const channel = diagnostics_channel.channel('my-channel'); * ``` @@ -56,19 +57,86 @@ declare module 'diagnostics_channel' { * @param name The channel name * @return The named channel object */ - function channel(name: string): Channel; - type ChannelListener = (message: unknown, name: string) => void; + function channel(name: string | symbol): Channel; + type ChannelListener = (message: unknown, name: string | symbol) => void; + /** + * Register a message handler to subscribe to this channel. This message handler + * will be run synchronously whenever a message is published to the channel. Any + * errors thrown in the message handler will trigger an `'uncaughtException'`. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * diagnostics_channel.subscribe('my-channel', (message, name) => { + * // Received data + * }); + * ``` + * @since v18.7.0, v16.17.0 + * @param name The channel name + * @param onMessage The handler to receive channel messages + */ + function subscribe(name: string | symbol, onMessage: ChannelListener): void; + /** + * Remove a message handler previously registered to this channel with {@link subscribe}. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * function onMessage(message, name) { + * // Received data + * } + * + * diagnostics_channel.subscribe('my-channel', onMessage); + * + * diagnostics_channel.unsubscribe('my-channel', onMessage); + * ``` + * @since v18.7.0, v16.17.0 + * @param name The channel name + * @param onMessage The previous subscribed handler to remove + * @return `true` if the handler was found, `false` otherwise. + */ + function unsubscribe(name: string | symbol, onMessage: ChannelListener): boolean; + /** + * Creates a `TracingChannel` wrapper for the given `TracingChannel Channels`. If a name is given, the corresponding tracing + * channels will be created in the form of `tracing:${name}:${eventType}` where`eventType` corresponds to the types of `TracingChannel Channels`. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channelsByName = diagnostics_channel.tracingChannel('my-channel'); + * + * // or... + * + * const channelsByCollection = diagnostics_channel.tracingChannel({ + * start: diagnostics_channel.channel('tracing:my-channel:start'), + * end: diagnostics_channel.channel('tracing:my-channel:end'), + * asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'), + * asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'), + * error: diagnostics_channel.channel('tracing:my-channel:error'), + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param nameOrChannels Channel name or object containing all the `TracingChannel Channels` + * @return Collection of channels to trace with + */ + function tracingChannel< + StoreType = unknown, + ContextType extends object = StoreType extends object ? StoreType : object, + >( + nameOrChannels: string | TracingChannelCollection, + ): TracingChannel; /** * The class `Channel` represents an individual named channel within the data - * pipeline. It is use to track subscribers and to publish messages when there + * pipeline. It is used to track subscribers and to publish messages when there * are subscribers present. It exists as a separate object to avoid channel * lookups at publish time, enabling very fast publish speeds and allowing * for heavy use while incurring very minimal cost. Channels are created with {@link channel}, constructing a channel directly * with `new Channel(name)` is not supported. * @since v15.1.0, v14.17.0 */ - class Channel { - readonly name: string; + class Channel { + readonly name: string | symbol; /** * Check if there are active subscribers to this channel. This is helpful if * the message you want to send might be expensive to prepare. @@ -77,7 +145,7 @@ declare module 'diagnostics_channel' { * performance-sensitive code. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * const channel = diagnostics_channel.channel('my-channel'); * @@ -88,19 +156,18 @@ declare module 'diagnostics_channel' { * @since v15.1.0, v14.17.0 */ readonly hasSubscribers: boolean; - private constructor(name: string); + private constructor(name: string | symbol); /** - * Publish a message to any subscribers to the channel. This will - * trigger message handlers synchronously so they will execute within - * the same context. + * Publish a message to any subscribers to the channel. This will trigger + * message handlers synchronously so they will execute within the same context. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * const channel = diagnostics_channel.channel('my-channel'); * * channel.publish({ - * some: 'message' + * some: 'message', * }); * ``` * @since v15.1.0, v14.17.0 @@ -113,7 +180,7 @@ declare module 'diagnostics_channel' { * errors thrown in the message handler will trigger an `'uncaughtException'`. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * const channel = diagnostics_channel.channel('my-channel'); * @@ -122,6 +189,7 @@ declare module 'diagnostics_channel' { * }); * ``` * @since v15.1.0, v14.17.0 + * @deprecated Since v18.7.0,v16.17.0 - Use {@link subscribe(name, onMessage)} * @param onMessage The handler to receive channel messages */ subscribe(onMessage: ChannelListener): void; @@ -129,7 +197,7 @@ declare module 'diagnostics_channel' { * Remove a message handler previously registered to this channel with `channel.subscribe(onMessage)`. * * ```js - * import diagnostics_channel from 'diagnostics_channel'; + * import diagnostics_channel from 'node:diagnostics_channel'; * * const channel = diagnostics_channel.channel('my-channel'); * @@ -142,11 +210,336 @@ declare module 'diagnostics_channel' { * channel.unsubscribe(onMessage); * ``` * @since v15.1.0, v14.17.0 + * @deprecated Since v18.7.0,v16.17.0 - Use {@link unsubscribe(name, onMessage)} * @param onMessage The previous subscribed handler to remove + * @return `true` if the handler was found, `false` otherwise. */ unsubscribe(onMessage: ChannelListener): void; + /** + * When `channel.runStores(context, ...)` is called, the given context data + * will be applied to any store bound to the channel. If the store has already been + * bound the previous `transform` function will be replaced with the new one. + * The `transform` function may be omitted to set the given context data as the + * context directly. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * import { AsyncLocalStorage } from 'node:async_hooks'; + * + * const store = new AsyncLocalStorage(); + * + * const channel = diagnostics_channel.channel('my-channel'); + * + * channel.bindStore(store, (data) => { + * return { data }; + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param store The store to which to bind the context data + * @param transform Transform context data before setting the store context + */ + bindStore(store: AsyncLocalStorage, transform?: (context: ContextType) => StoreType): void; + /** + * Remove a message handler previously registered to this channel with `channel.bindStore(store)`. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * import { AsyncLocalStorage } from 'node:async_hooks'; + * + * const store = new AsyncLocalStorage(); + * + * const channel = diagnostics_channel.channel('my-channel'); + * + * channel.bindStore(store); + * channel.unbindStore(store); + * ``` + * @since v19.9.0 + * @experimental + * @param store The store to unbind from the channel. + * @return `true` if the store was found, `false` otherwise. + */ + unbindStore(store: any): void; + /** + * Applies the given data to any AsyncLocalStorage instances bound to the channel + * for the duration of the given function, then publishes to the channel within + * the scope of that data is applied to the stores. + * + * If a transform function was given to `channel.bindStore(store)` it will be + * applied to transform the message data before it becomes the context value for + * the store. The prior storage context is accessible from within the transform + * function in cases where context linking is required. + * + * The context applied to the store should be accessible in any async code which + * continues from execution which began during the given function, however + * there are some situations in which `context loss` may occur. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * import { AsyncLocalStorage } from 'node:async_hooks'; + * + * const store = new AsyncLocalStorage(); + * + * const channel = diagnostics_channel.channel('my-channel'); + * + * channel.bindStore(store, (message) => { + * const parent = store.getStore(); + * return new Span(message, parent); + * }); + * channel.runStores({ some: 'message' }, () => { + * store.getStore(); // Span({ some: 'message' }) + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param context Message to send to subscribers and bind to stores + * @param fn Handler to run within the entered storage context + * @param thisArg The receiver to be used for the function call. + * @param args Optional arguments to pass to the function. + */ + runStores(): void; + } + interface TracingChannelSubscribers { + start: (message: ContextType) => void; + end: ( + message: ContextType & { + error?: unknown; + result?: unknown; + }, + ) => void; + asyncStart: ( + message: ContextType & { + error?: unknown; + result?: unknown; + }, + ) => void; + asyncEnd: ( + message: ContextType & { + error?: unknown; + result?: unknown; + }, + ) => void; + error: ( + message: ContextType & { + error: unknown; + }, + ) => void; + } + interface TracingChannelCollection { + start: Channel; + end: Channel; + asyncStart: Channel; + asyncEnd: Channel; + error: Channel; + } + /** + * The class `TracingChannel` is a collection of `TracingChannel Channels` which + * together express a single traceable action. It is used to formalize and + * simplify the process of producing events for tracing application flow.{@link tracingChannel} is used to construct a`TracingChannel`. As with `Channel` it is recommended to create and reuse a + * single `TracingChannel` at the top-level of the file rather than creating them + * dynamically. + * @since v19.9.0 + * @experimental + */ + class TracingChannel implements TracingChannelCollection { + start: Channel; + end: Channel; + asyncStart: Channel; + asyncEnd: Channel; + error: Channel; + /** + * Helper to subscribe a collection of functions to the corresponding channels. + * This is the same as calling `channel.subscribe(onMessage)` on each channel + * individually. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * channels.subscribe({ + * start(message) { + * // Handle start message + * }, + * end(message) { + * // Handle end message + * }, + * asyncStart(message) { + * // Handle asyncStart message + * }, + * asyncEnd(message) { + * // Handle asyncEnd message + * }, + * error(message) { + * // Handle error message + * }, + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param subscribers Set of `TracingChannel Channels` subscribers + */ + subscribe(subscribers: TracingChannelSubscribers): void; + /** + * Helper to unsubscribe a collection of functions from the corresponding channels. + * This is the same as calling `channel.unsubscribe(onMessage)` on each channel + * individually. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * channels.unsubscribe({ + * start(message) { + * // Handle start message + * }, + * end(message) { + * // Handle end message + * }, + * asyncStart(message) { + * // Handle asyncStart message + * }, + * asyncEnd(message) { + * // Handle asyncEnd message + * }, + * error(message) { + * // Handle error message + * }, + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param subscribers Set of `TracingChannel Channels` subscribers + * @return `true` if all handlers were successfully unsubscribed, and `false` otherwise. + */ + unsubscribe(subscribers: TracingChannelSubscribers): void; + /** + * Trace a synchronous function call. This will always produce a `start event` and `end event` around the execution and may produce an `error event` if the given function throws an error. + * This will run the given function using `channel.runStores(context, ...)` on the `start` channel which ensures all + * events should have any bound stores set to match this trace context. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * channels.traceSync(() => { + * // Do something + * }, { + * some: 'thing', + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param fn Function to wrap a trace around + * @param context Shared object to correlate events through + * @param thisArg The receiver to be used for the function call + * @param args Optional arguments to pass to the function + * @return The return value of the given function + */ + traceSync( + fn: (this: ThisArg, ...args: Args) => any, + context?: ContextType, + thisArg?: ThisArg, + ...args: Args + ): void; + /** + * Trace a promise-returning function call. This will always produce a `start event` and `end event` around the synchronous portion of the + * function execution, and will produce an `asyncStart event` and `asyncEnd event` when a promise continuation is reached. It may also + * produce an `error event` if the given function throws an error or the + * returned promise rejects. This will run the given function using `channel.runStores(context, ...)` on the `start` channel which ensures all + * events should have any bound stores set to match this trace context. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * channels.tracePromise(async () => { + * // Do something + * }, { + * some: 'thing', + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param fn Promise-returning function to wrap a trace around + * @param context Shared object to correlate trace events through + * @param thisArg The receiver to be used for the function call + * @param args Optional arguments to pass to the function + * @return Chained from promise returned by the given function + */ + tracePromise( + fn: (this: ThisArg, ...args: Args) => Promise, + context?: ContextType, + thisArg?: ThisArg, + ...args: Args + ): void; + /** + * Trace a callback-receiving function call. This will always produce a `start event` and `end event` around the synchronous portion of the + * function execution, and will produce a `asyncStart event` and `asyncEnd event` around the callback execution. It may also produce an `error event` if the given function throws an error or + * the returned + * promise rejects. This will run the given function using `channel.runStores(context, ...)` on the `start` channel which ensures all + * events should have any bound stores set to match this trace context. + * + * The `position` will be -1 by default to indicate the final argument should + * be used as the callback. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * + * channels.traceCallback((arg1, callback) => { + * // Do something + * callback(null, 'result'); + * }, 1, { + * some: 'thing', + * }, thisArg, arg1, callback); + * ``` + * + * The callback will also be run with `channel.runStores(context, ...)` which + * enables context loss recovery in some cases. + * + * ```js + * import diagnostics_channel from 'node:diagnostics_channel'; + * import { AsyncLocalStorage } from 'node:async_hooks'; + * + * const channels = diagnostics_channel.tracingChannel('my-channel'); + * const myStore = new AsyncLocalStorage(); + * + * // The start channel sets the initial store data to something + * // and stores that store data value on the trace context object + * channels.start.bindStore(myStore, (data) => { + * const span = new Span(data); + * data.span = span; + * return span; + * }); + * + * // Then asyncStart can restore from that data it stored previously + * channels.asyncStart.bindStore(myStore, (data) => { + * return data.span; + * }); + * ``` + * @since v19.9.0 + * @experimental + * @param fn callback using function to wrap a trace around + * @param position Zero-indexed argument position of expected callback + * @param context Shared object to correlate trace events through + * @param thisArg The receiver to be used for the function call + * @param args Optional arguments to pass to the function + * @return The return value of the given function + */ + traceCallback any>( + fn: Fn, + position: number | undefined, + context: ContextType | undefined, + thisArg: any, + ...args: Parameters + ): void; } } -declare module 'node:diagnostics_channel' { - export * from 'diagnostics_channel'; +declare module "node:diagnostics_channel" { + export * from "diagnostics_channel"; } diff --git a/node_modules/@types/node/ts4.8/dns.d.ts b/node_modules/@types/node/ts4.8/dns.d.ts old mode 100755 new mode 100644 index 78776f4..380cf7d --- a/node_modules/@types/node/ts4.8/dns.d.ts +++ b/node_modules/@types/node/ts4.8/dns.d.ts @@ -1,5 +1,5 @@ /** - * The `dns` module enables name resolution. For example, use it to look up IP + * The `node:dns` module enables name resolution. For example, use it to look up IP * addresses of host names. * * Although named for the [Domain Name System (DNS)](https://en.wikipedia.org/wiki/Domain_Name_System), it does not always use the @@ -9,7 +9,7 @@ * system do, use {@link lookup}. * * ```js - * const dns = require('dns'); + * const dns = require('node:dns'); * * dns.lookup('example.org', (err, address, family) => { * console.log('address: %j family: IPv%s', address, family); @@ -17,13 +17,13 @@ * // address: "93.184.216.34" family: IPv4 * ``` * - * All other functions in the `dns` module connect to an actual DNS server to + * All other functions in the `node:dns` module connect to an actual DNS server to * perform name resolution. They will always use the network to perform DNS * queries. These functions do not use the same set of configuration files used by {@link lookup} (e.g. `/etc/hosts`). Use these functions to always perform * DNS queries, bypassing other name-resolution facilities. * * ```js - * const dns = require('dns'); + * const dns = require('node:dns'); * * dns.resolve4('archive.org', (err, addresses) => { * if (err) throw err; @@ -42,10 +42,10 @@ * ``` * * See the `Implementation considerations section` for more information. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/dns.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/dns.js) */ -declare module 'dns' { - import * as dnsPromises from 'node:dns/promises'; +declare module "dns" { + import * as dnsPromises from "node:dns/promises"; // Supported getaddrinfo flags. export const ADDRCONFIG: number; export const V4MAPPED: number; @@ -58,6 +58,9 @@ declare module 'dns' { family?: number | undefined; hints?: number | undefined; all?: boolean | undefined; + /** + * @default true + */ verbatim?: boolean | undefined; } export interface LookupOneOptions extends LookupOptions { @@ -73,8 +76,8 @@ declare module 'dns' { /** * Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or * AAAA (IPv6) record. All `option` properties are optional. If `options` is an - * integer, then it must be `4` or `6` – if `options` is not provided, then IPv4 - * and IPv6 addresses are both returned if found. + * integer, then it must be `4` or `6` – if `options` is `0` or not provided, then + * IPv4 and IPv6 addresses are both returned if found. * * With the `all` option set to `true`, the arguments for `callback` change to`(err, addresses)`, with `addresses` being an array of objects with the * properties `address` and `family`. @@ -86,14 +89,14 @@ declare module 'dns' { * * `dns.lookup()` does not necessarily have anything to do with the DNS protocol. * The implementation uses an operating system facility that can associate names - * with addresses, and vice versa. This implementation can have subtle but + * with addresses and vice versa. This implementation can have subtle but * important consequences on the behavior of any Node.js program. Please take some * time to consult the `Implementation considerations section` before using`dns.lookup()`. * * Example usage: * * ```js - * const dns = require('dns'); + * const dns = require('node:dns'); * const options = { * family: 6, * hints: dns.ADDRCONFIG | dns.V4MAPPED, @@ -112,11 +115,30 @@ declare module 'dns' { * If this method is invoked as its `util.promisify()` ed version, and `all`is not set to `true`, it returns a `Promise` for an `Object` with `address` and`family` properties. * @since v0.1.90 */ - export function lookup(hostname: string, family: number, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void): void; - export function lookup(hostname: string, options: LookupOneOptions, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void): void; - export function lookup(hostname: string, options: LookupAllOptions, callback: (err: NodeJS.ErrnoException | null, addresses: LookupAddress[]) => void): void; - export function lookup(hostname: string, options: LookupOptions, callback: (err: NodeJS.ErrnoException | null, address: string | LookupAddress[], family: number) => void): void; - export function lookup(hostname: string, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void): void; + export function lookup( + hostname: string, + family: number, + callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, + ): void; + export function lookup( + hostname: string, + options: LookupOneOptions, + callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, + ): void; + export function lookup( + hostname: string, + options: LookupAllOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: LookupAddress[]) => void, + ): void; + export function lookup( + hostname: string, + options: LookupOptions, + callback: (err: NodeJS.ErrnoException | null, address: string | LookupAddress[], family: number) => void, + ): void; + export function lookup( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, + ): void; export namespace lookup { function __promisify__(hostname: string, options: LookupAllOptions): Promise; function __promisify__(hostname: string, options?: LookupOneOptions | number): Promise; @@ -132,7 +154,7 @@ declare module 'dns' { * On an error, `err` is an `Error` object, where `err.code` is the error code. * * ```js - * const dns = require('dns'); + * const dns = require('node:dns'); * dns.lookupService('127.0.0.1', 22, (err, hostname, service) => { * console.log(hostname, service); * // Prints: localhost ssh @@ -142,11 +164,15 @@ declare module 'dns' { * If this method is invoked as its `util.promisify()` ed version, it returns a`Promise` for an `Object` with `hostname` and `service` properties. * @since v0.11.14 */ - export function lookupService(address: string, port: number, callback: (err: NodeJS.ErrnoException | null, hostname: string, service: string) => void): void; + export function lookupService( + address: string, + port: number, + callback: (err: NodeJS.ErrnoException | null, hostname: string, service: string) => void, + ): void; export namespace lookupService { function __promisify__( address: string, - port: number + port: number, ): Promise<{ hostname: string; service: string; @@ -165,13 +191,13 @@ declare module 'dns' { /** @deprecated Use `AnyARecord` or `AnyAaaaRecord` instead. */ export type AnyRecordWithTtl = AnyARecord | AnyAaaaRecord; export interface AnyARecord extends RecordWithTtl { - type: 'A'; + type: "A"; } export interface AnyAaaaRecord extends RecordWithTtl { - type: 'AAAA'; + type: "AAAA"; } export interface CaaRecord { - critial: number; + critical: number; issue?: string | undefined; issuewild?: string | undefined; iodef?: string | undefined; @@ -183,7 +209,7 @@ declare module 'dns' { exchange: string; } export interface AnyMxRecord extends MxRecord { - type: 'MX'; + type: "MX"; } export interface NaptrRecord { flags: string; @@ -194,7 +220,7 @@ declare module 'dns' { preference: number; } export interface AnyNaptrRecord extends NaptrRecord { - type: 'NAPTR'; + type: "NAPTR"; } export interface SoaRecord { nsname: string; @@ -206,7 +232,7 @@ declare module 'dns' { minttl: number; } export interface AnySoaRecord extends SoaRecord { - type: 'SOA'; + type: "SOA"; } export interface SrvRecord { priority: number; @@ -215,25 +241,35 @@ declare module 'dns' { name: string; } export interface AnySrvRecord extends SrvRecord { - type: 'SRV'; + type: "SRV"; } export interface AnyTxtRecord { - type: 'TXT'; + type: "TXT"; entries: string[]; } export interface AnyNsRecord { - type: 'NS'; + type: "NS"; value: string; } export interface AnyPtrRecord { - type: 'PTR'; + type: "PTR"; value: string; } export interface AnyCnameRecord { - type: 'CNAME'; + type: "CNAME"; value: string; } - export type AnyRecord = AnyARecord | AnyAaaaRecord | AnyCnameRecord | AnyMxRecord | AnyNaptrRecord | AnyNsRecord | AnyPtrRecord | AnySoaRecord | AnySrvRecord | AnyTxtRecord; + export type AnyRecord = + | AnyARecord + | AnyAaaaRecord + | AnyCnameRecord + | AnyMxRecord + | AnyNaptrRecord + | AnyNsRecord + | AnyPtrRecord + | AnySoaRecord + | AnySrvRecord + | AnyTxtRecord; /** * Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array * of the resource records. The `callback` function has arguments`(err, records)`. When successful, `records` will be an array of resource @@ -246,32 +282,85 @@ declare module 'dns' { * @param hostname Host name to resolve. * @param [rrtype='A'] Resource record type. */ - export function resolve(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'A', callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'AAAA', callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'ANY', callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void): void; - export function resolve(hostname: string, rrtype: 'CNAME', callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'MX', callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void): void; - export function resolve(hostname: string, rrtype: 'NAPTR', callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void): void; - export function resolve(hostname: string, rrtype: 'NS', callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'PTR', callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve(hostname: string, rrtype: 'SOA', callback: (err: NodeJS.ErrnoException | null, addresses: SoaRecord) => void): void; - export function resolve(hostname: string, rrtype: 'SRV', callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void): void; - export function resolve(hostname: string, rrtype: 'TXT', callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void): void; + export function resolve( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "A", + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "AAAA", + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "ANY", + callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "CNAME", + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "MX", + callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "NAPTR", + callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "NS", + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "PTR", + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "SOA", + callback: (err: NodeJS.ErrnoException | null, addresses: SoaRecord) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "SRV", + callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void, + ): void; + export function resolve( + hostname: string, + rrtype: "TXT", + callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void, + ): void; export function resolve( hostname: string, rrtype: string, - callback: (err: NodeJS.ErrnoException | null, addresses: string[] | MxRecord[] | NaptrRecord[] | SoaRecord | SrvRecord[] | string[][] | AnyRecord[]) => void + callback: ( + err: NodeJS.ErrnoException | null, + addresses: string[] | MxRecord[] | NaptrRecord[] | SoaRecord | SrvRecord[] | string[][] | AnyRecord[], + ) => void, ): void; export namespace resolve { - function __promisify__(hostname: string, rrtype?: 'A' | 'AAAA' | 'CNAME' | 'NS' | 'PTR'): Promise; - function __promisify__(hostname: string, rrtype: 'ANY'): Promise; - function __promisify__(hostname: string, rrtype: 'MX'): Promise; - function __promisify__(hostname: string, rrtype: 'NAPTR'): Promise; - function __promisify__(hostname: string, rrtype: 'SOA'): Promise; - function __promisify__(hostname: string, rrtype: 'SRV'): Promise; - function __promisify__(hostname: string, rrtype: 'TXT'): Promise; - function __promisify__(hostname: string, rrtype: string): Promise; + function __promisify__(hostname: string, rrtype?: "A" | "AAAA" | "CNAME" | "NS" | "PTR"): Promise; + function __promisify__(hostname: string, rrtype: "ANY"): Promise; + function __promisify__(hostname: string, rrtype: "MX"): Promise; + function __promisify__(hostname: string, rrtype: "NAPTR"): Promise; + function __promisify__(hostname: string, rrtype: "SOA"): Promise; + function __promisify__(hostname: string, rrtype: "SRV"): Promise; + function __promisify__(hostname: string, rrtype: "TXT"): Promise; + function __promisify__( + hostname: string, + rrtype: string, + ): Promise; } /** * Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the`hostname`. The `addresses` argument passed to the `callback` function @@ -279,23 +368,45 @@ declare module 'dns' { * @since v0.1.16 * @param hostname Host name to resolve. */ - export function resolve4(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve4(hostname: string, options: ResolveWithTtlOptions, callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void): void; - export function resolve4(hostname: string, options: ResolveOptions, callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void): void; + export function resolve4( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve4( + hostname: string, + options: ResolveWithTtlOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void, + ): void; + export function resolve4( + hostname: string, + options: ResolveOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void, + ): void; export namespace resolve4 { function __promisify__(hostname: string): Promise; function __promisify__(hostname: string, options: ResolveWithTtlOptions): Promise; function __promisify__(hostname: string, options?: ResolveOptions): Promise; } /** - * Uses the DNS protocol to resolve a IPv6 addresses (`AAAA` records) for the`hostname`. The `addresses` argument passed to the `callback` function + * Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the`hostname`. The `addresses` argument passed to the `callback` function * will contain an array of IPv6 addresses. * @since v0.1.16 * @param hostname Host name to resolve. */ - export function resolve6(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; - export function resolve6(hostname: string, options: ResolveWithTtlOptions, callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void): void; - export function resolve6(hostname: string, options: ResolveOptions, callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void): void; + export function resolve6( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; + export function resolve6( + hostname: string, + options: ResolveWithTtlOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void, + ): void; + export function resolve6( + hostname: string, + options: ResolveOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void, + ): void; export namespace resolve6 { function __promisify__(hostname: string): Promise; function __promisify__(hostname: string, options: ResolveWithTtlOptions): Promise; @@ -306,7 +417,10 @@ declare module 'dns' { * will contain an array of canonical name records available for the `hostname`(e.g. `['bar.example.com']`). * @since v0.3.2 */ - export function resolveCname(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; + export function resolveCname( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; export namespace resolveCname { function __promisify__(hostname: string): Promise; } @@ -314,9 +428,12 @@ declare module 'dns' { * Uses the DNS protocol to resolve `CAA` records for the `hostname`. The`addresses` argument passed to the `callback` function * will contain an array of certification authority authorization records * available for the `hostname` (e.g. `[{critical: 0, iodef: 'mailto:pki@example.com'}, {critical: 128, issue: 'pki.example.com'}]`). - * @since v15.0.0 + * @since v15.0.0, v14.17.0 */ - export function resolveCaa(hostname: string, callback: (err: NodeJS.ErrnoException | null, records: CaaRecord[]) => void): void; + export function resolveCaa( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, records: CaaRecord[]) => void, + ): void; export namespace resolveCaa { function __promisify__(hostname: string): Promise; } @@ -325,12 +442,15 @@ declare module 'dns' { * contain an array of objects containing both a `priority` and `exchange`property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`). * @since v0.1.27 */ - export function resolveMx(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void): void; + export function resolveMx( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void, + ): void; export namespace resolveMx { function __promisify__(hostname: string): Promise; } /** - * Uses the DNS protocol to resolve regular expression based records (`NAPTR`records) for the `hostname`. The `addresses` argument passed to the `callback`function will contain an array of + * Uses the DNS protocol to resolve regular expression-based records (`NAPTR`records) for the `hostname`. The `addresses` argument passed to the `callback`function will contain an array of * objects with the following properties: * * * `flags` @@ -352,7 +472,10 @@ declare module 'dns' { * ``` * @since v0.9.12 */ - export function resolveNaptr(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void): void; + export function resolveNaptr( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void, + ): void; export namespace resolveNaptr { function __promisify__(hostname: string): Promise; } @@ -361,7 +484,10 @@ declare module 'dns' { * contain an array of name server records available for `hostname`(e.g. `['ns1.example.com', 'ns2.example.com']`). * @since v0.1.90 */ - export function resolveNs(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; + export function resolveNs( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; export namespace resolveNs { function __promisify__(hostname: string): Promise; } @@ -370,7 +496,10 @@ declare module 'dns' { * be an array of strings containing the reply records. * @since v6.0.0 */ - export function resolvePtr(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void): void; + export function resolvePtr( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void, + ): void; export namespace resolvePtr { function __promisify__(hostname: string): Promise; } @@ -400,7 +529,10 @@ declare module 'dns' { * ``` * @since v0.11.10 */ - export function resolveSoa(hostname: string, callback: (err: NodeJS.ErrnoException | null, address: SoaRecord) => void): void; + export function resolveSoa( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, address: SoaRecord) => void, + ): void; export namespace resolveSoa { function __promisify__(hostname: string): Promise; } @@ -423,7 +555,10 @@ declare module 'dns' { * ``` * @since v0.1.27 */ - export function resolveSrv(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void): void; + export function resolveSrv( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void, + ): void; export namespace resolveSrv { function __promisify__(hostname: string): Promise; } @@ -434,7 +569,10 @@ declare module 'dns' { * treated separately. * @since v0.1.27 */ - export function resolveTxt(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void): void; + export function resolveTxt( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void, + ): void; export namespace resolveTxt { function __promisify__(hostname: string): Promise; } @@ -468,7 +606,10 @@ declare module 'dns' { * DNS server operators may choose not to respond to `ANY`queries. It may be better to call individual methods like {@link resolve4},{@link resolveMx}, and so on. For more details, see [RFC * 8482](https://tools.ietf.org/html/rfc8482). */ - export function resolveAny(hostname: string, callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void): void; + export function resolveAny( + hostname: string, + callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void, + ): void; export namespace resolveAny { function __promisify__(hostname: string): Promise; } @@ -480,7 +621,18 @@ declare module 'dns' { * one of the `DNS error codes`. * @since v0.1.16 */ - export function reverse(ip: string, callback: (err: NodeJS.ErrnoException | null, hostnames: string[]) => void): void; + export function reverse( + ip: string, + callback: (err: NodeJS.ErrnoException | null, hostnames: string[]) => void, + ): void; + /** + * Get the default value for `verbatim` in {@link lookup} and `dnsPromises.lookup()`. The value could be: + * + * * `ipv4first`: for `verbatim` defaulting to `false`. + * * `verbatim`: for `verbatim` defaulting to `true`. + * @since v20.1.0 + */ + export function getDefaultResultOrder(): "ipv4first" | "verbatim"; /** * Sets the IP address and port of servers to be used when performing DNS * resolution. The `servers` argument is an array of [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6) formatted @@ -509,7 +661,7 @@ declare module 'dns' { * @since v0.11.3 * @param servers array of `RFC 5952` formatted addresses */ - export function setServers(servers: ReadonlyArray): void; + export function setServers(servers: readonly string[]): void; /** * Returns an array of IP address strings, formatted according to [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6), * that are currently configured for DNS resolution. A string will include a port @@ -527,16 +679,18 @@ declare module 'dns' { */ export function getServers(): string[]; /** - * Set the default value of `verbatim` in {@link lookup}. The value could be: - * - `ipv4first`: sets default `verbatim` `false`. - * - `verbatim`: sets default `verbatim` `true`. + * Set the default value of `verbatim` in {@link lookup} and `dnsPromises.lookup()`. The value could be: * - * The default is `ipv4first` and {@link setDefaultResultOrder} have higher priority than `--dns-result-order`. - * When using worker threads, {@link setDefaultResultOrder} from the main thread won't affect the default dns orders in workers. - * @since v14.18.0 - * @param order must be 'ipv4first' or 'verbatim'. + * * `ipv4first`: sets default `verbatim` `false`. + * * `verbatim`: sets default `verbatim` `true`. + * + * The default is `verbatim` and {@link setDefaultResultOrder} have higher + * priority than `--dns-result-order`. When using `worker threads`,{@link setDefaultResultOrder} from the main thread won't affect the default + * dns orders in workers. + * @since v16.4.0, v14.18.0 + * @param order must be `'ipv4first'` or `'verbatim'`. */ - export function setDefaultResultOrder(order: 'ipv4first' | 'verbatim'): void; + export function setDefaultResultOrder(order: "ipv4first" | "verbatim"): void; // Error codes export const NODATA: string; export const FORMERR: string; @@ -577,7 +731,7 @@ declare module 'dns' { * other resolvers: * * ```js - * const { Resolver } = require('dns'); + * const { Resolver } = require('node:dns'); * const resolver = new Resolver(); * resolver.setServers(['4.4.4.4']); * @@ -587,7 +741,7 @@ declare module 'dns' { * }); * ``` * - * The following methods from the `dns` module are available: + * The following methods from the `node:dns` module are available: * * * `resolver.getServers()` * * `resolver.resolve()` @@ -620,6 +774,7 @@ declare module 'dns' { resolve4: typeof resolve4; resolve6: typeof resolve6; resolveAny: typeof resolveAny; + resolveCaa: typeof resolveCaa; resolveCname: typeof resolveCname; resolveMx: typeof resolveMx; resolveNaptr: typeof resolveNaptr; @@ -634,13 +789,13 @@ declare module 'dns' { * This allows programs to specify outbound interfaces when used on multi-homed * systems. * - * If a v4 or v6 address is not specified, it is set to the default, and the + * If a v4 or v6 address is not specified, it is set to the default and the * operating system will choose a local address automatically. * * The resolver will use the v4 local address when making requests to IPv4 DNS * servers, and the v6 local address when making requests to IPv6 DNS servers. * The `rrtype` of resolution requests has no impact on the local address used. - * @since v15.1.0 + * @since v15.1.0, v14.17.0 * @param [ipv4='0.0.0.0'] A string representation of an IPv4 address. * @param [ipv6='::0'] A string representation of an IPv6 address. */ @@ -649,6 +804,6 @@ declare module 'dns' { } export { dnsPromises as promises }; } -declare module 'node:dns' { - export * from 'dns'; +declare module "node:dns" { + export * from "dns"; } diff --git a/node_modules/@types/node/ts4.8/dns/promises.d.ts b/node_modules/@types/node/ts4.8/dns/promises.d.ts old mode 100755 new mode 100644 index a236b5a..ef9b222 --- a/node_modules/@types/node/ts4.8/dns/promises.d.ts +++ b/node_modules/@types/node/ts4.8/dns/promises.d.ts @@ -1,26 +1,26 @@ /** * The `dns.promises` API provides an alternative set of asynchronous DNS methods * that return `Promise` objects rather than using callbacks. The API is accessible - * via `require('dns').promises` or `require('dns/promises')`. + * via `require('node:dns').promises` or `require('node:dns/promises')`. * @since v10.6.0 */ -declare module 'dns/promises' { +declare module "dns/promises" { import { - LookupAddress, - LookupOneOptions, - LookupAllOptions, - LookupOptions, AnyRecord, CaaRecord, + LookupAddress, + LookupAllOptions, + LookupOneOptions, + LookupOptions, MxRecord, NaptrRecord, - SoaRecord, - SrvRecord, - ResolveWithTtlOptions, RecordWithTtl, ResolveOptions, ResolverOptions, - } from 'node:dns'; + ResolveWithTtlOptions, + SoaRecord, + SrvRecord, + } from "node:dns"; /** * Returns an array of IP address strings, formatted according to [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6), * that are currently configured for DNS resolution. A string will include a port @@ -52,7 +52,7 @@ declare module 'dns/promises' { * * `dnsPromises.lookup()` does not necessarily have anything to do with the DNS * protocol. The implementation uses an operating system facility that can - * associate names with addresses, and vice versa. This implementation can have + * associate names with addresses and vice versa. This implementation can have * subtle but important consequences on the behavior of any Node.js program. Please * take some time to consult the `Implementation considerations section` before * using `dnsPromises.lookup()`. @@ -60,7 +60,7 @@ declare module 'dns/promises' { * Example usage: * * ```js - * const dns = require('dns'); + * const dns = require('node:dns'); * const dnsPromises = dns.promises; * const options = { * family: 6, @@ -96,7 +96,7 @@ declare module 'dns/promises' { * On error, the `Promise` is rejected with an `Error` object, where `err.code`is the error code. * * ```js - * const dnsPromises = require('dns').promises; + * const dnsPromises = require('node:dns').promises; * dnsPromises.lookupService('127.0.0.1', 22).then((result) => { * console.log(result.hostname, result.service); * // Prints: localhost ssh @@ -106,7 +106,7 @@ declare module 'dns/promises' { */ function lookupService( address: string, - port: number + port: number, ): Promise<{ hostname: string; service: string; @@ -125,19 +125,22 @@ declare module 'dns/promises' { * @param [rrtype='A'] Resource record type. */ function resolve(hostname: string): Promise; - function resolve(hostname: string, rrtype: 'A'): Promise; - function resolve(hostname: string, rrtype: 'AAAA'): Promise; - function resolve(hostname: string, rrtype: 'ANY'): Promise; - function resolve(hostname: string, rrtype: 'CAA'): Promise; - function resolve(hostname: string, rrtype: 'CNAME'): Promise; - function resolve(hostname: string, rrtype: 'MX'): Promise; - function resolve(hostname: string, rrtype: 'NAPTR'): Promise; - function resolve(hostname: string, rrtype: 'NS'): Promise; - function resolve(hostname: string, rrtype: 'PTR'): Promise; - function resolve(hostname: string, rrtype: 'SOA'): Promise; - function resolve(hostname: string, rrtype: 'SRV'): Promise; - function resolve(hostname: string, rrtype: 'TXT'): Promise; - function resolve(hostname: string, rrtype: string): Promise; + function resolve(hostname: string, rrtype: "A"): Promise; + function resolve(hostname: string, rrtype: "AAAA"): Promise; + function resolve(hostname: string, rrtype: "ANY"): Promise; + function resolve(hostname: string, rrtype: "CAA"): Promise; + function resolve(hostname: string, rrtype: "CNAME"): Promise; + function resolve(hostname: string, rrtype: "MX"): Promise; + function resolve(hostname: string, rrtype: "NAPTR"): Promise; + function resolve(hostname: string, rrtype: "NS"): Promise; + function resolve(hostname: string, rrtype: "PTR"): Promise; + function resolve(hostname: string, rrtype: "SOA"): Promise; + function resolve(hostname: string, rrtype: "SRV"): Promise; + function resolve(hostname: string, rrtype: "TXT"): Promise; + function resolve( + hostname: string, + rrtype: string, + ): Promise; /** * Uses the DNS protocol to resolve IPv4 addresses (`A` records) for the`hostname`. On success, the `Promise` is resolved with an array of IPv4 * addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`). @@ -189,7 +192,7 @@ declare module 'dns/promises' { * Uses the DNS protocol to resolve `CAA` records for the `hostname`. On success, * the `Promise` is resolved with an array of objects containing available * certification authority authorization records available for the `hostname`(e.g. `[{critical: 0, iodef: 'mailto:pki@example.com'},{critical: 128, issue: 'pki.example.com'}]`). - * @since v15.0.0 + * @since v15.0.0, v14.17.0 */ function resolveCaa(hostname: string): Promise; /** @@ -206,7 +209,7 @@ declare module 'dns/promises' { */ function resolveMx(hostname: string): Promise; /** - * Uses the DNS protocol to resolve regular expression based records (`NAPTR`records) for the `hostname`. On success, the `Promise` is resolved with an array + * Uses the DNS protocol to resolve regular expression-based records (`NAPTR`records) for the `hostname`. On success, the `Promise` is resolved with an array * of objects with the following properties: * * * `flags` @@ -304,6 +307,14 @@ declare module 'dns/promises' { * @since v10.6.0 */ function reverse(ip: string): Promise; + /** + * Get the default value for `verbatim` in {@link lookup} and `dnsPromises.lookup()`. The value could be: + * + * * `ipv4first`: for `verbatim` defaulting to `false`. + * * `verbatim`: for `verbatim` defaulting to `true`. + * @since v20.1.0 + */ + function getDefaultResultOrder(): "ipv4first" | "verbatim"; /** * Sets the IP address and port of servers to be used when performing DNS * resolution. The `servers` argument is an array of [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6) formatted @@ -330,18 +341,63 @@ declare module 'dns/promises' { * @since v10.6.0 * @param servers array of `RFC 5952` formatted addresses */ - function setServers(servers: ReadonlyArray): void; + function setServers(servers: readonly string[]): void; /** - * Set the default value of `verbatim` in {@link lookup}. The value could be: - * - `ipv4first`: sets default `verbatim` `false`. - * - `verbatim`: sets default `verbatim` `true`. + * Set the default value of `verbatim` in `dns.lookup()` and `dnsPromises.lookup()`. The value could be: * - * The default is `ipv4first` and {@link setDefaultResultOrder} have higher priority than `--dns-result-order`. - * When using worker threads, {@link setDefaultResultOrder} from the main thread won't affect the default dns orders in workers. - * @since v14.18.0 - * @param order must be 'ipv4first' or 'verbatim'. + * * `ipv4first`: sets default `verbatim` `false`. + * * `verbatim`: sets default `verbatim` `true`. + * + * The default is `verbatim` and `dnsPromises.setDefaultResultOrder()` have + * higher priority than `--dns-result-order`. When using `worker threads`,`dnsPromises.setDefaultResultOrder()` from the main thread won't affect the + * default dns orders in workers. + * @since v16.4.0, v14.18.0 + * @param order must be `'ipv4first'` or `'verbatim'`. + */ + function setDefaultResultOrder(order: "ipv4first" | "verbatim"): void; + /** + * An independent resolver for DNS requests. + * + * Creating a new resolver uses the default server settings. Setting + * the servers used for a resolver using `resolver.setServers()` does not affect + * other resolvers: + * + * ```js + * const { Resolver } = require('node:dns').promises; + * const resolver = new Resolver(); + * resolver.setServers(['4.4.4.4']); + * + * // This request will use the server at 4.4.4.4, independent of global settings. + * resolver.resolve4('example.org').then((addresses) => { + * // ... + * }); + * + * // Alternatively, the same code can be written using async-await style. + * (async function() { + * const addresses = await resolver.resolve4('example.org'); + * })(); + * ``` + * + * The following methods from the `dnsPromises` API are available: + * + * * `resolver.getServers()` + * * `resolver.resolve()` + * * `resolver.resolve4()` + * * `resolver.resolve6()` + * * `resolver.resolveAny()` + * * `resolver.resolveCaa()` + * * `resolver.resolveCname()` + * * `resolver.resolveMx()` + * * `resolver.resolveNaptr()` + * * `resolver.resolveNs()` + * * `resolver.resolvePtr()` + * * `resolver.resolveSoa()` + * * `resolver.resolveSrv()` + * * `resolver.resolveTxt()` + * * `resolver.reverse()` + * * `resolver.setServers()` + * @since v10.6.0 */ - function setDefaultResultOrder(order: 'ipv4first' | 'verbatim'): void; class Resolver { constructor(options?: ResolverOptions); cancel(): void; @@ -350,6 +406,7 @@ declare module 'dns/promises' { resolve4: typeof resolve4; resolve6: typeof resolve6; resolveAny: typeof resolveAny; + resolveCaa: typeof resolveCaa; resolveCname: typeof resolveCname; resolveMx: typeof resolveMx; resolveNaptr: typeof resolveNaptr; @@ -363,6 +420,6 @@ declare module 'dns/promises' { setServers: typeof setServers; } } -declare module 'node:dns/promises' { - export * from 'dns/promises'; +declare module "node:dns/promises" { + export * from "dns/promises"; } diff --git a/node_modules/@types/node/ts4.8/dom-events.d.ts b/node_modules/@types/node/ts4.8/dom-events.d.ts new file mode 100644 index 0000000..147a7b6 --- /dev/null +++ b/node_modules/@types/node/ts4.8/dom-events.d.ts @@ -0,0 +1,122 @@ +export {}; // Don't export anything! + +//// DOM-like Events +// NB: The Event / EventTarget / EventListener implementations below were copied +// from lib.dom.d.ts, then edited to reflect Node's documentation at +// https://nodejs.org/api/events.html#class-eventtarget. +// Please read that link to understand important implementation differences. + +// This conditional type will be the existing global Event in a browser, or +// the copy below in a Node environment. +type __Event = typeof globalThis extends { onmessage: any; Event: any } ? {} + : { + /** This is not used in Node.js and is provided purely for completeness. */ + readonly bubbles: boolean; + /** Alias for event.stopPropagation(). This is not used in Node.js and is provided purely for completeness. */ + cancelBubble: () => void; + /** True if the event was created with the cancelable option */ + readonly cancelable: boolean; + /** This is not used in Node.js and is provided purely for completeness. */ + readonly composed: boolean; + /** Returns an array containing the current EventTarget as the only entry or empty if the event is not being dispatched. This is not used in Node.js and is provided purely for completeness. */ + composedPath(): [EventTarget?]; + /** Alias for event.target. */ + readonly currentTarget: EventTarget | null; + /** Is true if cancelable is true and event.preventDefault() has been called. */ + readonly defaultPrevented: boolean; + /** This is not used in Node.js and is provided purely for completeness. */ + readonly eventPhase: 0 | 2; + /** The `AbortSignal` "abort" event is emitted with `isTrusted` set to `true`. The value is `false` in all other cases. */ + readonly isTrusted: boolean; + /** Sets the `defaultPrevented` property to `true` if `cancelable` is `true`. */ + preventDefault(): void; + /** This is not used in Node.js and is provided purely for completeness. */ + returnValue: boolean; + /** Alias for event.target. */ + readonly srcElement: EventTarget | null; + /** Stops the invocation of event listeners after the current one completes. */ + stopImmediatePropagation(): void; + /** This is not used in Node.js and is provided purely for completeness. */ + stopPropagation(): void; + /** The `EventTarget` dispatching the event */ + readonly target: EventTarget | null; + /** The millisecond timestamp when the Event object was created. */ + readonly timeStamp: number; + /** Returns the type of event, e.g. "click", "hashchange", or "submit". */ + readonly type: string; + }; + +// See comment above explaining conditional type +type __EventTarget = typeof globalThis extends { onmessage: any; EventTarget: any } ? {} + : { + /** + * Adds a new handler for the `type` event. Any given `listener` is added only once per `type` and per `capture` option value. + * + * If the `once` option is true, the `listener` is removed after the next time a `type` event is dispatched. + * + * The `capture` option is not used by Node.js in any functional way other than tracking registered event listeners per the `EventTarget` specification. + * Specifically, the `capture` option is used as part of the key when registering a `listener`. + * Any individual `listener` may be added once with `capture = false`, and once with `capture = true`. + */ + addEventListener( + type: string, + listener: EventListener | EventListenerObject, + options?: AddEventListenerOptions | boolean, + ): void; + /** Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. */ + dispatchEvent(event: Event): boolean; + /** Removes the event listener in target's event listener list with the same type, callback, and options. */ + removeEventListener( + type: string, + listener: EventListener | EventListenerObject, + options?: EventListenerOptions | boolean, + ): void; + }; + +interface EventInit { + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; +} + +interface EventListenerOptions { + /** Not directly used by Node.js. Added for API completeness. Default: `false`. */ + capture?: boolean; +} + +interface AddEventListenerOptions extends EventListenerOptions { + /** When `true`, the listener is automatically removed when it is first invoked. Default: `false`. */ + once?: boolean; + /** When `true`, serves as a hint that the listener will not call the `Event` object's `preventDefault()` method. Default: false. */ + passive?: boolean; +} + +interface EventListener { + (evt: Event): void; +} + +interface EventListenerObject { + handleEvent(object: Event): void; +} + +import {} from "events"; // Make this an ambient declaration +declare global { + /** An event which takes place in the DOM. */ + interface Event extends __Event {} + var Event: typeof globalThis extends { onmessage: any; Event: infer T } ? T + : { + prototype: __Event; + new(type: string, eventInitDict?: EventInit): __Event; + }; + + /** + * EventTarget is a DOM interface implemented by objects that can + * receive events and may have listeners for them. + */ + interface EventTarget extends __EventTarget {} + var EventTarget: typeof globalThis extends { onmessage: any; EventTarget: infer T } ? T + : { + prototype: __EventTarget; + new(): __EventTarget; + }; +} diff --git a/node_modules/@types/node/ts4.8/domain.d.ts b/node_modules/@types/node/ts4.8/domain.d.ts old mode 100755 new mode 100644 index a3ce7ee..72f17bd --- a/node_modules/@types/node/ts4.8/domain.d.ts +++ b/node_modules/@types/node/ts4.8/domain.d.ts @@ -12,10 +12,10 @@ * will be notified, rather than losing the context of the error in the`process.on('uncaughtException')` handler, or causing the program to * exit immediately with an error code. * @deprecated Since v1.4.2 - Deprecated - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/domain.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/domain.js) */ -declare module 'domain' { - import EventEmitter = require('node:events'); +declare module "domain" { + import EventEmitter = require("node:events"); /** * The `Domain` class encapsulates the functionality of routing errors and * uncaught exceptions to the active `Domain` object. @@ -56,15 +56,15 @@ declare module 'domain' { exit(): void; /** * Run the supplied function in the context of the domain, implicitly - * binding all event emitters, timers, and lowlevel requests that are + * binding all event emitters, timers, and low-level requests that are * created in that context. Optionally, arguments can be passed to * the function. * * This is the most basic way to use a domain. * * ```js - * const domain = require('domain'); - * const fs = require('fs'); + * const domain = require('node:domain'); + * const fs = require('node:fs'); * const d = domain.create(); * d.on('error', (er) => { * console.error('Caught error!', er); @@ -165,6 +165,6 @@ declare module 'domain' { } function create(): Domain; } -declare module 'node:domain' { - export * from 'domain'; +declare module "node:domain" { + export * from "domain"; } diff --git a/node_modules/@types/node/ts4.8/events.d.ts b/node_modules/@types/node/ts4.8/events.d.ts old mode 100755 new mode 100644 index 631841a..6ed47c5 --- a/node_modules/@types/node/ts4.8/events.d.ts +++ b/node_modules/@types/node/ts4.8/events.d.ts @@ -22,7 +22,7 @@ * the `eventEmitter.emit()` method is used to trigger the event. * * ```js - * const EventEmitter = require('events'); + * import { EventEmitter } from 'node:events'; * * class MyEmitter extends EventEmitter {} * @@ -32,25 +32,61 @@ * }); * myEmitter.emit('event'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/events.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/events.js) */ -declare module 'events' { +declare module "events" { + import { AsyncResource, AsyncResourceOptions } from "node:async_hooks"; + // NOTE: This class is in the docs but is **not actually exported** by Node. + // If https://github.com/nodejs/node/issues/39903 gets resolved and Node + // actually starts exporting the class, uncomment below. + // import { EventListener, EventListenerObject } from '__dom-events'; + // /** The NodeEventTarget is a Node.js-specific extension to EventTarget that emulates a subset of the EventEmitter API. */ + // interface NodeEventTarget extends EventTarget { + // /** + // * Node.js-specific extension to the `EventTarget` class that emulates the equivalent `EventEmitter` API. + // * The only difference between `addListener()` and `addEventListener()` is that addListener() will return a reference to the EventTarget. + // */ + // addListener(type: string, listener: EventListener | EventListenerObject, options?: { once: boolean }): this; + // /** Node.js-specific extension to the `EventTarget` class that returns an array of event `type` names for which event listeners are registered. */ + // eventNames(): string[]; + // /** Node.js-specific extension to the `EventTarget` class that returns the number of event listeners registered for the `type`. */ + // listenerCount(type: string): number; + // /** Node.js-specific alias for `eventTarget.removeListener()`. */ + // off(type: string, listener: EventListener | EventListenerObject): this; + // /** Node.js-specific alias for `eventTarget.addListener()`. */ + // on(type: string, listener: EventListener | EventListenerObject, options?: { once: boolean }): this; + // /** Node.js-specific extension to the `EventTarget` class that adds a `once` listener for the given event `type`. This is equivalent to calling `on` with the `once` option set to `true`. */ + // once(type: string, listener: EventListener | EventListenerObject): this; + // /** + // * Node.js-specific extension to the `EventTarget` class. + // * If `type` is specified, removes all registered listeners for `type`, + // * otherwise removes all registered listeners. + // */ + // removeAllListeners(type: string): this; + // /** + // * Node.js-specific extension to the `EventTarget` class that removes the listener for the given `type`. + // * The only difference between `removeListener()` and `removeEventListener()` is that `removeListener()` will return a reference to the `EventTarget`. + // */ + // removeListener(type: string, listener: EventListener | EventListenerObject): this; + // } interface EventEmitterOptions { /** * Enables automatic capturing of promise rejection. */ captureRejections?: boolean | undefined; } - interface NodeEventTarget { + // Any EventTarget with a Node-style `once` function + interface _NodeEventTarget { once(eventName: string | symbol, listener: (...args: any[]) => void): this; } - interface DOMEventTarget { + // Any EventTarget with a DOM-style `addEventListener` + interface _DOMEventTarget { addEventListener( eventName: string, listener: (...args: any[]) => void, opts?: { once: boolean; - } + }, ): any; } interface StaticEventEmitterOptions { @@ -58,10 +94,10 @@ declare module 'events' { } interface EventEmitter extends NodeJS.EventEmitter {} /** - * The `EventEmitter` class is defined and exposed by the `events` module: + * The `EventEmitter` class is defined and exposed by the `node:events` module: * * ```js - * const EventEmitter = require('events'); + * import { EventEmitter } from 'node:events'; * ``` * * All `EventEmitter`s emit the event `'newListener'` when new listeners are @@ -72,6 +108,9 @@ declare module 'events' { */ class EventEmitter { constructor(options?: EventEmitterOptions); + + [EventEmitter.captureRejectionSymbol]?(error: Error, event: string, ...args: any[]): void; + /** * Creates a `Promise` that is fulfilled when the `EventEmitter` emits the given * event or that is rejected if the `EventEmitter` emits `'error'` while waiting. @@ -82,31 +121,28 @@ declare module 'events' { * semantics and does not listen to the `'error'` event. * * ```js - * const { once, EventEmitter } = require('events'); + * import { once, EventEmitter } from 'node:events'; + * import process from 'node:process'; * - * async function run() { - * const ee = new EventEmitter(); + * const ee = new EventEmitter(); * - * process.nextTick(() => { - * ee.emit('myevent', 42); - * }); + * process.nextTick(() => { + * ee.emit('myevent', 42); + * }); * - * const [value] = await once(ee, 'myevent'); - * console.log(value); + * const [value] = await once(ee, 'myevent'); + * console.log(value); * - * const err = new Error('kaboom'); - * process.nextTick(() => { - * ee.emit('error', err); - * }); + * const err = new Error('kaboom'); + * process.nextTick(() => { + * ee.emit('error', err); + * }); * - * try { - * await once(ee, 'myevent'); - * } catch (err) { - * console.log('error happened', err); - * } + * try { + * await once(ee, 'myevent'); + * } catch (err) { + * console.error('error happened', err); * } - * - * run(); * ``` * * The special handling of the `'error'` event is only used when `events.once()`is used to wait for another event. If `events.once()` is used to wait for the @@ -114,13 +150,13 @@ declare module 'events' { * special handling: * * ```js - * const { EventEmitter, once } = require('events'); + * import { EventEmitter, once } from 'node:events'; * * const ee = new EventEmitter(); * * once(ee, 'error') * .then(([err]) => console.log('ok', err.message)) - * .catch((err) => console.log('error', err.message)); + * .catch((err) => console.error('error', err.message)); * * ee.emit('error', new Error('boom')); * @@ -130,7 +166,7 @@ declare module 'events' { * An `AbortSignal` can be used to cancel waiting for the event: * * ```js - * const { EventEmitter, once } = require('events'); + * import { EventEmitter, once } from 'node:events'; * * const ee = new EventEmitter(); * const ac = new AbortController(); @@ -154,29 +190,32 @@ declare module 'events' { * ``` * @since v11.13.0, v10.16.0 */ - static once(emitter: NodeEventTarget, eventName: string | symbol, options?: StaticEventEmitterOptions): Promise; - static once(emitter: DOMEventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise; + static once( + emitter: _NodeEventTarget, + eventName: string | symbol, + options?: StaticEventEmitterOptions, + ): Promise; + static once(emitter: _DOMEventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise; /** * ```js - * const { on, EventEmitter } = require('events'); + * import { on, EventEmitter } from 'node:events'; + * import process from 'node:process'; * - * (async () => { - * const ee = new EventEmitter(); + * const ee = new EventEmitter(); * - * // Emit later on - * process.nextTick(() => { - * ee.emit('foo', 'bar'); - * ee.emit('foo', 42); - * }); + * // Emit later on + * process.nextTick(() => { + * ee.emit('foo', 'bar'); + * ee.emit('foo', 42); + * }); * - * for await (const event of on(ee, 'foo')) { - * // The execution of this inner block is synchronous and it - * // processes one event at a time (even with await). Do not use - * // if concurrent execution is required. - * console.log(event); // prints ['bar'] [42] - * } - * // Unreachable here - * })(); + * for await (const event of on(ee, 'foo')) { + * // The execution of this inner block is synchronous and it + * // processes one event at a time (even with await). Do not use + * // if concurrent execution is required. + * console.log(event); // prints ['bar'] [42] + * } + * // Unreachable here * ``` * * Returns an `AsyncIterator` that iterates `eventName` events. It will throw @@ -187,7 +226,9 @@ declare module 'events' { * An `AbortSignal` can be used to cancel waiting on events: * * ```js - * const { on, EventEmitter } = require('events'); + * import { on, EventEmitter } from 'node:events'; + * import process from 'node:process'; + * * const ac = new AbortController(); * * (async () => { @@ -214,12 +255,17 @@ declare module 'events' { * @param eventName The name of the event being listened for * @return that iterates `eventName` events emitted by the `emitter` */ - static on(emitter: NodeJS.EventEmitter, eventName: string, options?: StaticEventEmitterOptions): AsyncIterableIterator; + static on( + emitter: NodeJS.EventEmitter, + eventName: string, + options?: StaticEventEmitterOptions, + ): AsyncIterableIterator; /** * A class method that returns the number of listeners for the given `eventName`registered on the given `emitter`. * * ```js - * const { EventEmitter, listenerCount } = require('events'); + * import { EventEmitter, listenerCount } from 'node:events'; + * * const myEmitter = new EventEmitter(); * myEmitter.on('event', () => {}); * myEmitter.on('event', () => {}); @@ -242,30 +288,56 @@ declare module 'events' { * event target. This is useful for debugging and diagnostic purposes. * * ```js - * const { getEventListeners, EventEmitter } = require('events'); + * import { getEventListeners, EventEmitter } from 'node:events'; * * { * const ee = new EventEmitter(); * const listener = () => console.log('Events are fun'); * ee.on('foo', listener); - * getEventListeners(ee, 'foo'); // [listener] + * console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ] * } * { * const et = new EventTarget(); * const listener = () => console.log('Events are fun'); * et.addEventListener('foo', listener); - * getEventListeners(et, 'foo'); // [listener] + * console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ] * } * ``` - * @since v15.2.0 + * @since v15.2.0, v14.17.0 */ - static getEventListeners(emitter: DOMEventTarget | NodeJS.EventEmitter, name: string | symbol): Function[]; + static getEventListeners(emitter: _DOMEventTarget | NodeJS.EventEmitter, name: string | symbol): Function[]; + /** + * Returns the currently set max amount of listeners. + * + * For `EventEmitter`s this behaves exactly the same as calling `.getMaxListeners` on + * the emitter. + * + * For `EventTarget`s this is the only way to get the max event listeners for the + * event target. If the number of event handlers on a single EventTarget exceeds + * the max set, the EventTarget will print a warning. + * + * ```js + * import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events'; + * + * { + * const ee = new EventEmitter(); + * console.log(getMaxListeners(ee)); // 10 + * setMaxListeners(11, ee); + * console.log(getMaxListeners(ee)); // 11 + * } + * { + * const et = new EventTarget(); + * console.log(getMaxListeners(et)); // 10 + * setMaxListeners(11, et); + * console.log(getMaxListeners(et)); // 11 + * } + * ``` + * @since v19.9.0 + */ + static getMaxListeners(emitter: _DOMEventTarget | NodeJS.EventEmitter): number; /** * ```js - * const { - * setMaxListeners, - * EventEmitter - * } = require('events'); + * import { setMaxListeners, EventEmitter } from 'node:events'; * * const target = new EventTarget(); * const emitter = new EventEmitter(); @@ -277,26 +349,103 @@ declare module 'events' { * @param eventsTargets Zero or more {EventTarget} or {EventEmitter} instances. If none are specified, `n` is set as the default max for all newly created {EventTarget} and {EventEmitter} * objects. */ - static setMaxListeners(n?: number, ...eventTargets: Array): void; + static setMaxListeners(n?: number, ...eventTargets: Array<_DOMEventTarget | NodeJS.EventEmitter>): void; /** - * This symbol shall be used to install a listener for only monitoring `'error'` - * events. Listeners installed using this symbol are called before the regular - * `'error'` listeners are called. + * Listens once to the `abort` event on the provided `signal`. * - * Installing a listener using this symbol does not change the behavior once an - * `'error'` event is emitted, therefore the process will still crash if no + * Listening to the `abort` event on abort signals is unsafe and may + * lead to resource leaks since another third party with the signal can + * call `e.stopImmediatePropagation()`. Unfortunately Node.js cannot change + * this since it would violate the web standard. Additionally, the original + * API makes it easy to forget to remove listeners. + * + * This API allows safely using `AbortSignal`s in Node.js APIs by solving these + * two issues by listening to the event such that `stopImmediatePropagation` does + * not prevent the listener from running. + * + * Returns a disposable so that it may be unsubscribed from more easily. + * + * ```js + * import { addAbortListener } from 'node:events'; + * + * function example(signal) { + * let disposable; + * try { + * signal.addEventListener('abort', (e) => e.stopImmediatePropagation()); + * disposable = addAbortListener(signal, (e) => { + * // Do something when signal is aborted. + * }); + * } finally { + * disposable?.[Symbol.dispose](); + * } + * } + * ``` + * @since v20.5.0 + * @experimental + * @return Disposable that removes the `abort` listener. + */ + static addAbortListener(signal: AbortSignal, resource: (event: Event) => void): Disposable; + /** + * This symbol shall be used to install a listener for only monitoring `'error'`events. Listeners installed using this symbol are called before the regular`'error'` listeners are called. + * + * Installing a listener using this symbol does not change the behavior once an`'error'` event is emitted. Therefore, the process will still crash if no * regular `'error'` listener is installed. + * @since v13.6.0, v12.17.0 */ static readonly errorMonitor: unique symbol; + /** + * Value: `Symbol.for('nodejs.rejection')` + * + * See how to write a custom `rejection handler`. + * @since v13.4.0, v12.16.0 + */ static readonly captureRejectionSymbol: unique symbol; /** - * Sets or gets the default captureRejection value for all emitters. + * Value: [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) + * + * Change the default `captureRejections` option on all new `EventEmitter` objects. + * @since v13.4.0, v12.16.0 */ - // TODO: These should be described using static getter/setter pairs: static captureRejections: boolean; + /** + * By default, a maximum of `10` listeners can be registered for any single + * event. This limit can be changed for individual `EventEmitter` instances + * using the `emitter.setMaxListeners(n)` method. To change the default + * for _all_`EventEmitter` instances, the `events.defaultMaxListeners`property can be used. If this value is not a positive number, a `RangeError`is thrown. + * + * Take caution when setting the `events.defaultMaxListeners` because the + * change affects _all_`EventEmitter` instances, including those created before + * the change is made. However, calling `emitter.setMaxListeners(n)` still has + * precedence over `events.defaultMaxListeners`. + * + * This is not a hard limit. The `EventEmitter` instance will allow + * more listeners to be added but will output a trace warning to stderr indicating + * that a "possible EventEmitter memory leak" has been detected. For any single`EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()`methods can be used to + * temporarily avoid this warning: + * + * ```js + * import { EventEmitter } from 'node:events'; + * const emitter = new EventEmitter(); + * emitter.setMaxListeners(emitter.getMaxListeners() + 1); + * emitter.once('event', () => { + * // do stuff + * emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0)); + * }); + * ``` + * + * The `--trace-warnings` command-line flag can be used to display the + * stack trace for such warnings. + * + * The emitted warning can be inspected with `process.on('warning')` and will + * have the additional `emitter`, `type`, and `count` properties, referring to + * the event emitter instance, the event's name and the number of attached + * listeners, respectively. + * Its `name` property is set to `'MaxListenersExceededWarning'`. + * @since v0.11.2 + */ static defaultMaxListeners: number; } - import internal = require('node:events'); + import internal = require("node:events"); namespace EventEmitter { // Should just be `export { EventEmitter }`, but that doesn't work in TypeScript 3.4 export { internal as EventEmitter }; @@ -306,10 +455,89 @@ declare module 'events' { */ signal?: AbortSignal | undefined; } + + export interface EventEmitterReferencingAsyncResource extends AsyncResource { + readonly eventEmitter: EventEmitterAsyncResource; + } + + export interface EventEmitterAsyncResourceOptions extends AsyncResourceOptions, EventEmitterOptions { + /** + * The type of async event, this is required when instantiating `EventEmitterAsyncResource` + * directly rather than as a child class. + * @default new.target.name if instantiated as a child class. + */ + name?: string; + } + + /** + * Integrates `EventEmitter` with `AsyncResource` for `EventEmitter`s that + * require manual async tracking. Specifically, all events emitted by instances + * of `events.EventEmitterAsyncResource` will run within its `async context`. + * + * ```js + * import { EventEmitterAsyncResource, EventEmitter } from 'node:events'; + * import { notStrictEqual, strictEqual } from 'node:assert'; + * import { executionAsyncId, triggerAsyncId } from 'node:async_hooks'; + * + * // Async tracking tooling will identify this as 'Q'. + * const ee1 = new EventEmitterAsyncResource({ name: 'Q' }); + * + * // 'foo' listeners will run in the EventEmitters async context. + * ee1.on('foo', () => { + * strictEqual(executionAsyncId(), ee1.asyncId); + * strictEqual(triggerAsyncId(), ee1.triggerAsyncId); + * }); + * + * const ee2 = new EventEmitter(); + * + * // 'foo' listeners on ordinary EventEmitters that do not track async + * // context, however, run in the same async context as the emit(). + * ee2.on('foo', () => { + * notStrictEqual(executionAsyncId(), ee2.asyncId); + * notStrictEqual(triggerAsyncId(), ee2.triggerAsyncId); + * }); + * + * Promise.resolve().then(() => { + * ee1.emit('foo'); + * ee2.emit('foo'); + * }); + * ``` + * + * The `EventEmitterAsyncResource` class has the same methods and takes the + * same options as `EventEmitter` and `AsyncResource` themselves. + * @since v17.4.0, v16.14.0 + */ + export class EventEmitterAsyncResource extends EventEmitter { + /** + * @param options Only optional in child class. + */ + constructor(options?: EventEmitterAsyncResourceOptions); + /** + * Call all `destroy` hooks. This should only ever be called once. An error will + * be thrown if it is called more than once. This **must** be manually called. If + * the resource is left to be collected by the GC then the `destroy` hooks will + * never be called. + */ + emitDestroy(): void; + /** + * The unique `asyncId` assigned to the resource. + */ + readonly asyncId: number; + /** + * The same triggerAsyncId that is passed to the AsyncResource constructor. + */ + readonly triggerAsyncId: number; + /** + * The returned `AsyncResource` object has an additional `eventEmitter` property + * that provides a reference to this `EventEmitterAsyncResource`. + */ + readonly asyncResource: EventEmitterReferencingAsyncResource; + } } global { namespace NodeJS { interface EventEmitter { + [EventEmitter.captureRejectionSymbol]?(error: Error, event: string, ...args: any[]): void; /** * Alias for `emitter.on(eventName, listener)`. * @since v0.1.26 @@ -333,6 +561,7 @@ declare module 'events' { * event listener to the beginning of the listeners array. * * ```js + * import { EventEmitter } from 'node:events'; * const myEE = new EventEmitter(); * myEE.on('foo', () => console.log('a')); * myEE.prependListener('foo', () => console.log('b')); @@ -362,6 +591,7 @@ declare module 'events' { * event listener to the beginning of the listeners array. * * ```js + * import { EventEmitter } from 'node:events'; * const myEE = new EventEmitter(); * myEE.once('foo', () => console.log('a')); * myEE.prependOnceListener('foo', () => console.log('b')); @@ -393,10 +623,12 @@ declare module 'events' { * called multiple times to remove each instance. * * Once an event is emitted, all listeners attached to it at the - * time of emitting are called in order. This implies that any`removeListener()` or `removeAllListeners()` calls _after_ emitting and_before_ the last listener finishes execution will - * not remove them from`emit()` in progress. Subsequent events behave as expected. + * time of emitting are called in order. This implies that any`removeListener()` or `removeAllListeners()` calls _after_ emitting and _before_ the last listener finishes execution + * will not remove them from`emit()` in progress. Subsequent events behave as expected. * * ```js + * import { EventEmitter } from 'node:events'; + * class MyEmitter extends EventEmitter {} * const myEmitter = new MyEmitter(); * * const callbackA = () => { @@ -437,6 +669,7 @@ declare module 'events' { * recently added instance. In the example the `once('ping')`listener is removed: * * ```js + * import { EventEmitter } from 'node:events'; * const ee = new EventEmitter(); * * function pong() { @@ -505,6 +738,7 @@ declare module 'events' { * including any wrappers (such as those created by `.once()`). * * ```js + * import { EventEmitter } from 'node:events'; * const emitter = new EventEmitter(); * emitter.once('log', () => console.log('log once')); * @@ -537,7 +771,7 @@ declare module 'events' { * Returns `true` if the event had listeners, `false` otherwise. * * ```js - * const EventEmitter = require('events'); + * import { EventEmitter } from 'node:events'; * const myEmitter = new EventEmitter(); * * // First listener @@ -572,11 +806,14 @@ declare module 'events' { */ emit(eventName: string | symbol, ...args: any[]): boolean; /** - * Returns the number of listeners listening to the event named `eventName`. + * Returns the number of listeners listening for the event named `eventName`. + * If `listener` is provided, it will return how many times the listener is found + * in the list of the listeners of the event. * @since v3.2.0 * @param eventName The name of the event being listened for + * @param listener The event handler function */ - listenerCount(eventName: string | symbol): number; + listenerCount(eventName: string | symbol, listener?: Function): number; /** * Adds the `listener` function to the _beginning_ of the listeners array for the * event named `eventName`. No checks are made to see if the `listener` has @@ -596,7 +833,7 @@ declare module 'events' { */ prependListener(eventName: string | symbol, listener: (...args: any[]) => void): this; /** - * Adds a **one-time**`listener` function for the event named `eventName` to the_beginning_ of the listeners array. The next time `eventName` is triggered, this + * Adds a **one-time**`listener` function for the event named `eventName` to the _beginning_ of the listeners array. The next time `eventName` is triggered, this * listener is removed, and then invoked. * * ```js @@ -616,7 +853,8 @@ declare module 'events' { * listeners. The values in the array are strings or `Symbol`s. * * ```js - * const EventEmitter = require('events'); + * import { EventEmitter } from 'node:events'; + * * const myEE = new EventEmitter(); * myEE.on('foo', () => {}); * myEE.on('bar', () => {}); @@ -635,7 +873,7 @@ declare module 'events' { } export = EventEmitter; } -declare module 'node:events' { - import events = require('events'); +declare module "node:events" { + import events = require("events"); export = events; } diff --git a/node_modules/@types/node/ts4.8/fs.d.ts b/node_modules/@types/node/ts4.8/fs.d.ts old mode 100755 new mode 100644 index a7b46c0..5cbca12 --- a/node_modules/@types/node/ts4.8/fs.d.ts +++ b/node_modules/@types/node/ts4.8/fs.d.ts @@ -1,28 +1,28 @@ /** - * The `fs` module enables interacting with the file system in a + * The `node:fs` module enables interacting with the file system in a * way modeled on standard POSIX functions. * * To use the promise-based APIs: * * ```js - * import * as fs from 'fs/promises'; + * import * as fs from 'node:fs/promises'; * ``` * * To use the callback and sync APIs: * * ```js - * import * as fs from 'fs'; + * import * as fs from 'node:fs'; * ``` * * All file system operations have synchronous, callback, and promise-based * forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM). - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/fs.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/fs.js) */ -declare module 'fs' { - import * as stream from 'node:stream'; - import { Abortable, EventEmitter } from 'node:events'; - import { URL } from 'node:url'; - import * as promises from 'node:fs/promises'; +declare module "fs" { + import * as stream from "node:stream"; + import { Abortable, EventEmitter } from "node:events"; + import { URL } from "node:url"; + import * as promises from "node:fs/promises"; export { promises }; /** * Valid types for path values in "fs". @@ -32,10 +32,10 @@ declare module 'fs' { export type TimeLike = string | number | Date; export type NoParamCallback = (err: NodeJS.ErrnoException | null) => void; export type BufferEncodingOption = - | 'buffer' + | "buffer" | { - encoding: 'buffer'; - }; + encoding: "buffer"; + }; export interface ObjectEncodingOptions { encoding?: BufferEncoding | null | undefined; } @@ -73,7 +73,7 @@ declare module 'fs' { /** * A `fs.Stats` object provides information about a file. * - * Objects returned from {@link stat}, {@link lstat} and {@link fstat} and + * Objects returned from {@link stat}, {@link lstat}, {@link fstat}, and * their synchronous counterparts are of this type. * If `bigint` in the `options` passed to those methods is true, the numeric values * will be `bigint` instead of `number`, and the object will contain additional @@ -131,6 +131,62 @@ declare module 'fs' { * @since v0.1.21 */ export class Stats {} + export interface StatsFsBase { + /** Type of file system. */ + type: T; + /** Optimal transfer block size. */ + bsize: T; + /** Total data blocks in file system. */ + blocks: T; + /** Free blocks in file system. */ + bfree: T; + /** Available blocks for unprivileged users */ + bavail: T; + /** Total file nodes in file system. */ + files: T; + /** Free file nodes in file system. */ + ffree: T; + } + export interface StatsFs extends StatsFsBase {} + /** + * Provides information about a mounted file system. + * + * Objects returned from {@link statfs} and its synchronous counterpart are of + * this type. If `bigint` in the `options` passed to those methods is `true`, the + * numeric values will be `bigint` instead of `number`. + * + * ```console + * StatFs { + * type: 1397114950, + * bsize: 4096, + * blocks: 121938943, + * bfree: 61058895, + * bavail: 61058895, + * files: 999, + * ffree: 1000000 + * } + * ``` + * + * `bigint` version: + * + * ```console + * StatFs { + * type: 1397114950n, + * bsize: 4096n, + * blocks: 121938943n, + * bfree: 61058895n, + * bavail: 61058895n, + * files: 999n, + * ffree: 1000000n + * } + * ``` + * @since v19.6.0, v18.15.0 + */ + export class StatsFs {} + export interface BigIntStatsFs extends StatsFsBase {} + export interface StatFsOptions { + bigint?: boolean | undefined; + } /** * A representation of a directory entry, which can be a file or a subdirectory * within the directory, as returned by reading from an `fs.Dir`. The @@ -184,6 +240,11 @@ declare module 'fs' { * @since v10.10.0 */ name: string; + /** + * The base path that this `fs.Dirent` object refers to. + * @since v20.1.0 + */ + path: string; } /** * A class representing a directory stream. @@ -191,7 +252,7 @@ declare module 'fs' { * Created by {@link opendir}, {@link opendirSync}, or `fsPromises.opendir()`. * * ```js - * import { opendir } from 'fs/promises'; + * import { opendir } from 'node:fs/promises'; * * try { * const dir = await opendir('./'); @@ -220,7 +281,7 @@ declare module 'fs' { * Asynchronously close the directory's underlying resource handle. * Subsequent reads will result in errors. * - * A promise is returned that will be resolved after the resource has been + * A promise is returned that will be fulfilled after the resource has been * closed. * @since v12.12.0 */ @@ -235,7 +296,7 @@ declare module 'fs' { /** * Asynchronously read the next directory entry via [`readdir(3)`](http://man7.org/linux/man-pages/man3/readdir.3.html) as an `fs.Dirent`. * - * A promise is returned that will be resolved with an `fs.Dirent`, or `null`if there are no more directory entries to read. + * A promise is returned that will be fulfilled with an `fs.Dirent`, or `null`if there are no more directory entries to read. * * Directory entries returned by this function are in no particular order as * provided by the operating system's underlying directory mechanisms. @@ -268,18 +329,22 @@ declare module 'fs' { */ export interface StatWatcher extends EventEmitter { /** + * When called, requests that the Node.js event loop _not_ exit so long as the `fs.StatWatcher` is active. Calling `watcher.ref()` multiple times will have + * no effect. + * + * By default, all `fs.StatWatcher` objects are "ref'ed", making it normally + * unnecessary to call `watcher.ref()` unless `watcher.unref()` had been + * called previously. * @since v14.3.0, v12.20.0 - * When called, requests that the Node.js event loop not exit so long as the `fs.StatWatcher` is active. - * Calling `watcher.ref()` multiple times will have no effect. - * By default, all `fs.StatWatcher`` objects are "ref'ed", making it normally unnecessary to call `watcher.ref()` - * unless `watcher.unref()` had been called previously. */ ref(): this; /** + * When called, the active `fs.StatWatcher` object will not require the Node.js + * event loop to remain active. If there is no other activity keeping the + * event loop running, the process may exit before the `fs.StatWatcher` object's + * callback is invoked. Calling `watcher.unref()` multiple times will have + * no effect. * @since v14.3.0, v12.20.0 - * When called, the active `fs.StatWatcher`` object will not require the Node.js event loop to remain active. - * If there is no other activity keeping the event loop running, the process may exit before the `fs.StatWatcher`` object's callback is invoked. - * `Calling watcher.unref()` multiple times will have no effect. */ unref(): this; } @@ -289,31 +354,51 @@ declare module 'fs' { * @since v0.5.8 */ close(): void; + /** + * When called, requests that the Node.js event loop _not_ exit so long as the `fs.FSWatcher` is active. Calling `watcher.ref()` multiple times will have + * no effect. + * + * By default, all `fs.FSWatcher` objects are "ref'ed", making it normally + * unnecessary to call `watcher.ref()` unless `watcher.unref()` had been + * called previously. + * @since v14.3.0, v12.20.0 + */ + ref(): this; + /** + * When called, the active `fs.FSWatcher` object will not require the Node.js + * event loop to remain active. If there is no other activity keeping the + * event loop running, the process may exit before the `fs.FSWatcher` object's + * callback is invoked. Calling `watcher.unref()` multiple times will have + * no effect. + * @since v14.3.0, v12.20.0 + */ + unref(): this; /** * events.EventEmitter * 1. change - * 2. error + * 2. close + * 3. error */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'change', listener: (eventType: string, filename: string | Buffer) => void): this; - addListener(event: 'error', listener: (error: Error) => void): this; - addListener(event: 'close', listener: () => void): this; + addListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "error", listener: (error: Error) => void): this; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'change', listener: (eventType: string, filename: string | Buffer) => void): this; - on(event: 'error', listener: (error: Error) => void): this; - on(event: 'close', listener: () => void): this; + on(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; + on(event: "close", listener: () => void): this; + on(event: "error", listener: (error: Error) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'change', listener: (eventType: string, filename: string | Buffer) => void): this; - once(event: 'error', listener: (error: Error) => void): this; - once(event: 'close', listener: () => void): this; + once(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; + once(event: "close", listener: () => void): this; + once(event: "error", listener: (error: Error) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'change', listener: (eventType: string, filename: string | Buffer) => void): this; - prependListener(event: 'error', listener: (error: Error) => void): this; - prependListener(event: 'close', listener: () => void): this; + prependListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "error", listener: (error: Error) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'change', listener: (eventType: string, filename: string | Buffer) => void): this; - prependOnceListener(event: 'error', listener: (error: Error) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; + prependOnceListener(event: "change", listener: (eventType: string, filename: string | Buffer) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "error", listener: (error: Error) => void): this; } /** * Instances of `fs.ReadStream` are created and returned using the {@link createReadStream} function. @@ -345,55 +430,55 @@ declare module 'fs' { * 2. close * 3. ready */ - addListener(event: 'close', listener: () => void): this; - addListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - addListener(event: 'end', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'open', listener: (fd: number) => void): this; - addListener(event: 'pause', listener: () => void): this; - addListener(event: 'readable', listener: () => void): this; - addListener(event: 'ready', listener: () => void): this; - addListener(event: 'resume', listener: () => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: Buffer | string) => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "open", listener: (fd: number) => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "readable", listener: () => void): this; + addListener(event: "ready", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'data', listener: (chunk: Buffer | string) => void): this; - on(event: 'end', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'open', listener: (fd: number) => void): this; - on(event: 'pause', listener: () => void): this; - on(event: 'readable', listener: () => void): this; - on(event: 'ready', listener: () => void): this; - on(event: 'resume', listener: () => void): this; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: Buffer | string) => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "open", listener: (fd: number) => void): this; + on(event: "pause", listener: () => void): this; + on(event: "readable", listener: () => void): this; + on(event: "ready", listener: () => void): this; + on(event: "resume", listener: () => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'data', listener: (chunk: Buffer | string) => void): this; - once(event: 'end', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'open', listener: (fd: number) => void): this; - once(event: 'pause', listener: () => void): this; - once(event: 'readable', listener: () => void): this; - once(event: 'ready', listener: () => void): this; - once(event: 'resume', listener: () => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: Buffer | string) => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "open", listener: (fd: number) => void): this; + once(event: "pause", listener: () => void): this; + once(event: "readable", listener: () => void): this; + once(event: "ready", listener: () => void): this; + once(event: "resume", listener: () => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependListener(event: 'end', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'open', listener: (fd: number) => void): this; - prependListener(event: 'pause', listener: () => void): this; - prependListener(event: 'readable', listener: () => void): this; - prependListener(event: 'ready', listener: () => void): this; - prependListener(event: 'resume', listener: () => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "open", listener: (fd: number) => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "readable", listener: () => void): this; + prependListener(event: "ready", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependOnceListener(event: 'end', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'open', listener: (fd: number) => void): this; - prependOnceListener(event: 'pause', listener: () => void): this; - prependOnceListener(event: 'readable', listener: () => void): this; - prependOnceListener(event: 'ready', listener: () => void): this; - prependOnceListener(event: 'resume', listener: () => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "open", listener: (fd: number) => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "readable", listener: () => void): this; + prependOnceListener(event: "ready", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } /** @@ -434,50 +519,50 @@ declare module 'fs' { * 2. close * 3. ready */ - addListener(event: 'close', listener: () => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'finish', listener: () => void): this; - addListener(event: 'open', listener: (fd: number) => void): this; - addListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - addListener(event: 'ready', listener: () => void): this; - addListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "open", listener: (fd: number) => void): this; + addListener(event: "pipe", listener: (src: stream.Readable) => void): this; + addListener(event: "ready", listener: () => void): this; + addListener(event: "unpipe", listener: (src: stream.Readable) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'finish', listener: () => void): this; - on(event: 'open', listener: (fd: number) => void): this; - on(event: 'pipe', listener: (src: stream.Readable) => void): this; - on(event: 'ready', listener: () => void): this; - on(event: 'unpipe', listener: (src: stream.Readable) => void): this; + on(event: "close", listener: () => void): this; + on(event: "drain", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "open", listener: (fd: number) => void): this; + on(event: "pipe", listener: (src: stream.Readable) => void): this; + on(event: "ready", listener: () => void): this; + on(event: "unpipe", listener: (src: stream.Readable) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'finish', listener: () => void): this; - once(event: 'open', listener: (fd: number) => void): this; - once(event: 'pipe', listener: (src: stream.Readable) => void): this; - once(event: 'ready', listener: () => void): this; - once(event: 'unpipe', listener: (src: stream.Readable) => void): this; + once(event: "close", listener: () => void): this; + once(event: "drain", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "open", listener: (fd: number) => void): this; + once(event: "pipe", listener: (src: stream.Readable) => void): this; + once(event: "ready", listener: () => void): this; + once(event: "unpipe", listener: (src: stream.Readable) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'finish', listener: () => void): this; - prependListener(event: 'open', listener: (fd: number) => void): this; - prependListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependListener(event: 'ready', listener: () => void): this; - prependListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "open", listener: (fd: number) => void): this; + prependListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependListener(event: "ready", listener: () => void): this; + prependListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'finish', listener: () => void): this; - prependOnceListener(event: 'open', listener: (fd: number) => void): this; - prependOnceListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependOnceListener(event: 'ready', listener: () => void): this; - prependOnceListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "open", listener: (fd: number) => void): this; + prependOnceListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "ready", listener: () => void): this; + prependOnceListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } /** @@ -490,7 +575,7 @@ declare module 'fs' { * See also: [`rename(2)`](http://man7.org/linux/man-pages/man2/rename.2.html). * * ```js - * import { rename } from 'fs'; + * import { rename } from 'node:fs'; * * rename('oldFile.txt', 'newFile.txt', (err) => { * if (err) throw err; @@ -523,7 +608,7 @@ declare module 'fs' { * first argument. In this case, `fs.ftruncate()` is called. * * ```js - * import { truncate } from 'fs'; + * import { truncate } from 'node:fs'; * // Assuming that 'path/file.txt' is a regular file. * truncate('path/file.txt', (err) => { * if (err) throw err; @@ -575,7 +660,7 @@ declare module 'fs' { * file: * * ```js - * import { open, close, ftruncate } from 'fs'; + * import { open, close, ftruncate } from 'node:fs'; * * function closeFd(fd) { * close(fd, (err) => { @@ -732,7 +817,7 @@ declare module 'fs' { * See the POSIX [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html) documentation for more detail. * * ```js - * import { chmod } from 'fs'; + * import { chmod } from 'node:fs'; * * chmod('my_file.txt', 0o775, (err) => { * if (err) throw err; @@ -814,7 +899,10 @@ declare module 'fs' { * * In case of an error, the `err.code` will be one of `Common System Errors`. * - * Using `fs.stat()` to check for the existence of a file before calling`fs.open()`, `fs.readFile()` or `fs.writeFile()` is not recommended. + * {@link stat} follows symbolic links. Use {@link lstat} to look at the + * links themselves. + * + * Using `fs.stat()` to check for the existence of a file before calling`fs.open()`, `fs.readFile()`, or `fs.writeFile()` is not recommended. * Instead, user code should open/read/write the file directly and handle the * error raised if the file is not available. * @@ -831,7 +919,7 @@ declare module 'fs' { * The next program will check for the stats of the given paths: * * ```js - * import { stat } from 'fs'; + * import { stat } from 'node:fs'; * * const pathsToCheck = ['./txtDir', './txtDir/file.txt']; * @@ -896,19 +984,23 @@ declare module 'fs' { path: PathLike, options: | (StatOptions & { - bigint?: false | undefined; - }) + bigint?: false | undefined; + }) | undefined, - callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void + callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void, ): void; export function stat( path: PathLike, options: StatOptions & { bigint: true; }, - callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void + callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void, + ): void; + export function stat( + path: PathLike, + options: StatOptions | undefined, + callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void, ): void; - export function stat(path: PathLike, options: StatOptions | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void): void; export namespace stat { /** * Asynchronous stat(2) - Get file status. @@ -918,13 +1010,13 @@ declare module 'fs' { path: PathLike, options?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; function __promisify__( path: PathLike, options: StatOptions & { bigint: true; - } + }, ): Promise; function __promisify__(path: PathLike, options?: StatOptions): Promise; } @@ -935,33 +1027,33 @@ declare module 'fs' { options?: StatSyncOptions & { bigint?: false | undefined; throwIfNoEntry: false; - } + }, ): Stats | undefined; ( path: PathLike, options: StatSyncOptions & { bigint: true; throwIfNoEntry: false; - } + }, ): BigIntStats | undefined; ( path: PathLike, options?: StatSyncOptions & { bigint?: false | undefined; - } + }, ): Stats; ( path: PathLike, options: StatSyncOptions & { bigint: true; - } + }, ): BigIntStats; ( path: PathLike, options: StatSyncOptions & { bigint: boolean; throwIfNoEntry?: false | undefined; - } + }, ): Stats | BigIntStats; (path: PathLike, options?: StatSyncOptions): Stats | BigIntStats | undefined; } @@ -981,19 +1073,23 @@ declare module 'fs' { fd: number, options: | (StatOptions & { - bigint?: false | undefined; - }) + bigint?: false | undefined; + }) | undefined, - callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void + callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void, ): void; export function fstat( fd: number, options: StatOptions & { bigint: true; }, - callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void + callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void, + ): void; + export function fstat( + fd: number, + options: StatOptions | undefined, + callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void, ): void; - export function fstat(fd: number, options: StatOptions | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void): void; export namespace fstat { /** * Asynchronous fstat(2) - Get file status. @@ -1003,34 +1099,35 @@ declare module 'fs' { fd: number, options?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; function __promisify__( fd: number, options: StatOptions & { bigint: true; - } + }, ): Promise; function __promisify__(fd: number, options?: StatOptions): Promise; } /** - * Synchronous fstat(2) - Get file status. - * @param fd A file descriptor. + * Retrieves the `fs.Stats` for the file descriptor. + * + * See the POSIX [`fstat(2)`](http://man7.org/linux/man-pages/man2/fstat.2.html) documentation for more detail. + * @since v0.1.95 */ export function fstatSync( fd: number, options?: StatOptions & { bigint?: false | undefined; - } + }, ): Stats; export function fstatSync( fd: number, options: StatOptions & { bigint: true; - } + }, ): BigIntStats; export function fstatSync(fd: number, options?: StatOptions): Stats | BigIntStats; - /** * Retrieves the `fs.Stats` for the symbolic link referred to by the path. * The callback gets two arguments `(err, stats)` where `stats` is a `fs.Stats` object. `lstat()` is identical to `stat()`, except that if `path` is a symbolic @@ -1044,19 +1141,23 @@ declare module 'fs' { path: PathLike, options: | (StatOptions & { - bigint?: false | undefined; - }) + bigint?: false | undefined; + }) | undefined, - callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void + callback: (err: NodeJS.ErrnoException | null, stats: Stats) => void, ): void; export function lstat( path: PathLike, options: StatOptions & { bigint: true; }, - callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void + callback: (err: NodeJS.ErrnoException | null, stats: BigIntStats) => void, + ): void; + export function lstat( + path: PathLike, + options: StatOptions | undefined, + callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void, ): void; - export function lstat(path: PathLike, options: StatOptions | undefined, callback: (err: NodeJS.ErrnoException | null, stats: Stats | BigIntStats) => void): void; export namespace lstat { /** * Asynchronous lstat(2) - Get file status. Does not dereference symbolic links. @@ -1066,16 +1167,86 @@ declare module 'fs' { path: PathLike, options?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; function __promisify__( path: PathLike, options: StatOptions & { bigint: true; - } + }, ): Promise; function __promisify__(path: PathLike, options?: StatOptions): Promise; } + /** + * Asynchronous [`statfs(2)`](http://man7.org/linux/man-pages/man2/statfs.2.html). Returns information about the mounted file system which + * contains `path`. The callback gets two arguments `(err, stats)` where `stats`is an `fs.StatFs` object. + * + * In case of an error, the `err.code` will be one of `Common System Errors`. + * @since v19.6.0, v18.15.0 + * @param path A path to an existing file or directory on the file system to be queried. + */ + export function statfs(path: PathLike, callback: (err: NodeJS.ErrnoException | null, stats: StatsFs) => void): void; + export function statfs( + path: PathLike, + options: + | (StatFsOptions & { + bigint?: false | undefined; + }) + | undefined, + callback: (err: NodeJS.ErrnoException | null, stats: StatsFs) => void, + ): void; + export function statfs( + path: PathLike, + options: StatFsOptions & { + bigint: true; + }, + callback: (err: NodeJS.ErrnoException | null, stats: BigIntStatsFs) => void, + ): void; + export function statfs( + path: PathLike, + options: StatFsOptions | undefined, + callback: (err: NodeJS.ErrnoException | null, stats: StatsFs | BigIntStatsFs) => void, + ): void; + export namespace statfs { + /** + * Asynchronous statfs(2) - Returns information about the mounted file system which contains path. The callback gets two arguments (err, stats) where stats is an object. + * @param path A path to an existing file or directory on the file system to be queried. + */ + function __promisify__( + path: PathLike, + options?: StatFsOptions & { + bigint?: false | undefined; + }, + ): Promise; + function __promisify__( + path: PathLike, + options: StatFsOptions & { + bigint: true; + }, + ): Promise; + function __promisify__(path: PathLike, options?: StatFsOptions): Promise; + } + /** + * Synchronous [`statfs(2)`](http://man7.org/linux/man-pages/man2/statfs.2.html). Returns information about the mounted file system which + * contains `path`. + * + * In case of an error, the `err.code` will be one of `Common System Errors`. + * @since v19.6.0, v18.15.0 + * @param path A path to an existing file or directory on the file system to be queried. + */ + export function statfsSync( + path: PathLike, + options?: StatFsOptions & { + bigint?: false | undefined; + }, + ): StatsFs; + export function statfsSync( + path: PathLike, + options: StatFsOptions & { + bigint: true; + }, + ): BigIntStatsFs; + export function statfsSync(path: PathLike, options?: StatFsOptions): StatsFs | BigIntStatsFs; /** * Synchronous lstat(2) - Get file status. Does not dereference symbolic links. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -1109,30 +1280,37 @@ declare module 'fs' { * * The `type` argument is only available on Windows and ignored on other platforms. * It can be set to `'dir'`, `'file'`, or `'junction'`. If the `type` argument is - * not set, Node.js will autodetect `target` type and use `'file'` or `'dir'`. If - * the `target` does not exist, `'file'` will be used. Windows junction points - * require the destination path to be absolute. When using `'junction'`, the`target` argument will automatically be normalized to absolute path. + * not a string, Node.js will autodetect `target` type and use `'file'` or `'dir'`. + * If the `target` does not exist, `'file'` will be used. Windows junction points + * require the destination path to be absolute. When using `'junction'`, the`target` argument will automatically be normalized to absolute path. Junction + * points on NTFS volumes can only point to directories. * - * Relative targets are relative to the link’s parent directory. + * Relative targets are relative to the link's parent directory. * * ```js - * import { symlink } from 'fs'; + * import { symlink } from 'node:fs'; * - * symlink('./mew', './example/mewtwo', callback); + * symlink('./mew', './mewtwo', callback); * ``` * - * The above example creates a symbolic link `mewtwo` in the `example` which points - * to `mew` in the same directory: + * The above example creates a symbolic link `mewtwo` which points to `mew` in the + * same directory: * * ```bash - * $ tree example/ - * example/ + * $ tree . + * . * ├── mew * └── mewtwo -> ./mew * ``` * @since v0.1.31 + * @param [type='null'] */ - export function symlink(target: PathLike, path: PathLike, type: symlink.Type | undefined | null, callback: NoParamCallback): void; + export function symlink( + target: PathLike, + path: PathLike, + type: symlink.Type | undefined | null, + callback: NoParamCallback, + ): void; /** * Asynchronous symlink(2) - Create a new symbolic link to an existing file. * @param target A path to an existing file. If a URL is provided, it must use the `file:` protocol. @@ -1148,7 +1326,7 @@ declare module 'fs' { * When using `'junction'`, the `target` argument will automatically be normalized to an absolute path. */ function __promisify__(target: PathLike, path: PathLike, type?: string | null): Promise; - type Type = 'dir' | 'file' | 'junction'; + type Type = "dir" | "file" | "junction"; } /** * Returns `undefined`. @@ -1156,6 +1334,7 @@ declare module 'fs' { * For detailed information, see the documentation of the asynchronous version of * this API: {@link symlink}. * @since v0.1.31 + * @param [type='null'] */ export function symlinkSync(target: PathLike, path: PathLike, type?: symlink.Type | null): void; /** @@ -1170,24 +1349,39 @@ declare module 'fs' { * the link path returned will be passed as a `Buffer` object. * @since v0.1.31 */ - export function readlink(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, linkString: string) => void): void; + export function readlink( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, linkString: string) => void, + ): void; /** * Asynchronous readlink(2) - read value of a symbolic link. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - export function readlink(path: PathLike, options: BufferEncodingOption, callback: (err: NodeJS.ErrnoException | null, linkString: Buffer) => void): void; + export function readlink( + path: PathLike, + options: BufferEncodingOption, + callback: (err: NodeJS.ErrnoException | null, linkString: Buffer) => void, + ): void; /** * Asynchronous readlink(2) - read value of a symbolic link. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - export function readlink(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, linkString: string | Buffer) => void): void; + export function readlink( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, linkString: string | Buffer) => void, + ): void; /** * Asynchronous readlink(2) - read value of a symbolic link. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ - export function readlink(path: PathLike, callback: (err: NodeJS.ErrnoException | null, linkString: string) => void): void; + export function readlink( + path: PathLike, + callback: (err: NodeJS.ErrnoException | null, linkString: string) => void, + ): void; export namespace readlink { /** * Asynchronous readlink(2) - read value of a symbolic link. @@ -1233,7 +1427,7 @@ declare module 'fs' { */ export function readlinkSync(path: PathLike, options?: EncodingOption): string | Buffer; /** - * Asynchronously computes the canonical pathname by resolving `.`, `..` and + * Asynchronously computes the canonical pathname by resolving `.`, `..`, and * symbolic links. * * A canonical pathname is not necessarily unique. Hard links and bind mounts can @@ -1258,24 +1452,39 @@ declare module 'fs' { * dependent name for that object. * @since v0.1.31 */ - export function realpath(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void): void; + export function realpath( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void, + ): void; /** * Asynchronous realpath(3) - return the canonicalized absolute pathname. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - export function realpath(path: PathLike, options: BufferEncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: Buffer) => void): void; + export function realpath( + path: PathLike, + options: BufferEncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: Buffer) => void, + ): void; /** * Asynchronous realpath(3) - return the canonicalized absolute pathname. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - export function realpath(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | Buffer) => void): void; + export function realpath( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | Buffer) => void, + ): void; /** * Asynchronous realpath(3) - return the canonicalized absolute pathname. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ - export function realpath(path: PathLike, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void): void; + export function realpath( + path: PathLike, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void, + ): void; export namespace realpath { /** * Asynchronous realpath(3) - return the canonicalized absolute pathname. @@ -1312,10 +1521,25 @@ declare module 'fs' { * this restriction. * @since v9.2.0 */ - function native(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void): void; - function native(path: PathLike, options: BufferEncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: Buffer) => void): void; - function native(path: PathLike, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | Buffer) => void): void; - function native(path: PathLike, callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void): void; + function native( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void, + ): void; + function native( + path: PathLike, + options: BufferEncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: Buffer) => void, + ): void; + function native( + path: PathLike, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string | Buffer) => void, + ): void; + function native( + path: PathLike, + callback: (err: NodeJS.ErrnoException | null, resolvedPath: string) => void, + ): void; } /** * Returns the resolved pathname. @@ -1347,7 +1571,7 @@ declare module 'fs' { * possible exception are given to the completion callback. * * ```js - * import { unlink } from 'fs'; + * import { unlink } from 'node:fs'; * // Assuming that 'path/file.txt' is a regular file. * unlink('path/file.txt', (err) => { * if (err) throw err; @@ -1390,7 +1614,7 @@ declare module 'fs' { * Use `fs.rm(path, { recursive: true, force: true })` instead. * * If `true`, perform a recursive directory removal. In - * recursive mode soperations are retried on failure. + * recursive mode, operations are retried on failure. * @default false */ recursive?: boolean | undefined; @@ -1494,18 +1718,19 @@ declare module 'fs' { * * The callback is given a possible exception and, if `recursive` is `true`, the * first directory path created, `(err[, path])`.`path` can still be `undefined` when `recursive` is `true`, if no directory was - * created. + * created (for instance, if it was previously created). * * The optional `options` argument can be an integer specifying `mode` (permission * and sticky bits), or an object with a `mode` property and a `recursive`property indicating whether parent directories should be created. Calling`fs.mkdir()` when `path` is a directory that * exists results in an error only - * when `recursive` is false. + * when `recursive` is false. If `recursive` is false and the directory exists, + * an `EEXIST` error occurs. * * ```js - * import { mkdir } from 'fs'; + * import { mkdir } from 'node:fs'; * - * // Creates /tmp/a/apple, regardless of whether `/tmp` and /tmp/a exist. - * mkdir('/tmp/a/apple', { recursive: true }, (err) => { + * // Create ./tmp/a/apple, regardless of whether ./tmp and ./tmp/a exist. + * mkdir('./tmp/a/apple', { recursive: true }, (err) => { * if (err) throw err; * }); * ``` @@ -1514,7 +1739,7 @@ declare module 'fs' { * result in an error: * * ```js - * import { mkdir } from 'fs'; + * import { mkdir } from 'node:fs'; * * mkdir('/', { recursive: true }, (err) => { * // => [Error: EPERM: operation not permitted, mkdir 'C:\'] @@ -1529,7 +1754,7 @@ declare module 'fs' { options: MakeDirectoryOptions & { recursive: true; }, - callback: (err: NodeJS.ErrnoException | null, path?: string) => void + callback: (err: NodeJS.ErrnoException | null, path?: string) => void, ): void; /** * Asynchronous mkdir(2) - create a directory. @@ -1542,11 +1767,11 @@ declare module 'fs' { options: | Mode | (MakeDirectoryOptions & { - recursive?: false | undefined; - }) + recursive?: false | undefined; + }) | null | undefined, - callback: NoParamCallback + callback: NoParamCallback, ): void; /** * Asynchronous mkdir(2) - create a directory. @@ -1554,7 +1779,11 @@ declare module 'fs' { * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`. */ - export function mkdir(path: PathLike, options: Mode | MakeDirectoryOptions | null | undefined, callback: (err: NodeJS.ErrnoException | null, path?: string) => void): void; + export function mkdir( + path: PathLike, + options: Mode | MakeDirectoryOptions | null | undefined, + callback: (err: NodeJS.ErrnoException | null, path?: string) => void, + ): void; /** * Asynchronous mkdir(2) - create a directory with a mode of `0o777`. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -1571,7 +1800,7 @@ declare module 'fs' { path: PathLike, options: MakeDirectoryOptions & { recursive: true; - } + }, ): Promise; /** * Asynchronous mkdir(2) - create a directory. @@ -1584,9 +1813,9 @@ declare module 'fs' { options?: | Mode | (MakeDirectoryOptions & { - recursive?: false | undefined; - }) - | null + recursive?: false | undefined; + }) + | null, ): Promise; /** * Asynchronous mkdir(2) - create a directory. @@ -1594,7 +1823,10 @@ declare module 'fs' { * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`. */ - function __promisify__(path: PathLike, options?: Mode | MakeDirectoryOptions | null): Promise; + function __promisify__( + path: PathLike, + options?: Mode | MakeDirectoryOptions | null, + ): Promise; } /** * Synchronously creates a directory. Returns `undefined`, or if `recursive` is`true`, the first directory path created. @@ -1607,7 +1839,7 @@ declare module 'fs' { path: PathLike, options: MakeDirectoryOptions & { recursive: true; - } + }, ): string | undefined; /** * Synchronous mkdir(2) - create a directory. @@ -1620,9 +1852,9 @@ declare module 'fs' { options?: | Mode | (MakeDirectoryOptions & { - recursive?: false | undefined; - }) - | null + recursive?: false | undefined; + }) + | null, ): void; /** * Synchronous mkdir(2) - create a directory. @@ -1646,9 +1878,11 @@ declare module 'fs' { * object with an `encoding` property specifying the character encoding to use. * * ```js - * import { mkdtemp } from 'fs'; + * import { mkdtemp } from 'node:fs'; + * import { join } from 'node:path'; + * import { tmpdir } from 'node:os'; * - * mkdtemp(path.join(os.tmpdir(), 'foo-'), (err, directory) => { + * mkdtemp(join(tmpdir(), 'foo-'), (err, directory) => { * if (err) throw err; * console.log(directory); * // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2 @@ -1658,11 +1892,11 @@ declare module 'fs' { * The `fs.mkdtemp()` method will append the six randomly selected characters * directly to the `prefix` string. For instance, given a directory `/tmp`, if the * intention is to create a temporary directory _within_`/tmp`, the `prefix`must end with a trailing platform-specific path separator - * (`require('path').sep`). + * (`require('node:path').sep`). * * ```js - * import { tmpdir } from 'os'; - * import { mkdtemp } from 'fs'; + * import { tmpdir } from 'node:os'; + * import { mkdtemp } from 'node:fs'; * * // The parent directory for the new temporary directory * const tmpDir = tmpdir(); @@ -1677,7 +1911,7 @@ declare module 'fs' { * }); * * // This method is *CORRECT*: - * import { sep } from 'path'; + * import { sep } from 'node:path'; * mkdtemp(`${tmpDir}${sep}`, (err, directory) => { * if (err) throw err; * console.log(directory); @@ -1688,7 +1922,11 @@ declare module 'fs' { * ``` * @since v5.10.0 */ - export function mkdtemp(prefix: string, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, folder: string) => void): void; + export function mkdtemp( + prefix: string, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, folder: string) => void, + ): void; /** * Asynchronously creates a unique temporary directory. * Generates six random characters to be appended behind a required prefix to create a unique temporary directory. @@ -1697,23 +1935,30 @@ declare module 'fs' { export function mkdtemp( prefix: string, options: - | 'buffer' + | "buffer" | { - encoding: 'buffer'; - }, - callback: (err: NodeJS.ErrnoException | null, folder: Buffer) => void + encoding: "buffer"; + }, + callback: (err: NodeJS.ErrnoException | null, folder: Buffer) => void, ): void; /** * Asynchronously creates a unique temporary directory. * Generates six random characters to be appended behind a required prefix to create a unique temporary directory. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - export function mkdtemp(prefix: string, options: EncodingOption, callback: (err: NodeJS.ErrnoException | null, folder: string | Buffer) => void): void; + export function mkdtemp( + prefix: string, + options: EncodingOption, + callback: (err: NodeJS.ErrnoException | null, folder: string | Buffer) => void, + ): void; /** * Asynchronously creates a unique temporary directory. * Generates six random characters to be appended behind a required prefix to create a unique temporary directory. */ - export function mkdtemp(prefix: string, callback: (err: NodeJS.ErrnoException | null, folder: string) => void): void; + export function mkdtemp( + prefix: string, + callback: (err: NodeJS.ErrnoException | null, folder: string) => void, + ): void; export namespace mkdtemp { /** * Asynchronously creates a unique temporary directory. @@ -1774,13 +2019,14 @@ declare module 'fs' { path: PathLike, options: | { - encoding: BufferEncoding | null; - withFileTypes?: false | undefined; - } + encoding: BufferEncoding | null; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } | BufferEncoding | undefined | null, - callback: (err: NodeJS.ErrnoException | null, files: string[]) => void + callback: (err: NodeJS.ErrnoException | null, files: string[]) => void, ): void; /** * Asynchronous readdir(3) - read a directory. @@ -1791,11 +2037,12 @@ declare module 'fs' { path: PathLike, options: | { - encoding: 'buffer'; - withFileTypes?: false | undefined; - } - | 'buffer', - callback: (err: NodeJS.ErrnoException | null, files: Buffer[]) => void + encoding: "buffer"; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } + | "buffer", + callback: (err: NodeJS.ErrnoException | null, files: Buffer[]) => void, ): void; /** * Asynchronous readdir(3) - read a directory. @@ -1806,18 +2053,22 @@ declare module 'fs' { path: PathLike, options: | (ObjectEncodingOptions & { - withFileTypes?: false | undefined; - }) + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }) | BufferEncoding | undefined | null, - callback: (err: NodeJS.ErrnoException | null, files: string[] | Buffer[]) => void + callback: (err: NodeJS.ErrnoException | null, files: string[] | Buffer[]) => void, ): void; /** * Asynchronous readdir(3) - read a directory. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. */ - export function readdir(path: PathLike, callback: (err: NodeJS.ErrnoException | null, files: string[]) => void): void; + export function readdir( + path: PathLike, + callback: (err: NodeJS.ErrnoException | null, files: string[]) => void, + ): void; /** * Asynchronous readdir(3) - read a directory. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -1827,8 +2078,9 @@ declare module 'fs' { path: PathLike, options: ObjectEncodingOptions & { withFileTypes: true; + recursive?: boolean | undefined; }, - callback: (err: NodeJS.ErrnoException | null, files: Dirent[]) => void + callback: (err: NodeJS.ErrnoException | null, files: Dirent[]) => void, ): void; export namespace readdir { /** @@ -1840,11 +2092,12 @@ declare module 'fs' { path: PathLike, options?: | { - encoding: BufferEncoding | null; - withFileTypes?: false | undefined; - } + encoding: BufferEncoding | null; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } | BufferEncoding - | null + | null, ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -1854,11 +2107,12 @@ declare module 'fs' { function __promisify__( path: PathLike, options: - | 'buffer' + | "buffer" | { - encoding: 'buffer'; - withFileTypes?: false | undefined; - } + encoding: "buffer"; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }, ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -1869,10 +2123,11 @@ declare module 'fs' { path: PathLike, options?: | (ObjectEncodingOptions & { - withFileTypes?: false | undefined; - }) + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }) | BufferEncoding - | null + | null, ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -1883,7 +2138,8 @@ declare module 'fs' { path: PathLike, options: ObjectEncodingOptions & { withFileTypes: true; - } + recursive?: boolean | undefined; + }, ): Promise; } /** @@ -1903,11 +2159,12 @@ declare module 'fs' { path: PathLike, options?: | { - encoding: BufferEncoding | null; - withFileTypes?: false | undefined; - } + encoding: BufferEncoding | null; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } | BufferEncoding - | null + | null, ): string[]; /** * Synchronous readdir(3) - read a directory. @@ -1918,10 +2175,11 @@ declare module 'fs' { path: PathLike, options: | { - encoding: 'buffer'; - withFileTypes?: false | undefined; - } - | 'buffer' + encoding: "buffer"; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } + | "buffer", ): Buffer[]; /** * Synchronous readdir(3) - read a directory. @@ -1932,10 +2190,11 @@ declare module 'fs' { path: PathLike, options?: | (ObjectEncodingOptions & { - withFileTypes?: false | undefined; - }) + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }) | BufferEncoding - | null + | null, ): string[] | Buffer[]; /** * Synchronous readdir(3) - read a directory. @@ -1946,7 +2205,8 @@ declare module 'fs' { path: PathLike, options: ObjectEncodingOptions & { withFileTypes: true; - } + recursive?: boolean | undefined; + }, ): Dirent[]; /** * Closes the file descriptor. No arguments other than a possible exception are @@ -1993,13 +2253,22 @@ declare module 'fs' { * @param [flags='r'] See `support of file system `flags``. * @param [mode=0o666] */ - export function open(path: PathLike, flags: OpenMode | undefined, mode: Mode | undefined | null, callback: (err: NodeJS.ErrnoException | null, fd: number) => void): void; + export function open( + path: PathLike, + flags: OpenMode | undefined, + mode: Mode | undefined | null, + callback: (err: NodeJS.ErrnoException | null, fd: number) => void, + ): void; /** * Asynchronous open(2) - open and possibly create a file. If the file is created, its mode will be `0o666`. - * @param [flags='r'] See `support of file system `flags``. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. + * @param [flags='r'] See `support of file system `flags``. */ - export function open(path: PathLike, flags: OpenMode | undefined, callback: (err: NodeJS.ErrnoException | null, fd: number) => void): void; + export function open( + path: PathLike, + flags: OpenMode | undefined, + callback: (err: NodeJS.ErrnoException | null, fd: number) => void, + ): void; /** * Asynchronous open(2) - open and possibly create a file. If the file is created, its mode will be `0o666`. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -2029,7 +2298,7 @@ declare module 'fs' { * The `atime` and `mtime` arguments follow these rules: * * * Values can be either numbers representing Unix epoch time in seconds,`Date`s, or a numeric string like `'123456789.0'`. - * * If the value can not be converted to a number, or is `NaN`, `Infinity` or`-Infinity`, an `Error` will be thrown. + * * If the value can not be converted to a number, or is `NaN`, `Infinity`, or`-Infinity`, an `Error` will be thrown. * @since v0.4.2 */ export function utimes(path: PathLike, atime: TimeLike, mtime: TimeLike, callback: NoParamCallback): void; @@ -2093,8 +2362,7 @@ declare module 'fs' { */ export function fsyncSync(fd: number): void; /** - * Write `buffer` to the file specified by `fd`. If `buffer` is a normal object, it - * must have an own `toString` function property. + * Write `buffer` to the file specified by `fd`. * * `offset` determines the part of the buffer to be written, and `length` is * an integer specifying the number of bytes to write. @@ -2116,6 +2384,9 @@ declare module 'fs' { * The kernel ignores the position argument and always appends the data to * the end of the file. * @since v0.0.2 + * @param [offset=0] + * @param [length=buffer.byteLength - offset] + * @param [position='null'] */ export function write( fd: number, @@ -2123,7 +2394,7 @@ declare module 'fs' { offset: number | undefined | null, length: number | undefined | null, position: number | undefined | null, - callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void + callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void, ): void; /** * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor. @@ -2136,7 +2407,7 @@ declare module 'fs' { buffer: TBuffer, offset: number | undefined | null, length: number | undefined | null, - callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void + callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void, ): void; /** * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor. @@ -2147,13 +2418,17 @@ declare module 'fs' { fd: number, buffer: TBuffer, offset: number | undefined | null, - callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void + callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void, ): void; /** * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor. * @param fd A file descriptor. */ - export function write(fd: number, buffer: TBuffer, callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void): void; + export function write( + fd: number, + buffer: TBuffer, + callback: (err: NodeJS.ErrnoException | null, written: number, buffer: TBuffer) => void, + ): void; /** * Asynchronously writes `string` to the file referenced by the supplied file descriptor. * @param fd A file descriptor. @@ -2166,7 +2441,7 @@ declare module 'fs' { string: string, position: number | undefined | null, encoding: BufferEncoding | undefined | null, - callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void + callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void, ): void; /** * Asynchronously writes `string` to the file referenced by the supplied file descriptor. @@ -2174,13 +2449,22 @@ declare module 'fs' { * @param string A string to write. * @param position The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position. */ - export function write(fd: number, string: string, position: number | undefined | null, callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void): void; + export function write( + fd: number, + string: string, + position: number | undefined | null, + callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void, + ): void; /** * Asynchronously writes `string` to the file referenced by the supplied file descriptor. * @param fd A file descriptor. * @param string A string to write. */ - export function write(fd: number, string: string, callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void): void; + export function write( + fd: number, + string: string, + callback: (err: NodeJS.ErrnoException | null, written: number, str: string) => void, + ): void; export namespace write { /** * Asynchronously writes `buffer` to the file referenced by the supplied file descriptor. @@ -2194,7 +2478,7 @@ declare module 'fs' { buffer?: TBuffer, offset?: number, length?: number, - position?: number | null + position?: number | null, ): Promise<{ bytesWritten: number; buffer: TBuffer; @@ -2210,21 +2494,28 @@ declare module 'fs' { fd: number, string: string, position?: number | null, - encoding?: BufferEncoding | null + encoding?: BufferEncoding | null, ): Promise<{ bytesWritten: number; buffer: string; }>; } /** - * If `buffer` is a plain object, it must have an own (not inherited) `toString`function property. - * * For detailed information, see the documentation of the asynchronous version of * this API: {@link write}. * @since v0.1.21 + * @param [offset=0] + * @param [length=buffer.byteLength - offset] + * @param [position='null'] * @return The number of bytes written. */ - export function writeSync(fd: number, buffer: NodeJS.ArrayBufferView, offset?: number | null, length?: number | null, position?: number | null): number; + export function writeSync( + fd: number, + buffer: NodeJS.ArrayBufferView, + offset?: number | null, + length?: number | null, + position?: number | null, + ): number; /** * Synchronously writes `string` to the file referenced by the supplied file descriptor, returning the number of bytes written. * @param fd A file descriptor. @@ -2232,8 +2523,30 @@ declare module 'fs' { * @param position The offset from the beginning of the file where this data should be written. If not supplied, defaults to the current position. * @param encoding The expected string encoding. */ - export function writeSync(fd: number, string: string, position?: number | null, encoding?: BufferEncoding | null): number; + export function writeSync( + fd: number, + string: string, + position?: number | null, + encoding?: BufferEncoding | null, + ): number; export type ReadPosition = number | bigint; + export interface ReadSyncOptions { + /** + * @default 0 + */ + offset?: number | undefined; + /** + * @default `length of buffer` + */ + length?: number | undefined; + /** + * @default null + */ + position?: ReadPosition | null | undefined; + } + export interface ReadAsyncOptions extends ReadSyncOptions { + buffer?: TBuffer; + } /** * Read data from the file specified by `fd`. * @@ -2257,7 +2570,25 @@ declare module 'fs' { offset: number, length: number, position: ReadPosition | null, - callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void + callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void, + ): void; + /** + * Similar to the above `fs.read` function, this version takes an optional `options` object. + * If not otherwise specified in an `options` object, + * `buffer` defaults to `Buffer.alloc(16384)`, + * `offset` defaults to `0`, + * `length` defaults to `buffer.byteLength`, `- offset` as of Node 17.6.0 + * `position` defaults to `null` + * @since v12.17.0, 13.11.0 + */ + export function read( + fd: number, + options: ReadAsyncOptions, + callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: TBuffer) => void, + ): void; + export function read( + fd: number, + callback: (err: NodeJS.ErrnoException | null, bytesRead: number, buffer: NodeJS.ArrayBufferView) => void, ): void; export namespace read { /** @@ -2272,25 +2603,22 @@ declare module 'fs' { buffer: TBuffer, offset: number, length: number, - position: number | null + position: number | null, ): Promise<{ bytesRead: number; buffer: TBuffer; }>; - } - export interface ReadSyncOptions { - /** - * @default 0 - */ - offset?: number | undefined; - /** - * @default `length of buffer` - */ - length?: number | undefined; - /** - * @default null - */ - position?: ReadPosition | null | undefined; + function __promisify__( + fd: number, + options: ReadAsyncOptions, + ): Promise<{ + bytesRead: number; + buffer: TBuffer; + }>; + function __promisify__(fd: number): Promise<{ + bytesRead: number; + buffer: NodeJS.ArrayBufferView; + }>; } /** * Returns the number of `bytesRead`. @@ -2298,8 +2626,15 @@ declare module 'fs' { * For detailed information, see the documentation of the asynchronous version of * this API: {@link read}. * @since v0.1.21 + * @param [position='null'] */ - export function readSync(fd: number, buffer: NodeJS.ArrayBufferView, offset: number, length: number, position: ReadPosition | null): number; + export function readSync( + fd: number, + buffer: NodeJS.ArrayBufferView, + offset: number, + length: number, + position: ReadPosition | null, + ): number; /** * Similar to the above `fs.readSync` function, this version takes an optional `options` object. * If no `options` object is specified, it will default with the above values. @@ -2309,7 +2644,7 @@ declare module 'fs' { * Asynchronously reads the entire contents of a file. * * ```js - * import { readFile } from 'fs'; + * import { readFile } from 'node:fs'; * * readFile('/etc/passwd', (err, data) => { * if (err) throw err; @@ -2325,7 +2660,7 @@ declare module 'fs' { * If `options` is a string, then it specifies the encoding: * * ```js - * import { readFile } from 'fs'; + * import { readFile } from 'node:fs'; * * readFile('/etc/passwd', 'utf8', callback); * ``` @@ -2335,7 +2670,7 @@ declare module 'fs' { * will be returned. * * ```js - * import { readFile } from 'fs'; + * import { readFile } from 'node:fs'; * * // macOS, Linux, and Windows * readFile('', (err, data) => { @@ -2352,7 +2687,7 @@ declare module 'fs' { * request is aborted the callback is called with an `AbortError`: * * ```js - * import { readFile } from 'fs'; + * import { readFile } from 'node:fs'; * * const controller = new AbortController(); * const signal = controller.signal; @@ -2375,12 +2710,12 @@ declare module 'fs' { path: PathOrFileDescriptor, options: | ({ - encoding?: null | undefined; - flag?: string | undefined; - } & Abortable) + encoding?: null | undefined; + flag?: string | undefined; + } & Abortable) | undefined | null, - callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void + callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void, ): void; /** * Asynchronously reads the entire contents of a file. @@ -2393,11 +2728,11 @@ declare module 'fs' { path: PathOrFileDescriptor, options: | ({ - encoding: BufferEncoding; - flag?: string | undefined; - } & Abortable) + encoding: BufferEncoding; + flag?: string | undefined; + } & Abortable) | BufferEncoding, - callback: (err: NodeJS.ErrnoException | null, data: string) => void + callback: (err: NodeJS.ErrnoException | null, data: string) => void, ): void; /** * Asynchronously reads the entire contents of a file. @@ -2410,19 +2745,22 @@ declare module 'fs' { path: PathOrFileDescriptor, options: | (ObjectEncodingOptions & { - flag?: string | undefined; - } & Abortable) + flag?: string | undefined; + } & Abortable) | BufferEncoding | undefined | null, - callback: (err: NodeJS.ErrnoException | null, data: string | Buffer) => void + callback: (err: NodeJS.ErrnoException | null, data: string | Buffer) => void, ): void; /** * Asynchronously reads the entire contents of a file. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * If a file descriptor is provided, the underlying file will _not_ be closed automatically. */ - export function readFile(path: PathOrFileDescriptor, callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void): void; + export function readFile( + path: PathOrFileDescriptor, + callback: (err: NodeJS.ErrnoException | null, data: Buffer) => void, + ): void; export namespace readFile { /** * Asynchronously reads the entire contents of a file. @@ -2436,7 +2774,7 @@ declare module 'fs' { options?: { encoding?: null | undefined; flag?: string | undefined; - } | null + } | null, ): Promise; /** * Asynchronously reads the entire contents of a file. @@ -2450,10 +2788,10 @@ declare module 'fs' { path: PathOrFileDescriptor, options: | { - encoding: BufferEncoding; - flag?: string | undefined; - } - | BufferEncoding + encoding: BufferEncoding; + flag?: string | undefined; + } + | BufferEncoding, ): Promise; /** * Asynchronously reads the entire contents of a file. @@ -2467,10 +2805,10 @@ declare module 'fs' { path: PathOrFileDescriptor, options?: | (ObjectEncodingOptions & { - flag?: string | undefined; - }) + flag?: string | undefined; + }) | BufferEncoding - | null + | null, ): Promise; } /** @@ -2485,7 +2823,7 @@ declare module 'fs' { * Similar to {@link readFile}, when the path is a directory, the behavior of`fs.readFileSync()` is platform-specific. * * ```js - * import { readFileSync } from 'fs'; + * import { readFileSync } from 'node:fs'; * * // macOS, Linux, and Windows * readFileSync(''); @@ -2502,7 +2840,7 @@ declare module 'fs' { options?: { encoding?: null | undefined; flag?: string | undefined; - } | null + } | null, ): Buffer; /** * Synchronously reads the entire contents of a file. @@ -2515,10 +2853,10 @@ declare module 'fs' { path: PathOrFileDescriptor, options: | { - encoding: BufferEncoding; - flag?: string | undefined; - } - | BufferEncoding + encoding: BufferEncoding; + flag?: string | undefined; + } + | BufferEncoding, ): string; /** * Synchronously reads the entire contents of a file. @@ -2531,17 +2869,21 @@ declare module 'fs' { path: PathOrFileDescriptor, options?: | (ObjectEncodingOptions & { - flag?: string | undefined; - }) + flag?: string | undefined; + }) | BufferEncoding - | null + | null, ): string | Buffer; export type WriteFileOptions = - | (ObjectEncodingOptions & - Abortable & { - mode?: Mode | undefined; - flag?: string | undefined; - }) + | ( + & ObjectEncodingOptions + & Abortable + & { + mode?: Mode | undefined; + flag?: string | undefined; + flush?: boolean | undefined; + } + ) | BufferEncoding | null; /** @@ -2555,11 +2897,9 @@ declare module 'fs' { * * The `mode` option only affects the newly created file. See {@link open} for more details. * - * If `data` is a plain object, it must have an own (not inherited) `toString`function property. - * * ```js - * import { writeFile } from 'fs'; - * import { Buffer } from 'buffer'; + * import { writeFile } from 'node:fs'; + * import { Buffer } from 'node:buffer'; * * const data = new Uint8Array(Buffer.from('Hello Node.js')); * writeFile('message.txt', data, (err) => { @@ -2571,7 +2911,7 @@ declare module 'fs' { * If `options` is a string, then it specifies the encoding: * * ```js - * import { writeFile } from 'fs'; + * import { writeFile } from 'node:fs'; * * writeFile('message.txt', 'Hello Node.js', 'utf8', callback); * ``` @@ -2589,8 +2929,8 @@ declare module 'fs' { * to be written. * * ```js - * import { writeFile } from 'fs'; - * import { Buffer } from 'buffer'; + * import { writeFile } from 'node:fs'; + * import { Buffer } from 'node:buffer'; * * const controller = new AbortController(); * const { signal } = controller; @@ -2607,14 +2947,23 @@ declare module 'fs' { * @since v0.1.29 * @param file filename or file descriptor */ - export function writeFile(file: PathOrFileDescriptor, data: string | NodeJS.ArrayBufferView, options: WriteFileOptions, callback: NoParamCallback): void; + export function writeFile( + file: PathOrFileDescriptor, + data: string | NodeJS.ArrayBufferView, + options: WriteFileOptions, + callback: NoParamCallback, + ): void; /** * Asynchronously writes data to a file, replacing the file if it already exists. * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * If a file descriptor is provided, the underlying file will _not_ be closed automatically. * @param data The data to write. If something other than a Buffer or Uint8Array is provided, the value is coerced to a string. */ - export function writeFile(path: PathOrFileDescriptor, data: string | NodeJS.ArrayBufferView, callback: NoParamCallback): void; + export function writeFile( + path: PathOrFileDescriptor, + data: string | NodeJS.ArrayBufferView, + callback: NoParamCallback, + ): void; export namespace writeFile { /** * Asynchronously writes data to a file, replacing the file if it already exists. @@ -2628,13 +2977,15 @@ declare module 'fs' { * If `mode` is a string, it is parsed as an octal integer. * If `flag` is not supplied, the default of `'w'` is used. */ - function __promisify__(path: PathOrFileDescriptor, data: string | NodeJS.ArrayBufferView, options?: WriteFileOptions): Promise; + function __promisify__( + path: PathOrFileDescriptor, + data: string | NodeJS.ArrayBufferView, + options?: WriteFileOptions, + ): Promise; } /** * Returns `undefined`. * - * If `data` is a plain object, it must have an own (not inherited) `toString`function property. - * * The `mode` option only affects the newly created file. See {@link open} for more details. * * For detailed information, see the documentation of the asynchronous version of @@ -2642,7 +2993,11 @@ declare module 'fs' { * @since v0.1.29 * @param file filename or file descriptor */ - export function writeFileSync(file: PathOrFileDescriptor, data: string | NodeJS.ArrayBufferView, options?: WriteFileOptions): void; + export function writeFileSync( + file: PathOrFileDescriptor, + data: string | NodeJS.ArrayBufferView, + options?: WriteFileOptions, + ): void; /** * Asynchronously append data to a file, creating the file if it does not yet * exist. `data` can be a string or a `Buffer`. @@ -2650,7 +3005,7 @@ declare module 'fs' { * The `mode` option only affects the newly created file. See {@link open} for more details. * * ```js - * import { appendFile } from 'fs'; + * import { appendFile } from 'node:fs'; * * appendFile('message.txt', 'data to append', (err) => { * if (err) throw err; @@ -2661,7 +3016,7 @@ declare module 'fs' { * If `options` is a string, then it specifies the encoding: * * ```js - * import { appendFile } from 'fs'; + * import { appendFile } from 'node:fs'; * * appendFile('message.txt', 'data to append', 'utf8', callback); * ``` @@ -2671,7 +3026,7 @@ declare module 'fs' { * not be closed automatically. * * ```js - * import { open, close, appendFile } from 'fs'; + * import { open, close, appendFile } from 'node:fs'; * * function closeFd(fd) { * close(fd, (err) => { @@ -2696,7 +3051,12 @@ declare module 'fs' { * @since v0.6.7 * @param path filename or file descriptor */ - export function appendFile(path: PathOrFileDescriptor, data: string | Uint8Array, options: WriteFileOptions, callback: NoParamCallback): void; + export function appendFile( + path: PathOrFileDescriptor, + data: string | Uint8Array, + options: WriteFileOptions, + callback: NoParamCallback, + ): void; /** * Asynchronously append data to a file, creating the file if it does not exist. * @param file A path to a file. If a URL is provided, it must use the `file:` protocol. @@ -2717,7 +3077,11 @@ declare module 'fs' { * If `mode` is a string, it is parsed as an octal integer. * If `flag` is not supplied, the default of `'a'` is used. */ - function __promisify__(file: PathOrFileDescriptor, data: string | Uint8Array, options?: WriteFileOptions): Promise; + function __promisify__( + file: PathOrFileDescriptor, + data: string | Uint8Array, + options?: WriteFileOptions, + ): Promise; } /** * Synchronously append data to a file, creating the file if it does not yet @@ -2726,7 +3090,7 @@ declare module 'fs' { * The `mode` option only affects the newly created file. See {@link open} for more details. * * ```js - * import { appendFileSync } from 'fs'; + * import { appendFileSync } from 'node:fs'; * * try { * appendFileSync('message.txt', 'data to append'); @@ -2739,7 +3103,7 @@ declare module 'fs' { * If `options` is a string, then it specifies the encoding: * * ```js - * import { appendFileSync } from 'fs'; + * import { appendFileSync } from 'node:fs'; * * appendFileSync('message.txt', 'data to append', 'utf8'); * ``` @@ -2749,7 +3113,7 @@ declare module 'fs' { * not be closed automatically. * * ```js - * import { openSync, closeSync, appendFileSync } from 'fs'; + * import { openSync, closeSync, appendFileSync } from 'node:fs'; * * let fd; * @@ -2766,7 +3130,11 @@ declare module 'fs' { * @since v0.6.7 * @param path filename or file descriptor */ - export function appendFileSync(path: PathOrFileDescriptor, data: string | Uint8Array, options?: WriteFileOptions): void; + export function appendFileSync( + path: PathOrFileDescriptor, + data: string | Uint8Array, + options?: WriteFileOptions, + ): void; /** * Watch for changes on `filename`. The callback `listener` will be called each * time the file is accessed. @@ -2818,29 +3186,75 @@ declare module 'fs' { persistent?: boolean | undefined; interval?: number | undefined; } + /** + * Watch for changes on `filename`. The callback `listener` will be called each + * time the file is accessed. + * + * The `options` argument may be omitted. If provided, it should be an object. The`options` object may contain a boolean named `persistent` that indicates + * whether the process should continue to run as long as files are being watched. + * The `options` object may specify an `interval` property indicating how often the + * target should be polled in milliseconds. + * + * The `listener` gets two arguments the current stat object and the previous + * stat object: + * + * ```js + * import { watchFile } from 'node:fs'; + * + * watchFile('message.text', (curr, prev) => { + * console.log(`the current mtime is: ${curr.mtime}`); + * console.log(`the previous mtime was: ${prev.mtime}`); + * }); + * ``` + * + * These stat objects are instances of `fs.Stat`. If the `bigint` option is `true`, + * the numeric values in these objects are specified as `BigInt`s. + * + * To be notified when the file was modified, not just accessed, it is necessary + * to compare `curr.mtimeMs` and `prev.mtimeMs`. + * + * When an `fs.watchFile` operation results in an `ENOENT` error, it + * will invoke the listener once, with all the fields zeroed (or, for dates, the + * Unix Epoch). If the file is created later on, the listener will be called + * again, with the latest stat objects. This is a change in functionality since + * v0.10. + * + * Using {@link watch} is more efficient than `fs.watchFile` and`fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and`fs.unwatchFile` when possible. + * + * When a file being watched by `fs.watchFile()` disappears and reappears, + * then the contents of `previous` in the second callback event (the file's + * reappearance) will be the same as the contents of `previous` in the first + * callback event (its disappearance). + * + * This happens when: + * + * * the file is deleted, followed by a restore + * * the file is renamed and then renamed a second time back to its original name + * @since v0.1.31 + */ export function watchFile( filename: PathLike, options: | (WatchFileOptions & { - bigint?: false | undefined; - }) + bigint?: false | undefined; + }) | undefined, - listener: (curr: Stats, prev: Stats) => void + listener: StatsListener, ): StatWatcher; export function watchFile( filename: PathLike, options: | (WatchFileOptions & { - bigint: true; - }) + bigint: true; + }) | undefined, - listener: (curr: BigIntStats, prev: BigIntStats) => void + listener: BigIntStatsListener, ): StatWatcher; /** * Watch for changes on `filename`. The callback `listener` will be called each time the file is accessed. * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol. */ - export function watchFile(filename: PathLike, listener: (curr: Stats, prev: Stats) => void): StatWatcher; + export function watchFile(filename: PathLike, listener: StatsListener): StatWatcher; /** * Stop watching for changes on `filename`. If `listener` is specified, only that * particular listener is removed. Otherwise, _all_ listeners are removed, @@ -2853,14 +3267,17 @@ declare module 'fs' { * @since v0.1.31 * @param listener Optional, a listener previously attached using `fs.watchFile()` */ - export function unwatchFile(filename: PathLike, listener?: (curr: Stats, prev: Stats) => void): void; + export function unwatchFile(filename: PathLike, listener?: StatsListener): void; + export function unwatchFile(filename: PathLike, listener?: BigIntStatsListener): void; export interface WatchOptions extends Abortable { - encoding?: BufferEncoding | 'buffer' | undefined; + encoding?: BufferEncoding | "buffer" | undefined; persistent?: boolean | undefined; recursive?: boolean | undefined; } - export type WatchEventType = 'rename' | 'change'; - export type WatchListener = (event: WatchEventType, filename: T) => void; + export type WatchEventType = "rename" | "change"; + export type WatchListener = (event: WatchEventType, filename: T | null) => void; + export type StatsListener = (curr: Stats, prev: Stats) => void; + export type BigIntStatsListener = (curr: BigIntStats, prev: BigIntStats) => void; /** * Watch for changes on `filename`, where `filename` is either a file or a * directory. @@ -2885,10 +3302,10 @@ declare module 'fs' { filename: PathLike, options: | (WatchOptions & { - encoding: 'buffer'; - }) - | 'buffer', - listener?: WatchListener + encoding: "buffer"; + }) + | "buffer", + listener?: WatchListener, ): FSWatcher; /** * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`. @@ -2898,7 +3315,11 @@ declare module 'fs' { * If `persistent` is not supplied, the default of `true` is used. * If `recursive` is not supplied, the default of `false` is used. */ - export function watch(filename: PathLike, options?: WatchOptions | BufferEncoding | null, listener?: WatchListener): FSWatcher; + export function watch( + filename: PathLike, + options?: WatchOptions | BufferEncoding | null, + listener?: WatchListener, + ): FSWatcher; /** * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`. * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol. @@ -2907,7 +3328,11 @@ declare module 'fs' { * If `persistent` is not supplied, the default of `true` is used. * If `recursive` is not supplied, the default of `false` is used. */ - export function watch(filename: PathLike, options: WatchOptions | string, listener?: WatchListener): FSWatcher; + export function watch( + filename: PathLike, + options: WatchOptions | string, + listener?: WatchListener, + ): FSWatcher; /** * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`. * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol. @@ -2918,7 +3343,7 @@ declare module 'fs' { * Then call the `callback` argument with either true or false: * * ```js - * import { exists } from 'fs'; + * import { exists } from 'node:fs'; * * exists('/etc/passwd', (e) => { * console.log(e ? 'it exists' : 'no passwd!'); @@ -2930,7 +3355,7 @@ declare module 'fs' { * has only one boolean parameter. This is one reason `fs.access()` is recommended * instead of `fs.exists()`. * - * Using `fs.exists()` to check for the existence of a file before calling`fs.open()`, `fs.readFile()` or `fs.writeFile()` is not recommended. Doing + * Using `fs.exists()` to check for the existence of a file before calling`fs.open()`, `fs.readFile()`, or `fs.writeFile()` is not recommended. Doing * so introduces a race condition, since other processes may change the file's * state between the two calls. Instead, user code should open/read/write the * file directly and handle the error raised if the file does not exist. @@ -2938,7 +3363,7 @@ declare module 'fs' { * **write (NOT RECOMMENDED)** * * ```js - * import { exists, open, close } from 'fs'; + * import { exists, open, close } from 'node:fs'; * * exists('myfile', (e) => { * if (e) { @@ -2962,7 +3387,7 @@ declare module 'fs' { * **write (RECOMMENDED)** * * ```js - * import { open, close } from 'fs'; + * import { open, close } from 'node:fs'; * open('myfile', 'wx', (err, fd) => { * if (err) { * if (err.code === 'EEXIST') { @@ -2986,7 +3411,7 @@ declare module 'fs' { * **read (NOT RECOMMENDED)** * * ```js - * import { open, close, exists } from 'fs'; + * import { open, close, exists } from 'node:fs'; * * exists('myfile', (e) => { * if (e) { @@ -3010,7 +3435,7 @@ declare module 'fs' { * **read (RECOMMENDED)** * * ```js - * import { open, close } from 'fs'; + * import { open, close } from 'node:fs'; * * open('myfile', 'r', (err, fd) => { * if (err) { @@ -3036,7 +3461,7 @@ declare module 'fs' { * file; the "recommended" examples are better because they use the file directly * and handle the error, if any. * - * In general, check for the existence of a file only if the file won’t be + * In general, check for the existence of a file only if the file won't be * used directly, for example when its existence is a signal from another * process. * @since v0.0.2 @@ -3061,7 +3486,7 @@ declare module 'fs' { * Node.js callbacks. `fs.existsSync()` does not use a callback. * * ```js - * import { existsSync } from 'fs'; + * import { existsSync } from 'node:fs'; * * if (existsSync('/etc/passwd')) * console.log('The path exists.'); @@ -3186,16 +3611,16 @@ declare module 'fs' { /** * Tests a user's permissions for the file or directory specified by `path`. * The `mode` argument is an optional integer that specifies the accessibility - * checks to be performed. Check `File access constants` for possible values - * of `mode`. It is possible to create a mask consisting of the bitwise OR of - * two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). + * checks to be performed. `mode` should be either the value `fs.constants.F_OK`or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`,`fs.constants.W_OK`, and `fs.constants.X_OK` + * (e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for + * possible values of `mode`. * * The final argument, `callback`, is a callback function that is invoked with * a possible error argument. If any of the accessibility checks fail, the error * argument will be an `Error` object. The following examples check if`package.json` exists, and if it is readable or writable. * * ```js - * import { access, constants } from 'fs'; + * import { access, constants } from 'node:fs'; * * const file = 'package.json'; * @@ -3214,18 +3639,13 @@ declare module 'fs' { * console.log(`${file} ${err ? 'is not writable' : 'is writable'}`); * }); * - * // Check if the file exists in the current directory, and if it is writable. - * access(file, constants.F_OK | constants.W_OK, (err) => { - * if (err) { - * console.error( - * `${file} ${err.code === 'ENOENT' ? 'does not exist' : 'is read-only'}`); - * } else { - * console.log(`${file} exists, and it is writable`); - * } + * // Check if the file is readable and writable. + * access(file, constants.R_OK | constants.W_OK, (err) => { + * console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`); * }); * ``` * - * Do not use `fs.access()` to check for the accessibility of a file before calling`fs.open()`, `fs.readFile()` or `fs.writeFile()`. Doing + * Do not use `fs.access()` to check for the accessibility of a file before calling`fs.open()`, `fs.readFile()`, or `fs.writeFile()`. Doing * so introduces a race condition, since other processes may change the file's * state between the two calls. Instead, user code should open/read/write the * file directly and handle the error raised if the file is not accessible. @@ -3233,7 +3653,7 @@ declare module 'fs' { * **write (NOT RECOMMENDED)** * * ```js - * import { access, open, close } from 'fs'; + * import { access, open, close } from 'node:fs'; * * access('myfile', (err) => { * if (!err) { @@ -3258,7 +3678,7 @@ declare module 'fs' { * **write (RECOMMENDED)** * * ```js - * import { open, close } from 'fs'; + * import { open, close } from 'node:fs'; * * open('myfile', 'wx', (err, fd) => { * if (err) { @@ -3283,7 +3703,7 @@ declare module 'fs' { * **read (NOT RECOMMENDED)** * * ```js - * import { access, open, close } from 'fs'; + * import { access, open, close } from 'node:fs'; * access('myfile', (err) => { * if (err) { * if (err.code === 'ENOENT') { @@ -3311,7 +3731,7 @@ declare module 'fs' { * **read (RECOMMENDED)** * * ```js - * import { open, close } from 'fs'; + * import { open, close } from 'node:fs'; * * open('myfile', 'r', (err, fd) => { * if (err) { @@ -3365,16 +3785,15 @@ declare module 'fs' { /** * Synchronously tests a user's permissions for the file or directory specified * by `path`. The `mode` argument is an optional integer that specifies the - * accessibility checks to be performed. Check `File access constants` for - * possible values of `mode`. It is possible to create a mask consisting of - * the bitwise OR of two or more values - * (e.g. `fs.constants.W_OK | fs.constants.R_OK`). + * accessibility checks to be performed. `mode` should be either the value`fs.constants.F_OK` or a mask consisting of the bitwise OR of any of`fs.constants.R_OK`, `fs.constants.W_OK`, and + * `fs.constants.X_OK` (e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for + * possible values of `mode`. * * If any of the accessibility checks fail, an `Error` will be thrown. Otherwise, * the method will return `undefined`. * * ```js - * import { accessSync, constants } from 'fs'; + * import { accessSync, constants } from 'node:fs'; * * try { * accessSync('etc/passwd', constants.R_OK | constants.W_OK); @@ -3393,19 +3812,33 @@ declare module 'fs' { fd?: number | promises.FileHandle | undefined; mode?: number | undefined; autoClose?: boolean | undefined; - /** - * @default false - */ emitClose?: boolean | undefined; start?: number | undefined; + signal?: AbortSignal | null | undefined; highWaterMark?: number | undefined; } + interface FSImplementation { + open?: (...args: any[]) => any; + close?: (...args: any[]) => any; + } + interface CreateReadStreamFSImplementation extends FSImplementation { + read: (...args: any[]) => any; + } + interface CreateWriteStreamFSImplementation extends FSImplementation { + write: (...args: any[]) => any; + writev?: (...args: any[]) => any; + } interface ReadStreamOptions extends StreamOptions { + fs?: CreateReadStreamFSImplementation | null | undefined; end?: number | undefined; } + interface WriteStreamOptions extends StreamOptions { + fs?: CreateWriteStreamFSImplementation | null | undefined; + flush?: boolean | undefined; + } /** - * Unlike the 16 kb default `highWaterMark` for a `stream.Readable`, the stream - * returned by this method has a default `highWaterMark` of 64 kb. + * Unlike the 16 KiB default `highWaterMark` for a `stream.Readable`, the stream + * returned by this method has a default `highWaterMark` of 64 KiB. * * `options` can include `start` and `end` values to read a range of bytes from * the file instead of the entire file. Both `start` and `end` are inclusive and @@ -3431,7 +3864,7 @@ declare module 'fs' { * also required. * * ```js - * import { createReadStream } from 'fs'; + * import { createReadStream } from 'node:fs'; * * // Create a stream from some character device. * const stream = createReadStream('/dev/input/event0'); @@ -3459,7 +3892,7 @@ declare module 'fs' { * An example to read the last 10 bytes of a file which is 100 bytes long: * * ```js - * import { createReadStream } from 'fs'; + * import { createReadStream } from 'node:fs'; * * createReadStream('sample.txt', { start: 90, end: 99 }); * ``` @@ -3471,9 +3904,9 @@ declare module 'fs' { /** * `options` may also include a `start` option to allow writing data at some * position past the beginning of the file, allowed values are in the - * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than replacing - * it may require the `flags` option to be set to `r+` rather than the default `w`. - * The `encoding` can be any one of those accepted by `Buffer`. + * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than + * replacing it may require the `flags` option to be set to `r+` rather than the + * default `w`. The `encoding` can be any one of those accepted by `Buffer`. * * If `autoClose` is set to true (default behavior) on `'error'` or `'finish'`the file descriptor will be closed automatically. If `autoClose` is false, * then the file descriptor won't be closed, even if there's an error. @@ -3483,7 +3916,7 @@ declare module 'fs' { * By default, the stream will emit a `'close'` event after it has been * destroyed. Set the `emitClose` option to `false` to change this behavior. * - * By providing the `fs` option it is possible to override the corresponding `fs`implementations for `open`, `write`, `writev` and `close`. Overriding `write()`without `writev()` can reduce + * By providing the `fs` option it is possible to override the corresponding `fs`implementations for `open`, `write`, `writev`, and `close`. Overriding `write()`without `writev()` can reduce * performance as some optimizations (`_writev()`) * will be disabled. When providing the `fs` option, overrides for at least one of`write` and `writev` are required. If no `fd` option is supplied, an override * for `open` is also required. If `autoClose` is `true`, an override for `close`is also required. @@ -3495,7 +3928,7 @@ declare module 'fs' { * If `options` is a string, then it specifies the encoding. * @since v0.1.31 */ - export function createWriteStream(path: PathLike, options?: BufferEncoding | StreamOptions): WriteStream; + export function createWriteStream(path: PathLike, options?: BufferEncoding | WriteStreamOptions): WriteStream; /** * Forces all currently queued I/O operations associated with the file to the * operating system's synchronized I/O completion state. Refer to the POSIX [`fdatasync(2)`](http://man7.org/linux/man-pages/man2/fdatasync.2.html) documentation for details. No arguments other @@ -3538,7 +3971,7 @@ declare module 'fs' { * copy-on-write, then the operation will fail. * * ```js - * import { copyFile, constants } from 'fs'; + * import { copyFile, constants } from 'node:fs'; * * function callback(err) { * if (err) throw err; @@ -3581,7 +4014,7 @@ declare module 'fs' { * copy-on-write, then the operation will fail. * * ```js - * import { copyFileSync, constants } from 'fs'; + * import { copyFileSync, constants } from 'node:fs'; * * // destination.txt will be created or overwritten by default. * copyFileSync('source.txt', 'destination.txt'); @@ -3614,28 +4047,38 @@ declare module 'fs' { * The kernel ignores the position argument and always appends the data to * the end of the file. * @since v12.9.0 + * @param [position='null'] */ - export function writev(fd: number, buffers: ReadonlyArray, cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void): void; export function writev( fd: number, - buffers: ReadonlyArray, + buffers: readonly NodeJS.ArrayBufferView[], + cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void, + ): void; + export function writev( + fd: number, + buffers: readonly NodeJS.ArrayBufferView[], position: number, - cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void + cb: (err: NodeJS.ErrnoException | null, bytesWritten: number, buffers: NodeJS.ArrayBufferView[]) => void, ): void; export interface WriteVResult { bytesWritten: number; buffers: NodeJS.ArrayBufferView[]; } export namespace writev { - function __promisify__(fd: number, buffers: ReadonlyArray, position?: number): Promise; + function __promisify__( + fd: number, + buffers: readonly NodeJS.ArrayBufferView[], + position?: number, + ): Promise; } /** * For detailed information, see the documentation of the asynchronous version of * this API: {@link writev}. * @since v12.9.0 + * @param [position='null'] * @return The number of bytes written. */ - export function writevSync(fd: number, buffers: ReadonlyArray, position?: number): number; + export function writevSync(fd: number, buffers: readonly NodeJS.ArrayBufferView[], position?: number): number; /** * Read from a file specified by `fd` and write to an array of `ArrayBufferView`s * using `readv()`. @@ -3649,29 +4092,72 @@ declare module 'fs' { * If this method is invoked as its `util.promisify()` ed version, it returns * a promise for an `Object` with `bytesRead` and `buffers` properties. * @since v13.13.0, v12.17.0 + * @param [position='null'] */ - export function readv(fd: number, buffers: ReadonlyArray, cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void): void; export function readv( fd: number, - buffers: ReadonlyArray, + buffers: readonly NodeJS.ArrayBufferView[], + cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void, + ): void; + export function readv( + fd: number, + buffers: readonly NodeJS.ArrayBufferView[], position: number, - cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void + cb: (err: NodeJS.ErrnoException | null, bytesRead: number, buffers: NodeJS.ArrayBufferView[]) => void, ): void; export interface ReadVResult { bytesRead: number; buffers: NodeJS.ArrayBufferView[]; } export namespace readv { - function __promisify__(fd: number, buffers: ReadonlyArray, position?: number): Promise; + function __promisify__( + fd: number, + buffers: readonly NodeJS.ArrayBufferView[], + position?: number, + ): Promise; } /** * For detailed information, see the documentation of the asynchronous version of * this API: {@link readv}. * @since v13.13.0, v12.17.0 + * @param [position='null'] * @return The number of bytes read. */ - export function readvSync(fd: number, buffers: ReadonlyArray, position?: number): number; + export function readvSync(fd: number, buffers: readonly NodeJS.ArrayBufferView[], position?: number): number; + + export interface OpenAsBlobOptions { + /** + * An optional mime type for the blob. + * + * @default 'undefined' + */ + type?: string | undefined; + } + + /** + * Returns a `Blob` whose data is backed by the given file. + * + * The file must not be modified after the `Blob` is created. Any modifications + * will cause reading the `Blob` data to fail with a `DOMException` error. + * Synchronous stat operations on the file when the `Blob` is created, and before + * each read in order to detect whether the file data has been modified on disk. + * + * ```js + * import { openAsBlob } from 'node:fs'; + * + * const blob = await openAsBlob('the.file.txt'); + * const ab = await blob.arrayBuffer(); + * blob.stream(); + * ``` + * @since v19.8.0 + * @experimental + */ + export function openAsBlob(path: PathLike, options?: OpenAsBlobOptions): Promise; + export interface OpenDirOptions { + /** + * @default 'utf8' + */ encoding?: BufferEncoding | undefined; /** * Number of directory entries that are buffered @@ -3680,6 +4166,10 @@ declare module 'fs' { * @default 32 */ bufferSize?: number | undefined; + /** + * @default false + */ + recursive?: boolean; } /** * Synchronously open a directory. See [`opendir(3)`](http://man7.org/linux/man-pages/man3/opendir.3.html). @@ -3704,7 +4194,11 @@ declare module 'fs' { * @since v12.12.0 */ export function opendir(path: PathLike, cb: (err: NodeJS.ErrnoException | null, dir: Dir) => void): void; - export function opendir(path: PathLike, options: OpenDirOptions, cb: (err: NodeJS.ErrnoException | null, dir: Dir) => void): void; + export function opendir( + path: PathLike, + options: OpenDirOptions, + cb: (err: NodeJS.ErrnoException | null, dir: Dir) => void, + ): void; export namespace opendir { function __promisify__(path: PathLike, options?: OpenDirOptions): Promise

; } @@ -3742,6 +4236,10 @@ declare module 'fs' { * @default true */ force?: boolean; + /** + * Modifiers for copy operation. See `mode` flag of {@link copyFileSync()} + */ + mode?: number; /** * When `true` timestamps from `src` will * be preserved. @@ -3753,6 +4251,11 @@ declare module 'fs' { * @default false */ recursive?: boolean; + /** + * When true, path resolution for symlinks will be skipped + * @default false + */ + verbatimSymlinks?: boolean; } export interface CopyOptions extends CopyOptionsBase { /** @@ -3779,8 +4282,17 @@ declare module 'fs' { * @param src source path to copy. * @param dest destination path to copy to. */ - export function cp(source: string | URL, destination: string | URL, callback: (err: NodeJS.ErrnoException | null) => void): void; - export function cp(source: string | URL, destination: string | URL, opts: CopyOptions, callback: (err: NodeJS.ErrnoException | null) => void): void; + export function cp( + source: string | URL, + destination: string | URL, + callback: (err: NodeJS.ErrnoException | null) => void, + ): void; + export function cp( + source: string | URL, + destination: string | URL, + opts: CopyOptions, + callback: (err: NodeJS.ErrnoException | null) => void, + ): void; /** * Synchronously copies the entire directory structure from `src` to `dest`, * including subdirectories and files. @@ -3794,6 +4306,6 @@ declare module 'fs' { */ export function cpSync(source: string | URL, destination: string | URL, opts?: CopySyncOptions): void; } -declare module 'node:fs' { - export * from 'fs'; +declare module "node:fs" { + export * from "fs"; } diff --git a/node_modules/@types/node/ts4.8/fs/promises.d.ts b/node_modules/@types/node/ts4.8/fs/promises.d.ts old mode 100755 new mode 100644 index c1667d8..88a9fc3 --- a/node_modules/@types/node/ts4.8/fs/promises.d.ts +++ b/node_modules/@types/node/ts4.8/fs/promises.d.ts @@ -8,11 +8,13 @@ * concurrent modifications on the same file or data corruption may occur. * @since v10.0.0 */ -declare module 'fs/promises' { - import { Abortable } from 'node:events'; - import { Stream } from 'node:stream'; +declare module "fs/promises" { + import { Abortable } from "node:events"; + import { Stream } from "node:stream"; + import { ReadableStream } from "node:stream/web"; import { BigIntStats, + BigIntStatsFs, BufferEncodingOption, constants as fsConstants, CopyOptions, @@ -28,26 +30,30 @@ declare module 'fs/promises' { ReadVResult, RmDirOptions, RmOptions, + StatFsOptions, StatOptions, Stats, + StatsFs, + TimeLike, WatchEventType, WatchOptions, WriteStream, WriteVResult, - } from 'node:fs'; + } from "node:fs"; + import { Interface as ReadlineInterface } from "node:readline"; interface FileChangeInfo { eventType: WatchEventType; - filename: T; + filename: T | null; } interface FlagAndOpenMode { mode?: Mode | undefined; flag?: OpenMode | undefined; } - interface FileReadResult { + interface FileReadResult { bytesRead: number; buffer: T; } - interface FileReadOptions { + interface FileReadOptions { /** * @default `Buffer.alloc(0xffff)` */ @@ -75,6 +81,15 @@ declare module 'fs/promises' { autoClose?: boolean | undefined; emitClose?: boolean | undefined; start?: number | undefined; + highWaterMark?: number | undefined; + flush?: boolean | undefined; + } + interface ReadableWebStreamOptions { + /** + * Whether to open a normal or a `'bytes'` stream. + * @since v20.0.0 + */ + type?: "bytes" | undefined; } // TODO: Add `EventEmitter` close interface FileHandle { @@ -91,7 +106,13 @@ declare module 'fs/promises' { * @since v10.0.0 * @return Fulfills with `undefined` upon success. */ - appendFile(data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null): Promise; + appendFile( + data: string | Uint8Array, + options?: + | (ObjectEncodingOptions & FlagAndOpenMode & { flush?: boolean | undefined }) + | BufferEncoding + | null, + ): Promise; /** * Changes the ownership of the file. A wrapper for [`chown(2)`](http://man7.org/linux/man-pages/man2/chown.2.html). * @since v10.0.0 @@ -108,8 +129,8 @@ declare module 'fs/promises' { */ chmod(mode: Mode): Promise; /** - * Unlike the 16 kb default `highWaterMark` for a `stream.Readable`, the stream - * returned by this method has a default `highWaterMark` of 64 kb. + * Unlike the 16 KiB default `highWaterMark` for a `stream.Readable`, the stream + * returned by this method has a default `highWaterMark` of 64 KiB. * * `options` can include `start` and `end` values to read a range of bytes from * the file instead of the entire file. Both `start` and `end` are inclusive and @@ -127,7 +148,7 @@ declare module 'fs/promises' { * destroyed. Set the `emitClose` option to `false` to change this behavior. * * ```js - * import { open } from 'fs/promises'; + * import { open } from 'node:fs/promises'; * * const fd = await open('/dev/input/event0'); * // Create a stream from some character device. @@ -153,7 +174,7 @@ declare module 'fs/promises' { * An example to read the last 10 bytes of a file which is 100 bytes long: * * ```js - * import { open } from 'fs/promises'; + * import { open } from 'node:fs/promises'; * * const fd = await open('sample.txt'); * fd.createReadStream({ start: 90, end: 99 }); @@ -164,9 +185,9 @@ declare module 'fs/promises' { /** * `options` may also include a `start` option to allow writing data at some * position past the beginning of the file, allowed values are in the - * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than replacing - * it may require the `flags` `open` option to be set to `r+` rather than the - * default `r`. The `encoding` can be any one of those accepted by `Buffer`. + * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than + * replacing it may require the `flags` `open` option to be set to `r+` rather than + * the default `r`. The `encoding` can be any one of those accepted by `Buffer`. * * If `autoClose` is set to true (default behavior) on `'error'` or `'finish'`the file descriptor will be closed automatically. If `autoClose` is false, * then the file descriptor won't be closed, even if there's an error. @@ -192,7 +213,7 @@ declare module 'fs/promises' { * device. The specific implementation is operating system and device specific. * Refer to the POSIX [`fsync(2)`](http://man7.org/linux/man-pages/man2/fsync.2.html) documentation for more detail. * @since v10.0.0 - * @return Fufills with `undefined` upon success. + * @return Fulfills with `undefined` upon success. */ sync(): Promise; /** @@ -208,8 +229,38 @@ declare module 'fs/promises' { * integer, the current file position will remain unchanged. * @return Fulfills upon success with an object with two properties: */ - read(buffer: T, offset?: number | null, length?: number | null, position?: number | null): Promise>; - read(options?: FileReadOptions): Promise>; + read( + buffer: T, + offset?: number | null, + length?: number | null, + position?: number | null, + ): Promise>; + read(options?: FileReadOptions): Promise>; + /** + * Returns a `ReadableStream` that may be used to read the files data. + * + * An error will be thrown if this method is called more than once or is called + * after the `FileHandle` is closed or closing. + * + * ```js + * import { + * open, + * } from 'node:fs/promises'; + * + * const file = await open('./some/file/to/read'); + * + * for await (const chunk of file.readableWebStream()) + * console.log(chunk); + * + * await file.close(); + * ``` + * + * While the `ReadableStream` will read the file to completion, it will not + * close the `FileHandle` automatically. User code must still call the`fileHandle.close()` method. + * @since v17.0.0 + * @experimental + */ + readableWebStream(options?: ReadableWebStreamOptions): ReadableStream; /** * Asynchronously reads the entire contents of a file. * @@ -228,7 +279,7 @@ declare module 'fs/promises' { options?: { encoding?: null | undefined; flag?: OpenMode | undefined; - } | null + } | null, ): Promise; /** * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically. @@ -239,10 +290,10 @@ declare module 'fs/promises' { readFile( options: | { - encoding: BufferEncoding; - flag?: OpenMode | undefined; - } - | BufferEncoding + encoding: BufferEncoding; + flag?: OpenMode | undefined; + } + | BufferEncoding, ): Promise; /** * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically. @@ -253,11 +304,27 @@ declare module 'fs/promises' { readFile( options?: | (ObjectEncodingOptions & { - flag?: OpenMode | undefined; - }) + flag?: OpenMode | undefined; + }) | BufferEncoding - | null + | null, ): Promise; + /** + * Convenience method to create a `readline` interface and stream over the file. + * See `filehandle.createReadStream()` for the options. + * + * ```js + * import { open } from 'node:fs/promises'; + * + * const file = await open('./some/file/to/read'); + * + * for await (const line of file.readLines()) { + * console.log(line); + * } + * ``` + * @since v18.11.0 + */ + readLines(options?: CreateReadStreamOptions): ReadlineInterface; /** * @since v10.0.0 * @return Fulfills with an {fs.Stats} for the file. @@ -265,12 +332,12 @@ declare module 'fs/promises' { stat( opts?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; stat( opts: StatOptions & { bigint: true; - } + }, ): Promise; stat(opts?: StatOptions): Promise; /** @@ -282,7 +349,7 @@ declare module 'fs/promises' { * The following example retains only the first four bytes of the file: * * ```js - * import { open } from 'fs/promises'; + * import { open } from 'node:fs/promises'; * * let filehandle = null; * try { @@ -303,55 +370,58 @@ declare module 'fs/promises' { */ truncate(len?: number): Promise; /** - * Change the file system timestamps of the object referenced by the `FileHandle` then resolves the promise with no arguments upon success. + * Change the file system timestamps of the object referenced by the `FileHandle` then fulfills the promise with no arguments upon success. * @since v10.0.0 */ - utimes(atime: string | number | Date, mtime: string | number | Date): Promise; + utimes(atime: TimeLike, mtime: TimeLike): Promise; /** * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an - * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface) or - * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object, or an - * object with an own `toString` function - * property. The promise is resolved with no arguments upon success. + * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface), or an + * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object. + * The promise is fulfilled with no arguments upon success. * * If `options` is a string, then it specifies the `encoding`. * * The `FileHandle` has to support writing. * * It is unsafe to use `filehandle.writeFile()` multiple times on the same file - * without waiting for the promise to be resolved (or rejected). + * without waiting for the promise to be fulfilled (or rejected). * * If one or more `filehandle.write()` calls are made on a file handle and then a`filehandle.writeFile()` call is made, the data will be written from the * current position till the end of the file. It doesn't always write from the * beginning of the file. * @since v10.0.0 */ - writeFile(data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode & Abortable) | BufferEncoding | null): Promise; + writeFile( + data: string | Uint8Array, + options?: + | (ObjectEncodingOptions & FlagAndOpenMode & Abortable & { flush?: boolean | undefined }) + | BufferEncoding + | null, + ): Promise; /** * Write `buffer` to the file. * - * If `buffer` is a plain object, it must have an own (not inherited) `toString`function property. - * - * The promise is resolved with an object containing two properties: + * The promise is fulfilled with an object containing two properties: * * It is unsafe to use `filehandle.write()` multiple times on the same file - * without waiting for the promise to be resolved (or rejected). For this - * scenario, use `fs.createWriteStream()`. + * without waiting for the promise to be fulfilled (or rejected). For this + * scenario, use `filehandle.createWriteStream()`. * * On Linux, positional writes do not work when the file is opened in append mode. * The kernel ignores the position argument and always appends the data to * the end of the file. * @since v10.0.0 - * @param [offset=0] The start position from within `buffer` where the data to write begins. - * @param [length=buffer.byteLength] The number of bytes from `buffer` to write. - * @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. - * See the POSIX pwrite(2) documentation for more detail. + * @param offset The start position from within `buffer` where the data to write begins. + * @param [length=buffer.byteLength - offset] The number of bytes from `buffer` to write. + * @param [position='null'] 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. See the POSIX pwrite(2) documentation for more detail. */ write( buffer: TBuffer, offset?: number | null, length?: number | null, - position?: number | null + position?: number | null, ): Promise<{ bytesWritten: number; buffer: TBuffer; @@ -359,7 +429,7 @@ declare module 'fs/promises' { write( data: string, position?: number | null, - encoding?: BufferEncoding | null + encoding?: BufferEncoding | null, ): Promise<{ bytesWritten: number; buffer: string; @@ -367,32 +437,32 @@ declare module 'fs/promises' { /** * Write an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s to the file. * - * The promise is resolved with an object containing a two properties: + * The promise is fulfilled with an object containing a two properties: * * It is unsafe to call `writev()` multiple times on the same file without waiting - * for the promise to be resolved (or rejected). + * for the promise to be fulfilled (or rejected). * * On Linux, positional writes don't work when the file is opened in append mode. * The kernel ignores the position argument and always appends the data to * the end of the file. * @since v12.9.0 - * @param position The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current + * @param [position='null'] The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current * position. */ - writev(buffers: ReadonlyArray, position?: number): Promise; + writev(buffers: readonly NodeJS.ArrayBufferView[], position?: number): Promise; /** * Read from a file and write to an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s * @since v13.13.0, v12.17.0 - * @param position The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position. + * @param [position='null'] The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position. * @return Fulfills upon success an object containing two properties: */ - readv(buffers: ReadonlyArray, position?: number): Promise; + readv(buffers: readonly NodeJS.ArrayBufferView[], position?: number): Promise; /** * Closes the file handle after waiting for any pending operation on the handle to * complete. * * ```js - * import { open } from 'fs/promises'; + * import { open } from 'node:fs/promises'; * * let filehandle; * try { @@ -405,24 +475,27 @@ declare module 'fs/promises' { * @return Fulfills with `undefined` upon success. */ close(): Promise; + /** + * An alias for {@link FileHandle.close()}. + * @since v20.4.0 + */ + [Symbol.asyncDispose](): Promise; } - const constants: typeof fsConstants; /** * Tests a user's permissions for the file or directory specified by `path`. * The `mode` argument is an optional integer that specifies the accessibility - * checks to be performed. Check `File access constants` for possible values - * of `mode`. It is possible to create a mask consisting of the bitwise OR of - * two or more values (e.g. `fs.constants.W_OK | fs.constants.R_OK`). + * checks to be performed. `mode` should be either the value `fs.constants.F_OK`or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`,`fs.constants.W_OK`, and `fs.constants.X_OK` + * (e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for + * possible values of `mode`. * - * If the accessibility check is successful, the promise is resolved with no + * If the accessibility check is successful, the promise is fulfilled with no * value. If any of the accessibility checks fail, the promise is rejected * with an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object. The following example checks if the file`/etc/passwd` can be read and * written by the current process. * * ```js - * import { access } from 'fs/promises'; - * import { constants } from 'fs'; + * import { access, constants } from 'node:fs/promises'; * * try { * await access('/etc/passwd', constants.R_OK | constants.W_OK); @@ -451,14 +524,13 @@ declare module 'fs/promises' { * will be made to remove the destination. * * ```js - * import { constants } from 'fs'; - * import { copyFile } from 'fs/promises'; + * import { copyFile, constants } from 'node:fs/promises'; * * try { * await copyFile('source.txt', 'destination.txt'); * console.log('source.txt was copied to destination.txt'); * } catch { - * console.log('The file could not be copied'); + * console.error('The file could not be copied'); * } * * // By using COPYFILE_EXCL, the operation will fail if destination.txt exists. @@ -466,7 +538,7 @@ declare module 'fs/promises' { * await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL); * console.log('source.txt was copied to destination.txt'); * } catch { - * console.log('The file could not be copied'); + * console.error('The file could not be copied'); * } * ``` * @since v10.0.0 @@ -528,6 +600,19 @@ declare module 'fs/promises' { * and sticky bits), or an object with a `mode` property and a `recursive`property indicating whether parent directories should be created. Calling`fsPromises.mkdir()` when `path` is a directory * that exists results in a * rejection only when `recursive` is false. + * + * ```js + * import { mkdir } from 'node:fs/promises'; + * + * try { + * const projectFolder = new URL('./test/project/', import.meta.url); + * const createDir = await mkdir(projectFolder, { recursive: true }); + * + * console.log(`created ${createDir}`); + * } catch (err) { + * console.error(err.message); + * } + * ``` * @since v10.0.0 * @return Upon success, fulfills with `undefined` if `recursive` is `false`, or the first directory path created if `recursive` is `true`. */ @@ -535,7 +620,7 @@ declare module 'fs/promises' { path: PathLike, options: MakeDirectoryOptions & { recursive: true; - } + }, ): Promise; /** * Asynchronous mkdir(2) - create a directory. @@ -548,9 +633,9 @@ declare module 'fs/promises' { options?: | Mode | (MakeDirectoryOptions & { - recursive?: false | undefined; - }) - | null + recursive?: false | undefined; + }) + | null, ): Promise; /** * Asynchronous mkdir(2) - create a directory. @@ -567,10 +652,10 @@ declare module 'fs/promises' { * the filenames. If the `encoding` is set to `'buffer'`, the filenames returned * will be passed as `Buffer` objects. * - * If `options.withFileTypes` is set to `true`, the resolved array will contain `fs.Dirent` objects. + * If `options.withFileTypes` is set to `true`, the returned array will contain `fs.Dirent` objects. * * ```js - * import { readdir } from 'fs/promises'; + * import { readdir } from 'node:fs/promises'; * * try { * const files = await readdir(path); @@ -587,10 +672,11 @@ declare module 'fs/promises' { path: PathLike, options?: | (ObjectEncodingOptions & { - withFileTypes?: false | undefined; - }) + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }) | BufferEncoding - | null + | null, ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -601,10 +687,11 @@ declare module 'fs/promises' { path: PathLike, options: | { - encoding: 'buffer'; - withFileTypes?: false | undefined; - } - | 'buffer' + encoding: "buffer"; + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + } + | "buffer", ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -615,10 +702,11 @@ declare module 'fs/promises' { path: PathLike, options?: | (ObjectEncodingOptions & { - withFileTypes?: false | undefined; - }) + withFileTypes?: false | undefined; + recursive?: boolean | undefined; + }) | BufferEncoding - | null + | null, ): Promise; /** * Asynchronous readdir(3) - read a directory. @@ -629,11 +717,12 @@ declare module 'fs/promises' { path: PathLike, options: ObjectEncodingOptions & { withFileTypes: true; - } + recursive?: boolean | undefined; + }, ): Promise; /** * Reads the contents of the symbolic link referred to by `path`. See the POSIX [`readlink(2)`](http://man7.org/linux/man-pages/man2/readlink.2.html) documentation for more detail. The promise is - * resolved with the`linkString` upon success. + * fulfilled with the`linkString` upon success. * * The optional `options` argument can be a string specifying an encoding, or an * object with an `encoding` property specifying the character encoding to use for @@ -658,11 +747,14 @@ declare module 'fs/promises' { /** * Creates a symbolic link. * - * The `type` argument is only used on Windows platforms and can be one of `'dir'`,`'file'`, or `'junction'`. Windows junction points require the destination path - * to be absolute. When using `'junction'`, the `target` argument will - * automatically be normalized to absolute path. + * The `type` argument is only used on Windows platforms and can be one of `'dir'`,`'file'`, or `'junction'`. If the `type` argument is not a string, Node.js will + * autodetect `target` type and use `'file'` or `'dir'`. If the `target` does not + * exist, `'file'` will be used. Windows junction points require the destination + * path to be absolute. When using `'junction'`, the `target` argument will + * automatically be normalized to absolute path. Junction points on NTFS volumes + * can only point to directories. * @since v10.0.0 - * @param [type='file'] + * @param [type='null'] * @return Fulfills with `undefined` upon success. */ function symlink(target: PathLike, path: PathLike, type?: string | null): Promise; @@ -677,13 +769,13 @@ declare module 'fs/promises' { path: PathLike, opts?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; function lstat( path: PathLike, opts: StatOptions & { bigint: true; - } + }, ): Promise; function lstat(path: PathLike, opts?: StatOptions): Promise; /** @@ -694,15 +786,32 @@ declare module 'fs/promises' { path: PathLike, opts?: StatOptions & { bigint?: false | undefined; - } + }, ): Promise; function stat( path: PathLike, opts: StatOptions & { bigint: true; - } + }, ): Promise; function stat(path: PathLike, opts?: StatOptions): Promise; + /** + * @since v19.6.0, v18.15.0 + * @return Fulfills with the {fs.StatFs} object for the given `path`. + */ + function statfs( + path: PathLike, + opts?: StatFsOptions & { + bigint?: false | undefined; + }, + ): Promise; + function statfs( + path: PathLike, + opts: StatFsOptions & { + bigint: true; + }, + ): Promise; + function statfs(path: PathLike, opts?: StatFsOptions): Promise; /** * Creates a new link from the `existingPath` to the `newPath`. See the POSIX [`link(2)`](http://man7.org/linux/man-pages/man2/link.2.html) documentation for more detail. * @since v10.0.0 @@ -744,7 +853,7 @@ declare module 'fs/promises' { * @since v14.5.0, v12.19.0 * @return Fulfills with `undefined` upon success. */ - function lutimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date): Promise; + function lutimes(path: PathLike, atime: TimeLike, mtime: TimeLike): Promise; /** * Changes the ownership of a file. * @since v10.0.0 @@ -758,11 +867,11 @@ declare module 'fs/promises' { * * * Values can be either numbers representing Unix epoch time, `Date`s, or a * numeric string like `'123456789.0'`. - * * If the value can not be converted to a number, or is `NaN`, `Infinity` or`-Infinity`, an `Error` will be thrown. + * * If the value can not be converted to a number, or is `NaN`, `Infinity`, or`-Infinity`, an `Error` will be thrown. * @since v10.0.0 * @return Fulfills with `undefined` upon success. */ - function utimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date): Promise; + function utimes(path: PathLike, atime: TimeLike, mtime: TimeLike): Promise; /** * Determines the actual location of `path` using the same semantics as the`fs.realpath.native()` function. * @@ -791,7 +900,10 @@ declare module 'fs/promises' { * @param path A path to a file. If a URL is provided, it must use the `file:` protocol. * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used. */ - function realpath(path: PathLike, options?: ObjectEncodingOptions | BufferEncoding | null): Promise; + function realpath( + path: PathLike, + options?: ObjectEncodingOptions | BufferEncoding | null, + ): Promise; /** * Creates a unique temporary directory. A unique directory name is generated by * appending six random characters to the end of the provided `prefix`. Due to @@ -803,10 +915,12 @@ declare module 'fs/promises' { * object with an `encoding` property specifying the character encoding to use. * * ```js - * import { mkdtemp } from 'fs/promises'; + * import { mkdtemp } from 'node:fs/promises'; + * import { join } from 'node:path'; + * import { tmpdir } from 'node:os'; * * try { - * await mkdtemp(path.join(os.tmpdir(), 'foo-')); + * await mkdtemp(join(tmpdir(), 'foo-')); * } catch (err) { * console.error(err); * } @@ -815,9 +929,9 @@ declare module 'fs/promises' { * The `fsPromises.mkdtemp()` method will append the six randomly selected * characters directly to the `prefix` string. For instance, given a directory`/tmp`, if the intention is to create a temporary directory _within_`/tmp`, the`prefix` must end with a trailing * platform-specific path separator - * (`require('path').sep`). + * (`require('node:path').sep`). * @since v10.0.0 - * @return Fulfills with a string containing the filesystem path of the newly created temporary directory. + * @return Fulfills with a string containing the file system path of the newly created temporary directory. */ function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise; /** @@ -833,7 +947,9 @@ declare module 'fs/promises' { */ function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise; /** - * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a `Buffer`, or, an object with an own (not inherited)`toString` function property. + * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an + * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface), or an + * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object. * * The `encoding` option is ignored if `data` is a buffer. * @@ -848,15 +964,15 @@ declare module 'fs/promises' { * * Similarly to `fsPromises.readFile` \- `fsPromises.writeFile` is a convenience * method that performs multiple `write` calls internally to write the buffer - * passed to it. For performance sensitive code consider using `fs.createWriteStream()`. + * passed to it. For performance sensitive code consider using `fs.createWriteStream()` or `filehandle.createWriteStream()`. * * It is possible to use an `AbortSignal` to cancel an `fsPromises.writeFile()`. * Cancelation is "best effort", and some amount of data is likely still * to be written. * * ```js - * import { writeFile } from 'fs/promises'; - * import { Buffer } from 'buffer'; + * import { writeFile } from 'node:fs/promises'; + * import { Buffer } from 'node:buffer'; * * try { * const controller = new AbortController(); @@ -882,14 +998,19 @@ declare module 'fs/promises' { */ function writeFile( file: PathLike | FileHandle, - data: string | NodeJS.ArrayBufferView | Iterable | AsyncIterable | Stream, + data: + | string + | NodeJS.ArrayBufferView + | Iterable + | AsyncIterable + | Stream, options?: | (ObjectEncodingOptions & { - mode?: Mode | undefined; - flag?: OpenMode | undefined; - } & Abortable) + mode?: Mode | undefined; + flag?: OpenMode | undefined; + } & Abortable) | BufferEncoding - | null + | null, ): Promise; /** * Asynchronously append data to a file, creating the file if it does not yet @@ -905,7 +1026,11 @@ declare module 'fs/promises' { * @param path filename or {FileHandle} * @return Fulfills with `undefined` upon success. */ - function appendFile(path: PathLike | FileHandle, data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null): Promise; + function appendFile( + path: PathLike | FileHandle, + data: string | Uint8Array, + options?: (ObjectEncodingOptions & FlagAndOpenMode & { flush?: boolean | undefined }) | BufferEncoding | null, + ): Promise; /** * Asynchronously reads the entire contents of a file. * @@ -919,11 +1044,25 @@ declare module 'fs/promises' { * with an error. On FreeBSD, a representation of the directory's contents will be * returned. * + * An example of reading a `package.json` file located in the same directory of the + * running code: + * + * ```js + * import { readFile } from 'node:fs/promises'; + * try { + * const filePath = new URL('./package.json', import.meta.url); + * const contents = await readFile(filePath, { encoding: 'utf8' }); + * console.log(contents); + * } catch (err) { + * console.error(err.message); + * } + * ``` + * * It is possible to abort an ongoing `readFile` using an `AbortSignal`. If a * request is aborted the promise returned is rejected with an `AbortError`: * * ```js - * import { readFile } from 'fs/promises'; + * import { readFile } from 'node:fs/promises'; * * try { * const controller = new AbortController(); @@ -952,10 +1091,10 @@ declare module 'fs/promises' { path: PathLike | FileHandle, options?: | ({ - encoding?: null | undefined; - flag?: OpenMode | undefined; - } & Abortable) - | null + encoding?: null | undefined; + flag?: OpenMode | undefined; + } & Abortable) + | null, ): Promise; /** * Asynchronously reads the entire contents of a file. @@ -968,10 +1107,10 @@ declare module 'fs/promises' { path: PathLike | FileHandle, options: | ({ - encoding: BufferEncoding; - flag?: OpenMode | undefined; - } & Abortable) - | BufferEncoding + encoding: BufferEncoding; + flag?: OpenMode | undefined; + } & Abortable) + | BufferEncoding, ): Promise; /** * Asynchronously reads the entire contents of a file. @@ -983,12 +1122,15 @@ declare module 'fs/promises' { function readFile( path: PathLike | FileHandle, options?: - | (ObjectEncodingOptions & - Abortable & { - flag?: OpenMode | undefined; - }) + | ( + & ObjectEncodingOptions + & Abortable + & { + flag?: OpenMode | undefined; + } + ) | BufferEncoding - | null + | null, ): Promise; /** * Asynchronously open a directory for iterative scanning. See the POSIX [`opendir(3)`](http://man7.org/linux/man-pages/man3/opendir.3.html) documentation for more detail. @@ -1002,7 +1144,7 @@ declare module 'fs/promises' { * Example using async iteration: * * ```js - * import { opendir } from 'fs/promises'; + * import { opendir } from 'node:fs/promises'; * * try { * const dir = await opendir('./'); @@ -1023,7 +1165,7 @@ declare module 'fs/promises' { * Returns an async iterator that watches for changes on `filename`, where `filename`is either a file or a directory. * * ```js - * const { watch } = require('fs/promises'); + * const { watch } = require('node:fs/promises'); * * const ac = new AbortController(); * const { signal } = ac; @@ -1046,16 +1188,16 @@ declare module 'fs/promises' { * disappears in the directory. * * All the `caveats` for `fs.watch()` also apply to `fsPromises.watch()`. - * @since v15.9.0 + * @since v15.9.0, v14.18.0 * @return of objects with the properties: */ function watch( filename: PathLike, options: | (WatchOptions & { - encoding: 'buffer'; - }) - | 'buffer' + encoding: "buffer"; + }) + | "buffer", ): AsyncIterable>; /** * Watch for changes on `filename`, where `filename` is either a file or a directory, returning an `FSWatcher`. @@ -1074,7 +1216,10 @@ declare module 'fs/promises' { * If `persistent` is not supplied, the default of `true` is used. * If `recursive` is not supplied, the default of `false` is used. */ - function watch(filename: PathLike, options: WatchOptions | string): AsyncIterable> | AsyncIterable>; + function watch( + filename: PathLike, + options: WatchOptions | string, + ): AsyncIterable> | AsyncIterable>; /** * Asynchronously copies the entire directory structure from `src` to `dest`, * including subdirectories and files. @@ -1089,6 +1234,6 @@ declare module 'fs/promises' { */ function cp(source: string | URL, destination: string | URL, opts?: CopyOptions): Promise; } -declare module 'node:fs/promises' { - export * from 'fs/promises'; +declare module "node:fs/promises" { + export * from "fs/promises"; } diff --git a/node_modules/@types/node/ts4.8/globals.d.ts b/node_modules/@types/node/ts4.8/globals.d.ts old mode 100755 new mode 100644 index 3d230a5..5f25006 --- a/node_modules/@types/node/ts4.8/globals.d.ts +++ b/node_modules/@types/node/ts4.8/globals.d.ts @@ -1,284 +1,411 @@ -// Declare "static" methods in Error -interface ErrorConstructor { - /** Create .stack property on a target object */ - captureStackTrace(targetObject: object, constructorOpt?: Function): void; +export {}; // Make this a module - /** - * Optional override for formatting stack traces - * - * @see https://v8.dev/docs/stack-trace-api#customizing-stack-traces - */ - prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined; +// #region Fetch and friends +// Conditional type aliases, used at the end of this file. +// Will either be empty if lib-dom is included, or the undici version otherwise. +type _Request = typeof globalThis extends { onmessage: any } ? {} : import("undici-types").Request; +type _Response = typeof globalThis extends { onmessage: any } ? {} : import("undici-types").Response; +type _FormData = typeof globalThis extends { onmessage: any } ? {} : import("undici-types").FormData; +type _Headers = typeof globalThis extends { onmessage: any } ? {} : import("undici-types").Headers; +type _RequestInit = typeof globalThis extends { onmessage: any } ? {} + : import("undici-types").RequestInit; +type _ResponseInit = typeof globalThis extends { onmessage: any } ? {} + : import("undici-types").ResponseInit; +type _File = typeof globalThis extends { onmessage: any } ? {} : import("node:buffer").File; +// #endregion Fetch and friends - stackTraceLimit: number; -} - -/*-----------------------------------------------* - * * - * GLOBAL * - * * - ------------------------------------------------*/ - -// For backwards compability -interface NodeRequire extends NodeJS.Require { } -interface RequireResolve extends NodeJS.RequireResolve { } -interface NodeModule extends NodeJS.Module { } - -declare var process: NodeJS.Process; -declare var console: Console; - -declare var __filename: string; -declare var __dirname: string; - -declare var require: NodeRequire; -declare var module: NodeModule; - -// Same as module.exports -declare var exports: any; - -/** - * Only available if `--expose-gc` is passed to the process. - */ -declare var gc: undefined | (() => void); - -//#region borrowed -// from https://github.com/microsoft/TypeScript/blob/38da7c600c83e7b31193a62495239a0fe478cb67/lib/lib.webworker.d.ts#L633 until moved to separate lib -/** A controller object that allows you to abort one or more DOM requests as and when desired. */ -interface AbortController { - /** - * Returns the AbortSignal object associated with this object. - */ - - readonly signal: AbortSignal; - /** - * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted. - */ - abort(): void; -} - -/** A signal object that allows you to communicate with a DOM request (such as a Fetch) and abort it if required via an AbortController object. */ -interface AbortSignal { - /** - * Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise. - */ - readonly aborted: boolean; -} - -declare var AbortController: { - prototype: AbortController; - new(): AbortController; -}; - -declare var AbortSignal: { - prototype: AbortSignal; - new(): AbortSignal; - // TODO: Add abort() static -}; -//#endregion borrowed - -//#region ArrayLike.at() -interface RelativeIndexable { - /** - * Takes an integer value and returns the item at that index, - * allowing for positive and negative integers. - * Negative integers count back from the last item in the array. - */ - at(index: number): T | undefined; -} -interface String extends RelativeIndexable {} -interface Array extends RelativeIndexable {} -interface Int8Array extends RelativeIndexable {} -interface Uint8Array extends RelativeIndexable {} -interface Uint8ClampedArray extends RelativeIndexable {} -interface Int16Array extends RelativeIndexable {} -interface Uint16Array extends RelativeIndexable {} -interface Int32Array extends RelativeIndexable {} -interface Uint32Array extends RelativeIndexable {} -interface Float32Array extends RelativeIndexable {} -interface Float64Array extends RelativeIndexable {} -interface BigInt64Array extends RelativeIndexable {} -interface BigUint64Array extends RelativeIndexable {} -//#endregion ArrayLike.at() end - -/*----------------------------------------------* -* * -* GLOBAL INTERFACES * -* * -*-----------------------------------------------*/ -declare namespace NodeJS { - interface CallSite { - /** - * Value of "this" - */ - getThis(): unknown; +declare global { + // Declare "static" methods in Error + interface ErrorConstructor { + /** Create .stack property on a target object */ + captureStackTrace(targetObject: object, constructorOpt?: Function): void; /** - * Type of "this" as a string. - * This is the name of the function stored in the constructor field of - * "this", if available. Otherwise the object's [[Class]] internal - * property. - */ - getTypeName(): string | null; - - /** - * Current function - */ - getFunction(): Function | undefined; - - /** - * Name of the current function, typically its name property. - * If a name property is not available an attempt will be made to try - * to infer a name from the function's context. - */ - getFunctionName(): string | null; - - /** - * Name of the property [of "this" or one of its prototypes] that holds - * the current function - */ - getMethodName(): string | null; - - /** - * Name of the script [if this function was defined in a script] - */ - getFileName(): string | null; - - /** - * Current line number [if this function was defined in a script] - */ - getLineNumber(): number | null; - - /** - * Current column number [if this function was defined in a script] - */ - getColumnNumber(): number | null; - - /** - * A call site object representing the location where eval was called - * [if this function was created using a call to eval] - */ - getEvalOrigin(): string | undefined; - - /** - * Is this a toplevel invocation, that is, is "this" the global object? - */ - isToplevel(): boolean; - - /** - * Does this call take place in code defined by a call to eval? - */ - isEval(): boolean; - - /** - * Is this call in native V8 code? - */ - isNative(): boolean; - - /** - * Is this a constructor call? - */ - isConstructor(): boolean; - } - - interface ErrnoException extends Error { - errno?: number | undefined; - code?: string | undefined; - path?: string | undefined; - syscall?: string | undefined; - } - - interface ReadableStream extends EventEmitter { - readable: boolean; - read(size?: number): string | Buffer; - setEncoding(encoding: BufferEncoding): this; - pause(): this; - resume(): this; - isPaused(): boolean; - pipe(destination: T, options?: { end?: boolean | undefined; }): T; - unpipe(destination?: WritableStream): this; - unshift(chunk: string | Uint8Array, encoding?: BufferEncoding): void; - wrap(oldStream: ReadableStream): this; - [Symbol.asyncIterator](): AsyncIterableIterator; - } - - interface WritableStream extends EventEmitter { - writable: boolean; - write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean; - write(str: string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean; - end(cb?: () => void): void; - end(data: string | Uint8Array, cb?: () => void): void; - end(str: string, encoding?: BufferEncoding, cb?: () => void): void; - } - - interface ReadWriteStream extends ReadableStream, WritableStream { } - - interface RefCounted { - ref(): this; - unref(): this; - } - - type TypedArray = - | Uint8Array - | Uint8ClampedArray - | Uint16Array - | Uint32Array - | Int8Array - | Int16Array - | Int32Array - | BigUint64Array - | BigInt64Array - | Float32Array - | Float64Array; - type ArrayBufferView = TypedArray | DataView; - - interface Require { - (id: string): any; - resolve: RequireResolve; - cache: Dict; - /** - * @deprecated - */ - extensions: RequireExtensions; - main: Module | undefined; - } - - interface RequireResolve { - (id: string, options?: { paths?: string[] | undefined; }): string; - paths(request: string): string[] | null; - } - - interface RequireExtensions extends Dict<(m: Module, filename: string) => any> { - '.js': (m: Module, filename: string) => any; - '.json': (m: Module, filename: string) => any; - '.node': (m: Module, filename: string) => any; - } - interface Module { - /** - * `true` if the module is running during the Node.js preload - */ - isPreloading: boolean; - exports: any; - require: Require; - id: string; - filename: string; - loaded: boolean; - /** @deprecated since v14.6.0 Please use `require.main` and `module.children` instead. */ - parent: Module | null | undefined; - children: Module[]; - /** - * @since v11.14.0 + * Optional override for formatting stack traces * - * The directory name of the module. This is usually the same as the path.dirname() of the module.id. + * @see https://v8.dev/docs/stack-trace-api#customizing-stack-traces */ - path: string; - paths: string[]; + prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined; + + stackTraceLimit: number; } - interface Dict { - [key: string]: T | undefined; + /*-----------------------------------------------* + * * + * GLOBAL * + * * + ------------------------------------------------*/ + + // For backwards compability + interface NodeRequire extends NodeJS.Require {} + interface RequireResolve extends NodeJS.RequireResolve {} + interface NodeModule extends NodeJS.Module {} + + var process: NodeJS.Process; + var console: Console; + + var __filename: string; + var __dirname: string; + + var require: NodeRequire; + var module: NodeModule; + + // Same as module.exports + var exports: any; + + /** + * Only available if `--expose-gc` is passed to the process. + */ + var gc: undefined | (() => void); + + // #region borrowed + // from https://github.com/microsoft/TypeScript/blob/38da7c600c83e7b31193a62495239a0fe478cb67/lib/lib.webworker.d.ts#L633 until moved to separate lib + /** A controller object that allows you to abort one or more DOM requests as and when desired. */ + interface AbortController { + /** + * Returns the AbortSignal object associated with this object. + */ + + readonly signal: AbortSignal; + /** + * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted. + */ + abort(reason?: any): void; } - interface ReadOnlyDict { - readonly [key: string]: T | undefined; + /** A signal object that allows you to communicate with a DOM request (such as a Fetch) and abort it if required via an AbortController object. */ + interface AbortSignal extends EventTarget { + /** + * Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise. + */ + readonly aborted: boolean; + readonly reason: any; + onabort: null | ((this: AbortSignal, event: Event) => any); + throwIfAborted(): void; } + + var AbortController: typeof globalThis extends { onmessage: any; AbortController: infer T } ? T + : { + prototype: AbortController; + new(): AbortController; + }; + + var AbortSignal: typeof globalThis extends { onmessage: any; AbortSignal: infer T } ? T + : { + prototype: AbortSignal; + new(): AbortSignal; + abort(reason?: any): AbortSignal; + timeout(milliseconds: number): AbortSignal; + }; + // #endregion borrowed + + // #region Disposable + interface SymbolConstructor { + /** + * A method that is used to release resources held by an object. Called by the semantics of the `using` statement. + */ + readonly dispose: unique symbol; + + /** + * A method that is used to asynchronously release resources held by an object. Called by the semantics of the `await using` statement. + */ + readonly asyncDispose: unique symbol; + } + + interface Disposable { + [Symbol.dispose](): void; + } + + interface AsyncDisposable { + [Symbol.asyncDispose](): PromiseLike; + } + // #endregion Disposable + + // #region ArrayLike.at() + interface RelativeIndexable { + /** + * Takes an integer value and returns the item at that index, + * allowing for positive and negative integers. + * Negative integers count back from the last item in the array. + */ + at(index: number): T | undefined; + } + interface String extends RelativeIndexable {} + interface Array extends RelativeIndexable {} + interface ReadonlyArray extends RelativeIndexable {} + interface Int8Array extends RelativeIndexable {} + interface Uint8Array extends RelativeIndexable {} + interface Uint8ClampedArray extends RelativeIndexable {} + interface Int16Array extends RelativeIndexable {} + interface Uint16Array extends RelativeIndexable {} + interface Int32Array extends RelativeIndexable {} + interface Uint32Array extends RelativeIndexable {} + interface Float32Array extends RelativeIndexable {} + interface Float64Array extends RelativeIndexable {} + interface BigInt64Array extends RelativeIndexable {} + interface BigUint64Array extends RelativeIndexable {} + // #endregion ArrayLike.at() end + + /** + * @since v17.0.0 + * + * Creates a deep clone of an object. + */ + function structuredClone( + value: T, + transfer?: { transfer: ReadonlyArray }, + ): T; + + /*----------------------------------------------* + * * + * GLOBAL INTERFACES * + * * + *-----------------------------------------------*/ + namespace NodeJS { + interface CallSite { + /** + * Value of "this" + */ + getThis(): unknown; + + /** + * Type of "this" as a string. + * This is the name of the function stored in the constructor field of + * "this", if available. Otherwise the object's [[Class]] internal + * property. + */ + getTypeName(): string | null; + + /** + * Current function + */ + getFunction(): Function | undefined; + + /** + * Name of the current function, typically its name property. + * If a name property is not available an attempt will be made to try + * to infer a name from the function's context. + */ + getFunctionName(): string | null; + + /** + * Name of the property [of "this" or one of its prototypes] that holds + * the current function + */ + getMethodName(): string | null; + + /** + * Name of the script [if this function was defined in a script] + */ + getFileName(): string | undefined; + + /** + * Current line number [if this function was defined in a script] + */ + getLineNumber(): number | null; + + /** + * Current column number [if this function was defined in a script] + */ + getColumnNumber(): number | null; + + /** + * A call site object representing the location where eval was called + * [if this function was created using a call to eval] + */ + getEvalOrigin(): string | undefined; + + /** + * Is this a toplevel invocation, that is, is "this" the global object? + */ + isToplevel(): boolean; + + /** + * Does this call take place in code defined by a call to eval? + */ + isEval(): boolean; + + /** + * Is this call in native V8 code? + */ + isNative(): boolean; + + /** + * Is this a constructor call? + */ + isConstructor(): boolean; + + /** + * is this an async call (i.e. await, Promise.all(), or Promise.any())? + */ + isAsync(): boolean; + + /** + * is this an async call to Promise.all()? + */ + isPromiseAll(): boolean; + + /** + * returns the index of the promise element that was followed in + * Promise.all() or Promise.any() for async stack traces, or null + * if the CallSite is not an async + */ + getPromiseIndex(): number | null; + + getScriptNameOrSourceURL(): string; + getScriptHash(): string; + + getEnclosingColumnNumber(): number; + getEnclosingLineNumber(): number; + getPosition(): number; + + toString(): string; + } + + interface ErrnoException extends Error { + errno?: number | undefined; + code?: string | undefined; + path?: string | undefined; + syscall?: string | undefined; + } + + interface ReadableStream extends EventEmitter { + readable: boolean; + read(size?: number): string | Buffer; + setEncoding(encoding: BufferEncoding): this; + pause(): this; + resume(): this; + isPaused(): boolean; + pipe(destination: T, options?: { end?: boolean | undefined }): T; + unpipe(destination?: WritableStream): this; + unshift(chunk: string | Uint8Array, encoding?: BufferEncoding): void; + wrap(oldStream: ReadableStream): this; + [Symbol.asyncIterator](): AsyncIterableIterator; + } + + interface WritableStream extends EventEmitter { + writable: boolean; + write(buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean; + write(str: string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean; + end(cb?: () => void): this; + end(data: string | Uint8Array, cb?: () => void): this; + end(str: string, encoding?: BufferEncoding, cb?: () => void): this; + } + + interface ReadWriteStream extends ReadableStream, WritableStream {} + + interface RefCounted { + ref(): this; + unref(): this; + } + + type TypedArray = + | Uint8Array + | Uint8ClampedArray + | Uint16Array + | Uint32Array + | Int8Array + | Int16Array + | Int32Array + | BigUint64Array + | BigInt64Array + | Float32Array + | Float64Array; + type ArrayBufferView = TypedArray | DataView; + + interface Require { + (id: string): any; + resolve: RequireResolve; + cache: Dict; + /** + * @deprecated + */ + extensions: RequireExtensions; + main: Module | undefined; + } + + interface RequireResolve { + (id: string, options?: { paths?: string[] | undefined }): string; + paths(request: string): string[] | null; + } + + interface RequireExtensions extends Dict<(m: Module, filename: string) => any> { + ".js": (m: Module, filename: string) => any; + ".json": (m: Module, filename: string) => any; + ".node": (m: Module, filename: string) => any; + } + interface Module { + /** + * `true` if the module is running during the Node.js preload + */ + isPreloading: boolean; + exports: any; + require: Require; + id: string; + filename: string; + loaded: boolean; + /** @deprecated since v14.6.0 Please use `require.main` and `module.children` instead. */ + parent: Module | null | undefined; + children: Module[]; + /** + * @since v11.14.0 + * + * The directory name of the module. This is usually the same as the path.dirname() of the module.id. + */ + path: string; + paths: string[]; + } + + interface Dict { + [key: string]: T | undefined; + } + + interface ReadOnlyDict { + readonly [key: string]: T | undefined; + } + } + + interface RequestInit extends _RequestInit {} + + function fetch( + input: string | URL | globalThis.Request, + init?: RequestInit, + ): Promise; + + interface Request extends _Request {} + var Request: typeof globalThis extends { + onmessage: any; + Request: infer T; + } ? T + : typeof import("undici-types").Request; + + interface ResponseInit extends _ResponseInit {} + + interface Response extends _Response {} + var Response: typeof globalThis extends { + onmessage: any; + Response: infer T; + } ? T + : typeof import("undici-types").Response; + + interface FormData extends _FormData {} + var FormData: typeof globalThis extends { + onmessage: any; + FormData: infer T; + } ? T + : typeof import("undici-types").FormData; + + interface Headers extends _Headers {} + var Headers: typeof globalThis extends { + onmessage: any; + Headers: infer T; + } ? T + : typeof import("undici-types").Headers; + + interface File extends _File {} + var File: typeof globalThis extends { + onmessage: any; + File: infer T; + } ? T + : typeof import("node:buffer").File; } diff --git a/node_modules/@types/node/ts4.8/globals.global.d.ts b/node_modules/@types/node/ts4.8/globals.global.d.ts old mode 100755 new mode 100644 diff --git a/node_modules/@types/node/ts4.8/http.d.ts b/node_modules/@types/node/ts4.8/http.d.ts old mode 100755 new mode 100644 index ed05862..710fe59 --- a/node_modules/@types/node/ts4.8/http.d.ts +++ b/node_modules/@types/node/ts4.8/http.d.ts @@ -1,5 +1,5 @@ /** - * To use the HTTP server and client one must `require('http')`. + * To use the HTTP server and client one must `require('node:http')`. * * The HTTP interfaces in Node.js are designed to support many features * of the protocol which have been traditionally difficult to use. @@ -9,12 +9,12 @@ * * HTTP message headers are represented by an object like this: * - * ```js - * { 'content-length': '123', - * 'content-type': 'text/plain', - * 'connection': 'keep-alive', - * 'host': 'mysite.com', - * 'accept': '*' } + * ```json + * { "content-length": "123", + * "content-type": "text/plain", + * "connection": "keep-alive", + * "host": "example.com", + * "accept": "*" } * ``` * * Keys are lowercased. Values are not modified. @@ -34,42 +34,44 @@ * 'content-LENGTH', '123', * 'content-type', 'text/plain', * 'CONNECTION', 'keep-alive', - * 'Host', 'mysite.com', + * 'Host', 'example.com', * 'accepT', '*' ] * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/http.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/http.js) */ -declare module 'http' { - import * as stream from 'node:stream'; - import { URL } from 'node:url'; - import { TcpSocketConnectOpts, Socket, Server as NetServer, LookupFunction } from 'node:net'; +declare module "http" { + import * as stream from "node:stream"; + import { URL } from "node:url"; + import { LookupOptions } from "node:dns"; + import { EventEmitter } from "node:events"; + import { LookupFunction, Server as NetServer, Socket, TcpSocketConnectOpts } from "node:net"; // incoming headers will never contain number interface IncomingHttpHeaders extends NodeJS.Dict { accept?: string | undefined; - 'accept-language'?: string | undefined; - 'accept-patch'?: string | undefined; - 'accept-ranges'?: string | undefined; - 'access-control-allow-credentials'?: string | undefined; - 'access-control-allow-headers'?: string | undefined; - 'access-control-allow-methods'?: string | undefined; - 'access-control-allow-origin'?: string | undefined; - 'access-control-expose-headers'?: string | undefined; - 'access-control-max-age'?: string | undefined; - 'access-control-request-headers'?: string | undefined; - 'access-control-request-method'?: string | undefined; + "accept-language"?: string | undefined; + "accept-patch"?: string | undefined; + "accept-ranges"?: string | undefined; + "access-control-allow-credentials"?: string | undefined; + "access-control-allow-headers"?: string | undefined; + "access-control-allow-methods"?: string | undefined; + "access-control-allow-origin"?: string | undefined; + "access-control-expose-headers"?: string | undefined; + "access-control-max-age"?: string | undefined; + "access-control-request-headers"?: string | undefined; + "access-control-request-method"?: string | undefined; age?: string | undefined; allow?: string | undefined; - 'alt-svc'?: string | undefined; + "alt-svc"?: string | undefined; authorization?: string | undefined; - 'cache-control'?: string | undefined; + "cache-control"?: string | undefined; connection?: string | undefined; - 'content-disposition'?: string | undefined; - 'content-encoding'?: string | undefined; - 'content-language'?: string | undefined; - 'content-length'?: string | undefined; - 'content-location'?: string | undefined; - 'content-range'?: string | undefined; - 'content-type'?: string | undefined; + "content-disposition"?: string | undefined; + "content-encoding"?: string | undefined; + "content-language"?: string | undefined; + "content-length"?: string | undefined; + "content-location"?: string | undefined; + "content-range"?: string | undefined; + "content-type"?: string | undefined; cookie?: string | undefined; date?: string | undefined; etag?: string | undefined; @@ -78,91 +80,216 @@ declare module 'http' { forwarded?: string | undefined; from?: string | undefined; host?: string | undefined; - 'if-match'?: string | undefined; - 'if-modified-since'?: string | undefined; - 'if-none-match'?: string | undefined; - 'if-unmodified-since'?: string | undefined; - 'last-modified'?: string | undefined; + "if-match"?: string | undefined; + "if-modified-since"?: string | undefined; + "if-none-match"?: string | undefined; + "if-unmodified-since"?: string | undefined; + "last-modified"?: string | undefined; location?: string | undefined; origin?: string | undefined; pragma?: string | undefined; - 'proxy-authenticate'?: string | undefined; - 'proxy-authorization'?: string | undefined; - 'public-key-pins'?: string | undefined; + "proxy-authenticate"?: string | undefined; + "proxy-authorization"?: string | undefined; + "public-key-pins"?: string | undefined; range?: string | undefined; referer?: string | undefined; - 'retry-after'?: string | undefined; - 'sec-websocket-accept'?: string | undefined; - 'sec-websocket-extensions'?: string | undefined; - 'sec-websocket-key'?: string | undefined; - 'sec-websocket-protocol'?: string | undefined; - 'sec-websocket-version'?: string | undefined; - 'set-cookie'?: string[] | undefined; - 'strict-transport-security'?: string | undefined; + "retry-after"?: string | undefined; + "sec-websocket-accept"?: string | undefined; + "sec-websocket-extensions"?: string | undefined; + "sec-websocket-key"?: string | undefined; + "sec-websocket-protocol"?: string | undefined; + "sec-websocket-version"?: string | undefined; + "set-cookie"?: string[] | undefined; + "strict-transport-security"?: string | undefined; tk?: string | undefined; trailer?: string | undefined; - 'transfer-encoding'?: string | undefined; + "transfer-encoding"?: string | undefined; upgrade?: string | undefined; - 'user-agent'?: string | undefined; + "user-agent"?: string | undefined; vary?: string | undefined; via?: string | undefined; warning?: string | undefined; - 'www-authenticate'?: string | undefined; + "www-authenticate"?: string | undefined; } // outgoing headers allows numbers (as they are converted internally to strings) type OutgoingHttpHeader = number | string | string[]; - interface OutgoingHttpHeaders extends NodeJS.Dict {} + interface OutgoingHttpHeaders extends NodeJS.Dict { + accept?: string | string[] | undefined; + "accept-charset"?: string | string[] | undefined; + "accept-encoding"?: string | string[] | undefined; + "accept-language"?: string | string[] | undefined; + "accept-ranges"?: string | undefined; + "access-control-allow-credentials"?: string | undefined; + "access-control-allow-headers"?: string | undefined; + "access-control-allow-methods"?: string | undefined; + "access-control-allow-origin"?: string | undefined; + "access-control-expose-headers"?: string | undefined; + "access-control-max-age"?: string | undefined; + "access-control-request-headers"?: string | undefined; + "access-control-request-method"?: string | undefined; + age?: string | undefined; + allow?: string | undefined; + authorization?: string | undefined; + "cache-control"?: string | undefined; + "cdn-cache-control"?: string | undefined; + connection?: string | string[] | undefined; + "content-disposition"?: string | undefined; + "content-encoding"?: string | undefined; + "content-language"?: string | undefined; + "content-length"?: string | number | undefined; + "content-location"?: string | undefined; + "content-range"?: string | undefined; + "content-security-policy"?: string | undefined; + "content-security-policy-report-only"?: string | undefined; + cookie?: string | string[] | undefined; + dav?: string | string[] | undefined; + dnt?: string | undefined; + date?: string | undefined; + etag?: string | undefined; + expect?: string | undefined; + expires?: string | undefined; + forwarded?: string | undefined; + from?: string | undefined; + host?: string | undefined; + "if-match"?: string | undefined; + "if-modified-since"?: string | undefined; + "if-none-match"?: string | undefined; + "if-range"?: string | undefined; + "if-unmodified-since"?: string | undefined; + "last-modified"?: string | undefined; + link?: string | string[] | undefined; + location?: string | undefined; + "max-forwards"?: string | undefined; + origin?: string | undefined; + prgama?: string | string[] | undefined; + "proxy-authenticate"?: string | string[] | undefined; + "proxy-authorization"?: string | undefined; + "public-key-pins"?: string | undefined; + "public-key-pins-report-only"?: string | undefined; + range?: string | undefined; + referer?: string | undefined; + "referrer-policy"?: string | undefined; + refresh?: string | undefined; + "retry-after"?: string | undefined; + "sec-websocket-accept"?: string | undefined; + "sec-websocket-extensions"?: string | string[] | undefined; + "sec-websocket-key"?: string | undefined; + "sec-websocket-protocol"?: string | string[] | undefined; + "sec-websocket-version"?: string | undefined; + server?: string | undefined; + "set-cookie"?: string | string[] | undefined; + "strict-transport-security"?: string | undefined; + te?: string | undefined; + trailer?: string | undefined; + "transfer-encoding"?: string | undefined; + "user-agent"?: string | undefined; + upgrade?: string | undefined; + "upgrade-insecure-requests"?: string | undefined; + vary?: string | undefined; + via?: string | string[] | undefined; + warning?: string | undefined; + "www-authenticate"?: string | string[] | undefined; + "x-content-type-options"?: string | undefined; + "x-dns-prefetch-control"?: string | undefined; + "x-frame-options"?: string | undefined; + "x-xss-protection"?: string | undefined; + } interface ClientRequestArgs { - signal?: AbortSignal | undefined; - protocol?: string | null | undefined; - host?: string | null | undefined; - hostname?: string | null | undefined; - family?: number | undefined; - port?: number | string | null | undefined; - defaultPort?: number | string | undefined; - localAddress?: string | undefined; - socketPath?: string | undefined; - /** - * @default 8192 - */ - maxHeaderSize?: number | undefined; - method?: string | undefined; - path?: string | null | undefined; - headers?: OutgoingHttpHeaders | undefined; - auth?: string | null | undefined; - agent?: Agent | boolean | undefined; _defaultAgent?: Agent | undefined; - timeout?: number | undefined; - setHost?: boolean | undefined; + agent?: Agent | boolean | undefined; + auth?: string | null | undefined; // https://github.com/nodejs/node/blob/master/lib/_http_client.js#L278 createConnection?: | ((options: ClientRequestArgs, oncreate: (err: Error, socket: Socket) => void) => Socket) | undefined; + defaultPort?: number | string | undefined; + family?: number | undefined; + headers?: OutgoingHttpHeaders | undefined; + hints?: LookupOptions["hints"]; + host?: string | null | undefined; + hostname?: string | null | undefined; + insecureHTTPParser?: boolean | undefined; + localAddress?: string | undefined; + localPort?: number | undefined; lookup?: LookupFunction | undefined; + /** + * @default 16384 + */ + maxHeaderSize?: number | undefined; + method?: string | undefined; + path?: string | null | undefined; + port?: number | string | null | undefined; + protocol?: string | null | undefined; + setHost?: boolean | undefined; + signal?: AbortSignal | undefined; + socketPath?: string | undefined; + timeout?: number | undefined; + uniqueHeaders?: Array | undefined; + joinDuplicateHeaders?: boolean; } interface ServerOptions< Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse, > { + /** + * Specifies the `IncomingMessage` class to be used. Useful for extending the original `IncomingMessage`. + */ IncomingMessage?: Request | undefined; + /** + * Specifies the `ServerResponse` class to be used. Useful for extending the original `ServerResponse`. + */ ServerResponse?: Response | undefined; /** - * Optionally overrides the value of - * `--max-http-header-size` for requests received by this server, i.e. - * the maximum length of request headers in bytes. - * @default 8192 + * Sets the timeout value in milliseconds for receiving the entire request from the client. + * @see Server.requestTimeout for more information. + * @default 300000 + * @since v18.0.0 */ - maxHeaderSize?: number | undefined; + requestTimeout?: number | undefined; /** - * Use an insecure HTTP parser that accepts invalid HTTP headers when true. + * It joins the field line values of multiple headers in a request with `, ` instead of discarding the duplicates. + * @default false + * @since v18.14.0 + */ + joinDuplicateHeaders?: boolean; + /** + * The number of milliseconds of inactivity a server needs to wait for additional incoming data, + * after it has finished writing the last response, before a socket will be destroyed. + * @see Server.keepAliveTimeout for more information. + * @default 5000 + * @since v18.0.0 + */ + keepAliveTimeout?: number | undefined; + /** + * Sets the interval value in milliseconds to check for request and headers timeout in incomplete requests. + * @default 30000 + */ + connectionsCheckingInterval?: number | undefined; + /** + * Optionally overrides all `socket`s' `readableHighWaterMark` and `writableHighWaterMark`. + * This affects `highWaterMark` property of both `IncomingMessage` and `ServerResponse`. + * Default: @see stream.getDefaultHighWaterMark(). + * @since v20.1.0 + */ + highWaterMark?: number | undefined; + /** + * Use an insecure HTTP parser that accepts invalid HTTP headers when `true`. * Using the insecure parser should be avoided. * See --insecure-http-parser for more information. * @default false */ insecureHTTPParser?: boolean | undefined; + /** + * Optionally overrides the value of + * `--max-http-header-size` for requests received by this server, i.e. + * the maximum length of request headers in bytes. + * @default 16384 + * @since v13.3.0 + */ + maxHeaderSize?: number | undefined; /** * If set to `true`, it disables the use of Nagle's algorithm immediately after a new incoming connection is received. - * @default false + * @default true * @since v16.5.0 */ noDelay?: boolean | undefined; @@ -179,6 +306,11 @@ declare module 'http' { * @since v16.5.0 */ keepAliveInitialDelay?: number | undefined; + /** + * A list of response headers that should be sent only once. + * If the header's value is an array, the items will be joined using `; `. + */ + uniqueHeaders?: Array | undefined; } type RequestListener< Request extends typeof IncomingMessage = typeof IncomingMessage, @@ -241,14 +373,12 @@ declare module 'http' { * Limit the amount of time the parser will wait to receive the complete HTTP * headers. * - * In case of inactivity, the rules defined in `server.timeout` apply. However, - * that inactivity based timeout would still allow the connection to be kept open - * if the headers are being sent very slowly (by default, up to a byte per 2 - * minutes). In order to prevent this, whenever header data arrives an additional - * check is made that more than `server.headersTimeout` milliseconds has not - * passed since the connection was established. If the check fails, a `'timeout'`event is emitted on the server object, and (by default) the socket is destroyed. - * See `server.timeout` for more information on how timeout behavior can be - * customized. + * If the timeout expires, the server responds with status 408 without + * forwarding the request to the request listener and then closes the connection. + * + * It must be set to a non-zero value (e.g. 120 seconds) to protect against + * potential Denial-of-Service attacks in case the server is deployed without a + * reverse proxy in front. * @since v11.3.0, v10.14.0 */ headersTimeout: number; @@ -281,112 +411,135 @@ declare module 'http' { * @since v14.11.0 */ requestTimeout: number; + /** + * Closes all connections connected to this server. + * @since v18.2.0 + */ + closeAllConnections(): void; + /** + * Closes all connections connected to this server which are not sending a request + * or waiting for a response. + * @since v18.2.0 + */ + closeIdleConnections(): void; addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'connection', listener: (socket: Socket) => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'listening', listener: () => void): this; - addListener(event: 'checkContinue', listener: RequestListener): this; - addListener(event: 'checkExpectation', listener: RequestListener): this; - addListener(event: 'clientError', listener: (err: Error, socket: stream.Duplex) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "connection", listener: (socket: Socket) => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "listening", listener: () => void): this; + addListener(event: "checkContinue", listener: RequestListener): this; + addListener(event: "checkExpectation", listener: RequestListener): this; + addListener(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this; addListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; - addListener(event: 'request', listener: RequestListener): this; + addListener(event: "dropRequest", listener: (req: InstanceType, socket: stream.Duplex) => void): this; + addListener(event: "request", listener: RequestListener): this; addListener( - event: 'upgrade', + event: "upgrade", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; emit(event: string, ...args: any[]): boolean; - emit(event: 'close'): boolean; - emit(event: 'connection', socket: Socket): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'listening'): boolean; + emit(event: "close"): boolean; + emit(event: "connection", socket: Socket): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "listening"): boolean; emit( - event: 'checkContinue', + event: "checkContinue", req: InstanceType, res: InstanceType & { req: InstanceType }, ): boolean; emit( - event: 'checkExpectation', + event: "checkExpectation", req: InstanceType, res: InstanceType & { req: InstanceType }, ): boolean; - emit(event: 'clientError', err: Error, socket: stream.Duplex): boolean; - emit(event: 'connect', req: InstanceType, socket: stream.Duplex, head: Buffer): boolean; + emit(event: "clientError", err: Error, socket: stream.Duplex): boolean; + emit(event: "connect", req: InstanceType, socket: stream.Duplex, head: Buffer): boolean; + emit(event: "dropRequest", req: InstanceType, socket: stream.Duplex): boolean; emit( - event: 'request', + event: "request", req: InstanceType, res: InstanceType & { req: InstanceType }, ): boolean; - emit(event: 'upgrade', req: InstanceType, socket: stream.Duplex, head: Buffer): boolean; + emit(event: "upgrade", req: InstanceType, socket: stream.Duplex, head: Buffer): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'connection', listener: (socket: Socket) => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'listening', listener: () => void): this; - on(event: 'checkContinue', listener: RequestListener): this; - on(event: 'checkExpectation', listener: RequestListener): this; - on(event: 'clientError', listener: (err: Error, socket: stream.Duplex) => void): this; - on(event: 'connect', listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void): this; - on(event: 'request', listener: RequestListener): this; - on(event: 'upgrade', listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void): this; + on(event: "close", listener: () => void): this; + on(event: "connection", listener: (socket: Socket) => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "listening", listener: () => void): this; + on(event: "checkContinue", listener: RequestListener): this; + on(event: "checkExpectation", listener: RequestListener): this; + on(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this; + on(event: "connect", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void): this; + on(event: "dropRequest", listener: (req: InstanceType, socket: stream.Duplex) => void): this; + on(event: "request", listener: RequestListener): this; + on(event: "upgrade", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'connection', listener: (socket: Socket) => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'listening', listener: () => void): this; - once(event: 'checkContinue', listener: RequestListener): this; - once(event: 'checkExpectation', listener: RequestListener): this; - once(event: 'clientError', listener: (err: Error, socket: stream.Duplex) => void): this; + once(event: "close", listener: () => void): this; + once(event: "connection", listener: (socket: Socket) => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "listening", listener: () => void): this; + once(event: "checkContinue", listener: RequestListener): this; + once(event: "checkExpectation", listener: RequestListener): this; + once(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this; once( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; - once(event: 'request', listener: RequestListener): this; + once(event: "dropRequest", listener: (req: InstanceType, socket: stream.Duplex) => void): this; + once(event: "request", listener: RequestListener): this; once( - event: 'upgrade', + event: "upgrade", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'connection', listener: (socket: Socket) => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'listening', listener: () => void): this; - prependListener(event: 'checkContinue', listener: RequestListener): this; - prependListener(event: 'checkExpectation', listener: RequestListener): this; - prependListener(event: 'clientError', listener: (err: Error, socket: stream.Duplex) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "connection", listener: (socket: Socket) => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "listening", listener: () => void): this; + prependListener(event: "checkContinue", listener: RequestListener): this; + prependListener(event: "checkExpectation", listener: RequestListener): this; + prependListener(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this; prependListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; - prependListener(event: 'request', listener: RequestListener): this; prependListener( - event: 'upgrade', + event: "dropRequest", + listener: (req: InstanceType, socket: stream.Duplex) => void, + ): this; + prependListener(event: "request", listener: RequestListener): this; + prependListener( + event: "upgrade", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'connection', listener: (socket: Socket) => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'listening', listener: () => void): this; - prependOnceListener(event: 'checkContinue', listener: RequestListener): this; - prependOnceListener(event: 'checkExpectation', listener: RequestListener): this; - prependOnceListener(event: 'clientError', listener: (err: Error, socket: stream.Duplex) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "connection", listener: (socket: Socket) => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "listening", listener: () => void): this; + prependOnceListener(event: "checkContinue", listener: RequestListener): this; + prependOnceListener(event: "checkExpectation", listener: RequestListener): this; + prependOnceListener(event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): this; prependOnceListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; - prependOnceListener(event: 'request', listener: RequestListener): this; prependOnceListener( - event: 'upgrade', + event: "dropRequest", + listener: (req: InstanceType, socket: stream.Duplex) => void, + ): this; + prependOnceListener(event: "request", listener: RequestListener): this; + prependOnceListener( + event: "upgrade", listener: (req: InstanceType, socket: stream.Duplex, head: Buffer) => void, ): this; } /** - * This class serves as the parent class of {@link ClientRequest} and {@link ServerResponse}. It is an abstract of outgoing message from - * the perspective of the participants of HTTP transaction. + * This class serves as the parent class of {@link ClientRequest} and {@link ServerResponse}. It is an abstract outgoing message from + * the perspective of the participants of an HTTP transaction. * @since v0.1.17 */ class OutgoingMessage extends stream.Writable { @@ -405,9 +558,9 @@ declare module 'http' { */ readonly headersSent: boolean; /** - * Aliases of `outgoingMessage.socket` + * Alias of `outgoingMessage.socket`. * @since v0.3.0 - * @deprecated Since v15.12.0 - Use `socket` instead. + * @deprecated Since v15.12.0,v14.17.1 - Use `socket` instead. */ readonly connection: Socket | null; /** @@ -426,15 +579,33 @@ declare module 'http' { */ setTimeout(msecs: number, callback?: () => void): this; /** - * Sets a single header value for the header object. + * Sets a single header value. If the header already exists in the to-be-sent + * headers, its value will be replaced. Use an array of strings to send multiple + * headers with the same name. * @since v0.4.0 * @param name Header name * @param value Header value */ - setHeader(name: string, value: number | string | ReadonlyArray): this; + setHeader(name: string, value: number | string | readonly string[]): this; /** - * Gets the value of HTTP header with the given name. If such a name doesn't - * exist in message, it will be `undefined`. + * Append a single header value for the header object. + * + * If the value is an array, this is equivalent of calling this method multiple + * times. + * + * If there were no previous value for the header, this is equivalent of calling `outgoingMessage.setHeader(name, value)`. + * + * Depending of the value of `options.uniqueHeaders` when the client request or the + * server were created, this will end up in the header being sent multiple times or + * a single time with values joined using `; `. + * @since v18.3.0, v16.17.0 + * @param name Header name + * @param value Header value + */ + appendHeader(name: string, value: string | readonly string[]): this; + /** + * Gets the value of the HTTP header with the given name. If that header is not + * set, the returned value will be `undefined`. * @since v0.4.0 * @param name Name of header */ @@ -447,8 +618,8 @@ declare module 'http' { * values. All header names are lowercase. * * The object returned by the `outgoingMessage.getHeaders()` method does - * not prototypically inherit from the JavaScript Object. This means that - * typical Object methods such as `obj.toString()`, `obj.hasOwnProperty()`, + * not prototypically inherit from the JavaScript `Object`. This means that + * typical `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, * and others are not defined and will not work. * * ```js @@ -458,13 +629,13 @@ declare module 'http' { * const headers = outgoingMessage.getHeaders(); * // headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } * ``` - * @since v8.0.0 + * @since v7.7.0 */ getHeaders(): OutgoingHttpHeaders; /** - * Returns an array of names of headers of the outgoing outgoingMessage. All - * names are lowercase. - * @since v8.0.0 + * Returns an array containing the unique names of the current outgoing headers. + * All names are lowercase. + * @since v7.7.0 */ getHeaderNames(): string[]; /** @@ -474,7 +645,7 @@ declare module 'http' { * ```js * const hasContentType = outgoingMessage.hasHeader('content-type'); * ``` - * @since v8.0.0 + * @since v7.7.0 */ hasHeader(name: string): boolean; /** @@ -484,16 +655,17 @@ declare module 'http' { * outgoingMessage.removeHeader('Content-Encoding'); * ``` * @since v0.4.0 + * @param name Header name */ removeHeader(name: string): void; /** * Adds HTTP trailers (headers but at the end of the message) to the message. * - * Trailers are **only** be emitted if the message is chunked encoded. If not, - * the trailer will be silently discarded. + * Trailers will **only** be emitted if the message is chunked encoded. If not, + * the trailers will be silently discarded. * * HTTP requires the `Trailer` header to be sent to emit trailers, - * with a list of header fields in its value, e.g. + * with a list of header field names in its value, e.g. * * ```js * message.writeHead(200, { 'Content-Type': 'text/plain', @@ -509,7 +681,7 @@ declare module 'http' { */ addTrailers(headers: OutgoingHttpHeaders | ReadonlyArray<[string, string]>): void; /** - * Compulsorily flushes the message headers + * Flushes the message headers. * * For efficiency reason, Node.js normally buffers the message headers * until `outgoingMessage.end()` is called or the first chunk of message data @@ -517,7 +689,7 @@ declare module 'http' { * packet. * * It is usually desired (it saves a TCP round-trip), but not when the first - * data is not sent until possibly much later. `outgoingMessage.flushHeaders()`bypasses the optimization and kickstarts the request. + * data is not sent until possibly much later. `outgoingMessage.flushHeaders()`bypasses the optimization and kickstarts the message. * @since v1.6.0 */ flushHeaders(): void; @@ -557,15 +729,56 @@ declare module 'http' { * @since v0.11.8 */ statusMessage: string; + /** + * If set to `true`, Node.js will check whether the `Content-Length`header value and the size of the body, in bytes, are equal. + * Mismatching the `Content-Length` header value will result + * in an `Error` being thrown, identified by `code:``'ERR_HTTP_CONTENT_LENGTH_MISMATCH'`. + * @since v18.10.0, v16.18.0 + */ + strictContentLength: boolean; constructor(req: Request); assignSocket(socket: Socket): void; detachSocket(socket: Socket): void; /** - * Sends a HTTP/1.1 100 Continue message to the client, indicating that + * Sends an HTTP/1.1 100 Continue message to the client, indicating that * the request body should be sent. See the `'checkContinue'` event on`Server`. * @since v0.3.0 */ writeContinue(callback?: () => void): void; + /** + * Sends an HTTP/1.1 103 Early Hints message to the client with a Link header, + * indicating that the user agent can preload/preconnect the linked resources. + * The `hints` is an object containing the values of headers to be sent with + * early hints message. The optional `callback` argument will be called when + * the response message has been written. + * + * **Example** + * + * ```js + * const earlyHintsLink = '; rel=preload; as=style'; + * response.writeEarlyHints({ + * 'link': earlyHintsLink, + * }); + * + * const earlyHintsLinks = [ + * '; rel=preload; as=style', + * '; rel=preload; as=script', + * ]; + * response.writeEarlyHints({ + * 'link': earlyHintsLinks, + * 'x-trace-id': 'id for diagnostics', + * }); + * + * const earlyHintsCallback = () => console.log('early hints message sent'); + * response.writeEarlyHints({ + * 'link': earlyHintsLinks, + * }, earlyHintsCallback); + * ``` + * @since v18.11.0 + * @param hints An object containing the values of headers + * @param callback Will be called when the response message has been written + */ + writeEarlyHints(hints: Record, callback?: () => void): void; /** * Sends a response header to the request. The status code is a 3-digit HTTP * status code, like `404`. The last argument, `headers`, are the response headers. @@ -584,7 +797,7 @@ declare module 'http' { * response * .writeHead(200, { * 'Content-Length': Buffer.byteLength(body), - * 'Content-Type': 'text/plain' + * 'Content-Type': 'text/plain', * }) * .end(body); * ``` @@ -615,12 +828,12 @@ declare module 'http' { * }); * ``` * - * `Content-Length` is given in bytes, not characters. Use `Buffer.byteLength()` to determine the length of the body in bytes. Node.js - * does not check whether `Content-Length` and the length of the body which has + * `Content-Length` is read in bytes, not characters. Use `Buffer.byteLength()` to determine the length of the body in bytes. Node.js + * will check whether `Content-Length` and the length of the body which has * been transmitted are equal or not. * * Attempting to set a header field name or value that contains invalid characters - * will result in a `TypeError` being thrown. + * will result in a \[`Error`\]\[\] being thrown. * @since v0.1.30 */ writeHead( @@ -669,8 +882,11 @@ declare module 'http' { * * For backward compatibility, `res` will only emit `'error'` if there is an`'error'` listener registered. * - * Node.js does not check whether Content-Length and the length of the - * body which has been transmitted are equal or not. + * Set `Content-Length` header to limit the response body size. + * If `response.strictContentLength` is set to `true`, mismatching the`Content-Length` header value will result in an `Error` being thrown, + * identified by `code:``'ERR_HTTP_CONTENT_LENGTH_MISMATCH'`. + * + * `Content-Length` value should be in bytes, not characters. Use `Buffer.byteLength()` to determine the length of the body in bytes. * @since v0.1.17 */ class ClientRequest extends OutgoingMessage { @@ -678,6 +894,7 @@ declare module 'http' { * The `request.aborted` property will be `true` if the request has * been aborted. * @since v0.11.14 + * @deprecated Since v17.0.0,v16.12.0 - Check `destroyed` instead. */ aborted: boolean; /** @@ -691,13 +908,58 @@ declare module 'http' { */ protocol: string; /** - * Whether the request is send through a reused socket. + * When sending request through a keep-alive enabled agent, the underlying socket + * might be reused. But if server closes connection at unfortunate time, client + * may run into a 'ECONNRESET' error. + * + * ```js + * import http from 'node:http'; + * + * // Server has a 5 seconds keep-alive timeout by default + * http + * .createServer((req, res) => { + * res.write('hello\n'); + * res.end(); + * }) + * .listen(3000); + * + * setInterval(() => { + * // Adapting a keep-alive agent + * http.get('http://localhost:3000', { agent }, (res) => { + * res.on('data', (data) => { + * // Do nothing + * }); + * }); + * }, 5000); // Sending request on 5s interval so it's easy to hit idle timeout + * ``` + * + * By marking a request whether it reused socket or not, we can do + * automatic error retry base on it. + * + * ```js + * import http from 'node:http'; + * const agent = new http.Agent({ keepAlive: true }); + * + * function retriableRequest() { + * const req = http + * .get('http://localhost:3000', { agent }, (res) => { + * // ... + * }) + * .on('error', (err) => { + * // Check if retry is needed + * if (req.reusedSocket && err.code === 'ECONNRESET') { + * retriableRequest(); + * } + * }); + * } + * + * retriableRequest(); + * ``` * @since v13.0.0, v12.16.0 */ reusedSocket: boolean; /** * Limits maximum response headers count. If set to 0, no limit will be applied. - * @default 2000 */ maxHeadersCount: number; constructor(url: string | URL | ClientRequestArgs, cb?: (res: IncomingMessage) => void); @@ -747,107 +1009,122 @@ declare module 'http' { * const headerNames = request.getRawHeaderNames(); * // headerNames === ['Foo', 'Set-Cookie'] * ``` - * @since v15.13.0 + * @since v15.13.0, v14.17.0 */ getRawHeaderNames(): string[]; - addListener(event: 'abort', listener: () => void): this; + /** + * @deprecated + */ + addListener(event: "abort", listener: () => void): this; addListener( - event: 'connect', + event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - addListener(event: 'continue', listener: () => void): this; - addListener(event: 'information', listener: (info: InformationEvent) => void): this; - addListener(event: 'response', listener: (response: IncomingMessage) => void): this; - addListener(event: 'socket', listener: (socket: Socket) => void): this; - addListener(event: 'timeout', listener: () => void): this; + addListener(event: "continue", listener: () => void): this; + addListener(event: "information", listener: (info: InformationEvent) => void): this; + addListener(event: "response", listener: (response: IncomingMessage) => void): this; + addListener(event: "socket", listener: (socket: Socket) => void): this; + addListener(event: "timeout", listener: () => void): this; addListener( - event: 'upgrade', + event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'finish', listener: () => void): this; - addListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - addListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "pipe", listener: (src: stream.Readable) => void): this; + addListener(event: "unpipe", listener: (src: stream.Readable) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - on(event: 'abort', listener: () => void): this; - on(event: 'connect', listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; - on(event: 'continue', listener: () => void): this; - on(event: 'information', listener: (info: InformationEvent) => void): this; - on(event: 'response', listener: (response: IncomingMessage) => void): this; - on(event: 'socket', listener: (socket: Socket) => void): this; - on(event: 'timeout', listener: () => void): this; - on(event: 'upgrade', listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'finish', listener: () => void): this; - on(event: 'pipe', listener: (src: stream.Readable) => void): this; - on(event: 'unpipe', listener: (src: stream.Readable) => void): this; + /** + * @deprecated + */ + on(event: "abort", listener: () => void): this; + on(event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; + on(event: "continue", listener: () => void): this; + on(event: "information", listener: (info: InformationEvent) => void): this; + on(event: "response", listener: (response: IncomingMessage) => void): this; + on(event: "socket", listener: (socket: Socket) => void): this; + on(event: "timeout", listener: () => void): this; + on(event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; + on(event: "close", listener: () => void): this; + on(event: "drain", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "pipe", listener: (src: stream.Readable) => void): this; + on(event: "unpipe", listener: (src: stream.Readable) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'abort', listener: () => void): this; - once(event: 'connect', listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; - once(event: 'continue', listener: () => void): this; - once(event: 'information', listener: (info: InformationEvent) => void): this; - once(event: 'response', listener: (response: IncomingMessage) => void): this; - once(event: 'socket', listener: (socket: Socket) => void): this; - once(event: 'timeout', listener: () => void): this; - once(event: 'upgrade', listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'finish', listener: () => void): this; - once(event: 'pipe', listener: (src: stream.Readable) => void): this; - once(event: 'unpipe', listener: (src: stream.Readable) => void): this; + /** + * @deprecated + */ + once(event: "abort", listener: () => void): this; + once(event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; + once(event: "continue", listener: () => void): this; + once(event: "information", listener: (info: InformationEvent) => void): this; + once(event: "response", listener: (response: IncomingMessage) => void): this; + once(event: "socket", listener: (socket: Socket) => void): this; + once(event: "timeout", listener: () => void): this; + once(event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void): this; + once(event: "close", listener: () => void): this; + once(event: "drain", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "pipe", listener: (src: stream.Readable) => void): this; + once(event: "unpipe", listener: (src: stream.Readable) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'abort', listener: () => void): this; + /** + * @deprecated + */ + prependListener(event: "abort", listener: () => void): this; prependListener( - event: 'connect', + event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - prependListener(event: 'continue', listener: () => void): this; - prependListener(event: 'information', listener: (info: InformationEvent) => void): this; - prependListener(event: 'response', listener: (response: IncomingMessage) => void): this; - prependListener(event: 'socket', listener: (socket: Socket) => void): this; - prependListener(event: 'timeout', listener: () => void): this; + prependListener(event: "continue", listener: () => void): this; + prependListener(event: "information", listener: (info: InformationEvent) => void): this; + prependListener(event: "response", listener: (response: IncomingMessage) => void): this; + prependListener(event: "socket", listener: (socket: Socket) => void): this; + prependListener(event: "timeout", listener: () => void): this; prependListener( - event: 'upgrade', + event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'finish', listener: () => void): this; - prependListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'abort', listener: () => void): this; + /** + * @deprecated + */ + prependOnceListener(event: "abort", listener: () => void): this; prependOnceListener( - event: 'connect', + event: "connect", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - prependOnceListener(event: 'continue', listener: () => void): this; - prependOnceListener(event: 'information', listener: (info: InformationEvent) => void): this; - prependOnceListener(event: 'response', listener: (response: IncomingMessage) => void): this; - prependOnceListener(event: 'socket', listener: (socket: Socket) => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; + prependOnceListener(event: "continue", listener: () => void): this; + prependOnceListener(event: "information", listener: (info: InformationEvent) => void): this; + prependOnceListener(event: "response", listener: (response: IncomingMessage) => void): this; + prependOnceListener(event: "socket", listener: (socket: Socket) => void): this; + prependOnceListener(event: "timeout", listener: () => void): this; prependOnceListener( - event: 'upgrade', + event: "upgrade", listener: (response: IncomingMessage, socket: Socket, head: Buffer) => void, ): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'finish', listener: () => void): this; - prependOnceListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependOnceListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } /** * An `IncomingMessage` object is created by {@link Server} or {@link ClientRequest} and passed as the first argument to the `'request'` and `'response'` event respectively. It may be used to * access response - * status, headers and data. + * status, headers, and data. * * Different from its `socket` value which is a subclass of `stream.Duplex`, the`IncomingMessage` itself extends `stream.Readable` and is created separately to * parse and emit the incoming HTTP headers and payload, as the underlying socket @@ -860,6 +1137,7 @@ declare module 'http' { * The `message.aborted` property will be `true` if the request has * been aborted. * @since v10.1.0 + * @deprecated Since v17.0.0,v16.12.0 - Check `message.destroyed` from stream.Readable. */ aborted: boolean; /** @@ -884,7 +1162,7 @@ declare module 'http' { * const req = http.request({ * host: '127.0.0.1', * port: 8080, - * method: 'POST' + * method: 'POST', * }, (res) => { * res.resume(); * res.on('end', () => { @@ -911,7 +1189,7 @@ declare module 'http' { * * This property is guaranteed to be an instance of the `net.Socket` class, * a subclass of `stream.Duplex`, unless the user specified a socket - * type other than `net.Socket`. + * type other than `net.Socket` or internally nulled. * @since v0.3.0 */ socket: Socket; @@ -934,12 +1212,30 @@ declare module 'http' { * * * Duplicates of `age`, `authorization`, `content-length`, `content-type`,`etag`, `expires`, `from`, `host`, `if-modified-since`, `if-unmodified-since`,`last-modified`, `location`, * `max-forwards`, `proxy-authorization`, `referer`,`retry-after`, `server`, or `user-agent` are discarded. + * To allow duplicate values of the headers listed above to be joined, + * use the option `joinDuplicateHeaders` in {@link request} and {@link createServer}. See RFC 9110 Section 5.3 for more + * information. * * `set-cookie` is always an array. Duplicates are added to the array. - * * For duplicate `cookie` headers, the values are joined together with '; '. - * * For all other headers, the values are joined together with ', '. + * * For duplicate `cookie` headers, the values are joined together with `; `. + * * For all other headers, the values are joined together with `, `. * @since v0.1.5 */ headers: IncomingHttpHeaders; + /** + * Similar to `message.headers`, but there is no join logic and the values are + * always arrays of strings, even for headers received just once. + * + * ```js + * // Prints something like: + * // + * // { 'user-agent': ['curl/7.22.0'], + * // host: ['127.0.0.1:8000'], + * // accept: ['*'] } + * console.log(request.headersDistinct); + * ``` + * @since v18.3.0, v16.17.0 + */ + headersDistinct: NodeJS.Dict; /** * The raw request/response headers list exactly as they were received. * @@ -970,6 +1266,13 @@ declare module 'http' { * @since v0.3.0 */ trailers: NodeJS.Dict; + /** + * Similar to `message.trailers`, but there is no join logic and the values are + * always arrays of strings, even for headers received just once. + * Only populated at the `'end'` event. + * @since v18.3.0, v16.17.0 + */ + trailersDistinct: NodeJS.Dict; /** * The raw request/response trailer keys and values exactly as they were * received. Only populated at the `'end'` event. @@ -1005,7 +1308,7 @@ declare module 'http' { * new URL(request.url, `http://${request.headers.host}`); * ``` * - * When `request.url` is `'/status?name=ryan'` and`request.headers.host` is `'localhost:3000'`: + * When `request.url` is `'/status?name=ryan'` and `request.headers.host` is`'localhost:3000'`: * * ```console * $ node @@ -1079,7 +1382,7 @@ declare module 'http' { * Scheduling strategy to apply when picking the next free socket to use. * @default `lifo` */ - scheduling?: 'fifo' | 'lifo' | undefined; + scheduling?: "fifo" | "lifo" | undefined; } /** * An `Agent` is responsible for managing connection persistence @@ -1129,16 +1432,16 @@ declare module 'http' { * hostname: 'localhost', * port: 80, * path: '/', - * agent: false // Create a new agent just for this one request + * agent: false, // Create a new agent just for this one request * }, (res) => { * // Do stuff with response * }); * ``` * @since v0.3.4 */ - class Agent { + class Agent extends EventEmitter { /** - * By default set to 256\. For agents with `keepAlive` enabled, this + * By default set to 256. For agents with `keepAlive` enabled, this * sets the maximum number of sockets that will be left open in the free * state. * @since v0.11.7 @@ -1200,6 +1503,37 @@ declare module 'http' { * * The `requestListener` is a function which is automatically * added to the `'request'` event. + * + * ```js + * import http from 'node:http'; + * + * // Create a local server to receive data from + * const server = http.createServer((req, res) => { + * res.writeHead(200, { 'Content-Type': 'application/json' }); + * res.end(JSON.stringify({ + * data: 'Hello World!', + * })); + * }); + * + * server.listen(8000); + * ``` + * + * ```js + * import http from 'node:http'; + * + * // Create a local server to receive data from + * const server = http.createServer(); + * + * // Listen to the request event + * server.on('request', (request, res) => { + * res.writeHead(200, { 'Content-Type': 'application/json' }); + * res.end(JSON.stringify({ + * data: 'Hello World!', + * })); + * }); + * + * server.listen(8000); + * ``` * @since v0.1.13 */ function createServer< @@ -1209,11 +1543,16 @@ declare module 'http' { function createServer< Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse, - >(options: ServerOptions, requestListener?: RequestListener): Server; + >( + options: ServerOptions, + requestListener?: RequestListener, + ): Server; // although RequestOptions are passed as ClientRequestArgs to ClientRequest directly, // create interface RequestOptions would make the naming more clear to developers interface RequestOptions extends ClientRequestArgs {} /** + * `options` in `socket.connect()` are also supported. + * * Node.js maintains several connections per server to make HTTP requests. * This function allows one to transparently issue requests. * @@ -1229,10 +1568,11 @@ declare module 'http' { * upload a file with a POST request, then write to the `ClientRequest` object. * * ```js - * const http = require('http'); + * import http from 'node:http'; + * import { Buffer } from 'node:buffer'; * * const postData = JSON.stringify({ - * 'msg': 'Hello World!' + * 'msg': 'Hello World!', * }); * * const options = { @@ -1242,8 +1582,8 @@ declare module 'http' { * method: 'POST', * headers: { * 'Content-Type': 'application/json', - * 'Content-Length': Buffer.byteLength(postData) - * } + * 'Content-Length': Buffer.byteLength(postData), + * }, * }; * * const req = http.request(options, (res) => { @@ -1330,7 +1670,7 @@ declare module 'http' { * * `'data'` any number of times, on the `res` object * * (connection closed here) * * `'aborted'` on the `res` object - * * `'error'` on the `res` object with an error with message`'Error: aborted'` and code `'ECONNRESET'`. + * * `'error'` on the `res` object with an error with message`'Error: aborted'` and code `'ECONNRESET'` * * `'close'` * * `'close'` on the `res` object * @@ -1338,7 +1678,7 @@ declare module 'http' { * events will be emitted in the following order: * * * (`req.destroy()` called here) - * * `'error'` with an error with message `'Error: socket hang up'` and code`'ECONNRESET'` + * * `'error'` with an error with message `'Error: socket hang up'` and code`'ECONNRESET'`, or the error with which `req.destroy()` was called * * `'close'` * * If `req.destroy()` is called before the connection succeeds, the following @@ -1346,7 +1686,7 @@ declare module 'http' { * * * `'socket'` * * (`req.destroy()` called here) - * * `'error'` with an error with message `'Error: socket hang up'` and code`'ECONNRESET'` + * * `'error'` with an error with message `'Error: socket hang up'` and code`'ECONNRESET'`, or the error with which `req.destroy()` was called * * `'close'` * * If `req.destroy()` is called after the response is received, the following @@ -1357,7 +1697,7 @@ declare module 'http' { * * `'data'` any number of times, on the `res` object * * (`req.destroy()` called here) * * `'aborted'` on the `res` object - * * `'error'` on the `res` object with an error with message`'Error: aborted'` and code `'ECONNRESET'`. + * * `'error'` on the `res` object with an error with message `'Error: aborted'`and code `'ECONNRESET'`, or the error with which `req.destroy()` was called * * `'close'` * * `'close'` on the `res` object * @@ -1393,8 +1733,9 @@ declare module 'http' { * Setting the `timeout` option or using the `setTimeout()` function will * not abort the request or do anything besides add a `'timeout'` event. * - * Passing an `AbortSignal` and then calling `abort` on the corresponding`AbortController` will behave the same way as calling `.destroy()` on the - * request itself. + * Passing an `AbortSignal` and then calling `abort()` on the corresponding`AbortController` will behave the same way as calling `.destroy()` on the + * request. Specifically, the `'error'` event will be emitted with an error with + * the message `'AbortError: The operation was aborted'`, the code `'ABORT_ERR'`and the `cause`, if one was provided. * @since v0.3.6 */ function request(options: RequestOptions | string | URL, callback?: (res: IncomingMessage) => void): ClientRequest; @@ -1405,8 +1746,8 @@ declare module 'http' { ): ClientRequest; /** * Since most requests are GET requests without bodies, Node.js provides this - * convenience method. The only difference between this method and {@link request} is that it sets the method to GET and calls `req.end()`automatically. The callback must take care to consume the - * response + * convenience method. The only difference between this method and {@link request} is that it sets the method to GET by default and calls `req.end()`automatically. The callback must take care to + * consume the response * data for reasons stated in {@link ClientRequest} section. * * The `callback` is invoked with a single argument that is an instance of {@link IncomingMessage}. @@ -1454,17 +1795,86 @@ declare module 'http' { * const server = http.createServer((req, res) => { * res.writeHead(200, { 'Content-Type': 'application/json' }); * res.end(JSON.stringify({ - * data: 'Hello World!' + * data: 'Hello World!', * })); * }); * * server.listen(8000); * ``` * @since v0.3.6 - * @param options Accepts the same `options` as {@link request}, with the `method` always set to `GET`. Properties that are inherited from the prototype are ignored. + * @param options Accepts the same `options` as {@link request}, with the method set to GET by default. */ function get(options: RequestOptions | string | URL, callback?: (res: IncomingMessage) => void): ClientRequest; function get(url: string | URL, options: RequestOptions, callback?: (res: IncomingMessage) => void): ClientRequest; + /** + * Performs the low-level validations on the provided `name` that are done when`res.setHeader(name, value)` is called. + * + * Passing illegal value as `name` will result in a `TypeError` being thrown, + * identified by `code: 'ERR_INVALID_HTTP_TOKEN'`. + * + * It is not necessary to use this method before passing headers to an HTTP request + * or response. The HTTP module will automatically validate such headers. + * + * Example: + * + * ```js + * import { validateHeaderName } from 'node:http'; + * + * try { + * validateHeaderName(''); + * } catch (err) { + * console.error(err instanceof TypeError); // --> true + * console.error(err.code); // --> 'ERR_INVALID_HTTP_TOKEN' + * console.error(err.message); // --> 'Header name must be a valid HTTP token [""]' + * } + * ``` + * @since v14.3.0 + * @param [label='Header name'] Label for error message. + */ + function validateHeaderName(name: string): void; + /** + * Performs the low-level validations on the provided `value` that are done when`res.setHeader(name, value)` is called. + * + * Passing illegal value as `value` will result in a `TypeError` being thrown. + * + * * Undefined value error is identified by `code: 'ERR_HTTP_INVALID_HEADER_VALUE'`. + * * Invalid value character error is identified by `code: 'ERR_INVALID_CHAR'`. + * + * It is not necessary to use this method before passing headers to an HTTP request + * or response. The HTTP module will automatically validate such headers. + * + * Examples: + * + * ```js + * import { validateHeaderValue } from 'node:http'; + * + * try { + * validateHeaderValue('x-my-header', undefined); + * } catch (err) { + * console.error(err instanceof TypeError); // --> true + * console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE'); // --> true + * console.error(err.message); // --> 'Invalid value "undefined" for header "x-my-header"' + * } + * + * try { + * validateHeaderValue('x-my-header', 'oʊmɪɡə'); + * } catch (err) { + * console.error(err instanceof TypeError); // --> true + * console.error(err.code === 'ERR_INVALID_CHAR'); // --> true + * console.error(err.message); // --> 'Invalid character in header content ["x-my-header"]' + * } + * ``` + * @since v14.3.0 + * @param name Header name + * @param value Header value + */ + function validateHeaderValue(name: string, value: string): void; + /** + * Set the maximum number of idle HTTP parsers. + * @since v18.8.0, v16.18.0 + * @param [max=1000] + */ + function setMaxIdleHTTPParsers(max: number): void; let globalAgent: Agent; /** * Read-only property specifying the maximum allowed size of HTTP headers in bytes. @@ -1472,6 +1882,6 @@ declare module 'http' { */ const maxHeaderSize: number; } -declare module 'node:http' { - export * from 'http'; +declare module "node:http" { + export * from "http"; } diff --git a/node_modules/@types/node/ts4.8/http2.d.ts b/node_modules/@types/node/ts4.8/http2.d.ts old mode 100755 new mode 100644 index f46a33e..c3b3e8e --- a/node_modules/@types/node/ts4.8/http2.d.ts +++ b/node_modules/@types/node/ts4.8/http2.d.ts @@ -1,30 +1,35 @@ /** - * The `http2` module provides an implementation of the [HTTP/2](https://tools.ietf.org/html/rfc7540) protocol. It - * can be accessed using: + * The `node:http2` module provides an implementation of the [HTTP/2](https://tools.ietf.org/html/rfc7540) protocol. + * It can be accessed using: * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * ``` * @since v8.4.0 - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/http2.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/http2.js) */ -declare module 'http2' { - import EventEmitter = require('node:events'); - import * as fs from 'node:fs'; - import * as net from 'node:net'; - import * as stream from 'node:stream'; - import * as tls from 'node:tls'; - import * as url from 'node:url'; - import { IncomingHttpHeaders as Http1IncomingHttpHeaders, OutgoingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http'; - export { OutgoingHttpHeaders } from 'node:http'; +declare module "http2" { + import EventEmitter = require("node:events"); + import * as fs from "node:fs"; + import * as net from "node:net"; + import * as stream from "node:stream"; + import * as tls from "node:tls"; + import * as url from "node:url"; + import { + IncomingHttpHeaders as Http1IncomingHttpHeaders, + IncomingMessage, + OutgoingHttpHeaders, + ServerResponse, + } from "node:http"; + export { OutgoingHttpHeaders } from "node:http"; export interface IncomingHttpStatusHeader { - ':status'?: number | undefined; + ":status"?: number | undefined; } export interface IncomingHttpHeaders extends Http1IncomingHttpHeaders { - ':path'?: string | undefined; - ':method'?: string | undefined; - ':authority'?: string | undefined; - ':scheme'?: string | undefined; + ":path"?: string | undefined; + ":method"?: string | undefined; + ":authority"?: string | undefined; + ":scheme"?: string | undefined; } // Http2Stream export interface StreamPriorityOptions { @@ -50,6 +55,7 @@ declare module 'http2' { length: number; } export interface ServerStreamFileResponseOptions { + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type statCheck?(stats: fs.Stats, headers: OutgoingHttpHeaders, statOptions: StatOptions): void | boolean; waitForTrailers?: boolean | undefined; offset?: number | undefined; @@ -83,7 +89,7 @@ declare module 'http2' { */ readonly destroyed: boolean; /** - * Set the `true` if the `END_STREAM` flag was set in the request or response + * Set to `true` if the `END_STREAM` flag was set in the request or response * HEADERS frame received, indicating that no additional data should be received * and the readable side of the `Http2Stream` will be closed. * @since v10.11.0 @@ -128,7 +134,7 @@ declare module 'http2' { * value will be `undefined` after the `Http2Stream` instance is destroyed. * @since v8.4.0 */ - readonly session: Http2Session; + readonly session: Http2Session | undefined; /** * Provides miscellaneous information about the current state of the`Http2Stream`. * @@ -151,7 +157,7 @@ declare module 'http2' { priority(options: StreamPriorityOptions): void; /** * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const client = http2.connect('http://example.org:8000'); * const { NGHTTP2_CANCEL } = http2.constants; * const req = client.request({ ':path': '/' }); @@ -171,7 +177,7 @@ declare module 'http2' { * trailers can be sent. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * stream.respond(undefined, { waitForTrailers: true }); @@ -187,127 +193,157 @@ declare module 'http2' { * @since v10.0.0 */ sendTrailers(headers: OutgoingHttpHeaders): void; - addListener(event: 'aborted', listener: () => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'end', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'finish', listener: () => void): this; - addListener(event: 'frameError', listener: (frameType: number, errorCode: number) => void): this; - addListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - addListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; - addListener(event: 'streamClosed', listener: (code: number) => void): this; - addListener(event: 'timeout', listener: () => void): this; - addListener(event: 'trailers', listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; - addListener(event: 'wantTrailers', listener: () => void): this; + addListener(event: "aborted", listener: () => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: Buffer | string) => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "frameError", listener: (frameType: number, errorCode: number) => void): this; + addListener(event: "pipe", listener: (src: stream.Readable) => void): this; + addListener(event: "unpipe", listener: (src: stream.Readable) => void): this; + addListener(event: "streamClosed", listener: (code: number) => void): this; + addListener(event: "timeout", listener: () => void): this; + addListener(event: "trailers", listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; + addListener(event: "wantTrailers", listener: () => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'aborted'): boolean; - emit(event: 'close'): boolean; - emit(event: 'data', chunk: Buffer | string): boolean; - emit(event: 'drain'): boolean; - emit(event: 'end'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'finish'): boolean; - emit(event: 'frameError', frameType: number, errorCode: number): boolean; - emit(event: 'pipe', src: stream.Readable): boolean; - emit(event: 'unpipe', src: stream.Readable): boolean; - emit(event: 'streamClosed', code: number): boolean; - emit(event: 'timeout'): boolean; - emit(event: 'trailers', trailers: IncomingHttpHeaders, flags: number): boolean; - emit(event: 'wantTrailers'): boolean; + emit(event: "aborted"): boolean; + emit(event: "close"): boolean; + emit(event: "data", chunk: Buffer | string): boolean; + emit(event: "drain"): boolean; + emit(event: "end"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "finish"): boolean; + emit(event: "frameError", frameType: number, errorCode: number): boolean; + emit(event: "pipe", src: stream.Readable): boolean; + emit(event: "unpipe", src: stream.Readable): boolean; + emit(event: "streamClosed", code: number): boolean; + emit(event: "timeout"): boolean; + emit(event: "trailers", trailers: IncomingHttpHeaders, flags: number): boolean; + emit(event: "wantTrailers"): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'aborted', listener: () => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'data', listener: (chunk: Buffer | string) => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'end', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'finish', listener: () => void): this; - on(event: 'frameError', listener: (frameType: number, errorCode: number) => void): this; - on(event: 'pipe', listener: (src: stream.Readable) => void): this; - on(event: 'unpipe', listener: (src: stream.Readable) => void): this; - on(event: 'streamClosed', listener: (code: number) => void): this; - on(event: 'timeout', listener: () => void): this; - on(event: 'trailers', listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; - on(event: 'wantTrailers', listener: () => void): this; + on(event: "aborted", listener: () => void): this; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: Buffer | string) => void): this; + on(event: "drain", listener: () => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "frameError", listener: (frameType: number, errorCode: number) => void): this; + on(event: "pipe", listener: (src: stream.Readable) => void): this; + on(event: "unpipe", listener: (src: stream.Readable) => void): this; + on(event: "streamClosed", listener: (code: number) => void): this; + on(event: "timeout", listener: () => void): this; + on(event: "trailers", listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; + on(event: "wantTrailers", listener: () => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'aborted', listener: () => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'data', listener: (chunk: Buffer | string) => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'end', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'finish', listener: () => void): this; - once(event: 'frameError', listener: (frameType: number, errorCode: number) => void): this; - once(event: 'pipe', listener: (src: stream.Readable) => void): this; - once(event: 'unpipe', listener: (src: stream.Readable) => void): this; - once(event: 'streamClosed', listener: (code: number) => void): this; - once(event: 'timeout', listener: () => void): this; - once(event: 'trailers', listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; - once(event: 'wantTrailers', listener: () => void): this; + once(event: "aborted", listener: () => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: Buffer | string) => void): this; + once(event: "drain", listener: () => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "frameError", listener: (frameType: number, errorCode: number) => void): this; + once(event: "pipe", listener: (src: stream.Readable) => void): this; + once(event: "unpipe", listener: (src: stream.Readable) => void): this; + once(event: "streamClosed", listener: (code: number) => void): this; + once(event: "timeout", listener: () => void): this; + once(event: "trailers", listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; + once(event: "wantTrailers", listener: () => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'aborted', listener: () => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'end', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'finish', listener: () => void): this; - prependListener(event: 'frameError', listener: (frameType: number, errorCode: number) => void): this; - prependListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; - prependListener(event: 'streamClosed', listener: (code: number) => void): this; - prependListener(event: 'timeout', listener: () => void): this; - prependListener(event: 'trailers', listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; - prependListener(event: 'wantTrailers', listener: () => void): this; + prependListener(event: "aborted", listener: () => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "frameError", listener: (frameType: number, errorCode: number) => void): this; + prependListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependListener(event: "unpipe", listener: (src: stream.Readable) => void): this; + prependListener(event: "streamClosed", listener: (code: number) => void): this; + prependListener(event: "timeout", listener: () => void): this; + prependListener(event: "trailers", listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; + prependListener(event: "wantTrailers", listener: () => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'aborted', listener: () => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'end', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'finish', listener: () => void): this; - prependOnceListener(event: 'frameError', listener: (frameType: number, errorCode: number) => void): this; - prependOnceListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependOnceListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; - prependOnceListener(event: 'streamClosed', listener: (code: number) => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; - prependOnceListener(event: 'trailers', listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; - prependOnceListener(event: 'wantTrailers', listener: () => void): this; + prependOnceListener(event: "aborted", listener: () => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "frameError", listener: (frameType: number, errorCode: number) => void): this; + prependOnceListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "unpipe", listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "streamClosed", listener: (code: number) => void): this; + prependOnceListener(event: "timeout", listener: () => void): this; + prependOnceListener(event: "trailers", listener: (trailers: IncomingHttpHeaders, flags: number) => void): this; + prependOnceListener(event: "wantTrailers", listener: () => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export interface ClientHttp2Stream extends Http2Stream { - addListener(event: 'continue', listener: () => {}): this; - addListener(event: 'headers', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; - addListener(event: 'push', listener: (headers: IncomingHttpHeaders, flags: number) => void): this; - addListener(event: 'response', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + addListener(event: "continue", listener: () => {}): this; + addListener( + event: "headers", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; + addListener(event: "push", listener: (headers: IncomingHttpHeaders, flags: number) => void): this; + addListener( + event: "response", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'continue'): boolean; - emit(event: 'headers', headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number): boolean; - emit(event: 'push', headers: IncomingHttpHeaders, flags: number): boolean; - emit(event: 'response', headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number): boolean; + emit(event: "continue"): boolean; + emit(event: "headers", headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number): boolean; + emit(event: "push", headers: IncomingHttpHeaders, flags: number): boolean; + emit(event: "response", headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'continue', listener: () => {}): this; - on(event: 'headers', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; - on(event: 'push', listener: (headers: IncomingHttpHeaders, flags: number) => void): this; - on(event: 'response', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + on(event: "continue", listener: () => {}): this; + on( + event: "headers", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; + on(event: "push", listener: (headers: IncomingHttpHeaders, flags: number) => void): this; + on( + event: "response", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'continue', listener: () => {}): this; - once(event: 'headers', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; - once(event: 'push', listener: (headers: IncomingHttpHeaders, flags: number) => void): this; - once(event: 'response', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + once(event: "continue", listener: () => {}): this; + once( + event: "headers", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; + once(event: "push", listener: (headers: IncomingHttpHeaders, flags: number) => void): this; + once( + event: "response", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'continue', listener: () => {}): this; - prependListener(event: 'headers', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; - prependListener(event: 'push', listener: (headers: IncomingHttpHeaders, flags: number) => void): this; - prependListener(event: 'response', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + prependListener(event: "continue", listener: () => {}): this; + prependListener( + event: "headers", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; + prependListener(event: "push", listener: (headers: IncomingHttpHeaders, flags: number) => void): this; + prependListener( + event: "response", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'continue', listener: () => {}): this; - prependOnceListener(event: 'headers', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; - prependOnceListener(event: 'push', listener: (headers: IncomingHttpHeaders, flags: number) => void): this; - prependOnceListener(event: 'response', listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + prependOnceListener(event: "continue", listener: () => {}): this; + prependOnceListener( + event: "headers", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; + prependOnceListener(event: "push", listener: (headers: IncomingHttpHeaders, flags: number) => void): this; + prependOnceListener( + event: "response", + listener: (headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void, + ): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export interface ServerHttp2Stream extends Http2Stream { @@ -332,7 +368,7 @@ declare module 'http2' { * Initiates a push stream. The callback is invoked with the new `Http2Stream`instance created for the push stream passed as the second argument, or an`Error` passed as the first argument. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * stream.respond({ ':status': 200 }); @@ -353,11 +389,18 @@ declare module 'http2' { * @since v8.4.0 * @param callback Callback that is called once the push stream has been initiated. */ - pushStream(headers: OutgoingHttpHeaders, callback?: (err: Error | null, pushStream: ServerHttp2Stream, headers: OutgoingHttpHeaders) => void): void; - pushStream(headers: OutgoingHttpHeaders, options?: StreamPriorityOptions, callback?: (err: Error | null, pushStream: ServerHttp2Stream, headers: OutgoingHttpHeaders) => void): void; + pushStream( + headers: OutgoingHttpHeaders, + callback?: (err: Error | null, pushStream: ServerHttp2Stream, headers: OutgoingHttpHeaders) => void, + ): void; + pushStream( + headers: OutgoingHttpHeaders, + options?: StreamPriorityOptions, + callback?: (err: Error | null, pushStream: ServerHttp2Stream, headers: OutgoingHttpHeaders) => void, + ): void; /** * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * stream.respond({ ':status': 200 }); @@ -365,16 +408,15 @@ declare module 'http2' { * }); * ``` * - * When the `options.waitForTrailers` option is set, the `'wantTrailers'` event - * will be emitted immediately after queuing the last chunk of payload data to be - * sent. The `http2stream.sendTrailers()` method can then be used to sent trailing - * header fields to the peer. + * Initiates a response. When the `options.waitForTrailers` option is set, the`'wantTrailers'` event will be emitted immediately after queuing the last chunk + * of payload data to be sent. The `http2stream.sendTrailers()` method can then be + * used to sent trailing header fields to the peer. * * When `options.waitForTrailers` is set, the `Http2Stream` will not automatically * close when the final `DATA` frame is transmitted. User code must call either`http2stream.sendTrailers()` or `http2stream.close()` to close the`Http2Stream`. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * stream.respond({ ':status': 200 }, { waitForTrailers: true }); @@ -397,8 +439,8 @@ declare module 'http2' { * automatically. * * ```js - * const http2 = require('http2'); - * const fs = require('fs'); + * const http2 = require('node:http2'); + * const fs = require('node:fs'); * * const server = http2.createServer(); * server.on('stream', (stream) => { @@ -408,7 +450,7 @@ declare module 'http2' { * const headers = { * 'content-length': stat.size, * 'last-modified': stat.mtime.toUTCString(), - * 'content-type': 'text/plain; charset=utf-8' + * 'content-type': 'text/plain; charset=utf-8', * }; * stream.respondWithFD(fd, headers); * stream.on('close', () => fs.closeSync(fd)); @@ -439,8 +481,8 @@ declare module 'http2' { * close when the final `DATA` frame is transmitted. User code _must_ call either`http2stream.sendTrailers()` or `http2stream.close()` to close the`Http2Stream`. * * ```js - * const http2 = require('http2'); - * const fs = require('fs'); + * const http2 = require('node:http2'); + * const fs = require('node:fs'); * * const server = http2.createServer(); * server.on('stream', (stream) => { @@ -450,7 +492,7 @@ declare module 'http2' { * const headers = { * 'content-length': stat.size, * 'last-modified': stat.mtime.toUTCString(), - * 'content-type': 'text/plain; charset=utf-8' + * 'content-type': 'text/plain; charset=utf-8', * }; * stream.respondWithFD(fd, headers, { waitForTrailers: true }); * stream.on('wantTrailers', () => { @@ -463,7 +505,11 @@ declare module 'http2' { * @since v8.4.0 * @param fd A readable file descriptor. */ - respondWithFD(fd: number | fs.promises.FileHandle, headers?: OutgoingHttpHeaders, options?: ServerStreamFileResponseOptions): void; + respondWithFD( + fd: number | fs.promises.FileHandle, + headers?: OutgoingHttpHeaders, + options?: ServerStreamFileResponseOptions, + ): void; /** * Sends a regular file as the response. The `path` must specify a regular file * or an `'error'` event will be emitted on the `Http2Stream` object. @@ -482,7 +528,7 @@ declare module 'http2' { * Example using a file path: * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * function statCheck(stat, headers) { @@ -500,7 +546,7 @@ declare module 'http2' { * } * } catch (err) { * // Perform actual error handling. - * console.log(err); + * console.error(err); * } * stream.end(); * } @@ -516,7 +562,7 @@ declare module 'http2' { * results to determine if the file has been modified to return an appropriate`304` response: * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * function statCheck(stat, headers) { @@ -549,7 +595,7 @@ declare module 'http2' { * close when the final `DATA` frame is transmitted. User code must call either`http2stream.sendTrailers()` or `http2stream.close()` to close the`Http2Stream`. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer(); * server.on('stream', (stream) => { * stream.respondWithFile('/some/file', @@ -562,7 +608,11 @@ declare module 'http2' { * ``` * @since v8.4.0 */ - respondWithFile(path: string, headers?: OutgoingHttpHeaders, options?: ServerStreamFileResponseOptionsWithError): void; + respondWithFile( + path: string, + headers?: OutgoingHttpHeaders, + options?: ServerStreamFileResponseOptionsWithError, + ): void; } // Http2Session export interface Settings { @@ -736,7 +786,10 @@ declare module 'http2' { * @param payload Optional ping payload. */ ping(callback: (err: Error | null, duration: number, payload: Buffer) => void): boolean; - ping(payload: NodeJS.ArrayBufferView, callback: (err: Error | null, duration: number, payload: Buffer) => void): boolean; + ping( + payload: NodeJS.ArrayBufferView, + callback: (err: Error | null, duration: number, payload: Buffer) => void, + ): boolean; /** * Calls `ref()` on this `Http2Session`instance's underlying `net.Socket`. * @since v9.4.0 @@ -748,7 +801,7 @@ declare module 'http2' { * the delta. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * * const server = http2.createServer(); * const expectedWindowSize = 2 ** 20; @@ -758,7 +811,7 @@ declare module 'http2' { * session.setLocalWindowSize(expectedWindowSize); * }); * ``` - * @since v15.3.0 + * @since v15.3.0, v14.18.0 */ setLocalWindowSize(windowSize: number): void; /** @@ -780,65 +833,86 @@ declare module 'http2' { * @since v8.4.0 * @param callback Callback that is called once the session is connected or right away if the session is already connected. */ - settings(settings: Settings, callback?: (err: Error | null, settings: Settings, duration: number) => void): void; + settings( + settings: Settings, + callback?: (err: Error | null, settings: Settings, duration: number) => void, + ): void; /** * Calls `unref()` on this `Http2Session`instance's underlying `net.Socket`. * @since v9.4.0 */ unref(): void; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'frameError', listener: (frameType: number, errorCode: number, streamID: number) => void): this; - addListener(event: 'goaway', listener: (errorCode: number, lastStreamID: number, opaqueData: Buffer) => void): this; - addListener(event: 'localSettings', listener: (settings: Settings) => void): this; - addListener(event: 'ping', listener: () => void): this; - addListener(event: 'remoteSettings', listener: (settings: Settings) => void): this; - addListener(event: 'timeout', listener: () => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener( + event: "frameError", + listener: (frameType: number, errorCode: number, streamID: number) => void, + ): this; + addListener( + event: "goaway", + listener: (errorCode: number, lastStreamID: number, opaqueData?: Buffer) => void, + ): this; + addListener(event: "localSettings", listener: (settings: Settings) => void): this; + addListener(event: "ping", listener: () => void): this; + addListener(event: "remoteSettings", listener: (settings: Settings) => void): this; + addListener(event: "timeout", listener: () => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'close'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'frameError', frameType: number, errorCode: number, streamID: number): boolean; - emit(event: 'goaway', errorCode: number, lastStreamID: number, opaqueData: Buffer): boolean; - emit(event: 'localSettings', settings: Settings): boolean; - emit(event: 'ping'): boolean; - emit(event: 'remoteSettings', settings: Settings): boolean; - emit(event: 'timeout'): boolean; + emit(event: "close"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "frameError", frameType: number, errorCode: number, streamID: number): boolean; + emit(event: "goaway", errorCode: number, lastStreamID: number, opaqueData?: Buffer): boolean; + emit(event: "localSettings", settings: Settings): boolean; + emit(event: "ping"): boolean; + emit(event: "remoteSettings", settings: Settings): boolean; + emit(event: "timeout"): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'close', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'frameError', listener: (frameType: number, errorCode: number, streamID: number) => void): this; - on(event: 'goaway', listener: (errorCode: number, lastStreamID: number, opaqueData: Buffer) => void): this; - on(event: 'localSettings', listener: (settings: Settings) => void): this; - on(event: 'ping', listener: () => void): this; - on(event: 'remoteSettings', listener: (settings: Settings) => void): this; - on(event: 'timeout', listener: () => void): this; + on(event: "close", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "frameError", listener: (frameType: number, errorCode: number, streamID: number) => void): this; + on(event: "goaway", listener: (errorCode: number, lastStreamID: number, opaqueData?: Buffer) => void): this; + on(event: "localSettings", listener: (settings: Settings) => void): this; + on(event: "ping", listener: () => void): this; + on(event: "remoteSettings", listener: (settings: Settings) => void): this; + on(event: "timeout", listener: () => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'frameError', listener: (frameType: number, errorCode: number, streamID: number) => void): this; - once(event: 'goaway', listener: (errorCode: number, lastStreamID: number, opaqueData: Buffer) => void): this; - once(event: 'localSettings', listener: (settings: Settings) => void): this; - once(event: 'ping', listener: () => void): this; - once(event: 'remoteSettings', listener: (settings: Settings) => void): this; - once(event: 'timeout', listener: () => void): this; + once(event: "close", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "frameError", listener: (frameType: number, errorCode: number, streamID: number) => void): this; + once(event: "goaway", listener: (errorCode: number, lastStreamID: number, opaqueData?: Buffer) => void): this; + once(event: "localSettings", listener: (settings: Settings) => void): this; + once(event: "ping", listener: () => void): this; + once(event: "remoteSettings", listener: (settings: Settings) => void): this; + once(event: "timeout", listener: () => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'frameError', listener: (frameType: number, errorCode: number, streamID: number) => void): this; - prependListener(event: 'goaway', listener: (errorCode: number, lastStreamID: number, opaqueData: Buffer) => void): this; - prependListener(event: 'localSettings', listener: (settings: Settings) => void): this; - prependListener(event: 'ping', listener: () => void): this; - prependListener(event: 'remoteSettings', listener: (settings: Settings) => void): this; - prependListener(event: 'timeout', listener: () => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener( + event: "frameError", + listener: (frameType: number, errorCode: number, streamID: number) => void, + ): this; + prependListener( + event: "goaway", + listener: (errorCode: number, lastStreamID: number, opaqueData?: Buffer) => void, + ): this; + prependListener(event: "localSettings", listener: (settings: Settings) => void): this; + prependListener(event: "ping", listener: () => void): this; + prependListener(event: "remoteSettings", listener: (settings: Settings) => void): this; + prependListener(event: "timeout", listener: () => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'frameError', listener: (frameType: number, errorCode: number, streamID: number) => void): this; - prependOnceListener(event: 'goaway', listener: (errorCode: number, lastStreamID: number, opaqueData: Buffer) => void): this; - prependOnceListener(event: 'localSettings', listener: (settings: Settings) => void): this; - prependOnceListener(event: 'ping', listener: () => void): this; - prependOnceListener(event: 'remoteSettings', listener: (settings: Settings) => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener( + event: "frameError", + listener: (frameType: number, errorCode: number, streamID: number) => void, + ): this; + prependOnceListener( + event: "goaway", + listener: (errorCode: number, lastStreamID: number, opaqueData?: Buffer) => void, + ): this; + prependOnceListener(event: "localSettings", listener: (settings: Settings) => void): this; + prependOnceListener(event: "ping", listener: () => void): this; + prependOnceListener(event: "remoteSettings", listener: (settings: Settings) => void): this; + prependOnceListener(event: "timeout", listener: () => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export interface ClientHttp2Session extends Http2Session { @@ -846,14 +920,19 @@ declare module 'http2' { * For HTTP/2 Client `Http2Session` instances only, the `http2session.request()`creates and returns an `Http2Stream` instance that can be used to send an * HTTP/2 request to the connected server. * + * When a `ClientHttp2Session` is first created, the socket may not yet be + * connected. if `clienthttp2session.request()` is called during this time, the + * actual request will be deferred until the socket is ready to go. + * If the `session` is closed before the actual request be executed, an`ERR_HTTP2_GOAWAY_SESSION` is thrown. + * * This method is only available if `http2session.type` is equal to`http2.constants.NGHTTP2_SESSION_CLIENT`. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const clientSession = http2.connect('https://localhost:1234'); * const { * HTTP2_HEADER_PATH, - * HTTP2_HEADER_STATUS + * HTTP2_HEADER_STATUS, * } = http2.constants; * * const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' }); @@ -883,35 +962,87 @@ declare module 'http2' { * @since v8.4.0 */ request(headers?: OutgoingHttpHeaders, options?: ClientSessionRequestOptions): ClientHttp2Stream; - addListener(event: 'altsvc', listener: (alt: string, origin: string, stream: number) => void): this; - addListener(event: 'origin', listener: (origins: string[]) => void): this; - addListener(event: 'connect', listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - addListener(event: 'stream', listener: (stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + addListener(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; + addListener(event: "origin", listener: (origins: string[]) => void): this; + addListener( + event: "connect", + listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + addListener( + event: "stream", + listener: ( + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ) => void, + ): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'altsvc', alt: string, origin: string, stream: number): boolean; - emit(event: 'origin', origins: ReadonlyArray): boolean; - emit(event: 'connect', session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket): boolean; - emit(event: 'stream', stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number): boolean; + emit(event: "altsvc", alt: string, origin: string, stream: number): boolean; + emit(event: "origin", origins: readonly string[]): boolean; + emit(event: "connect", session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket): boolean; + emit( + event: "stream", + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'altsvc', listener: (alt: string, origin: string, stream: number) => void): this; - on(event: 'origin', listener: (origins: string[]) => void): this; - on(event: 'connect', listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - on(event: 'stream', listener: (stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + on(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; + on(event: "origin", listener: (origins: string[]) => void): this; + on(event: "connect", listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; + on( + event: "stream", + listener: ( + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ) => void, + ): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'altsvc', listener: (alt: string, origin: string, stream: number) => void): this; - once(event: 'origin', listener: (origins: string[]) => void): this; - once(event: 'connect', listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - once(event: 'stream', listener: (stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + once(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; + once(event: "origin", listener: (origins: string[]) => void): this; + once( + event: "connect", + listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + once( + event: "stream", + listener: ( + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ) => void, + ): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'altsvc', listener: (alt: string, origin: string, stream: number) => void): this; - prependListener(event: 'origin', listener: (origins: string[]) => void): this; - prependListener(event: 'connect', listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - prependListener(event: 'stream', listener: (stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + prependListener(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; + prependListener(event: "origin", listener: (origins: string[]) => void): this; + prependListener( + event: "connect", + listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + prependListener( + event: "stream", + listener: ( + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ) => void, + ): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'altsvc', listener: (alt: string, origin: string, stream: number) => void): this; - prependOnceListener(event: 'origin', listener: (origins: string[]) => void): this; - prependOnceListener(event: 'connect', listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - prependOnceListener(event: 'stream', listener: (stream: ClientHttp2Stream, headers: IncomingHttpHeaders & IncomingHttpStatusHeader, flags: number) => void): this; + prependOnceListener(event: "altsvc", listener: (alt: string, origin: string, stream: number) => void): this; + prependOnceListener(event: "origin", listener: (origins: string[]) => void): this; + prependOnceListener( + event: "connect", + listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + prependOnceListener( + event: "stream", + listener: ( + stream: ClientHttp2Stream, + headers: IncomingHttpHeaders & IncomingHttpStatusHeader, + flags: number, + ) => void, + ): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export interface AlternativeServiceOptions { @@ -923,7 +1054,7 @@ declare module 'http2' { * Submits an `ALTSVC` frame (as defined by [RFC 7838](https://tools.ietf.org/html/rfc7838)) to the connected client. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * * const server = http2.createServer(); * server.on('session', (session) => { @@ -964,7 +1095,7 @@ declare module 'http2' { * authoritative responses. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const options = getSecureOptionsSomehow(); * const server = http2.createSecureServer(options); * server.on('stream', (stream) => { @@ -990,7 +1121,7 @@ declare module 'http2' { * server using the `http2.createSecureServer()` method: * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const options = getSecureOptionsSomehow(); * options.origins = ['https://example.com', 'https://example.org']; * const server = http2.createSecureServer(options); @@ -1007,27 +1138,54 @@ declare module 'http2' { | string | url.URL | { - origin: string; - } + origin: string; + } > ): void; - addListener(event: 'connect', listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - addListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; + addListener( + event: "connect", + listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + addListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'connect', session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket): boolean; - emit(event: 'stream', stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; + emit(event: "connect", session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket): boolean; + emit(event: "stream", stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'connect', listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - on(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; + on(event: "connect", listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; + on( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'connect', listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - once(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; + once( + event: "connect", + listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + once( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'connect', listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - prependListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; + prependListener( + event: "connect", + listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + prependListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'connect', listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void): this; - prependOnceListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; + prependOnceListener( + event: "connect", + listener: (session: ServerHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): this; + prependOnceListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } // Http2Server @@ -1048,12 +1206,11 @@ declare module 'http2' { */ unknownProtocolTimeout?: number | undefined; selectPadding?(frameLen: number, maxFrameLen: number): number; - createConnection?(authority: url.URL, option: SessionOptions): stream.Duplex; } export interface ClientSessionOptions extends SessionOptions { maxReservedRemoteStreams?: number | undefined; createConnection?: ((authority: url.URL, option: SessionOptions) => stream.Duplex) | undefined; - protocol?: 'http:' | 'https:' | undefined; + protocol?: "http:" | "https:" | undefined; } export interface ServerSessionOptions extends SessionOptions { Http1IncomingMessage?: typeof IncomingMessage | undefined; @@ -1077,97 +1234,175 @@ declare module 'http2' { updateSettings(settings: Settings): void; } export interface Http2Server extends net.Server, HTTP2ServerCommon { - addListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - addListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - addListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - addListener(event: 'sessionError', listener: (err: Error) => void): this; - addListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - addListener(event: 'timeout', listener: () => void): this; + addListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + addListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + addListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + addListener(event: "sessionError", listener: (err: Error) => void): this; + addListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + addListener(event: "timeout", listener: () => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'checkContinue', request: Http2ServerRequest, response: Http2ServerResponse): boolean; - emit(event: 'request', request: Http2ServerRequest, response: Http2ServerResponse): boolean; - emit(event: 'session', session: ServerHttp2Session): boolean; - emit(event: 'sessionError', err: Error): boolean; - emit(event: 'stream', stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; - emit(event: 'timeout'): boolean; + emit(event: "checkContinue", request: Http2ServerRequest, response: Http2ServerResponse): boolean; + emit(event: "request", request: Http2ServerRequest, response: Http2ServerResponse): boolean; + emit(event: "session", session: ServerHttp2Session): boolean; + emit(event: "sessionError", err: Error): boolean; + emit(event: "stream", stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; + emit(event: "timeout"): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - on(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - on(event: 'session', listener: (session: ServerHttp2Session) => void): this; - on(event: 'sessionError', listener: (err: Error) => void): this; - on(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - on(event: 'timeout', listener: () => void): this; + on( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + on(event: "request", listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; + on(event: "session", listener: (session: ServerHttp2Session) => void): this; + on(event: "sessionError", listener: (err: Error) => void): this; + on( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + on(event: "timeout", listener: () => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - once(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - once(event: 'session', listener: (session: ServerHttp2Session) => void): this; - once(event: 'sessionError', listener: (err: Error) => void): this; - once(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - once(event: 'timeout', listener: () => void): this; + once( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + once(event: "request", listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; + once(event: "session", listener: (session: ServerHttp2Session) => void): this; + once(event: "sessionError", listener: (err: Error) => void): this; + once( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + once(event: "timeout", listener: () => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - prependListener(event: 'sessionError', listener: (err: Error) => void): this; - prependListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - prependListener(event: 'timeout', listener: () => void): this; + prependListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + prependListener(event: "sessionError", listener: (err: Error) => void): this; + prependListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + prependListener(event: "timeout", listener: () => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependOnceListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependOnceListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - prependOnceListener(event: 'sessionError', listener: (err: Error) => void): this; - prependOnceListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; + prependOnceListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependOnceListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependOnceListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + prependOnceListener(event: "sessionError", listener: (err: Error) => void): this; + prependOnceListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + prependOnceListener(event: "timeout", listener: () => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export interface Http2SecureServer extends tls.Server, HTTP2ServerCommon { - addListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - addListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - addListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - addListener(event: 'sessionError', listener: (err: Error) => void): this; - addListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - addListener(event: 'timeout', listener: () => void): this; - addListener(event: 'unknownProtocol', listener: (socket: tls.TLSSocket) => void): this; + addListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + addListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + addListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + addListener(event: "sessionError", listener: (err: Error) => void): this; + addListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + addListener(event: "timeout", listener: () => void): this; + addListener(event: "unknownProtocol", listener: (socket: tls.TLSSocket) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'checkContinue', request: Http2ServerRequest, response: Http2ServerResponse): boolean; - emit(event: 'request', request: Http2ServerRequest, response: Http2ServerResponse): boolean; - emit(event: 'session', session: ServerHttp2Session): boolean; - emit(event: 'sessionError', err: Error): boolean; - emit(event: 'stream', stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; - emit(event: 'timeout'): boolean; - emit(event: 'unknownProtocol', socket: tls.TLSSocket): boolean; + emit(event: "checkContinue", request: Http2ServerRequest, response: Http2ServerResponse): boolean; + emit(event: "request", request: Http2ServerRequest, response: Http2ServerResponse): boolean; + emit(event: "session", session: ServerHttp2Session): boolean; + emit(event: "sessionError", err: Error): boolean; + emit(event: "stream", stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number): boolean; + emit(event: "timeout"): boolean; + emit(event: "unknownProtocol", socket: tls.TLSSocket): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - on(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - on(event: 'session', listener: (session: ServerHttp2Session) => void): this; - on(event: 'sessionError', listener: (err: Error) => void): this; - on(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - on(event: 'timeout', listener: () => void): this; - on(event: 'unknownProtocol', listener: (socket: tls.TLSSocket) => void): this; + on( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + on(event: "request", listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; + on(event: "session", listener: (session: ServerHttp2Session) => void): this; + on(event: "sessionError", listener: (err: Error) => void): this; + on( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + on(event: "timeout", listener: () => void): this; + on(event: "unknownProtocol", listener: (socket: tls.TLSSocket) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - once(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - once(event: 'session', listener: (session: ServerHttp2Session) => void): this; - once(event: 'sessionError', listener: (err: Error) => void): this; - once(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - once(event: 'timeout', listener: () => void): this; - once(event: 'unknownProtocol', listener: (socket: tls.TLSSocket) => void): this; + once( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + once(event: "request", listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; + once(event: "session", listener: (session: ServerHttp2Session) => void): this; + once(event: "sessionError", listener: (err: Error) => void): this; + once( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + once(event: "timeout", listener: () => void): this; + once(event: "unknownProtocol", listener: (socket: tls.TLSSocket) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - prependListener(event: 'sessionError', listener: (err: Error) => void): this; - prependListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - prependListener(event: 'timeout', listener: () => void): this; - prependListener(event: 'unknownProtocol', listener: (socket: tls.TLSSocket) => void): this; + prependListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + prependListener(event: "sessionError", listener: (err: Error) => void): this; + prependListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + prependListener(event: "timeout", listener: () => void): this; + prependListener(event: "unknownProtocol", listener: (socket: tls.TLSSocket) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'checkContinue', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependOnceListener(event: 'request', listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void): this; - prependOnceListener(event: 'session', listener: (session: ServerHttp2Session) => void): this; - prependOnceListener(event: 'sessionError', listener: (err: Error) => void): this; - prependOnceListener(event: 'stream', listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; - prependOnceListener(event: 'unknownProtocol', listener: (socket: tls.TLSSocket) => void): this; + prependOnceListener( + event: "checkContinue", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependOnceListener( + event: "request", + listener: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): this; + prependOnceListener(event: "session", listener: (session: ServerHttp2Session) => void): this; + prependOnceListener(event: "sessionError", listener: (err: Error) => void): this; + prependOnceListener( + event: "stream", + listener: (stream: ServerHttp2Stream, headers: IncomingHttpHeaders, flags: number) => void, + ): this; + prependOnceListener(event: "timeout", listener: () => void): this; + prependOnceListener(event: "unknownProtocol", listener: (socket: tls.TLSSocket) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } /** @@ -1177,7 +1412,12 @@ declare module 'http2' { * @since v8.4.0 */ export class Http2ServerRequest extends stream.Readable { - constructor(stream: ServerHttp2Stream, headers: IncomingHttpHeaders, options: stream.ReadableOptions, rawHeaders: ReadonlyArray); + constructor( + stream: ServerHttp2Stream, + headers: IncomingHttpHeaders, + options: stream.ReadableOptions, + rawHeaders: readonly string[], + ); /** * The `request.aborted` property will be `true` if the request has * been aborted. @@ -1363,47 +1603,47 @@ declare module 'http2' { */ setTimeout(msecs: number, callback?: () => void): void; read(size?: number): Buffer | string | null; - addListener(event: 'aborted', listener: (hadError: boolean, code: number) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - addListener(event: 'end', listener: () => void): this; - addListener(event: 'readable', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; + addListener(event: "aborted", listener: (hadError: boolean, code: number) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: Buffer | string) => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "readable", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'aborted', hadError: boolean, code: number): boolean; - emit(event: 'close'): boolean; - emit(event: 'data', chunk: Buffer | string): boolean; - emit(event: 'end'): boolean; - emit(event: 'readable'): boolean; - emit(event: 'error', err: Error): boolean; + emit(event: "aborted", hadError: boolean, code: number): boolean; + emit(event: "close"): boolean; + emit(event: "data", chunk: Buffer | string): boolean; + emit(event: "end"): boolean; + emit(event: "readable"): boolean; + emit(event: "error", err: Error): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'aborted', listener: (hadError: boolean, code: number) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'data', listener: (chunk: Buffer | string) => void): this; - on(event: 'end', listener: () => void): this; - on(event: 'readable', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; + on(event: "aborted", listener: (hadError: boolean, code: number) => void): this; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: Buffer | string) => void): this; + on(event: "end", listener: () => void): this; + on(event: "readable", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'aborted', listener: (hadError: boolean, code: number) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'data', listener: (chunk: Buffer | string) => void): this; - once(event: 'end', listener: () => void): this; - once(event: 'readable', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; + once(event: "aborted", listener: (hadError: boolean, code: number) => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: Buffer | string) => void): this; + once(event: "end", listener: () => void): this; + once(event: "readable", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'aborted', listener: (hadError: boolean, code: number) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependListener(event: 'end', listener: () => void): this; - prependListener(event: 'readable', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; + prependListener(event: "aborted", listener: (hadError: boolean, code: number) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "readable", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'aborted', listener: (hadError: boolean, code: number) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'data', listener: (chunk: Buffer | string) => void): this; - prependOnceListener(event: 'end', listener: () => void): this; - prependOnceListener(event: 'readable', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; + prependOnceListener(event: "aborted", listener: (hadError: boolean, code: number) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: Buffer | string) => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "readable", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } /** @@ -1432,7 +1672,7 @@ declare module 'http2' { */ readonly headersSent: boolean; /** - * A reference to the original HTTP2 request object. + * A reference to the original HTTP2 `request` object. * @since v15.7.0 */ readonly req: Http2ServerRequest; @@ -1453,7 +1693,7 @@ declare module 'http2' { * All other interactions will be routed directly to the socket. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const server = http2.createServer((req, res) => { * const ip = req.socket.remoteAddress; * const port = req.socket.remotePort; @@ -1496,7 +1736,7 @@ declare module 'http2' { * an empty string. * @since v8.4.0 */ - statusMessage: ''; + statusMessage: ""; /** * This method adds HTTP trailing headers (a header but at the end of the * message) to the response. @@ -1617,7 +1857,7 @@ declare module 'http2' { * ``` * @since v8.4.0 */ - setHeader(name: string, value: number | string | ReadonlyArray): void; + setHeader(name: string, value: number | string | readonly string[]): void; /** * Sets the `Http2Stream`'s timeout value to `msecs`. If a callback is * provided, then it is added as a listener on the `'timeout'` event on @@ -1636,8 +1876,8 @@ declare module 'http2' { * This sends a chunk of the response body. This method may * be called multiple times to provide successive parts of the body. * - * In the `http` module, the response body is omitted when the - * request is a HEAD request. Similarly, the `204` and `304` responses_must not_ include a message body. + * In the `node:http` module, the response body is omitted when the + * request is a HEAD request. Similarly, the `204` and `304` responses _must not_ include a message body. * * `chunk` can be a string or a buffer. If `chunk` is a string, * the second parameter specifies how to encode it into a byte stream. @@ -1665,6 +1905,31 @@ declare module 'http2' { * @since v8.4.0 */ writeContinue(): void; + /** + * Sends a status `103 Early Hints` to the client with a Link header, + * indicating that the user agent can preload/preconnect the linked resources. + * The `hints` is an object containing the values of headers to be sent with + * early hints message. + * + * **Example** + * + * ```js + * const earlyHintsLink = '; rel=preload; as=style'; + * response.writeEarlyHints({ + * 'link': earlyHintsLink, + * }); + * + * const earlyHintsLinks = [ + * '; rel=preload; as=style', + * '; rel=preload; as=script', + * ]; + * response.writeEarlyHints({ + * 'link': earlyHintsLinks, + * }); + * ``` + * @since v18.11.0 + */ + writeEarlyHints(hints: Record): void; /** * Sends a response header to the request. The status code is a 3-digit HTTP * status code, like `404`. The last argument, `headers`, are the response headers. @@ -1724,48 +1989,51 @@ declare module 'http2' { * @param callback Called once `http2stream.pushStream()` is finished, or either when the attempt to create the pushed `Http2Stream` has failed or has been rejected, or the state of * `Http2ServerRequest` is closed prior to calling the `http2stream.pushStream()` method */ - createPushResponse(headers: OutgoingHttpHeaders, callback: (err: Error | null, res: Http2ServerResponse) => void): void; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'error', listener: (error: Error) => void): this; - addListener(event: 'finish', listener: () => void): this; - addListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - addListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + createPushResponse( + headers: OutgoingHttpHeaders, + callback: (err: Error | null, res: Http2ServerResponse) => void, + ): void; + addListener(event: "close", listener: () => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "error", listener: (error: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "pipe", listener: (src: stream.Readable) => void): this; + addListener(event: "unpipe", listener: (src: stream.Readable) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'close'): boolean; - emit(event: 'drain'): boolean; - emit(event: 'error', error: Error): boolean; - emit(event: 'finish'): boolean; - emit(event: 'pipe', src: stream.Readable): boolean; - emit(event: 'unpipe', src: stream.Readable): boolean; + emit(event: "close"): boolean; + emit(event: "drain"): boolean; + emit(event: "error", error: Error): boolean; + emit(event: "finish"): boolean; + emit(event: "pipe", src: stream.Readable): boolean; + emit(event: "unpipe", src: stream.Readable): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'close', listener: () => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'error', listener: (error: Error) => void): this; - on(event: 'finish', listener: () => void): this; - on(event: 'pipe', listener: (src: stream.Readable) => void): this; - on(event: 'unpipe', listener: (src: stream.Readable) => void): this; + on(event: "close", listener: () => void): this; + on(event: "drain", listener: () => void): this; + on(event: "error", listener: (error: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "pipe", listener: (src: stream.Readable) => void): this; + on(event: "unpipe", listener: (src: stream.Readable) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'error', listener: (error: Error) => void): this; - once(event: 'finish', listener: () => void): this; - once(event: 'pipe', listener: (src: stream.Readable) => void): this; - once(event: 'unpipe', listener: (src: stream.Readable) => void): this; + once(event: "close", listener: () => void): this; + once(event: "drain", listener: () => void): this; + once(event: "error", listener: (error: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "pipe", listener: (src: stream.Readable) => void): this; + once(event: "unpipe", listener: (src: stream.Readable) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'error', listener: (error: Error) => void): this; - prependListener(event: 'finish', listener: () => void): this; - prependListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "error", listener: (error: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'error', listener: (error: Error) => void): this; - prependOnceListener(event: 'finish', listener: () => void): this; - prependOnceListener(event: 'pipe', listener: (src: stream.Readable) => void): this; - prependOnceListener(event: 'unpipe', listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "error", listener: (error: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "pipe", listener: (src: stream.Readable) => void): this; + prependOnceListener(event: "unpipe", listener: (src: stream.Readable) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; } export namespace constants { @@ -1995,7 +2263,7 @@ declare module 'http2' { * for use with the `HTTP2-Settings` header field. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * * const packed = http2.getPackedSettings({ enablePush: false }); * @@ -2020,7 +2288,7 @@ declare module 'http2' { * with browser clients. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * * // Create an unencrypted HTTP/2 server. * // Since there are no browsers known that support @@ -2031,28 +2299,33 @@ declare module 'http2' { * server.on('stream', (stream, headers) => { * stream.respond({ * 'content-type': 'text/html; charset=utf-8', - * ':status': 200 + * ':status': 200, * }); * stream.end('

Hello World

'); * }); * - * server.listen(80); + * server.listen(8000); * ``` * @since v8.4.0 * @param onRequestHandler See `Compatibility API` */ - export function createServer(onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void): Http2Server; - export function createServer(options: ServerOptions, onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void): Http2Server; + export function createServer( + onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): Http2Server; + export function createServer( + options: ServerOptions, + onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): Http2Server; /** * Returns a `tls.Server` instance that creates and manages `Http2Session`instances. * * ```js - * const http2 = require('http2'); - * const fs = require('fs'); + * const http2 = require('node:http2'); + * const fs = require('node:fs'); * * const options = { * key: fs.readFileSync('server-key.pem'), - * cert: fs.readFileSync('server-cert.pem') + * cert: fs.readFileSync('server-cert.pem'), * }; * * // Create a secure HTTP/2 server @@ -2061,23 +2334,28 @@ declare module 'http2' { * server.on('stream', (stream, headers) => { * stream.respond({ * 'content-type': 'text/html; charset=utf-8', - * ':status': 200 + * ':status': 200, * }); * stream.end('

Hello World

'); * }); * - * server.listen(80); + * server.listen(8443); * ``` * @since v8.4.0 * @param onRequestHandler See `Compatibility API` */ - export function createSecureServer(onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void): Http2SecureServer; - export function createSecureServer(options: SecureServerOptions, onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void): Http2SecureServer; + export function createSecureServer( + onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): Http2SecureServer; + export function createSecureServer( + options: SecureServerOptions, + onRequestHandler?: (request: Http2ServerRequest, response: Http2ServerResponse) => void, + ): Http2SecureServer; /** * Returns a `ClientHttp2Session` instance. * * ```js - * const http2 = require('http2'); + * const http2 = require('node:http2'); * const client = http2.connect('https://localhost:1234'); * * // Use the client @@ -2089,13 +2367,16 @@ declare module 'http2' { * is used). Userinfo (user ID and password), path, querystring, and fragment details in the URL will be ignored. * @param listener Will be registered as a one-time listener of the {@link 'connect'} event. */ - export function connect(authority: string | url.URL, listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void): ClientHttp2Session; + export function connect( + authority: string | url.URL, + listener: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, + ): ClientHttp2Session; export function connect( authority: string | url.URL, options?: ClientSessionOptions | SecureClientSessionOptions, - listener?: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void + listener?: (session: ClientHttp2Session, socket: net.Socket | tls.TLSSocket) => void, ): ClientHttp2Session; } -declare module 'node:http2' { - export * from 'http2'; +declare module "node:http2" { + export * from "http2"; } diff --git a/node_modules/@types/node/ts4.8/https.d.ts b/node_modules/@types/node/ts4.8/https.d.ts old mode 100755 new mode 100644 index 9514866..36ae5b2 --- a/node_modules/@types/node/ts4.8/https.d.ts +++ b/node_modules/@types/node/ts4.8/https.d.ts @@ -1,19 +1,22 @@ /** * HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a * separate module. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/https.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/https.js) */ -declare module 'https' { - import { Duplex } from 'node:stream'; - import * as tls from 'node:tls'; - import * as http from 'node:http'; - import { URL } from 'node:url'; +declare module "https" { + import { Duplex } from "node:stream"; + import * as tls from "node:tls"; + import * as http from "node:http"; + import { URL } from "node:url"; type ServerOptions< Request extends typeof http.IncomingMessage = typeof http.IncomingMessage, Response extends typeof http.ServerResponse = typeof http.ServerResponse, > = tls.SecureContextOptions & tls.TlsOptions & http.ServerOptions; - type RequestOptions = http.RequestOptions & - tls.SecureContextOptions & { + type RequestOptions = + & http.RequestOptions + & tls.SecureContextOptions + & { + checkServerIdentity?: typeof tls.checkServerIdentity | undefined; rejectUnauthorized?: boolean | undefined; // Defaults to true servername?: string | undefined; // SNI TLS Extension }; @@ -46,14 +49,24 @@ declare module 'https' { options: ServerOptions, requestListener?: http.RequestListener, ); + /** + * Closes all connections connected to this server. + * @since v18.2.0 + */ + closeAllConnections(): void; + /** + * Closes all connections connected to this server which are not sending a request or waiting for a response. + * @since v18.2.0 + */ + closeIdleConnections(): void; addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; + addListener(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; addListener( - event: 'newSession', + event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, ): this; addListener( - event: 'OCSPRequest', + event: "OCSPRequest", listener: ( certificate: Buffer, issuer: Buffer, @@ -61,74 +74,80 @@ declare module 'https' { ) => void, ): this; addListener( - event: 'resumeSession', + event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, ): this; - addListener(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this; - addListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'connection', listener: (socket: Duplex) => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'listening', listener: () => void): this; - addListener(event: 'checkContinue', listener: http.RequestListener): this; - addListener(event: 'checkExpectation', listener: http.RequestListener): this; - addListener(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this; + addListener(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; + addListener(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "connection", listener: (socket: Duplex) => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "listening", listener: () => void): this; + addListener(event: "checkContinue", listener: http.RequestListener): this; + addListener(event: "checkExpectation", listener: http.RequestListener): this; + addListener(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; addListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; - addListener(event: 'request', listener: http.RequestListener): this; + addListener(event: "request", listener: http.RequestListener): this; addListener( - event: 'upgrade', + event: "upgrade", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; emit(event: string, ...args: any[]): boolean; - emit(event: 'keylog', line: Buffer, tlsSocket: tls.TLSSocket): boolean; + emit(event: "keylog", line: Buffer, tlsSocket: tls.TLSSocket): boolean; emit( - event: 'newSession', + event: "newSession", sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void, ): boolean; emit( - event: 'OCSPRequest', + event: "OCSPRequest", certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void, ): boolean; - emit(event: 'resumeSession', sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void): boolean; - emit(event: 'secureConnection', tlsSocket: tls.TLSSocket): boolean; - emit(event: 'tlsClientError', err: Error, tlsSocket: tls.TLSSocket): boolean; - emit(event: 'close'): boolean; - emit(event: 'connection', socket: Duplex): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'listening'): boolean; + emit(event: "resumeSession", sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void): boolean; + emit(event: "secureConnection", tlsSocket: tls.TLSSocket): boolean; + emit(event: "tlsClientError", err: Error, tlsSocket: tls.TLSSocket): boolean; + emit(event: "close"): boolean; + emit(event: "connection", socket: Duplex): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "listening"): boolean; emit( - event: 'checkContinue', + event: "checkContinue", req: InstanceType, - res: InstanceType & { req: InstanceType }, + res: InstanceType & { + req: InstanceType; + }, ): boolean; emit( - event: 'checkExpectation', + event: "checkExpectation", req: InstanceType, - res: InstanceType & { req: InstanceType }, + res: InstanceType & { + req: InstanceType; + }, ): boolean; - emit(event: 'clientError', err: Error, socket: Duplex): boolean; - emit(event: 'connect', req: InstanceType, socket: Duplex, head: Buffer): boolean; + emit(event: "clientError", err: Error, socket: Duplex): boolean; + emit(event: "connect", req: InstanceType, socket: Duplex, head: Buffer): boolean; emit( - event: 'request', + event: "request", req: InstanceType, - res: InstanceType & { req: InstanceType }, + res: InstanceType & { + req: InstanceType; + }, ): boolean; - emit(event: 'upgrade', req: InstanceType, socket: Duplex, head: Buffer): boolean; + emit(event: "upgrade", req: InstanceType, socket: Duplex, head: Buffer): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; + on(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; on( - event: 'newSession', + event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, ): this; on( - event: 'OCSPRequest', + event: "OCSPRequest", listener: ( certificate: Buffer, issuer: Buffer, @@ -136,29 +155,29 @@ declare module 'https' { ) => void, ): this; on( - event: 'resumeSession', + event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, ): this; - on(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this; - on(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'connection', listener: (socket: Duplex) => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'listening', listener: () => void): this; - on(event: 'checkContinue', listener: http.RequestListener): this; - on(event: 'checkExpectation', listener: http.RequestListener): this; - on(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this; - on(event: 'connect', listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; - on(event: 'request', listener: http.RequestListener): this; - on(event: 'upgrade', listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; + on(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; + on(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; + on(event: "close", listener: () => void): this; + on(event: "connection", listener: (socket: Duplex) => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "listening", listener: () => void): this; + on(event: "checkContinue", listener: http.RequestListener): this; + on(event: "checkExpectation", listener: http.RequestListener): this; + on(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; + on(event: "connect", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; + on(event: "request", listener: http.RequestListener): this; + on(event: "upgrade", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; + once(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; once( - event: 'newSession', + event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, ): this; once( - event: 'OCSPRequest', + event: "OCSPRequest", listener: ( certificate: Buffer, issuer: Buffer, @@ -166,29 +185,29 @@ declare module 'https' { ) => void, ): this; once( - event: 'resumeSession', + event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, ): this; - once(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this; - once(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'connection', listener: (socket: Duplex) => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'listening', listener: () => void): this; - once(event: 'checkContinue', listener: http.RequestListener): this; - once(event: 'checkExpectation', listener: http.RequestListener): this; - once(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this; - once(event: 'connect', listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; - once(event: 'request', listener: http.RequestListener): this; - once(event: 'upgrade', listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; + once(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; + once(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; + once(event: "close", listener: () => void): this; + once(event: "connection", listener: (socket: Duplex) => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "listening", listener: () => void): this; + once(event: "checkContinue", listener: http.RequestListener): this; + once(event: "checkExpectation", listener: http.RequestListener): this; + once(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; + once(event: "connect", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; + once(event: "request", listener: http.RequestListener): this; + once(event: "upgrade", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; + prependListener(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; prependListener( - event: 'newSession', + event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, ): this; prependListener( - event: 'OCSPRequest', + event: "OCSPRequest", listener: ( certificate: Buffer, issuer: Buffer, @@ -196,35 +215,35 @@ declare module 'https' { ) => void, ): this; prependListener( - event: 'resumeSession', + event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, ): this; - prependListener(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this; - prependListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'connection', listener: (socket: Duplex) => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'listening', listener: () => void): this; - prependListener(event: 'checkContinue', listener: http.RequestListener): this; - prependListener(event: 'checkExpectation', listener: http.RequestListener): this; - prependListener(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this; + prependListener(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; + prependListener(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "connection", listener: (socket: Duplex) => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "listening", listener: () => void): this; + prependListener(event: "checkContinue", listener: http.RequestListener): this; + prependListener(event: "checkExpectation", listener: http.RequestListener): this; + prependListener(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; prependListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; - prependListener(event: 'request', listener: http.RequestListener): this; + prependListener(event: "request", listener: http.RequestListener): this; prependListener( - event: 'upgrade', + event: "upgrade", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'keylog', listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; + prependOnceListener(event: "keylog", listener: (line: Buffer, tlsSocket: tls.TLSSocket) => void): this; prependOnceListener( - event: 'newSession', + event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void, ): this; prependOnceListener( - event: 'OCSPRequest', + event: "OCSPRequest", listener: ( certificate: Buffer, issuer: Buffer, @@ -232,37 +251,37 @@ declare module 'https' { ) => void, ): this; prependOnceListener( - event: 'resumeSession', + event: "resumeSession", listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void, ): this; - prependOnceListener(event: 'secureConnection', listener: (tlsSocket: tls.TLSSocket) => void): this; - prependOnceListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'connection', listener: (socket: Duplex) => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'listening', listener: () => void): this; - prependOnceListener(event: 'checkContinue', listener: http.RequestListener): this; - prependOnceListener(event: 'checkExpectation', listener: http.RequestListener): this; - prependOnceListener(event: 'clientError', listener: (err: Error, socket: Duplex) => void): this; + prependOnceListener(event: "secureConnection", listener: (tlsSocket: tls.TLSSocket) => void): this; + prependOnceListener(event: "tlsClientError", listener: (err: Error, tlsSocket: tls.TLSSocket) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "connection", listener: (socket: Duplex) => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "listening", listener: () => void): this; + prependOnceListener(event: "checkContinue", listener: http.RequestListener): this; + prependOnceListener(event: "checkExpectation", listener: http.RequestListener): this; + prependOnceListener(event: "clientError", listener: (err: Error, socket: Duplex) => void): this; prependOnceListener( - event: 'connect', + event: "connect", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; - prependOnceListener(event: 'request', listener: http.RequestListener): this; + prependOnceListener(event: "request", listener: http.RequestListener): this; prependOnceListener( - event: 'upgrade', + event: "upgrade", listener: (req: InstanceType, socket: Duplex, head: Buffer) => void, ): this; } /** * ```js * // curl -k https://localhost:8000/ - * const https = require('https'); - * const fs = require('fs'); + * const https = require('node:https'); + * const fs = require('node:fs'); * * const options = { * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), - * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem') + * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'), * }; * * https.createServer(options, (req, res) => { @@ -274,12 +293,12 @@ declare module 'https' { * Or * * ```js - * const https = require('https'); - * const fs = require('fs'); + * const https = require('node:https'); + * const fs = require('node:fs'); * * const options = { * pfx: fs.readFileSync('test/fixtures/test_cert.pfx'), - * passphrase: 'sample' + * passphrase: 'sample', * }; * * https.createServer(options, (req, res) => { @@ -315,13 +334,13 @@ declare module 'https' { * upload a file with a POST request, then write to the `ClientRequest` object. * * ```js - * const https = require('https'); + * const https = require('node:https'); * * const options = { * hostname: 'encrypted.google.com', * port: 443, * path: '/', - * method: 'GET' + * method: 'GET', * }; * * const req = https.request(options, (res) => { @@ -348,7 +367,7 @@ declare module 'https' { * path: '/', * method: 'GET', * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), - * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem') + * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'), * }; * options.agent = new https.Agent(options); * @@ -367,7 +386,7 @@ declare module 'https' { * method: 'GET', * key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), * cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'), - * agent: false + * agent: false, * }; * * const req = https.request(options, (res) => { @@ -388,9 +407,9 @@ declare module 'https' { * Example pinning on certificate fingerprint, or the public key (similar to`pin-sha256`): * * ```js - * const tls = require('tls'); - * const https = require('https'); - * const crypto = require('crypto'); + * const tls = require('node:tls'); + * const https = require('node:https'); + * const crypto = require('node:crypto'); * * function sha256(s) { * return crypto.createHash('sha256').update(s).digest('base64'); @@ -407,7 +426,7 @@ declare module 'https' { * return err; * } * - * // Pin the public key, similar to HPKP pin-sha25 pinning + * // Pin the public key, similar to HPKP pin-sha256 pinning * const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU='; * if (sha256(cert.pubkey) !== pubkey256) { * const msg = 'Certificate verification error: ' + @@ -498,7 +517,7 @@ declare module 'https' { * string, it is automatically parsed with `new URL()`. If it is a `URL` object, it will be automatically converted to an ordinary `options` object. * * ```js - * const https = require('https'); + * const https = require('node:https'); * * https.get('https://encrypted.google.com/', (res) => { * console.log('statusCode:', res.statusCode); @@ -526,6 +545,6 @@ declare module 'https' { ): http.ClientRequest; let globalAgent: Agent; } -declare module 'node:https' { - export * from 'https'; +declare module "node:https" { + export * from "https"; } diff --git a/node_modules/@types/node/ts4.8/index.d.ts b/node_modules/@types/node/ts4.8/index.d.ts old mode 100755 new mode 100644 index cb60f9a..7c8b38c --- a/node_modules/@types/node/ts4.8/index.d.ts +++ b/node_modules/@types/node/ts4.8/index.d.ts @@ -22,7 +22,7 @@ * IN THE SOFTWARE. */ -// NOTE: These definitions support NodeJS and TypeScript 4.8 and earlier +// NOTE: These definitions support NodeJS and TypeScript 4.8 and earlier. // Reference required types from the default lib: /// @@ -47,6 +47,7 @@ /// /// /// +/// /// /// /// @@ -63,6 +64,7 @@ /// /// /// +/// /// /// /// diff --git a/node_modules/@types/node/ts4.8/inspector.d.ts b/node_modules/@types/node/ts4.8/inspector.d.ts old mode 100755 new mode 100644 index f79313f..3927b81 --- a/node_modules/@types/node/ts4.8/inspector.d.ts +++ b/node_modules/@types/node/ts4.8/inspector.d.ts @@ -1,21 +1,26 @@ -// eslint-disable-next-line dt-header // Type definitions for inspector // These definitions are auto-generated. // Please see https://github.com/DefinitelyTyped/DefinitelyTyped/pull/19330 // for more information. -// tslint:disable:max-line-length /** - * The `inspector` module provides an API for interacting with the V8 inspector. + * The `node:inspector` module provides an API for interacting with the V8 + * inspector. * * It can be accessed using: * * ```js - * const inspector = require('inspector'); + * import * as inspector from 'node:inspector/promises'; * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/inspector.js) + * + * or + * + * ```js + * import * as inspector from 'node:inspector'; + * ``` + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/inspector.js) */ declare module 'inspector' { import EventEmitter = require('node:events'); @@ -1688,7 +1693,7 @@ declare module 'inspector' { /** * Controls how the trace buffer stores data. */ - recordMode?: string; + recordMode?: string | undefined; /** * Included category filters. */ @@ -1778,13 +1783,6 @@ declare module 'inspector' { * @since v8.0.0 */ connect(): void; - /** - * Connects a session to the main thread inspector back-end. - * An exception will be thrown if this API was not called on a Worker - * thread. - * @since v12.11.0 - */ - connectToMainThread(): void; /** * Immediately close the session. All pending message callbacks will be called * with an error. `session.connect()` will need to be called to be able to send @@ -2696,7 +2694,7 @@ declare module 'inspector' { prependOnceListener(event: 'NodeRuntime.waitingForDisconnect', listener: () => void): this; } /** - * Activate inspector on host and port. Equivalent to `node --inspect=[[host:]port]`, but can be done programmatically after node has + * Activate inspector on host and port. Equivalent to`node --inspect=[[host:]port]`, but can be done programmatically after node has * started. * * If wait is `true`, will block until a client has connected to the inspect port @@ -2706,8 +2704,9 @@ declare module 'inspector' { * @param [port='what was specified on the CLI'] Port to listen on for inspector connections. Optional. * @param [host='what was specified on the CLI'] Host to listen on for inspector connections. Optional. * @param [wait=false] Block until a client has connected. Optional. + * @returns Disposable that calls `inspector.close()`. */ - function open(port?: number, host?: string, wait?: boolean): void; + function open(port?: number, host?: string, wait?: boolean): Disposable; /** * Deactivate the inspector. Blocks until there are no active connections. */ @@ -2718,12 +2717,12 @@ declare module 'inspector' { * ```console * $ node --inspect -p 'inspector.url()' * Debugger listening on ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34 - * For help see https://nodejs.org/en/docs/inspector + * For help, see: https://nodejs.org/en/docs/inspector * ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34 * * $ node --inspect=localhost:3000 -p 'inspector.url()' * Debugger listening on ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a - * For help see https://nodejs.org/en/docs/inspector + * For help, see: https://nodejs.org/en/docs/inspector * ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a * * $ node -p 'inspector.url()' @@ -2739,7 +2738,10 @@ declare module 'inspector' { */ function waitForDebugger(): void; } +/** + * The inspector module provides an API for interacting with the V8 inspector. + */ declare module 'node:inspector' { - import EventEmitter = require('inspector'); - export = EventEmitter; + import inspector = require('inspector'); + export = inspector; } diff --git a/node_modules/@types/node/ts4.8/module.d.ts b/node_modules/@types/node/ts4.8/module.d.ts old mode 100755 new mode 100644 index d83aec9..c38a9b8 --- a/node_modules/@types/node/ts4.8/module.d.ts +++ b/node_modules/@types/node/ts4.8/module.d.ts @@ -1,8 +1,10 @@ /** * @since v0.3.7 + * @experimental */ -declare module 'module' { - import { URL } from 'node:url'; +declare module "module" { + import { URL } from "node:url"; + import { MessagePort } from "node:worker_threads"; namespace Module { /** * The `module.syncBuiltinESMExports()` method updates all the live bindings for @@ -10,9 +12,9 @@ declare module 'module' { * does not add or remove exported names from the `ES Modules`. * * ```js - * const fs = require('fs'); - * const assert = require('assert'); - * const { syncBuiltinESMExports } = require('module'); + * const fs = require('node:fs'); + * const assert = require('node:assert'); + * const { syncBuiltinESMExports } = require('node:module'); * * fs.readFile = newAPI; * @@ -26,7 +28,7 @@ declare module 'module' { * * syncBuiltinESMExports(); * - * import('fs').then((esmFS) => { + * import('node:fs').then((esmFS) => { * // It syncs the existing readFile property with the new value * assert.strictEqual(esmFS.readFile, newAPI); * // readFileSync has been deleted from the required fs @@ -44,6 +46,7 @@ declare module 'module' { * `path` is the resolved path for the file for which a corresponding source map * should be fetched. * @since v13.7.0, v12.17.0 + * @return Returns `module.SourceMap` if a source map is found, `undefined` otherwise. */ function findSourceMap(path: string, error?: Error): SourceMap; interface SourceMapPayload { @@ -62,6 +65,24 @@ declare module 'module' { originalLine: number; originalColumn: number; } + interface SourceOrigin { + /** + * The name of the range in the source map, if one was provided + */ + name?: string; + /** + * The file name of the original source, as reported in the SourceMap + */ + fileName: string; + /** + * The 1-indexed lineNumber of the corresponding call site in the original source + */ + lineNumber: number; + /** + * The 1-indexed columnNumber of the corresponding call site in the original source + */ + columnNumber: number; + } /** * @since v13.7.0, v12.17.0 */ @@ -72,12 +93,170 @@ declare module 'module' { readonly payload: SourceMapPayload; constructor(payload: SourceMapPayload); /** - * Given a line number and column number in the generated source file, returns - * an object representing the position in the original file. The object returned - * consists of the following keys: + * Given a line offset and column offset in the generated source + * file, returns an object representing the SourceMap range in the + * original file if found, or an empty object if not. + * + * The object returned contains the following keys: + * + * The returned value represents the raw range as it appears in the + * SourceMap, based on zero-indexed offsets, _not_ 1-indexed line and + * column numbers as they appear in Error messages and CallSite + * objects. + * + * To get the corresponding 1-indexed line and column numbers from a + * lineNumber and columnNumber as they are reported by Error stacks + * and CallSite objects, use `sourceMap.findOrigin(lineNumber, columnNumber)` + * @param lineOffset The zero-indexed line number offset in the generated source + * @param columnOffset The zero-indexed column number offset in the generated source */ - findEntry(line: number, column: number): SourceMapping; + findEntry(lineOffset: number, columnOffset: number): SourceMapping; + /** + * Given a 1-indexed `lineNumber` and `columnNumber` from a call site in the generated source, + * find the corresponding call site location in the original source. + * + * If the `lineNumber` and `columnNumber` provided are not found in any source map, + * then an empty object is returned. + * @param lineNumber The 1-indexed line number of the call site in the generated source + * @param columnNumber The 1-indexed column number of the call site in the generated source + */ + findOrigin(lineNumber: number, columnNumber: number): SourceOrigin | {}; } + /** @deprecated Use `ImportAttributes` instead */ + interface ImportAssertions extends ImportAttributes {} + interface ImportAttributes extends NodeJS.Dict { + type?: string | undefined; + } + type ModuleFormat = "builtin" | "commonjs" | "json" | "module" | "wasm"; + type ModuleSource = string | ArrayBuffer | NodeJS.TypedArray; + interface GlobalPreloadContext { + port: MessagePort; + } + /** + * @deprecated This hook will be removed in a future version. + * Use `initialize` instead. When a loader has an `initialize` export, `globalPreload` will be ignored. + * + * Sometimes it might be necessary to run some code inside of the same global scope that the application runs in. + * This hook allows the return of a string that is run as a sloppy-mode script on startup. + * + * @param context Information to assist the preload code + * @return Code to run before application startup + */ + type GlobalPreloadHook = (context: GlobalPreloadContext) => string; + /** + * The `initialize` hook provides a way to define a custom function that runs in the hooks thread + * when the hooks module is initialized. Initialization happens when the hooks module is registered via `register`. + * + * This hook can receive data from a `register` invocation, including ports and other transferrable objects. + * The return value of `initialize` can be a `Promise`, in which case it will be awaited before the main application thread execution resumes. + */ + type InitializeHook = (data: Data) => void | Promise; + interface ResolveHookContext { + /** + * Export conditions of the relevant `package.json` + */ + conditions: string[]; + /** + * @deprecated Use `importAttributes` instead + */ + importAssertions: ImportAttributes; + /** + * An object whose key-value pairs represent the assertions for the module to import + */ + importAttributes: ImportAttributes; + /** + * The module importing this one, or undefined if this is the Node.js entry point + */ + parentURL: string | undefined; + } + interface ResolveFnOutput { + /** + * A hint to the load hook (it might be ignored) + */ + format?: ModuleFormat | null | undefined; + /** + * @deprecated Use `importAttributes` instead + */ + importAssertions?: ImportAttributes | undefined; + /** + * The import attributes to use when caching the module (optional; if excluded the input will be used) + */ + importAttributes?: ImportAttributes | undefined; + /** + * A signal that this hook intends to terminate the chain of `resolve` hooks. + * @default false + */ + shortCircuit?: boolean | undefined; + /** + * The absolute URL to which this input resolves + */ + url: string; + } + /** + * The `resolve` hook chain is responsible for resolving file URL for a given module specifier and parent URL, and optionally its format (such as `'module'`) as a hint to the `load` hook. + * If a format is specified, the load hook is ultimately responsible for providing the final `format` value (and it is free to ignore the hint provided by `resolve`); + * if `resolve` provides a format, a custom `load` hook is required even if only to pass the value to the Node.js default `load` hook. + * + * @param specifier The specified URL path of the module to be resolved + * @param context + * @param nextResolve The subsequent `resolve` hook in the chain, or the Node.js default `resolve` hook after the last user-supplied resolve hook + */ + type ResolveHook = ( + specifier: string, + context: ResolveHookContext, + nextResolve: ( + specifier: string, + context?: ResolveHookContext, + ) => ResolveFnOutput | Promise, + ) => ResolveFnOutput | Promise; + interface LoadHookContext { + /** + * Export conditions of the relevant `package.json` + */ + conditions: string[]; + /** + * The format optionally supplied by the `resolve` hook chain + */ + format: ModuleFormat; + /** + * @deprecated Use `importAttributes` instead + */ + importAssertions: ImportAttributes; + /** + * An object whose key-value pairs represent the assertions for the module to import + */ + importAttributes: ImportAttributes; + } + interface LoadFnOutput { + format: ModuleFormat; + /** + * A signal that this hook intends to terminate the chain of `resolve` hooks. + * @default false + */ + shortCircuit?: boolean | undefined; + /** + * The source for Node.js to evaluate + */ + source?: ModuleSource; + } + /** + * The `load` hook provides a way to define a custom method of determining how a URL should be interpreted, retrieved, and parsed. + * It is also in charge of validating the import assertion. + * + * @param url The URL/path of the module to be loaded + * @param context Metadata about the module + * @param nextLoad The subsequent `load` hook in the chain, or the Node.js default `load` hook after the last user-supplied `load` hook + */ + type LoadHook = ( + url: string, + context: LoadHookContext, + nextLoad: (url: string, context?: LoadHookContext) => LoadFnOutput | Promise, + ) => LoadFnOutput | Promise; + } + interface RegisterOptions { + parentURL: string | URL; + data?: Data | undefined; + transferList?: any[] | undefined; } interface Module extends NodeModule {} class Module { @@ -85,30 +264,52 @@ declare module 'module' { static wrap(code: string): string; static createRequire(path: string | URL): NodeRequire; static builtinModules: string[]; + static isBuiltin(moduleName: string): boolean; static Module: typeof Module; + static register( + specifier: string | URL, + parentURL?: string | URL, + options?: RegisterOptions, + ): void; + static register(specifier: string | URL, options?: RegisterOptions): void; constructor(id: string, parent?: Module); } global { interface ImportMeta { + /** + * The directory name of the current module. This is the same as the `path.dirname()` of the `import.meta.filename`. + * **Caveat:** only present on `file:` modules. + */ + dirname: string; + /** + * The full absolute path and filename of the current module, with symlinks resolved. + * This is the same as the `url.fileURLToPath()` of the `import.meta.url`. + * **Caveat:** only local modules support this property. Modules not using the `file:` protocol will not provide it. + */ + filename: string; + /** + * The absolute `file:` URL of the module. + */ url: string; /** - * @experimental - * This feature is only available with the `--experimental-import-meta-resolve` - * command flag enabled. - * * Provides a module-relative resolution function scoped to each module, returning * the URL string. * - * @param specified The module specifier to resolve relative to `parent`. - * @param parent The absolute parent module URL to resolve from. If none - * is specified, the value of `import.meta.url` is used as the default. + * Second `parent` parameter is only used when the `--experimental-import-meta-resolve` + * command flag enabled. + * + * @since v20.6.0 + * + * @param specifier The module specifier to resolve relative to `parent`. + * @param parent The absolute parent module URL to resolve from. + * @returns The absolute (`file:`) URL string for the resolved module. */ - resolve?(specified: string, parent?: string | URL): Promise; + resolve(specifier: string, parent?: string | URL | undefined): string; } } export = Module; } -declare module 'node:module' { - import module = require('module'); +declare module "node:module" { + import module = require("module"); export = module; } diff --git a/node_modules/@types/node/ts4.8/net.d.ts b/node_modules/@types/node/ts4.8/net.d.ts old mode 100755 new mode 100644 index 195b393..70789e1 --- a/node_modules/@types/node/ts4.8/net.d.ts +++ b/node_modules/@types/node/ts4.8/net.d.ts @@ -1,22 +1,26 @@ /** * > Stability: 2 - Stable * - * The `net` module provides an asynchronous network API for creating stream-based + * The `node:net` module provides an asynchronous network API for creating stream-based * TCP or `IPC` servers ({@link createServer}) and clients * ({@link createConnection}). * * It can be accessed using: * * ```js - * const net = require('net'); + * const net = require('node:net'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/net.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/net.js) */ -declare module 'net' { - import * as stream from 'node:stream'; - import { Abortable, EventEmitter } from 'node:events'; - import * as dns from 'node:dns'; - type LookupFunction = (hostname: string, options: dns.LookupOneOptions, callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void) => void; +declare module "net" { + import * as stream from "node:stream"; + import { Abortable, EventEmitter } from "node:events"; + import * as dns from "node:dns"; + type LookupFunction = ( + hostname: string, + options: dns.LookupAllOptions, + callback: (err: NodeJS.ErrnoException | null, addresses: dns.LookupAddress[]) => void, + ) => void; interface AddressInfo { address: string; family: string; @@ -57,12 +61,20 @@ declare module 'net' { noDelay?: boolean | undefined; keepAlive?: boolean | undefined; keepAliveInitialDelay?: number | undefined; + /** + * @since v18.13.0 + */ + autoSelectFamily?: boolean | undefined; + /** + * @since v18.13.0 + */ + autoSelectFamilyAttemptTimeout?: number | undefined; } interface IpcSocketConnectOpts extends ConnectOpts { path: string; } type SocketConnectOpts = TcpSocketConnectOpts | IpcSocketConnectOpts; - type SocketReadyState = 'opening' | 'open' | 'readOnly' | 'writeOnly' | 'closed'; + type SocketReadyState = "opening" | "open" | "readOnly" | "writeOnly" | "closed"; /** * This class is an abstraction of a TCP socket or a streaming `IPC` endpoint * (uses named pipes on Windows, and Unix domain sockets otherwise). It is also @@ -79,6 +91,12 @@ declare module 'net' { */ class Socket extends stream.Duplex { constructor(options?: SocketConstructorOpts); + /** + * Destroys the socket after all data is written. If the `finish` event was already emitted the socket is destroyed immediately. + * If the socket is still writable it implicitly calls `socket.end()`. + * @since v0.3.4 + */ + destroySoon(): void; /** * Sends data on the socket. The second parameter specifies the encoding in the * case of a string. It defaults to UTF8 encoding. @@ -131,6 +149,14 @@ declare module 'net' { * @return The socket itself. */ pause(): this; + /** + * Close the TCP connection by sending an RST packet and destroy the stream. + * If this TCP socket is in connecting status, it will send an RST packet and destroy this TCP socket once it is connected. + * Otherwise, it will call `socket.destroy` with an `ERR_SOCKET_CLOSED` Error. + * If this is not a TCP socket (for example, a pipe), calling this method will immediately throw an `ERR_INVALID_HANDLE_TYPE` Error. + * @since v18.3.0, v16.17.0 + */ + resetAndDestroy(): this; /** * Resumes reading after a call to `socket.pause()`. * @return The socket itself. @@ -208,12 +234,21 @@ declare module 'net' { */ unref(): this; /** - * Opposite of `unref()`, calling `ref()` on a previously `unref`ed socket will_not_ let the program exit if it's the only socket left (the default behavior). + * Opposite of `unref()`, calling `ref()` on a previously `unref`ed socket will _not_ let the program exit if it's the only socket left (the default behavior). * If the socket is `ref`ed calling `ref` again will have no effect. * @since v0.9.1 * @return The socket itself. */ ref(): this; + /** + * This property is only present if the family autoselection algorithm is enabled in `socket.connect(options)` + * and it is an array of the addresses that have been attempted. + * + * Each address is a string in the form of `$IP:$PORT`. + * If the connection was successful, then the last address is the one that the socket is currently connected to. + * @since v19.4.0 + */ + readonly autoSelectFamilyAttemptedAddresses: string[]; /** * This property shows the number of characters buffered for writing. The buffer * may contain strings whose length after encoding is not yet known. So this number @@ -250,6 +285,12 @@ declare module 'net' { * @since v6.1.0 */ readonly connecting: boolean; + /** + * This is `true` if the socket is not connected yet, either because `.connect()`has not yet been called or because it is still in the process of connecting + * (see `socket.connecting`). + * @since v11.2.0, v10.16.0 + */ + readonly pending: boolean; /** * See `writable.destroyed` for further details. */ @@ -266,9 +307,18 @@ declare module 'net' { * @since v0.9.6 */ readonly localPort?: number; + /** + * The string representation of the local IP family. `'IPv4'` or `'IPv6'`. + * @since v18.8.0, v16.18.0 + */ + readonly localFamily?: string; /** * This property represents the state of the connection as a string. - * @see {https://nodejs.org/api/net.html#socketreadystate} + * + * * If the stream is connecting `socket.readyState` is `opening`. + * * If the stream is readable and writable, it is `open`. + * * If the stream is readable and not writable, it is `readOnly`. + * * If the stream is not readable and writable, it is `writeOnly`. * @since v0.5.0 */ readonly readyState: SocketReadyState; @@ -279,17 +329,20 @@ declare module 'net' { */ readonly remoteAddress?: string | undefined; /** - * The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. + * The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. Value may be `undefined` if + * the socket is destroyed (for example, if the client disconnected). * @since v0.11.14 */ readonly remoteFamily?: string | undefined; /** - * The numeric representation of the remote port. For example, `80` or `21`. + * The numeric representation of the remote port. For example, `80` or `21`. Value may be `undefined` if + * the socket is destroyed (for example, if the client disconnected). * @since v0.5.10 */ readonly remotePort?: number | undefined; /** - * The socket timeout in milliseconds as set by socket.setTimeout(). It is undefined if a timeout has not been set. + * The socket timeout in milliseconds as set by `socket.setTimeout()`. + * It is `undefined` if a timeout has not been set. * @since v10.7.0 */ readonly timeout?: number | undefined; @@ -315,68 +368,84 @@ declare module 'net' { * 5. end * 6. error * 7. lookup - * 8. timeout + * 8. ready + * 9. timeout */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: (hadError: boolean) => void): this; - addListener(event: 'connect', listener: () => void): this; - addListener(event: 'data', listener: (data: Buffer) => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'end', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'lookup', listener: (err: Error, address: string, family: string | number, host: string) => void): this; - addListener(event: 'ready', listener: () => void): this; - addListener(event: 'timeout', listener: () => void): this; + addListener(event: "close", listener: (hadError: boolean) => void): this; + addListener(event: "connect", listener: () => void): this; + addListener(event: "data", listener: (data: Buffer) => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener( + event: "lookup", + listener: (err: Error, address: string, family: string | number, host: string) => void, + ): this; + addListener(event: "ready", listener: () => void): this; + addListener(event: "timeout", listener: () => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close', hadError: boolean): boolean; - emit(event: 'connect'): boolean; - emit(event: 'data', data: Buffer): boolean; - emit(event: 'drain'): boolean; - emit(event: 'end'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'lookup', err: Error, address: string, family: string | number, host: string): boolean; - emit(event: 'ready'): boolean; - emit(event: 'timeout'): boolean; + emit(event: "close", hadError: boolean): boolean; + emit(event: "connect"): boolean; + emit(event: "data", data: Buffer): boolean; + emit(event: "drain"): boolean; + emit(event: "end"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "lookup", err: Error, address: string, family: string | number, host: string): boolean; + emit(event: "ready"): boolean; + emit(event: "timeout"): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: (hadError: boolean) => void): this; - on(event: 'connect', listener: () => void): this; - on(event: 'data', listener: (data: Buffer) => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'end', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'lookup', listener: (err: Error, address: string, family: string | number, host: string) => void): this; - on(event: 'ready', listener: () => void): this; - on(event: 'timeout', listener: () => void): this; + on(event: "close", listener: (hadError: boolean) => void): this; + on(event: "connect", listener: () => void): this; + on(event: "data", listener: (data: Buffer) => void): this; + on(event: "drain", listener: () => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on( + event: "lookup", + listener: (err: Error, address: string, family: string | number, host: string) => void, + ): this; + on(event: "ready", listener: () => void): this; + on(event: "timeout", listener: () => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: (hadError: boolean) => void): this; - once(event: 'connect', listener: () => void): this; - once(event: 'data', listener: (data: Buffer) => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'end', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'lookup', listener: (err: Error, address: string, family: string | number, host: string) => void): this; - once(event: 'ready', listener: () => void): this; - once(event: 'timeout', listener: () => void): this; + once(event: "close", listener: (hadError: boolean) => void): this; + once(event: "connect", listener: () => void): this; + once(event: "data", listener: (data: Buffer) => void): this; + once(event: "drain", listener: () => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once( + event: "lookup", + listener: (err: Error, address: string, family: string | number, host: string) => void, + ): this; + once(event: "ready", listener: () => void): this; + once(event: "timeout", listener: () => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: (hadError: boolean) => void): this; - prependListener(event: 'connect', listener: () => void): this; - prependListener(event: 'data', listener: (data: Buffer) => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'end', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'lookup', listener: (err: Error, address: string, family: string | number, host: string) => void): this; - prependListener(event: 'ready', listener: () => void): this; - prependListener(event: 'timeout', listener: () => void): this; + prependListener(event: "close", listener: (hadError: boolean) => void): this; + prependListener(event: "connect", listener: () => void): this; + prependListener(event: "data", listener: (data: Buffer) => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener( + event: "lookup", + listener: (err: Error, address: string, family: string | number, host: string) => void, + ): this; + prependListener(event: "ready", listener: () => void): this; + prependListener(event: "timeout", listener: () => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: (hadError: boolean) => void): this; - prependOnceListener(event: 'connect', listener: () => void): this; - prependOnceListener(event: 'data', listener: (data: Buffer) => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'end', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'lookup', listener: (err: Error, address: string, family: string | number, host: string) => void): this; - prependOnceListener(event: 'ready', listener: () => void): this; - prependOnceListener(event: 'timeout', listener: () => void): this; + prependOnceListener(event: "close", listener: (hadError: boolean) => void): this; + prependOnceListener(event: "connect", listener: () => void): this; + prependOnceListener(event: "data", listener: (data: Buffer) => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener( + event: "lookup", + listener: (err: Error, address: string, family: string | number, host: string) => void, + ): this; + prependOnceListener(event: "ready", listener: () => void): this; + prependOnceListener(event: "timeout", listener: () => void): this; } interface ListenOptions extends Abortable { port?: number | undefined; @@ -422,6 +491,14 @@ declare module 'net' { */ keepAliveInitialDelay?: number | undefined; } + interface DropArgument { + localAddress?: string; + localPort?: number; + localFamily?: string; + remoteAddress?: string; + remotePort?: number; + remoteFamily?: string; + } /** * This class is used to create a TCP or `IPC` server. * @since v0.1.90 @@ -461,7 +538,7 @@ declare module 'net' { * ```js * server.on('error', (e) => { * if (e.code === 'EADDRINUSE') { - * console.log('Address in use, retrying...'); + * console.error('Address in use, retrying...'); * setTimeout(() => { * server.close(); * server.listen(PORT, HOST); @@ -526,7 +603,7 @@ declare module 'net' { */ getConnections(cb: (error: Error | null, count: number) => void): void; /** - * Opposite of `unref()`, calling `ref()` on a previously `unref`ed server will_not_ let the program exit if it's the only server left (the default behavior). + * Opposite of `unref()`, calling `ref()` on a previously `unref`ed server will _not_ let the program exit if it's the only server left (the default behavior). * If the server is `ref`ed calling `ref()` again will have no effect. * @since v0.9.1 */ @@ -558,49 +635,61 @@ declare module 'net' { * 2. connection * 3. error * 4. listening + * 5. drop */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'connection', listener: (socket: Socket) => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'listening', listener: () => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "connection", listener: (socket: Socket) => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "listening", listener: () => void): this; + addListener(event: "drop", listener: (data?: DropArgument) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close'): boolean; - emit(event: 'connection', socket: Socket): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'listening'): boolean; + emit(event: "close"): boolean; + emit(event: "connection", socket: Socket): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "listening"): boolean; + emit(event: "drop", data?: DropArgument): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'connection', listener: (socket: Socket) => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'listening', listener: () => void): this; + on(event: "close", listener: () => void): this; + on(event: "connection", listener: (socket: Socket) => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "listening", listener: () => void): this; + on(event: "drop", listener: (data?: DropArgument) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'connection', listener: (socket: Socket) => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'listening', listener: () => void): this; + once(event: "close", listener: () => void): this; + once(event: "connection", listener: (socket: Socket) => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "listening", listener: () => void): this; + once(event: "drop", listener: (data?: DropArgument) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'connection', listener: (socket: Socket) => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'listening', listener: () => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "connection", listener: (socket: Socket) => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "listening", listener: () => void): this; + prependListener(event: "drop", listener: (data?: DropArgument) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'connection', listener: (socket: Socket) => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'listening', listener: () => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "connection", listener: (socket: Socket) => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "listening", listener: () => void): this; + prependOnceListener(event: "drop", listener: (data?: DropArgument) => void): this; + /** + * Calls {@link Server.close()} and returns a promise that fulfills when the server has closed. + * @since v20.5.0 + */ + [Symbol.asyncDispose](): Promise; } - type IPVersion = 'ipv4' | 'ipv6'; + type IPVersion = "ipv4" | "ipv6"; /** * The `BlockList` object can be used with some network APIs to specify rules for * disabling inbound or outbound access to specific IP addresses, IP ranges, or * IP subnets. - * @since v15.0.0 + * @since v15.0.0, v14.18.0 */ class BlockList { /** * Adds a rule to block the given IP address. - * @since v15.0.0 + * @since v15.0.0, v14.18.0 * @param address An IPv4 or IPv6 address. * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. */ @@ -608,7 +697,7 @@ declare module 'net' { addAddress(address: SocketAddress): void; /** * Adds a rule to block a range of IP addresses from `start` (inclusive) to`end` (inclusive). - * @since v15.0.0 + * @since v15.0.0, v14.18.0 * @param start The starting IPv4 or IPv6 address in the range. * @param end The ending IPv4 or IPv6 address in the range. * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. @@ -617,7 +706,7 @@ declare module 'net' { addRange(start: SocketAddress, end: SocketAddress): void; /** * Adds a rule to block a range of IP addresses specified as a subnet mask. - * @since v15.0.0 + * @since v15.0.0, v14.18.0 * @param net The network IPv4 or IPv6 address. * @param prefix The number of CIDR prefix bits. For IPv4, this must be a value between `0` and `32`. For IPv6, this must be between `0` and `128`. * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. @@ -641,7 +730,7 @@ declare module 'net' { * console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true * console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true * ``` - * @since v15.0.0 + * @since v15.0.0, v14.18.0 * @param address The IP address to check * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. */ @@ -672,11 +761,11 @@ declare module 'net' { * * The server can be a TCP server or an `IPC` server, depending on what it `listen()` to. * - * Here is an example of an TCP echo server which listens for connections + * Here is an example of a TCP echo server which listens for connections * on port 8124: * * ```js - * const net = require('net'); + * const net = require('node:net'); * const server = net.createServer((c) => { * // 'connection' listener. * console.log('client connected'); @@ -696,8 +785,8 @@ declare module 'net' { * * Test this by using `telnet`: * - * ```console - * $ telnet localhost 8124 + * ```bash + * telnet localhost 8124 * ``` * * To listen on the socket `/tmp/echo.sock`: @@ -710,8 +799,8 @@ declare module 'net' { * * Use `nc` to connect to a Unix domain socket server: * - * ```console - * $ nc -U /tmp/echo.sock + * ```bash + * nc -U /tmp/echo.sock * ``` * @since v0.5.0 * @param connectionListener Automatically set as a listener for the {@link 'connection'} event. @@ -751,19 +840,61 @@ declare module 'net' { function createConnection(port: number, host?: string, connectionListener?: () => void): Socket; function createConnection(path: string, connectionListener?: () => void): Socket; /** - * Tests if input is an IP address. Returns `0` for invalid strings, - * returns `4` for IP version 4 addresses, and returns `6` for IP version 6 - * addresses. + * Gets the current default value of the `autoSelectFamily` option of `socket.connect(options)`. + * The initial default value is `true`, unless the command line option`--no-network-family-autoselection` is provided. + * @since v19.4.0 + */ + function getDefaultAutoSelectFamily(): boolean; + /** + * Sets the default value of the `autoSelectFamily` option of `socket.connect(options)`. + * @since v19.4.0 + */ + function setDefaultAutoSelectFamily(value: boolean): void; + /** + * Gets the current default value of the `autoSelectFamilyAttemptTimeout` option of `socket.connect(options)`. + * The initial default value is `250`. + * @since v19.8.0 + */ + function getDefaultAutoSelectFamilyAttemptTimeout(): number; + /** + * Sets the default value of the `autoSelectFamilyAttemptTimeout` option of `socket.connect(options)`. + * @since v19.8.0 + */ + function setDefaultAutoSelectFamilyAttemptTimeout(value: number): void; + /** + * Returns `6` if `input` is an IPv6 address. Returns `4` if `input` is an IPv4 + * address in [dot-decimal notation](https://en.wikipedia.org/wiki/Dot-decimal_notation) with no leading zeroes. Otherwise, returns`0`. + * + * ```js + * net.isIP('::1'); // returns 6 + * net.isIP('127.0.0.1'); // returns 4 + * net.isIP('127.000.000.001'); // returns 0 + * net.isIP('127.0.0.1/24'); // returns 0 + * net.isIP('fhqwhgads'); // returns 0 + * ``` * @since v0.3.0 */ function isIP(input: string): number; /** - * Returns `true` if input is a version 4 IP address, otherwise returns `false`. + * Returns `true` if `input` is an IPv4 address in [dot-decimal notation](https://en.wikipedia.org/wiki/Dot-decimal_notation) with no + * leading zeroes. Otherwise, returns `false`. + * + * ```js + * net.isIPv4('127.0.0.1'); // returns true + * net.isIPv4('127.000.000.001'); // returns false + * net.isIPv4('127.0.0.1/24'); // returns false + * net.isIPv4('fhqwhgads'); // returns false + * ``` * @since v0.3.0 */ function isIPv4(input: string): boolean; /** - * Returns `true` if input is a version 6 IP address, otherwise returns `false`. + * Returns `true` if `input` is an IPv6 address. Otherwise, returns `false`. + * + * ```js + * net.isIPv6('::1'); // returns true + * net.isIPv6('fhqwhgads'); // returns false + * ``` * @since v0.3.0 */ function isIPv6(input: string): boolean; @@ -789,29 +920,30 @@ declare module 'net' { port?: number | undefined; } /** - * @since v15.14.0 + * @since v15.14.0, v14.18.0 */ class SocketAddress { constructor(options: SocketAddressInitOptions); /** - * @since v15.14.0 + * Either \`'ipv4'\` or \`'ipv6'\`. + * @since v15.14.0, v14.18.0 */ readonly address: string; /** * Either \`'ipv4'\` or \`'ipv6'\`. - * @since v15.14.0 + * @since v15.14.0, v14.18.0 */ readonly family: IPVersion; /** - * @since v15.14.0 + * @since v15.14.0, v14.18.0 */ readonly port: number; /** - * @since v15.14.0 + * @since v15.14.0, v14.18.0 */ readonly flowlabel: number; } } -declare module 'node:net' { - export * from 'net'; +declare module "node:net" { + export * from "net"; } diff --git a/node_modules/@types/node/ts4.8/os.d.ts b/node_modules/@types/node/ts4.8/os.d.ts old mode 100755 new mode 100644 index 3186267..39a33f7 --- a/node_modules/@types/node/ts4.8/os.d.ts +++ b/node_modules/@types/node/ts4.8/os.d.ts @@ -1,13 +1,13 @@ /** - * The `os` module provides operating system-related utility methods and + * The `node:os` module provides operating system-related utility methods and * properties. It can be accessed using: * * ```js - * const os = require('os'); + * const os = require('node:os'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/os.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/os.js) */ -declare module 'os' { +declare module "os" { interface CpuInfo { model: string; speed: number; @@ -27,18 +27,18 @@ declare module 'os' { cidr: string | null; } interface NetworkInterfaceInfoIPv4 extends NetworkInterfaceBase { - family: 'IPv4'; + family: "IPv4"; scopeid?: undefined; } interface NetworkInterfaceInfoIPv6 extends NetworkInterfaceBase { - family: 'IPv6'; + family: "IPv6"; scopeid: number; } interface UserInfo { username: T; uid: number; gid: number; - shell: T; + shell: T | null; homedir: T; } type NetworkInterfaceInfo = NetworkInterfaceInfoIPv4 | NetworkInterfaceInfoIPv6; @@ -75,6 +75,7 @@ declare module 'os' { function totalmem(): number; /** * Returns an array of objects containing information about each logical CPU core. + * The array will be empty if no CPU information is available, such as if the`/proc` file system is unavailable. * * The properties included on each object include: * @@ -88,8 +89,8 @@ declare module 'os' { * nice: 0, * sys: 30340, * idle: 1070356870, - * irq: 0 - * } + * irq: 0, + * }, * }, * { * model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', @@ -99,8 +100,8 @@ declare module 'os' { * nice: 0, * sys: 26980, * idle: 1071569080, - * irq: 0 - * } + * irq: 0, + * }, * }, * { * model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', @@ -110,8 +111,8 @@ declare module 'os' { * nice: 0, * sys: 21750, * idle: 1070919370, - * irq: 0 - * } + * irq: 0, + * }, * }, * { * model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', @@ -121,17 +122,28 @@ declare module 'os' { * nice: 0, * sys: 19430, * idle: 1070905480, - * irq: 20 - * } + * irq: 20, + * }, * }, * ] * ``` * * `nice` values are POSIX-only. On Windows, the `nice` values of all processors * are always 0. + * + * `os.cpus().length` should not be used to calculate the amount of parallelism + * available to an application. Use {@link availableParallelism} for this purpose. * @since v0.3.3 */ function cpus(): CpuInfo[]; + /** + * Returns an estimate of the default amount of parallelism a program should use. + * Always returns a value greater than zero. + * + * This function is a small wrapper about libuv's [`uv_available_parallelism()`](https://docs.libuv.org/en/v1.x/misc.html#c.uv_available_parallelism). + * @since v19.4.0, v18.14.0 + */ + function availableParallelism(): number; /** * Returns the operating system name as returned by [`uname(3)`](https://linux.die.net/man/3/uname). For example, it * returns `'Linux'` on Linux, `'Darwin'` on macOS, and `'Windows_NT'` on Windows. @@ -227,7 +239,7 @@ declare module 'os' { * Throws a `SystemError` if a user has no `username` or `homedir`. * @since v6.0.0 */ - function userInfo(options: { encoding: 'buffer' }): UserInfo; + function userInfo(options: { encoding: "buffer" }): UserInfo; function userInfo(options?: { encoding: BufferEncoding }): UserInfo; type SignalConstants = { [key in NodeJS.Signals]: number; @@ -388,7 +400,8 @@ declare module 'os' { const EOL: string; /** * Returns the operating system CPU architecture for which the Node.js binary was - * compiled. Possible values are `'arm'`, `'arm64'`, `'ia32'`, `'mips'`,`'mipsel'`, `'ppc'`, `'ppc64'`, `'s390'`, `'s390x'`, `'x32'`, and `'x64'`. + * compiled. Possible values are `'arm'`, `'arm64'`, `'ia32'`, `'loong64'`,`'mips'`, `'mipsel'`, `'ppc'`, `'ppc64'`, `'riscv64'`, `'s390'`, `'s390x'`, + * and `'x64'`. * * The return value is equivalent to `process.arch`. * @since v0.5.0 @@ -403,8 +416,9 @@ declare module 'os' { */ function version(): string; /** - * Returns a string identifying the operating system platform. The value is set - * at compile time. Possible values are `'aix'`, `'darwin'`, `'freebsd'`,`'linux'`, `'openbsd'`, `'sunos'`, and `'win32'`. + * Returns a string identifying the operating system platform for which + * the Node.js binary was compiled. The value is set at compile time. + * Possible values are `'aix'`, `'darwin'`, `'freebsd'`,`'linux'`,`'openbsd'`, `'sunos'`, and `'win32'`. * * The return value is equivalent to `process.platform`. * @@ -413,6 +427,14 @@ declare module 'os' { * @since v0.5.0 */ function platform(): NodeJS.Platform; + /** + * Returns the machine type as a string, such as `arm`, `arm64`, `aarch64`,`mips`, `mips64`, `ppc64`, `ppc64le`, `s390`, `s390x`, `i386`, `i686`, `x86_64`. + * + * On POSIX systems, the machine type is determined by calling [`uname(3)`](https://linux.die.net/man/3/uname). On Windows, `RtlGetVersion()` is used, and if it is not + * available, `GetVersionExW()` will be used. See [https://en.wikipedia.org/wiki/Uname#Examples](https://en.wikipedia.org/wiki/Uname#Examples) for more information. + * @since v18.9.0, v16.18.0 + */ + function machine(): string; /** * Returns the operating system's default directory for temporary files as a * string. @@ -426,7 +448,7 @@ declare module 'os' { * Possible values are `'BE'` for big endian and `'LE'` for little endian. * @since v0.9.4 */ - function endianness(): 'BE' | 'LE'; + function endianness(): "BE" | "LE"; /** * Returns the scheduling priority for the process specified by `pid`. If `pid` is * not provided or is `0`, the priority of the current process is returned. @@ -451,6 +473,6 @@ declare module 'os' { function setPriority(priority: number): void; function setPriority(pid: number, priority: number): void; } -declare module 'node:os' { - export * from 'os'; +declare module "node:os" { + export * from "os"; } diff --git a/node_modules/@types/node/ts4.8/path.d.ts b/node_modules/@types/node/ts4.8/path.d.ts old mode 100755 new mode 100644 index a647f13..6f07681 --- a/node_modules/@types/node/ts4.8/path.d.ts +++ b/node_modules/@types/node/ts4.8/path.d.ts @@ -1,21 +1,21 @@ -declare module 'path/posix' { - import path = require('path'); +declare module "path/posix" { + import path = require("path"); export = path; } -declare module 'path/win32' { - import path = require('path'); +declare module "path/win32" { + import path = require("path"); export = path; } /** - * The `path` module provides utilities for working with file and directory paths. - * It can be accessed using: + * The `node:path` module provides utilities for working with file and directory + * paths. It can be accessed using: * * ```js - * const path = require('path'); + * const path = require('node:path'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/path.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/path.js) */ -declare module 'path' { +declare module "path" { namespace path { /** * A parsed path object generated by path.parse() or consumed by path.format(). @@ -90,7 +90,7 @@ declare module 'path' { * the current working directory is used as well. The resulting path is normalized, * and trailing slashes are removed unless the path gets resolved to the root directory. * - * @param paths string paths to join. + * @param paths A sequence of paths or path segments. * @throws {TypeError} if any of the arguments is not a string. */ resolve(...paths: string[]): string; @@ -122,10 +122,10 @@ declare module 'path' { * Often used to extract the file name from a fully qualified path. * * @param path the path to evaluate. - * @param ext optionally, an extension to remove from the result. + * @param suffix optionally, an extension to remove from the result. * @throws {TypeError} if `path` is not a string or if `ext` is given and is not a string. */ - basename(path: string, ext?: string): string; + basename(path: string, suffix?: string): string; /** * Return the extension of the path, from the last '.' to end of string in the last portion of the path. * If there is no '.' in the last portion of the path or the first character of it is '.', then it returns an empty string. @@ -137,11 +137,11 @@ declare module 'path' { /** * The platform-specific file separator. '\\' or '/'. */ - readonly sep: '\\' | '/'; + readonly sep: "\\" | "/"; /** * The platform-specific file delimiter. ';' or ':'. */ - readonly delimiter: ';' | ':'; + readonly delimiter: ";" | ":"; /** * Returns an object from a path string - the opposite of format(). * @@ -177,15 +177,15 @@ declare module 'path' { const path: path.PlatformPath; export = path; } -declare module 'node:path' { - import path = require('path'); +declare module "node:path" { + import path = require("path"); export = path; } -declare module 'node:path/posix' { - import path = require('path/posix'); +declare module "node:path/posix" { + import path = require("path/posix"); export = path; } -declare module 'node:path/win32' { - import path = require('path/win32'); +declare module "node:path/win32" { + import path = require("path/win32"); export = path; } diff --git a/node_modules/@types/node/ts4.8/perf_hooks.d.ts b/node_modules/@types/node/ts4.8/perf_hooks.d.ts old mode 100755 new mode 100644 index 6d57bb7..c0ce852 --- a/node_modules/@types/node/ts4.8/perf_hooks.d.ts +++ b/node_modules/@types/node/ts4.8/perf_hooks.d.ts @@ -7,9 +7,10 @@ * * [High Resolution Time](https://www.w3.org/TR/hr-time-2) * * [Performance Timeline](https://w3c.github.io/performance-timeline/) * * [User Timing](https://www.w3.org/TR/user-timing/) + * * [Resource Timing](https://www.w3.org/TR/resource-timing-2/) * * ```js - * const { PerformanceObserver, performance } = require('perf_hooks'); + * const { PerformanceObserver, performance } = require('node:perf_hooks'); * * const obs = new PerformanceObserver((items) => { * console.log(items.getEntries()[0].duration); @@ -26,11 +27,11 @@ * performance.measure('A to B', 'A', 'B'); * }); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/perf_hooks.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/perf_hooks.js) */ -declare module 'perf_hooks' { - import { AsyncResource } from 'node:async_hooks'; - type EntryType = 'node' | 'mark' | 'measure' | 'gc' | 'function' | 'http2' | 'http'; +declare module "perf_hooks" { + import { AsyncResource } from "node:async_hooks"; + type EntryType = "node" | "mark" | "measure" | "gc" | "function" | "http2" | "http" | "dns" | "net"; interface NodeGCPerformanceDetail { /** * When `performanceEntry.entryType` is equal to 'gc', `the performance.kind` property identifies @@ -46,6 +47,7 @@ declare module 'perf_hooks' { readonly flags?: number | undefined; } /** + * The constructor of this class is not exposed to users directly. * @since v8.5.0 */ class PerformanceEntry { @@ -85,6 +87,24 @@ declare module 'perf_hooks' { * @since v16.0.0 */ readonly detail?: NodeGCPerformanceDetail | unknown | undefined; // TODO: Narrow this based on entry type. + toJSON(): any; + } + /** + * Exposes marks created via the `Performance.mark()` method. + * @since v18.2.0, v16.17.0 + */ + class PerformanceMark extends PerformanceEntry { + readonly duration: 0; + readonly entryType: "mark"; + } + /** + * Exposes measures created via the `Performance.measure()` method. + * + * The constructor of this class is not exposed to users directly. + * @since v18.2.0, v16.17.0 + */ + class PerformanceMeasure extends PerformanceEntry { + readonly entryType: "measure"; } /** * _This property is an extension by Node.js. It is not available in Web browsers._ @@ -146,7 +166,10 @@ declare module 'perf_hooks' { * @param util1 The result of a previous call to eventLoopUtilization() * @param util2 The result of a previous call to eventLoopUtilization() prior to util1 */ - type EventLoopUtilityFunction = (util1?: EventLoopUtilization, util2?: EventLoopUtilization) => EventLoopUtilization; + type EventLoopUtilityFunction = ( + util1?: EventLoopUtilization, + util2?: EventLoopUtilization, + ) => EventLoopUtilization; interface MarkOptions { /** * Additional optional detail to include with the mark. @@ -226,8 +249,9 @@ declare module 'perf_hooks' { * and whose performanceEntry.duration is always 0. * Performance marks are used to mark specific significant moments in the Performance Timeline. * @param name + * @return The PerformanceMark entry that was created */ - mark(name?: string, options?: MarkOptions): void; + mark(name?: string, options?: MarkOptions): PerformanceMark; /** * Creates a new PerformanceMeasure entry in the Performance Timeline. * A PerformanceMeasure is a subclass of PerformanceEntry whose performanceEntry.entryType is always 'measure', @@ -242,9 +266,10 @@ declare module 'perf_hooks' { * @param name * @param startMark * @param endMark + * @return The PerformanceMeasure entry that was created */ - measure(name: string, startMark?: string, endMark?: string): void; - measure(name: string, options: MeasureOptions): void; + measure(name: string, startMark?: string, endMark?: string): PerformanceMeasure; + measure(name: string, options: MeasureOptions): PerformanceMeasure; /** * An instance of the PerformanceNodeTiming class that provides performance metrics for specific Node.js operational milestones. */ @@ -278,8 +303,8 @@ declare module 'perf_hooks' { * ```js * const { * performance, - * PerformanceObserver - * } = require('perf_hooks'); + * PerformanceObserver, + * } = require('node:perf_hooks'); * * const obs = new PerformanceObserver((perfObserverList, observer) => { * console.log(perfObserverList.getEntries()); @@ -289,16 +314,20 @@ declare module 'perf_hooks' { * * name: 'test', * * entryType: 'mark', * * startTime: 81.465639, - * * duration: 0 + * * duration: 0, + * * detail: null * * }, * * PerformanceEntry { * * name: 'meow', * * entryType: 'mark', * * startTime: 81.860064, - * * duration: 0 + * * duration: 0, + * * detail: null * * } * * ] * + * performance.clearMarks(); + * performance.clearMeasures(); * observer.disconnect(); * }); * obs.observe({ type: 'mark' }); @@ -317,8 +346,8 @@ declare module 'perf_hooks' { * ```js * const { * performance, - * PerformanceObserver - * } = require('perf_hooks'); + * PerformanceObserver, + * } = require('node:perf_hooks'); * * const obs = new PerformanceObserver((perfObserverList, observer) => { * console.log(perfObserverList.getEntriesByName('meow')); @@ -328,7 +357,8 @@ declare module 'perf_hooks' { * * name: 'meow', * * entryType: 'mark', * * startTime: 98.545991, - * * duration: 0 + * * duration: 0, + * * detail: null * * } * * ] * @@ -341,11 +371,15 @@ declare module 'perf_hooks' { * * name: 'test', * * entryType: 'mark', * * startTime: 63.518931, - * * duration: 0 + * * duration: 0, + * * detail: null * * } * * ] * * console.log(perfObserverList.getEntriesByName('test', 'measure')); // [] + * + * performance.clearMarks(); + * performance.clearMeasures(); * observer.disconnect(); * }); * obs.observe({ entryTypes: ['mark', 'measure'] }); @@ -363,8 +397,8 @@ declare module 'perf_hooks' { * ```js * const { * performance, - * PerformanceObserver - * } = require('perf_hooks'); + * PerformanceObserver, + * } = require('node:perf_hooks'); * * const obs = new PerformanceObserver((perfObserverList, observer) => { * console.log(perfObserverList.getEntriesByType('mark')); @@ -374,16 +408,20 @@ declare module 'perf_hooks' { * * name: 'test', * * entryType: 'mark', * * startTime: 55.897834, - * * duration: 0 + * * duration: 0, + * * detail: null * * }, * * PerformanceEntry { * * name: 'meow', * * entryType: 'mark', * * startTime: 56.350146, - * * duration: 0 + * * duration: 0, + * * detail: null * * } * * ] * + * performance.clearMarks(); + * performance.clearMeasures(); * observer.disconnect(); * }); * obs.observe({ type: 'mark' }); @@ -396,6 +434,9 @@ declare module 'perf_hooks' { getEntriesByType(type: EntryType): PerformanceEntry[]; } type PerformanceObserverCallback = (list: PerformanceObserverEntryList, observer: PerformanceObserver) => void; + /** + * @since v8.5.0 + */ class PerformanceObserver extends AsyncResource { constructor(callback: PerformanceObserverCallback); /** @@ -409,11 +450,11 @@ declare module 'perf_hooks' { * ```js * const { * performance, - * PerformanceObserver - * } = require('perf_hooks'); + * PerformanceObserver, + * } = require('node:perf_hooks'); * * const obs = new PerformanceObserver((list, observer) => { - * // Called three times synchronously. `list` contains one item. + * // Called once asynchronously. `list` contains three items. * }); * obs.observe({ type: 'mark' }); * @@ -425,13 +466,13 @@ declare module 'perf_hooks' { observe( options: | { - entryTypes: ReadonlyArray; - buffered?: boolean | undefined; - } + entryTypes: readonly EntryType[]; + buffered?: boolean | undefined; + } | { - type: EntryType; - buffered?: boolean | undefined; - } + type: EntryType; + buffered?: boolean | undefined; + }, ): void; } namespace constants { @@ -516,7 +557,7 @@ declare module 'perf_hooks' { } interface RecordableHistogram extends Histogram { /** - * @since v15.9.0 + * @since v15.9.0, v14.18.0 * @param val The amount to record in the histogram. */ record(val: number | bigint): void; @@ -525,9 +566,14 @@ declare module 'perf_hooks' { * previous call to `recordDelta()` and records that amount in the histogram. * * ## Examples - * @since v15.9.0 + * @since v15.9.0, v14.18.0 */ recordDelta(): void; + /** + * Adds the values from `other` to this histogram. + * @since v17.4.0, v16.14.0 + */ + add(other: RecordableHistogram): void; } /** * _This property is an extension by Node.js. It is not available in Web browsers._ @@ -542,7 +588,7 @@ declare module 'perf_hooks' { * detect. * * ```js - * const { monitorEventLoopDelay } = require('perf_hooks'); + * const { monitorEventLoopDelay } = require('node:perf_hooks'); * const h = monitorEventLoopDelay({ resolution: 20 }); * h.enable(); * // Do something. @@ -577,10 +623,23 @@ declare module 'perf_hooks' { } /** * Returns a `RecordableHistogram`. - * @since v15.9.0 + * @since v15.9.0, v14.18.0 */ function createHistogram(options?: CreateHistogramOptions): RecordableHistogram; + import { performance as _performance } from "perf_hooks"; + global { + /** + * `performance` is a global reference for `require('perf_hooks').performance` + * https://nodejs.org/api/globals.html#performance + * @since v16.0.0 + */ + var performance: typeof globalThis extends { + onmessage: any; + performance: infer T; + } ? T + : typeof _performance; + } } -declare module 'node:perf_hooks' { - export * from 'perf_hooks'; +declare module "node:perf_hooks" { + export * from "perf_hooks"; } diff --git a/node_modules/@types/node/ts4.8/process.d.ts b/node_modules/@types/node/ts4.8/process.d.ts old mode 100755 new mode 100644 index 2d0ef86..d22308f --- a/node_modules/@types/node/ts4.8/process.d.ts +++ b/node_modules/@types/node/ts4.8/process.d.ts @@ -1,6 +1,6 @@ -declare module 'process' { - import * as tty from 'node:tty'; - import { Worker } from 'node:worker_threads'; +declare module "process" { + import * as tty from "node:tty"; + import { Worker } from "node:worker_threads"; global { var process: NodeJS.Process; namespace NodeJS { @@ -48,47 +48,70 @@ declare module 'process' { modules: string; openssl: string; } - type Platform = 'aix' | 'android' | 'darwin' | 'freebsd' | 'haiku' | 'linux' | 'openbsd' | 'sunos' | 'win32' | 'cygwin' | 'netbsd'; + type Platform = + | "aix" + | "android" + | "darwin" + | "freebsd" + | "haiku" + | "linux" + | "openbsd" + | "sunos" + | "win32" + | "cygwin" + | "netbsd"; + type Architecture = + | "arm" + | "arm64" + | "ia32" + | "mips" + | "mipsel" + | "ppc" + | "ppc64" + | "riscv64" + | "s390" + | "s390x" + | "x64"; type Signals = - | 'SIGABRT' - | 'SIGALRM' - | 'SIGBUS' - | 'SIGCHLD' - | 'SIGCONT' - | 'SIGFPE' - | 'SIGHUP' - | 'SIGILL' - | 'SIGINT' - | 'SIGIO' - | 'SIGIOT' - | 'SIGKILL' - | 'SIGPIPE' - | 'SIGPOLL' - | 'SIGPROF' - | 'SIGPWR' - | 'SIGQUIT' - | 'SIGSEGV' - | 'SIGSTKFLT' - | 'SIGSTOP' - | 'SIGSYS' - | 'SIGTERM' - | 'SIGTRAP' - | 'SIGTSTP' - | 'SIGTTIN' - | 'SIGTTOU' - | 'SIGUNUSED' - | 'SIGURG' - | 'SIGUSR1' - | 'SIGUSR2' - | 'SIGVTALRM' - | 'SIGWINCH' - | 'SIGXCPU' - | 'SIGXFSZ' - | 'SIGBREAK' - | 'SIGLOST' - | 'SIGINFO'; - type UncaughtExceptionOrigin = 'uncaughtException' | 'unhandledRejection'; - type MultipleResolveType = 'resolve' | 'reject'; + | "SIGABRT" + | "SIGALRM" + | "SIGBUS" + | "SIGCHLD" + | "SIGCONT" + | "SIGFPE" + | "SIGHUP" + | "SIGILL" + | "SIGINT" + | "SIGIO" + | "SIGIOT" + | "SIGKILL" + | "SIGPIPE" + | "SIGPOLL" + | "SIGPROF" + | "SIGPWR" + | "SIGQUIT" + | "SIGSEGV" + | "SIGSTKFLT" + | "SIGSTOP" + | "SIGSYS" + | "SIGTERM" + | "SIGTRAP" + | "SIGTSTP" + | "SIGTTIN" + | "SIGTTOU" + | "SIGUNUSED" + | "SIGURG" + | "SIGUSR1" + | "SIGUSR2" + | "SIGVTALRM" + | "SIGWINCH" + | "SIGXCPU" + | "SIGXFSZ" + | "SIGBREAK" + | "SIGLOST" + | "SIGINFO"; + type UncaughtExceptionOrigin = "uncaughtException" | "unhandledRejection"; + type MultipleResolveType = "resolve" | "reject"; type BeforeExitListener = (code: number) => void; type DisconnectListener = () => void; type ExitListener = (code: number) => void; @@ -96,13 +119,17 @@ declare module 'process' { type UncaughtExceptionListener = (error: Error, origin: UncaughtExceptionOrigin) => void; /** * Most of the time the unhandledRejection will be an Error, but this should not be relied upon - * as *anything* can be thrown/rejected, it is therefore unsafe to assume the the value is an Error. + * as *anything* can be thrown/rejected, it is therefore unsafe to assume that the value is an Error. */ type UnhandledRejectionListener = (reason: unknown, promise: Promise) => void; type WarningListener = (warning: Error) => void; type MessageListener = (message: unknown, sendHandle: unknown) => void; type SignalsListener = (signal: Signals) => void; - type MultipleResolveListener = (type: MultipleResolveType, promise: Promise, value: unknown) => void; + type MultipleResolveListener = ( + type: MultipleResolveType, + promise: Promise, + value: unknown, + ) => void; type WorkerListener = (worker: Worker) => void; interface Socket extends ReadWriteStream { isTTY?: true | undefined; @@ -249,7 +276,7 @@ declare module 'process' { * For example, to copy `process.stdin` to `process.stdout`: * * ```js - * import { stdin, stdout } from 'process'; + * import { stdin, stdout } from 'node:process'; * * stdin.pipe(stdout); * ``` @@ -296,7 +323,7 @@ declare module 'process' { * For example, assuming the following script for `process-args.js`: * * ```js - * import { argv } from 'process'; + * import { argv } from 'node:process'; * * // print process.argv * argv.forEach((val, index) => { @@ -306,8 +333,8 @@ declare module 'process' { * * Launching the Node.js process as: * - * ```console - * $ node process-args.js one two=three four + * ```bash + * node process-args.js one two=three four * ``` * * Would generate the output: @@ -343,8 +370,8 @@ declare module 'process' { * the script name. These options are useful in order to spawn child processes with * the same execution environment as the parent. * - * ```console - * $ node --harmony script.js --version + * ```bash + * node --harmony script.js --version * ``` * * Results in `process.execArgv`: @@ -388,7 +415,7 @@ declare module 'process' { * the specified `directory` does not exist). * * ```js - * import { chdir, cwd } from 'process'; + * import { chdir, cwd } from 'node:process'; * * console.log(`Starting directory: ${cwd()}`); * try { @@ -408,7 +435,7 @@ declare module 'process' { * process. * * ```js - * import { cwd } from 'process'; + * import { cwd } from 'node:process'; * * console.log(`Current directory: ${cwd()}`); * ``` @@ -419,7 +446,7 @@ declare module 'process' { * The port used by the Node.js debugger when enabled. * * ```js - * import process from 'process'; + * import process from 'node:process'; * * process.debugPort = 5858; * ``` @@ -431,12 +458,12 @@ declare module 'process' { * specific process warnings. These can be listened for by adding a handler to the `'warning'` event. * * ```js - * import { emitWarning } from 'process'; + * import { emitWarning } from 'node:process'; * * // Emit a warning with a code and additional detail. * emitWarning('Something happened!', { * code: 'MY_WARNING', - * detail: 'This is some additional information' + * detail: 'This is some additional information', * }); * // Emits: * // (node:56338) [MY_WARNING] Warning: Something happened! @@ -446,7 +473,7 @@ declare module 'process' { * In this example, an `Error` object is generated internally by`process.emitWarning()` and passed through to the `'warning'` handler. * * ```js - * import process from 'process'; + * import process from 'node:process'; * * process.on('warning', (warning) => { * console.warn(warning.name); // 'Warning' @@ -491,14 +518,14 @@ declare module 'process' { * to other `Worker` threads. * In other words, the following example would not work: * - * ```console - * $ node -e 'process.env.foo = "bar"' && echo $foo + * ```bash + * node -e 'process.env.foo = "bar"' && echo $foo * ``` * * While the following will: * * ```js - * import { env } from 'process'; + * import { env } from 'node:process'; * * env.foo = 'bar'; * console.log(env.foo); @@ -509,7 +536,7 @@ declare module 'process' { * throw an error when the value is not a string, number, or boolean. * * ```js - * import { env } from 'process'; + * import { env } from 'node:process'; * * env.test = null; * console.log(env.test); @@ -522,7 +549,7 @@ declare module 'process' { * Use `delete` to delete a property from `process.env`. * * ```js - * import { env } from 'process'; + * import { env } from 'node:process'; * * env.TEST = 1; * delete env.TEST; @@ -533,7 +560,7 @@ declare module 'process' { * On Windows operating systems, environment variables are case-insensitive. * * ```js - * import { env } from 'process'; + * import { env } from 'node:process'; * * env.TEST = 1; * console.log(env.test); @@ -542,10 +569,11 @@ declare module 'process' { * * Unless explicitly specified when creating a `Worker` instance, * each `Worker` thread has its own copy of `process.env`, based on its - * parent thread’s `process.env`, or whatever was specified as the `env` option + * parent thread's `process.env`, or whatever was specified as the `env` option * to the `Worker` constructor. Changes to `process.env` will not be visible * across `Worker` threads, and only the main thread can make changes that - * are visible to the operating system or to native add-ons. + * are visible to the operating system or to native add-ons. On Windows, a copy of`process.env` on a `Worker` instance operates in a case-sensitive manner + * unlike the main thread. * @since v0.1.27 */ env: ProcessEnv; @@ -559,7 +587,7 @@ declare module 'process' { * To exit with a 'failure' code: * * ```js - * import { exit } from 'process'; + * import { exit } from 'node:process'; * * exit(1); * ``` @@ -578,7 +606,7 @@ declare module 'process' { * truncated and lost: * * ```js - * import { exit } from 'process'; + * import { exit } from 'node:process'; * * // This is an example of what *not* to do: * if (someConditionNotMet()) { @@ -589,13 +617,13 @@ declare module 'process' { * * The reason this is problematic is because writes to `process.stdout` in Node.js * are sometimes _asynchronous_ and may occur over multiple ticks of the Node.js - * event loop. Calling `process.exit()`, however, forces the process to exit_before_ those additional writes to `stdout` can be performed. + * event loop. Calling `process.exit()`, however, forces the process to exit _before_ those additional writes to `stdout` can be performed. * * Rather than calling `process.exit()` directly, the code _should_ set the`process.exitCode` and allow the process to exit naturally by avoiding * scheduling any additional work for the event loop: * * ```js - * import process from 'process'; + * import process from 'node:process'; * * // How to properly set the exit code while letting * // the process exit gracefully. @@ -612,7 +640,7 @@ declare module 'process' { * In `Worker` threads, this function stops the current thread rather * than the current process. * @since v0.1.13 - * @param [code=0] The exit code. + * @param [code=0] The exit code. For string type, only integer strings (e.g.,'1') are allowed. */ exit(code?: number): never; /** @@ -641,7 +669,7 @@ declare module 'process' { * Android). * @since v0.1.31 */ - getgid(): number; + getgid?: () => number; /** * The `process.setgid()` method sets the group identity of the process. (See [`setgid(2)`](http://man7.org/linux/man-pages/man2/setgid.2.html).) The `id` can be passed as either a * numeric ID or a group name @@ -668,7 +696,7 @@ declare module 'process' { * @since v0.1.31 * @param id The group name or ID */ - setgid(id: number | string): void; + setgid?: (id: number | string) => void; /** * The `process.getuid()` method returns the numeric user identity of the process. * (See [`getuid(2)`](http://man7.org/linux/man-pages/man2/getuid.2.html).) @@ -685,7 +713,7 @@ declare module 'process' { * Android). * @since v0.1.28 */ - getuid(): number; + getuid?: () => number; /** * The `process.setuid(id)` method sets the user identity of the process. (See [`setuid(2)`](http://man7.org/linux/man-pages/man2/setuid.2.html).) The `id` can be passed as either a * numeric ID or a username string. @@ -711,7 +739,7 @@ declare module 'process' { * This feature is not available in `Worker` threads. * @since v0.1.28 */ - setuid(id: number | string): void; + setuid?: (id: number | string) => void; /** * The `process.geteuid()` method returns the numerical effective user identity of * the process. (See [`geteuid(2)`](http://man7.org/linux/man-pages/man2/geteuid.2.html).) @@ -728,7 +756,7 @@ declare module 'process' { * Android). * @since v2.0.0 */ - geteuid(): number; + geteuid?: () => number; /** * The `process.seteuid()` method sets the effective user identity of the process. * (See [`seteuid(2)`](http://man7.org/linux/man-pages/man2/seteuid.2.html).) The `id` can be passed as either a numeric ID or a username @@ -755,7 +783,7 @@ declare module 'process' { * @since v2.0.0 * @param id A user name or ID */ - seteuid(id: number | string): void; + seteuid?: (id: number | string) => void; /** * The `process.getegid()` method returns the numerical effective group identity * of the Node.js process. (See [`getegid(2)`](http://man7.org/linux/man-pages/man2/getegid.2.html).) @@ -772,7 +800,7 @@ declare module 'process' { * Android). * @since v2.0.0 */ - getegid(): number; + getegid?: () => number; /** * The `process.setegid()` method sets the effective group identity of the process. * (See [`setegid(2)`](http://man7.org/linux/man-pages/man2/setegid.2.html).) The `id` can be passed as either a numeric ID or a group @@ -799,7 +827,7 @@ declare module 'process' { * @since v2.0.0 * @param id A group name or ID */ - setegid(id: number | string): void; + setegid?: (id: number | string) => void; /** * The `process.getgroups()` method returns an array with the supplementary group * IDs. POSIX leaves it unspecified if the effective group ID is included but @@ -817,7 +845,7 @@ declare module 'process' { * Android). * @since v0.9.4 */ - getgroups(): number[]; + getgroups?: () => number[]; /** * The `process.setgroups()` method sets the supplementary group IDs for the * Node.js process. This is a privileged operation that requires the Node.js @@ -843,7 +871,7 @@ declare module 'process' { * This feature is not available in `Worker` threads. * @since v0.9.4 */ - setgroups(groups: ReadonlyArray): void; + setgroups?: (groups: ReadonlyArray) => void; /** * The `process.setUncaughtExceptionCaptureCallback()` function sets a function * that will be invoked when an uncaught exception occurs, which will receive the @@ -868,11 +896,29 @@ declare module 'process' { * @since v9.3.0 */ hasUncaughtExceptionCaptureCallback(): boolean; + /** + * The `process.sourceMapsEnabled` property returns whether the [Source Map v3](https://sourcemaps.info/spec.html) support for stack traces is enabled. + * @since v20.7.0 + * @experimental + */ + readonly sourceMapsEnabled: boolean; + /** + * This function enables or disables the [Source Map v3](https://sourcemaps.info/spec.html) support for + * stack traces. + * + * It provides same features as launching Node.js process with commandline options`--enable-source-maps`. + * + * Only source maps in JavaScript files that are loaded after source maps has been + * enabled will be parsed and loaded. + * @since v16.6.0, v14.18.0 + * @experimental + */ + setSourceMapsEnabled(value: boolean): void; /** * The `process.version` property contains the Node.js version string. * * ```js - * import { version } from 'process'; + * import { version } from 'node:process'; * * console.log(`Version: ${version}`); * // Version: v14.8.0 @@ -889,7 +935,7 @@ declare module 'process' { * to load modules that were compiled against a different module ABI version. * * ```js - * import { versions } from 'process'; + * import { versions } from 'node:process'; * * console.log(versions); * ``` @@ -897,30 +943,39 @@ declare module 'process' { * Will generate an object similar to: * * ```console - * { node: '11.13.0', - * v8: '7.0.276.38-node.18', - * uv: '1.27.0', - * zlib: '1.2.11', - * brotli: '1.0.7', - * ares: '1.15.0', - * modules: '67', - * nghttp2: '1.34.0', - * napi: '4', - * llhttp: '1.1.1', - * openssl: '1.1.1b', - * cldr: '34.0', - * icu: '63.1', - * tz: '2018e', - * unicode: '11.0' } + * { node: '20.2.0', + * acorn: '8.8.2', + * ada: '2.4.0', + * ares: '1.19.0', + * base64: '0.5.0', + * brotli: '1.0.9', + * cjs_module_lexer: '1.2.2', + * cldr: '43.0', + * icu: '73.1', + * llhttp: '8.1.0', + * modules: '115', + * napi: '8', + * nghttp2: '1.52.0', + * nghttp3: '0.7.0', + * ngtcp2: '0.8.1', + * openssl: '3.0.8+quic', + * simdutf: '3.2.9', + * tz: '2023c', + * undici: '5.22.0', + * unicode: '15.0', + * uv: '1.44.2', + * uvwasi: '0.0.16', + * v8: '11.3.244.8-node.9', + * zlib: '1.2.13' } * ``` * @since v0.2.0 */ readonly versions: ProcessVersions; /** - * The `process.config` property returns an `Object` containing the JavaScript - * representation of the configure options used to compile the current Node.js - * executable. This is the same as the `config.gypi` file that was produced when - * running the `./configure` script. + * The `process.config` property returns a frozen `Object` containing the + * JavaScript representation of the configure options used to compile the current + * Node.js executable. This is the same as the `config.gypi` file that was produced + * when running the `./configure` script. * * An example of the possible output looks like: * @@ -942,7 +997,6 @@ declare module 'process' { * node_shared_http_parser: 'false', * node_shared_libuv: 'false', * node_shared_zlib: 'false', - * node_use_dtrace: 'false', * node_use_openssl: 'true', * node_shared_openssl: 'false', * strict_aliasing: 'true', @@ -951,13 +1005,6 @@ declare module 'process' { * } * } * ``` - * - * The `process.config` property is **not** read-only and there are existing - * modules in the ecosystem that are known to extend, modify, or entirely replace - * the value of `process.config`. - * - * Modifying the `process.config` property, or any child-property of the`process.config` object has been deprecated. The `process.config` will be made - * read-only in a future release. * @since v0.7.7 */ readonly config: ProcessConfig; @@ -976,7 +1023,7 @@ declare module 'process' { * other than kill the target process. * * ```js - * import process, { kill } from 'process'; + * import process, { kill } from 'node:process'; * * process.on('SIGHUP', () => { * console.log('Got SIGHUP signal.'); @@ -1001,7 +1048,7 @@ declare module 'process' { * The `process.pid` property returns the PID of the process. * * ```js - * import { pid } from 'process'; + * import { pid } from 'node:process'; * * console.log(`This process is pid ${pid}`); * ``` @@ -1013,7 +1060,7 @@ declare module 'process' { * current process. * * ```js - * import { ppid } from 'process'; + * import { ppid } from 'node:process'; * * console.log(`The parent process is pid ${ppid}`); * ``` @@ -1040,19 +1087,19 @@ declare module 'process' { title: string; /** * The operating system CPU architecture for which the Node.js binary was compiled. - * Possible values are: `'arm'`, `'arm64'`, `'ia32'`, `'mips'`,`'mipsel'`, `'ppc'`,`'ppc64'`, `'s390'`, `'s390x'`, `'x32'`, and `'x64'`. + * Possible values are: `'arm'`, `'arm64'`, `'ia32'`, `'loong64'`, `'mips'`,`'mipsel'`, `'ppc'`, `'ppc64'`, `'riscv64'`, `'s390'`, `'s390x'`, and `'x64'`. * * ```js - * import { arch } from 'process'; + * import { arch } from 'node:process'; * * console.log(`This processor architecture is ${arch}`); * ``` * @since v0.5.0 */ - readonly arch: string; + readonly arch: Architecture; /** * The `process.platform` property returns a string identifying the operating - * system platform on which the Node.js process is running. + * system platform for which the Node.js binary was compiled. * * Currently possible values are: * @@ -1065,7 +1112,7 @@ declare module 'process' { * * `'win32'` * * ```js - * import { platform } from 'process'; + * import { platform } from 'node:process'; * * console.log(`This platform is ${platform}`); * ``` @@ -1088,6 +1135,17 @@ declare module 'process' { */ mainModule?: Module | undefined; memoryUsage: MemoryUsageFn; + /** + * Gets the amount of memory available to the process (in bytes) based on + * limits imposed by the OS. If there is no such constraint, or the constraint + * is unknown, `undefined` is returned. + * + * See [`uv_get_constrained_memory`](https://docs.libuv.org/en/v1.x/misc.html#c.uv_get_constrained_memory) for more + * information. + * @since v19.6.0, v18.15.0 + * @experimental + */ + constrainedMemory(): number | undefined; /** * The `process.cpuUsage()` method returns the user and system CPU time usage of * the current process, in an object with properties `user` and `system`, whose @@ -1099,7 +1157,7 @@ declare module 'process' { * argument to the function, to get a diff reading. * * ```js - * import { cpuUsage } from 'process'; + * import { cpuUsage } from 'node:process'; * * const startUsage = cpuUsage(); * // { user: 38579, system: 6986 } @@ -1123,7 +1181,7 @@ declare module 'process' { * See the [Event Loop](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/#process-nexttick) guide for more background. * * ```js - * import { nextTick } from 'process'; + * import { nextTick } from 'node:process'; * * console.log('start'); * nextTick(() => { @@ -1141,7 +1199,7 @@ declare module 'process' { * I/O has occurred: * * ```js - * import { nextTick } from 'process'; + * import { nextTick } from 'node:process'; * * function MyThing(options) { * this.setupOptions(options); @@ -1189,7 +1247,7 @@ declare module 'process' { * The following approach is much better: * * ```js - * import { nextTick } from 'process'; + * import { nextTick } from 'node:process'; * * function definitelyAsync(arg, cb) { * if (arg) { @@ -1214,10 +1272,10 @@ declare module 'process' { * ```js * { * name: 'node', - * lts: 'Erbium', - * sourceUrl: 'https://nodejs.org/download/release/v12.18.1/node-v12.18.1.tar.gz', - * headersUrl: 'https://nodejs.org/download/release/v12.18.1/node-v12.18.1-headers.tar.gz', - * libUrl: 'https://nodejs.org/download/release/v12.18.1/win-x64/node.lib' + * lts: 'Hydrogen', + * sourceUrl: 'https://nodejs.org/download/release/v18.12.0/node-v18.12.0.tar.gz', + * headersUrl: 'https://nodejs.org/download/release/v18.12.0/node-v18.12.0-headers.tar.gz', + * libUrl: 'https://nodejs.org/download/release/v18.12.0/win-x64/node.lib' * } * ``` * @@ -1258,11 +1316,28 @@ declare module 'process' { */ uptime(): number; hrtime: HRTime; + /** + * If the Node.js process was spawned with an IPC channel, the process.channel property is a reference to the IPC channel. + * If no IPC channel exists, this property is undefined. + * @since v7.1.0 + */ + channel?: { + /** + * This method makes the IPC channel keep the event loop of the process running if .unref() has been called before. + * @since v7.1.0 + */ + ref(): void; + /** + * This method makes the IPC channel not keep the event loop of the process running, and lets it finish even while the channel is open. + * @since v7.1.0 + */ + unref(): void; + }; /** * If Node.js is spawned with an IPC channel, the `process.send()` method can be * used to send messages to the parent process. Messages will be received as a `'message'` event on the parent's `ChildProcess` object. * - * If Node.js was not spawned with an IPC channel, `process.send` will be`undefined`. + * If Node.js was not spawned with an IPC channel, `process.send` will be `undefined`. * * The message goes through serialization and parsing. The resulting message might * not be the same as what is originally sent. @@ -1275,7 +1350,7 @@ declare module 'process' { options?: { swallowErrors?: boolean | undefined; }, - callback?: (error: Error | null) => void + callback?: (error: Error | null) => void, ): boolean; /** * If the Node.js process is spawned with an IPC channel (see the `Child Process` and `Cluster` documentation), the `process.disconnect()` method will close the @@ -1321,7 +1396,7 @@ declare module 'process' { * dashes: * * ```js - * import { allowedNodeEnvironmentFlags } from 'process'; + * import { allowedNodeEnvironmentFlags } from 'node:process'; * * allowedNodeEnvironmentFlags.forEach((flag) => { * // -r @@ -1347,7 +1422,7 @@ declare module 'process' { report?: ProcessReport | undefined; /** * ```js - * import { resourceUsage } from 'process'; + * import { resourceUsage } from 'node:process'; * * console.log(resourceUsage()); * /* @@ -1384,98 +1459,103 @@ declare module 'process' { */ traceDeprecation: boolean; /* EventEmitter */ - addListener(event: 'beforeExit', listener: BeforeExitListener): this; - addListener(event: 'disconnect', listener: DisconnectListener): this; - addListener(event: 'exit', listener: ExitListener): this; - addListener(event: 'rejectionHandled', listener: RejectionHandledListener): this; - addListener(event: 'uncaughtException', listener: UncaughtExceptionListener): this; - addListener(event: 'uncaughtExceptionMonitor', listener: UncaughtExceptionListener): this; - addListener(event: 'unhandledRejection', listener: UnhandledRejectionListener): this; - addListener(event: 'warning', listener: WarningListener): this; - addListener(event: 'message', listener: MessageListener): this; + addListener(event: "beforeExit", listener: BeforeExitListener): this; + addListener(event: "disconnect", listener: DisconnectListener): this; + addListener(event: "exit", listener: ExitListener): this; + addListener(event: "rejectionHandled", listener: RejectionHandledListener): this; + addListener(event: "uncaughtException", listener: UncaughtExceptionListener): this; + addListener(event: "uncaughtExceptionMonitor", listener: UncaughtExceptionListener): this; + addListener(event: "unhandledRejection", listener: UnhandledRejectionListener): this; + addListener(event: "warning", listener: WarningListener): this; + addListener(event: "message", listener: MessageListener): this; addListener(event: Signals, listener: SignalsListener): this; - addListener(event: 'multipleResolves', listener: MultipleResolveListener): this; - addListener(event: 'worker', listener: WorkerListener): this; - emit(event: 'beforeExit', code: number): boolean; - emit(event: 'disconnect'): boolean; - emit(event: 'exit', code: number): boolean; - emit(event: 'rejectionHandled', promise: Promise): boolean; - emit(event: 'uncaughtException', error: Error): boolean; - emit(event: 'uncaughtExceptionMonitor', error: Error): boolean; - emit(event: 'unhandledRejection', reason: unknown, promise: Promise): boolean; - emit(event: 'warning', warning: Error): boolean; - emit(event: 'message', message: unknown, sendHandle: unknown): this; - emit(event: Signals, signal: Signals): boolean; - emit(event: 'multipleResolves', type: MultipleResolveType, promise: Promise, value: unknown): this; - emit(event: 'worker', listener: WorkerListener): this; - on(event: 'beforeExit', listener: BeforeExitListener): this; - on(event: 'disconnect', listener: DisconnectListener): this; - on(event: 'exit', listener: ExitListener): this; - on(event: 'rejectionHandled', listener: RejectionHandledListener): this; - on(event: 'uncaughtException', listener: UncaughtExceptionListener): this; - on(event: 'uncaughtExceptionMonitor', listener: UncaughtExceptionListener): this; - on(event: 'unhandledRejection', listener: UnhandledRejectionListener): this; - on(event: 'warning', listener: WarningListener): this; - on(event: 'message', listener: MessageListener): this; + addListener(event: "multipleResolves", listener: MultipleResolveListener): this; + addListener(event: "worker", listener: WorkerListener): this; + emit(event: "beforeExit", code: number): boolean; + emit(event: "disconnect"): boolean; + emit(event: "exit", code: number): boolean; + emit(event: "rejectionHandled", promise: Promise): boolean; + emit(event: "uncaughtException", error: Error): boolean; + emit(event: "uncaughtExceptionMonitor", error: Error): boolean; + emit(event: "unhandledRejection", reason: unknown, promise: Promise): boolean; + emit(event: "warning", warning: Error): boolean; + emit(event: "message", message: unknown, sendHandle: unknown): this; + emit(event: Signals, signal?: Signals): boolean; + emit( + event: "multipleResolves", + type: MultipleResolveType, + promise: Promise, + value: unknown, + ): this; + emit(event: "worker", listener: WorkerListener): this; + on(event: "beforeExit", listener: BeforeExitListener): this; + on(event: "disconnect", listener: DisconnectListener): this; + on(event: "exit", listener: ExitListener): this; + on(event: "rejectionHandled", listener: RejectionHandledListener): this; + on(event: "uncaughtException", listener: UncaughtExceptionListener): this; + on(event: "uncaughtExceptionMonitor", listener: UncaughtExceptionListener): this; + on(event: "unhandledRejection", listener: UnhandledRejectionListener): this; + on(event: "warning", listener: WarningListener): this; + on(event: "message", listener: MessageListener): this; on(event: Signals, listener: SignalsListener): this; - on(event: 'multipleResolves', listener: MultipleResolveListener): this; - on(event: 'worker', listener: WorkerListener): this; + on(event: "multipleResolves", listener: MultipleResolveListener): this; + on(event: "worker", listener: WorkerListener): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'beforeExit', listener: BeforeExitListener): this; - once(event: 'disconnect', listener: DisconnectListener): this; - once(event: 'exit', listener: ExitListener): this; - once(event: 'rejectionHandled', listener: RejectionHandledListener): this; - once(event: 'uncaughtException', listener: UncaughtExceptionListener): this; - once(event: 'uncaughtExceptionMonitor', listener: UncaughtExceptionListener): this; - once(event: 'unhandledRejection', listener: UnhandledRejectionListener): this; - once(event: 'warning', listener: WarningListener): this; - once(event: 'message', listener: MessageListener): this; + once(event: "beforeExit", listener: BeforeExitListener): this; + once(event: "disconnect", listener: DisconnectListener): this; + once(event: "exit", listener: ExitListener): this; + once(event: "rejectionHandled", listener: RejectionHandledListener): this; + once(event: "uncaughtException", listener: UncaughtExceptionListener): this; + once(event: "uncaughtExceptionMonitor", listener: UncaughtExceptionListener): this; + once(event: "unhandledRejection", listener: UnhandledRejectionListener): this; + once(event: "warning", listener: WarningListener): this; + once(event: "message", listener: MessageListener): this; once(event: Signals, listener: SignalsListener): this; - once(event: 'multipleResolves', listener: MultipleResolveListener): this; - once(event: 'worker', listener: WorkerListener): this; + once(event: "multipleResolves", listener: MultipleResolveListener): this; + once(event: "worker", listener: WorkerListener): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'beforeExit', listener: BeforeExitListener): this; - prependListener(event: 'disconnect', listener: DisconnectListener): this; - prependListener(event: 'exit', listener: ExitListener): this; - prependListener(event: 'rejectionHandled', listener: RejectionHandledListener): this; - prependListener(event: 'uncaughtException', listener: UncaughtExceptionListener): this; - prependListener(event: 'uncaughtExceptionMonitor', listener: UncaughtExceptionListener): this; - prependListener(event: 'unhandledRejection', listener: UnhandledRejectionListener): this; - prependListener(event: 'warning', listener: WarningListener): this; - prependListener(event: 'message', listener: MessageListener): this; + prependListener(event: "beforeExit", listener: BeforeExitListener): this; + prependListener(event: "disconnect", listener: DisconnectListener): this; + prependListener(event: "exit", listener: ExitListener): this; + prependListener(event: "rejectionHandled", listener: RejectionHandledListener): this; + prependListener(event: "uncaughtException", listener: UncaughtExceptionListener): this; + prependListener(event: "uncaughtExceptionMonitor", listener: UncaughtExceptionListener): this; + prependListener(event: "unhandledRejection", listener: UnhandledRejectionListener): this; + prependListener(event: "warning", listener: WarningListener): this; + prependListener(event: "message", listener: MessageListener): this; prependListener(event: Signals, listener: SignalsListener): this; - prependListener(event: 'multipleResolves', listener: MultipleResolveListener): this; - prependListener(event: 'worker', listener: WorkerListener): this; - prependOnceListener(event: 'beforeExit', listener: BeforeExitListener): this; - prependOnceListener(event: 'disconnect', listener: DisconnectListener): this; - prependOnceListener(event: 'exit', listener: ExitListener): this; - prependOnceListener(event: 'rejectionHandled', listener: RejectionHandledListener): this; - prependOnceListener(event: 'uncaughtException', listener: UncaughtExceptionListener): this; - prependOnceListener(event: 'uncaughtExceptionMonitor', listener: UncaughtExceptionListener): this; - prependOnceListener(event: 'unhandledRejection', listener: UnhandledRejectionListener): this; - prependOnceListener(event: 'warning', listener: WarningListener): this; - prependOnceListener(event: 'message', listener: MessageListener): this; + prependListener(event: "multipleResolves", listener: MultipleResolveListener): this; + prependListener(event: "worker", listener: WorkerListener): this; + prependOnceListener(event: "beforeExit", listener: BeforeExitListener): this; + prependOnceListener(event: "disconnect", listener: DisconnectListener): this; + prependOnceListener(event: "exit", listener: ExitListener): this; + prependOnceListener(event: "rejectionHandled", listener: RejectionHandledListener): this; + prependOnceListener(event: "uncaughtException", listener: UncaughtExceptionListener): this; + prependOnceListener(event: "uncaughtExceptionMonitor", listener: UncaughtExceptionListener): this; + prependOnceListener(event: "unhandledRejection", listener: UnhandledRejectionListener): this; + prependOnceListener(event: "warning", listener: WarningListener): this; + prependOnceListener(event: "message", listener: MessageListener): this; prependOnceListener(event: Signals, listener: SignalsListener): this; - prependOnceListener(event: 'multipleResolves', listener: MultipleResolveListener): this; - prependOnceListener(event: 'worker', listener: WorkerListener): this; - listeners(event: 'beforeExit'): BeforeExitListener[]; - listeners(event: 'disconnect'): DisconnectListener[]; - listeners(event: 'exit'): ExitListener[]; - listeners(event: 'rejectionHandled'): RejectionHandledListener[]; - listeners(event: 'uncaughtException'): UncaughtExceptionListener[]; - listeners(event: 'uncaughtExceptionMonitor'): UncaughtExceptionListener[]; - listeners(event: 'unhandledRejection'): UnhandledRejectionListener[]; - listeners(event: 'warning'): WarningListener[]; - listeners(event: 'message'): MessageListener[]; + prependOnceListener(event: "multipleResolves", listener: MultipleResolveListener): this; + prependOnceListener(event: "worker", listener: WorkerListener): this; + listeners(event: "beforeExit"): BeforeExitListener[]; + listeners(event: "disconnect"): DisconnectListener[]; + listeners(event: "exit"): ExitListener[]; + listeners(event: "rejectionHandled"): RejectionHandledListener[]; + listeners(event: "uncaughtException"): UncaughtExceptionListener[]; + listeners(event: "uncaughtExceptionMonitor"): UncaughtExceptionListener[]; + listeners(event: "unhandledRejection"): UnhandledRejectionListener[]; + listeners(event: "warning"): WarningListener[]; + listeners(event: "message"): MessageListener[]; listeners(event: Signals): SignalsListener[]; - listeners(event: 'multipleResolves'): MultipleResolveListener[]; - listeners(event: 'worker'): WorkerListener[]; + listeners(event: "multipleResolves"): MultipleResolveListener[]; + listeners(event: "worker"): WorkerListener[]; } } } export = process; } -declare module 'node:process' { - import process = require('process'); +declare module "node:process" { + import process = require("process"); export = process; } diff --git a/node_modules/@types/node/ts4.8/punycode.d.ts b/node_modules/@types/node/ts4.8/punycode.d.ts old mode 100755 new mode 100644 index 345af53..d2fc9f9 --- a/node_modules/@types/node/ts4.8/punycode.d.ts +++ b/node_modules/@types/node/ts4.8/punycode.d.ts @@ -24,9 +24,9 @@ * made available to developers as a convenience. Fixes or other modifications to * the module must be directed to the [Punycode.js](https://github.com/bestiejs/punycode.js) project. * @deprecated Since v7.0.0 - Deprecated - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/punycode.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/punycode.js) */ -declare module 'punycode' { +declare module "punycode" { /** * The `punycode.decode()` method converts a [Punycode](https://tools.ietf.org/html/rfc3492) string of ASCII-only * characters to the equivalent string of Unicode codepoints. @@ -101,7 +101,7 @@ declare module 'punycode' { * Users currently depending on the punycode module should switch to using * the userland-provided Punycode.js module instead. */ - encode(codePoints: ReadonlyArray): string; + encode(codePoints: readonly number[]): string; } /** * @deprecated since v7.0.0 @@ -112,6 +112,6 @@ declare module 'punycode' { */ const version: string; } -declare module 'node:punycode' { - export * from 'punycode'; +declare module "node:punycode" { + export * from "punycode"; } diff --git a/node_modules/@types/node/ts4.8/querystring.d.ts b/node_modules/@types/node/ts4.8/querystring.d.ts old mode 100755 new mode 100644 index 892440b..b36ea2c --- a/node_modules/@types/node/ts4.8/querystring.d.ts +++ b/node_modules/@types/node/ts4.8/querystring.d.ts @@ -1,17 +1,17 @@ /** - * The `querystring` module provides utilities for parsing and formatting URL + * The `node:querystring` module provides utilities for parsing and formatting URL * query strings. It can be accessed using: * * ```js - * const querystring = require('querystring'); + * const querystring = require('node:querystring'); * ``` * - * The `querystring` API is considered Legacy. While it is still maintained, - * new code should use the `URLSearchParams` API instead. - * @deprecated Legacy - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/querystring.js) + * `querystring` is more performant than `URLSearchParams` but is not a + * standardized API. Use `URLSearchParams` when performance is not critical or + * when compatibility with browser code is desirable. + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/querystring.js) */ -declare module 'querystring' { +declare module "querystring" { interface StringifyOptions { encodeURIComponent?: ((str: string) => string) | undefined; } @@ -20,7 +20,17 @@ declare module 'querystring' { decodeURIComponent?: ((str: string) => string) | undefined; } interface ParsedUrlQuery extends NodeJS.Dict {} - interface ParsedUrlQueryInput extends NodeJS.Dict | ReadonlyArray | ReadonlyArray | null> {} + interface ParsedUrlQueryInput extends + NodeJS.Dict< + | string + | number + | boolean + | readonly string[] + | readonly number[] + | readonly boolean[] + | null + > + {} /** * The `querystring.stringify()` method produces a URL query string from a * given `obj` by iterating through the object's "own properties". @@ -64,10 +74,10 @@ declare module 'querystring' { * * For example, the query string `'foo=bar&abc=xyz&abc=123'` is parsed into: * - * ```js + * ```json * { - * foo: 'bar', - * abc: ['xyz', '123'] + * "foo": "bar", + * "abc": ["xyz", "123"] * } * ``` * @@ -126,6 +136,6 @@ declare module 'querystring' { */ function unescape(str: string): string; } -declare module 'node:querystring' { - export * from 'querystring'; +declare module "node:querystring" { + export * from "querystring"; } diff --git a/node_modules/@types/node/ts4.8/readline.d.ts b/node_modules/@types/node/ts4.8/readline.d.ts old mode 100755 new mode 100644 index f1545fa..b06d58b --- a/node_modules/@types/node/ts4.8/readline.d.ts +++ b/node_modules/@types/node/ts4.8/readline.d.ts @@ -1,36 +1,42 @@ /** - * The `readline` module provides an interface for reading data from a `Readable` stream (such as `process.stdin`) one line at a time. It can be accessed - * using: + * The `node:readline` module provides an interface for reading data from a `Readable` stream (such as `process.stdin`) one line at a time. + * + * To use the promise-based APIs: * * ```js - * const readline = require('readline'); + * import * as readline from 'node:readline/promises'; * ``` * - * The following simple example illustrates the basic use of the `readline` module. + * To use the callback and sync APIs: * * ```js - * const readline = require('readline'); + * import * as readline from 'node:readline'; + * ``` * - * const rl = readline.createInterface({ - * input: process.stdin, - * output: process.stdout - * }); + * The following simple example illustrates the basic use of the `node:readline`module. * - * rl.question('What do you think of Node.js? ', (answer) => { - * // TODO: Log the answer in a database - * console.log(`Thank you for your valuable feedback: ${answer}`); + * ```js + * import * as readline from 'node:readline/promises'; + * import { stdin as input, stdout as output } from 'node:process'; * - * rl.close(); - * }); + * const rl = readline.createInterface({ input, output }); + * + * const answer = await rl.question('What do you think of Node.js? '); + * + * console.log(`Thank you for your valuable feedback: ${answer}`); + * + * rl.close(); * ``` * * Once this code is invoked, the Node.js application will not terminate until the`readline.Interface` is closed because the interface waits for data to be * received on the `input` stream. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/readline.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/readline.js) */ -declare module 'readline' { - import { Abortable, EventEmitter } from 'node:events'; - interface Key { +declare module "readline" { + import { Abortable, EventEmitter } from "node:events"; + import * as promises from "node:readline/promises"; + export { promises }; + export interface Key { sequence?: string | undefined; name?: string | undefined; ctrl?: boolean | undefined; @@ -44,7 +50,7 @@ declare module 'readline' { * and is read from, the `input` stream. * @since v0.1.104 */ - class Interface extends EventEmitter { + export class Interface extends EventEmitter { readonly terminal: boolean; /** * The current input data being processed by node. @@ -67,7 +73,7 @@ declare module 'readline' { * const showResults = debounce(() => { * console.log( * '\n', - * values.filter((val) => val.startsWith(rl.line)).join(' ') + * values.filter((val) => val.startsWith(rl.line)).join(' '), * ); * }, 300); * process.stdin.on('keypress', (c, k) => { @@ -93,21 +99,26 @@ declare module 'readline' { * > Instances of the `readline.Interface` class are constructed using the * > `readline.createInterface()` method. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/readline.html#readline_class_interface + * @see https://nodejs.org/dist/latest-v20.x/docs/api/readline.html#class-interfaceconstructor */ - protected constructor(input: NodeJS.ReadableStream, output?: NodeJS.WritableStream, completer?: Completer | AsyncCompleter, terminal?: boolean); + protected constructor( + input: NodeJS.ReadableStream, + output?: NodeJS.WritableStream, + completer?: Completer | AsyncCompleter, + terminal?: boolean, + ); /** * NOTE: According to the documentation: * * > Instances of the `readline.Interface` class are constructed using the * > `readline.createInterface()` method. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/readline.html#readline_class_interface + * @see https://nodejs.org/dist/latest-v20.x/docs/api/readline.html#class-interfaceconstructor */ protected constructor(options: ReadLineOptions); /** * The `rl.getPrompt()` method returns the current prompt used by `rl.prompt()`. - * @since v15.3.0 + * @since v15.3.0, v14.17.0 * @return the current prompt string */ getPrompt(): string; @@ -117,13 +128,13 @@ declare module 'readline' { */ setPrompt(prompt: string): void; /** - * The `rl.prompt()` method writes the `readline.Interface` instances configured`prompt` to a new line in `output` in order to provide a user with a new + * The `rl.prompt()` method writes the `Interface` instances configured`prompt` to a new line in `output` in order to provide a user with a new * location at which to provide input. * * When called, `rl.prompt()` will resume the `input` stream if it has been * paused. * - * If the `readline.Interface` was created with `output` set to `null` or`undefined` the prompt is not written. + * If the `Interface` was created with `output` set to `null` or`undefined` the prompt is not written. * @since v0.1.98 * @param preserveCursor If `true`, prevents the cursor placement from being reset to `0`. */ @@ -135,12 +146,14 @@ declare module 'readline' { * When called, `rl.question()` will resume the `input` stream if it has been * paused. * - * If the `readline.Interface` was created with `output` set to `null` or`undefined` the `query` is not written. + * If the `Interface` was created with `output` set to `null` or`undefined` the `query` is not written. * * The `callback` function passed to `rl.question()` does not follow the typical * pattern of accepting an `Error` object or `null` as the first argument. * The `callback` is called with the provided answer as the only argument. * + * An error will be thrown if calling `rl.question()` after `rl.close()`. + * * Example usage: * * ```js @@ -165,25 +178,6 @@ declare module 'readline' { * * setTimeout(() => ac.abort(), 10000); * ``` - * - * If this method is invoked as it's util.promisify()ed version, it returns a - * Promise that fulfills with the answer. If the question is canceled using - * an `AbortController` it will reject with an `AbortError`. - * - * ```js - * const util = require('util'); - * const question = util.promisify(rl.question).bind(rl); - * - * async function questionExample() { - * try { - * const answer = await question('What is you favorite food? '); - * console.log(`Oh, so your favorite food is ${answer}`); - * } catch (err) { - * console.error('Question rejected', err); - * } - * } - * questionExample(); - * ``` * @since v0.3.3 * @param query A statement or query to write to `output`, prepended to the prompt. * @param callback A callback function that is invoked with the user's input in response to the `query`. @@ -194,7 +188,7 @@ declare module 'readline' { * The `rl.pause()` method pauses the `input` stream, allowing it to be resumed * later if necessary. * - * Calling `rl.pause()` does not immediately pause other events (including`'line'`) from being emitted by the `readline.Interface` instance. + * Calling `rl.pause()` does not immediately pause other events (including`'line'`) from being emitted by the `Interface` instance. * @since v0.3.4 */ pause(): this; @@ -204,12 +198,12 @@ declare module 'readline' { */ resume(): this; /** - * The `rl.close()` method closes the `readline.Interface` instance and + * The `rl.close()` method closes the `Interface` instance and * relinquishes control over the `input` and `output` streams. When called, * the `'close'` event will be emitted. * * Calling `rl.close()` does not immediately stop other events (including `'line'`) - * from being emitted by the `readline.Interface` instance. + * from being emitted by the `Interface` instance. * @since v0.1.98 */ close(): void; @@ -224,7 +218,7 @@ declare module 'readline' { * When called, `rl.write()` will resume the `input` stream if it has been * paused. * - * If the `readline.Interface` was created with `output` set to `null` or`undefined` the `data` and `key` are not written. + * If the `Interface` was created with `output` set to `null` or`undefined` the `data` and `key` are not written. * * ```js * rl.write('Delete this!'); @@ -256,66 +250,69 @@ declare module 'readline' { * 8. history */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'line', listener: (input: string) => void): this; - addListener(event: 'pause', listener: () => void): this; - addListener(event: 'resume', listener: () => void): this; - addListener(event: 'SIGCONT', listener: () => void): this; - addListener(event: 'SIGINT', listener: () => void): this; - addListener(event: 'SIGTSTP', listener: () => void): this; - addListener(event: 'history', listener: (history: string[]) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "line", listener: (input: string) => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; + addListener(event: "SIGCONT", listener: () => void): this; + addListener(event: "SIGINT", listener: () => void): this; + addListener(event: "SIGTSTP", listener: () => void): this; + addListener(event: "history", listener: (history: string[]) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close'): boolean; - emit(event: 'line', input: string): boolean; - emit(event: 'pause'): boolean; - emit(event: 'resume'): boolean; - emit(event: 'SIGCONT'): boolean; - emit(event: 'SIGINT'): boolean; - emit(event: 'SIGTSTP'): boolean; - emit(event: 'history', history: string[]): boolean; + emit(event: "close"): boolean; + emit(event: "line", input: string): boolean; + emit(event: "pause"): boolean; + emit(event: "resume"): boolean; + emit(event: "SIGCONT"): boolean; + emit(event: "SIGINT"): boolean; + emit(event: "SIGTSTP"): boolean; + emit(event: "history", history: string[]): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'line', listener: (input: string) => void): this; - on(event: 'pause', listener: () => void): this; - on(event: 'resume', listener: () => void): this; - on(event: 'SIGCONT', listener: () => void): this; - on(event: 'SIGINT', listener: () => void): this; - on(event: 'SIGTSTP', listener: () => void): this; - on(event: 'history', listener: (history: string[]) => void): this; + on(event: "close", listener: () => void): this; + on(event: "line", listener: (input: string) => void): this; + on(event: "pause", listener: () => void): this; + on(event: "resume", listener: () => void): this; + on(event: "SIGCONT", listener: () => void): this; + on(event: "SIGINT", listener: () => void): this; + on(event: "SIGTSTP", listener: () => void): this; + on(event: "history", listener: (history: string[]) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'line', listener: (input: string) => void): this; - once(event: 'pause', listener: () => void): this; - once(event: 'resume', listener: () => void): this; - once(event: 'SIGCONT', listener: () => void): this; - once(event: 'SIGINT', listener: () => void): this; - once(event: 'SIGTSTP', listener: () => void): this; - once(event: 'history', listener: (history: string[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "line", listener: (input: string) => void): this; + once(event: "pause", listener: () => void): this; + once(event: "resume", listener: () => void): this; + once(event: "SIGCONT", listener: () => void): this; + once(event: "SIGINT", listener: () => void): this; + once(event: "SIGTSTP", listener: () => void): this; + once(event: "history", listener: (history: string[]) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'line', listener: (input: string) => void): this; - prependListener(event: 'pause', listener: () => void): this; - prependListener(event: 'resume', listener: () => void): this; - prependListener(event: 'SIGCONT', listener: () => void): this; - prependListener(event: 'SIGINT', listener: () => void): this; - prependListener(event: 'SIGTSTP', listener: () => void): this; - prependListener(event: 'history', listener: (history: string[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "line", listener: (input: string) => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; + prependListener(event: "SIGCONT", listener: () => void): this; + prependListener(event: "SIGINT", listener: () => void): this; + prependListener(event: "SIGTSTP", listener: () => void): this; + prependListener(event: "history", listener: (history: string[]) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'line', listener: (input: string) => void): this; - prependOnceListener(event: 'pause', listener: () => void): this; - prependOnceListener(event: 'resume', listener: () => void): this; - prependOnceListener(event: 'SIGCONT', listener: () => void): this; - prependOnceListener(event: 'SIGINT', listener: () => void): this; - prependOnceListener(event: 'SIGTSTP', listener: () => void): this; - prependOnceListener(event: 'history', listener: (history: string[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "line", listener: (input: string) => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; + prependOnceListener(event: "SIGCONT", listener: () => void): this; + prependOnceListener(event: "SIGINT", listener: () => void): this; + prependOnceListener(event: "SIGTSTP", listener: () => void): this; + prependOnceListener(event: "history", listener: (history: string[]) => void): this; [Symbol.asyncIterator](): AsyncIterableIterator; } - type ReadLine = Interface; // type forwarded for backwards compatibility - type Completer = (line: string) => CompleterResult; - type AsyncCompleter = (line: string, callback: (err?: null | Error, result?: CompleterResult) => void) => void; - type CompleterResult = [string[], string]; - interface ReadLineOptions { + export type ReadLine = Interface; // type forwarded for backwards compatibility + export type Completer = (line: string) => CompleterResult; + export type AsyncCompleter = ( + line: string, + callback: (err?: null | Error, result?: CompleterResult) => void, + ) => void; + export type CompleterResult = [string[], string]; + export interface ReadLineOptions { input: NodeJS.ReadableStream; output?: NodeJS.WritableStream | undefined; completer?: Completer | AsyncCompleter | undefined; @@ -344,10 +341,10 @@ declare module 'readline' { * The `readline.createInterface()` method creates a new `readline.Interface`instance. * * ```js - * const readline = require('readline'); + * const readline = require('node:readline'); * const rl = readline.createInterface({ * input: process.stdin, - * output: process.stdout + * output: process.stdout, * }); * ``` * @@ -366,18 +363,17 @@ declare module 'readline' { * (`process.stdout` does this automatically when it is a TTY). * * When creating a `readline.Interface` using `stdin` as input, the program - * will not terminate until it receives `EOF` (Ctrl+D on - * Linux/macOS, Ctrl+Z followed by Return on - * Windows). - * If you want your application to exit without waiting for user input, you can `unref()` the standard input stream: - * - * ```js - * process.stdin.unref(); - * ``` + * will not terminate until it receives an [EOF character](https://en.wikipedia.org/wiki/End-of-file#EOF_character). To exit without + * waiting for user input, call `process.stdin.unref()`. * @since v0.1.98 */ - function createInterface(input: NodeJS.ReadableStream, output?: NodeJS.WritableStream, completer?: Completer | AsyncCompleter, terminal?: boolean): Interface; - function createInterface(options: ReadLineOptions): Interface; + export function createInterface( + input: NodeJS.ReadableStream, + output?: NodeJS.WritableStream, + completer?: Completer | AsyncCompleter, + terminal?: boolean, + ): Interface; + export function createInterface(options: ReadLineOptions): Interface; /** * The `readline.emitKeypressEvents()` method causes the given `Readable` stream to begin emitting `'keypress'` events corresponding to received input. * @@ -394,41 +390,6 @@ declare module 'readline' { * if (process.stdin.isTTY) * process.stdin.setRawMode(true); * ``` - * @since v0.7.7 - */ - function emitKeypressEvents(stream: NodeJS.ReadableStream, readlineInterface?: Interface): void; - type Direction = -1 | 0 | 1; - interface CursorPos { - rows: number; - cols: number; - } - /** - * The `readline.clearLine()` method clears current line of given `TTY` stream - * in a specified direction identified by `dir`. - * @since v0.7.7 - * @param callback Invoked once the operation completes. - * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. - */ - function clearLine(stream: NodeJS.WritableStream, dir: Direction, callback?: () => void): boolean; - /** - * The `readline.clearScreenDown()` method clears the given `TTY` stream from - * the current position of the cursor down. - * @since v0.7.7 - * @param callback Invoked once the operation completes. - * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. - */ - function clearScreenDown(stream: NodeJS.WritableStream, callback?: () => void): boolean; - /** - * The `readline.cursorTo()` method moves cursor to the specified position in a - * given `TTY` `stream`. - * @since v0.7.7 - * @param callback Invoked once the operation completes. - * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. - */ - function cursorTo(stream: NodeJS.WritableStream, x: number, y?: number, callback?: () => void): boolean; - /** - * The `readline.moveCursor()` method moves the cursor _relative_ to its current - * position in a given `TTY` `stream`. * * ## Example: Tiny CLI * @@ -436,11 +397,11 @@ declare module 'readline' { * implement a small command-line interface: * * ```js - * const readline = require('readline'); + * const readline = require('node:readline'); * const rl = readline.createInterface({ * input: process.stdin, * output: process.stdout, - * prompt: 'OHAI> ' + * prompt: 'OHAI> ', * }); * * rl.prompt(); @@ -468,15 +429,15 @@ declare module 'readline' { * well as a `for await...of` loop: * * ```js - * const fs = require('fs'); - * const readline = require('readline'); + * const fs = require('node:fs'); + * const readline = require('node:readline'); * * async function processLineByLine() { * const fileStream = fs.createReadStream('input.txt'); * * const rl = readline.createInterface({ * input: fileStream, - * crlfDelay: Infinity + * crlfDelay: Infinity, * }); * // Note: we use the crlfDelay option to recognize all instances of CR LF * // ('\r\n') in input.txt as a single line break. @@ -493,12 +454,12 @@ declare module 'readline' { * Alternatively, one could use the `'line'` event: * * ```js - * const fs = require('fs'); - * const readline = require('readline'); + * const fs = require('node:fs'); + * const readline = require('node:readline'); * * const rl = readline.createInterface({ * input: fs.createReadStream('sample.txt'), - * crlfDelay: Infinity + * crlfDelay: Infinity, * }); * * rl.on('line', (line) => { @@ -509,15 +470,15 @@ declare module 'readline' { * Currently, `for await...of` loop can be a bit slower. If `async` / `await`flow and speed are both essential, a mixed approach can be applied: * * ```js - * const { once } = require('events'); - * const { createReadStream } = require('fs'); - * const { createInterface } = require('readline'); + * const { once } = require('node:events'); + * const { createReadStream } = require('node:fs'); + * const { createInterface } = require('node:readline'); * * (async function processLineByLine() { * try { * const rl = createInterface({ * input: createReadStream('big-file.txt'), - * crlfDelay: Infinity + * crlfDelay: Infinity, * }); * * rl.on('line', (line) => { @@ -533,11 +494,46 @@ declare module 'readline' { * })(); * ``` * @since v0.7.7 + */ + export function emitKeypressEvents(stream: NodeJS.ReadableStream, readlineInterface?: Interface): void; + export type Direction = -1 | 0 | 1; + export interface CursorPos { + rows: number; + cols: number; + } + /** + * The `readline.clearLine()` method clears current line of given `TTY` stream + * in a specified direction identified by `dir`. + * @since v0.7.7 * @param callback Invoked once the operation completes. * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. */ - function moveCursor(stream: NodeJS.WritableStream, dx: number, dy: number, callback?: () => void): boolean; + export function clearLine(stream: NodeJS.WritableStream, dir: Direction, callback?: () => void): boolean; + /** + * The `readline.clearScreenDown()` method clears the given `TTY` stream from + * the current position of the cursor down. + * @since v0.7.7 + * @param callback Invoked once the operation completes. + * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. + */ + export function clearScreenDown(stream: NodeJS.WritableStream, callback?: () => void): boolean; + /** + * The `readline.cursorTo()` method moves cursor to the specified position in a + * given `TTY` `stream`. + * @since v0.7.7 + * @param callback Invoked once the operation completes. + * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. + */ + export function cursorTo(stream: NodeJS.WritableStream, x: number, y?: number, callback?: () => void): boolean; + /** + * The `readline.moveCursor()` method moves the cursor _relative_ to its current + * position in a given `TTY` `stream`. + * @since v0.7.7 + * @param callback Invoked once the operation completes. + * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. + */ + export function moveCursor(stream: NodeJS.WritableStream, dx: number, dy: number, callback?: () => void): boolean; } -declare module 'node:readline' { - export * from 'readline'; +declare module "node:readline" { + export * from "readline"; } diff --git a/node_modules/@types/node/ts4.8/readline/promises.d.ts b/node_modules/@types/node/ts4.8/readline/promises.d.ts new file mode 100644 index 0000000..73fb111 --- /dev/null +++ b/node_modules/@types/node/ts4.8/readline/promises.d.ts @@ -0,0 +1,150 @@ +/** + * @since v17.0.0 + * @experimental + */ +declare module "readline/promises" { + import { AsyncCompleter, Completer, Direction, Interface as _Interface, ReadLineOptions } from "node:readline"; + import { Abortable } from "node:events"; + /** + * Instances of the `readlinePromises.Interface` class are constructed using the`readlinePromises.createInterface()` method. Every instance is associated with a + * single `input` `Readable` stream and a single `output` `Writable` stream. + * The `output` stream is used to print prompts for user input that arrives on, + * and is read from, the `input` stream. + * @since v17.0.0 + */ + class Interface extends _Interface { + /** + * The `rl.question()` method displays the `query` by writing it to the `output`, + * waits for user input to be provided on `input`, then invokes the `callback`function passing the provided input as the first argument. + * + * When called, `rl.question()` will resume the `input` stream if it has been + * paused. + * + * If the `Interface` was created with `output` set to `null` or`undefined` the `query` is not written. + * + * If the question is called after `rl.close()`, it returns a rejected promise. + * + * Example usage: + * + * ```js + * const answer = await rl.question('What is your favorite food? '); + * console.log(`Oh, so your favorite food is ${answer}`); + * ``` + * + * Using an `AbortSignal` to cancel a question. + * + * ```js + * const signal = AbortSignal.timeout(10_000); + * + * signal.addEventListener('abort', () => { + * console.log('The food question timed out'); + * }, { once: true }); + * + * const answer = await rl.question('What is your favorite food? ', { signal }); + * console.log(`Oh, so your favorite food is ${answer}`); + * ``` + * @since v17.0.0 + * @param query A statement or query to write to `output`, prepended to the prompt. + * @return A promise that is fulfilled with the user's input in response to the `query`. + */ + question(query: string): Promise; + question(query: string, options: Abortable): Promise; + } + /** + * @since v17.0.0 + */ + class Readline { + /** + * @param stream A TTY stream. + */ + constructor( + stream: NodeJS.WritableStream, + options?: { + autoCommit?: boolean; + }, + ); + /** + * The `rl.clearLine()` method adds to the internal list of pending action an + * action that clears current line of the associated `stream` in a specified + * direction identified by `dir`. + * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor. + * @since v17.0.0 + * @return this + */ + clearLine(dir: Direction): this; + /** + * The `rl.clearScreenDown()` method adds to the internal list of pending action an + * action that clears the associated stream from the current position of the + * cursor down. + * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor. + * @since v17.0.0 + * @return this + */ + clearScreenDown(): this; + /** + * The `rl.commit()` method sends all the pending actions to the associated`stream` and clears the internal list of pending actions. + * @since v17.0.0 + */ + commit(): Promise; + /** + * The `rl.cursorTo()` method adds to the internal list of pending action an action + * that moves cursor to the specified position in the associated `stream`. + * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor. + * @since v17.0.0 + * @return this + */ + cursorTo(x: number, y?: number): this; + /** + * The `rl.moveCursor()` method adds to the internal list of pending action an + * action that moves the cursor _relative_ to its current position in the + * associated `stream`. + * Call `rl.commit()` to see the effect of this method, unless `autoCommit: true`was passed to the constructor. + * @since v17.0.0 + * @return this + */ + moveCursor(dx: number, dy: number): this; + /** + * The `rl.rollback` methods clears the internal list of pending actions without + * sending it to the associated `stream`. + * @since v17.0.0 + * @return this + */ + rollback(): this; + } + /** + * The `readlinePromises.createInterface()` method creates a new `readlinePromises.Interface`instance. + * + * ```js + * const readlinePromises = require('node:readline/promises'); + * const rl = readlinePromises.createInterface({ + * input: process.stdin, + * output: process.stdout, + * }); + * ``` + * + * Once the `readlinePromises.Interface` instance is created, the most common case + * is to listen for the `'line'` event: + * + * ```js + * rl.on('line', (line) => { + * console.log(`Received: ${line}`); + * }); + * ``` + * + * If `terminal` is `true` for this instance then the `output` stream will get + * the best compatibility if it defines an `output.columns` property and emits + * a `'resize'` event on the `output` if or when the columns ever change + * (`process.stdout` does this automatically when it is a TTY). + * @since v17.0.0 + */ + function createInterface( + input: NodeJS.ReadableStream, + output?: NodeJS.WritableStream, + completer?: Completer | AsyncCompleter, + terminal?: boolean, + ): Interface; + function createInterface(options: ReadLineOptions): Interface; +} +declare module "node:readline/promises" { + export * from "readline/promises"; +} diff --git a/node_modules/@types/node/ts4.8/repl.d.ts b/node_modules/@types/node/ts4.8/repl.d.ts old mode 100755 new mode 100644 index 04f64e1..6c5f81b --- a/node_modules/@types/node/ts4.8/repl.d.ts +++ b/node_modules/@types/node/ts4.8/repl.d.ts @@ -1,17 +1,17 @@ /** - * The `repl` module provides a Read-Eval-Print-Loop (REPL) implementation that - * is available both as a standalone program or includible in other applications. - * It can be accessed using: + * The `node:repl` module provides a Read-Eval-Print-Loop (REPL) implementation + * that is available both as a standalone program or includible in other + * applications. It can be accessed using: * * ```js - * const repl = require('repl'); + * const repl = require('node:repl'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/repl.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/repl.js) */ -declare module 'repl' { - import { Interface, Completer, AsyncCompleter } from 'node:readline'; - import { Context } from 'node:vm'; - import { InspectOptions } from 'node:util'; +declare module "repl" { + import { AsyncCompleter, Completer, Interface } from "node:readline"; + import { Context } from "node:vm"; + import { InspectOptions } from "node:util"; interface ReplOptions { /** * The input prompt to display. @@ -41,8 +41,8 @@ declare module 'repl' { * error with `repl.Recoverable` to indicate the input was incomplete and prompt for * additional lines. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_default_evaluation - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_custom_evaluation_functions + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_default_evaluation + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_custom_evaluation_functions */ eval?: REPLEval | undefined; /** @@ -74,13 +74,13 @@ declare module 'repl' { * The function to invoke to format the output of each command before writing to `output`. * Default: a wrapper for `util.inspect`. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_customizing_repl_output + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_customizing_repl_output */ writer?: REPLWriter | undefined; /** * An optional function used for custom Tab auto completion. * - * @see https://nodejs.org/dist/latest-v11.x/docs/api/readline.html#readline_use_of_the_completer_function + * @see https://nodejs.org/dist/latest-v20.x/docs/api/readline.html#readline_use_of_the_completer_function */ completer?: Completer | AsyncCompleter | undefined; /** @@ -99,7 +99,13 @@ declare module 'repl' { */ breakEvalOnSigint?: boolean | undefined; } - type REPLEval = (this: REPLServer, evalCmd: string, context: Context, file: string, cb: (err: Error | null, result: any) => void) => void; + type REPLEval = ( + this: REPLServer, + evalCmd: string, + context: Context, + file: string, + cb: (err: Error | null, result: any) => void, + ) => void; type REPLWriter = (this: REPLServer, obj: any) => string; /** * This is the default "writer" value, if none is passed in the REPL options, @@ -124,7 +130,7 @@ declare module 'repl' { * or directly using the JavaScript `new` keyword. * * ```js - * const repl = require('repl'); + * const repl = require('node:repl'); * * const options = { useColors: true }; * @@ -162,33 +168,33 @@ declare module 'repl' { /** * A value indicating whether the REPL is currently in "editor mode". * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_commands_and_special_keys + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_commands_and_special_keys */ readonly editorMode: boolean; /** * A value indicating whether the `_` variable has been assigned. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable */ readonly underscoreAssigned: boolean; /** * The last evaluation result from the REPL (assigned to the `_` variable inside of the REPL). * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable */ readonly last: any; /** * A value indicating whether the `_error` variable has been assigned. * * @since v9.8.0 - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable */ readonly underscoreErrAssigned: boolean; /** * The last error raised inside the REPL (assigned to the `_error` variable inside of the REPL). * * @since v9.8.0 - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable */ readonly lastError: any; /** @@ -240,7 +246,7 @@ declare module 'repl' { * * `REPLServer` cannot be subclassed due to implementation specifics in NodeJS. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_class_replserver + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_class_replserver */ private constructor(); /** @@ -251,7 +257,7 @@ declare module 'repl' { * The following example shows two new commands added to the REPL instance: * * ```js - * const repl = require('repl'); + * const repl = require('node:repl'); * * const replServer = repl.start({ prompt: '> ' }); * replServer.defineCommand('sayhello', { @@ -260,7 +266,7 @@ declare module 'repl' { * this.clearBufferedCommand(); * console.log(`Hello, ${name}!`); * this.displayPrompt(); - * } + * }, * }); * replServer.defineCommand('saybye', function saybye() { * console.log('Goodbye!'); @@ -277,7 +283,7 @@ declare module 'repl' { * Goodbye! * ``` * @since v0.3.0 - * @param keyword The command keyword (*without* a leading `.` character). + * @param keyword The command keyword (_without_ a leading `.` character). * @param cmd The function to invoke when the command is processed. */ defineCommand(keyword: string, cmd: REPLCommandAction | REPLCommand): void; @@ -326,65 +332,65 @@ declare module 'repl' { * 9. reset */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'line', listener: (input: string) => void): this; - addListener(event: 'pause', listener: () => void): this; - addListener(event: 'resume', listener: () => void): this; - addListener(event: 'SIGCONT', listener: () => void): this; - addListener(event: 'SIGINT', listener: () => void): this; - addListener(event: 'SIGTSTP', listener: () => void): this; - addListener(event: 'exit', listener: () => void): this; - addListener(event: 'reset', listener: (context: Context) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "line", listener: (input: string) => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; + addListener(event: "SIGCONT", listener: () => void): this; + addListener(event: "SIGINT", listener: () => void): this; + addListener(event: "SIGTSTP", listener: () => void): this; + addListener(event: "exit", listener: () => void): this; + addListener(event: "reset", listener: (context: Context) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'close'): boolean; - emit(event: 'line', input: string): boolean; - emit(event: 'pause'): boolean; - emit(event: 'resume'): boolean; - emit(event: 'SIGCONT'): boolean; - emit(event: 'SIGINT'): boolean; - emit(event: 'SIGTSTP'): boolean; - emit(event: 'exit'): boolean; - emit(event: 'reset', context: Context): boolean; + emit(event: "close"): boolean; + emit(event: "line", input: string): boolean; + emit(event: "pause"): boolean; + emit(event: "resume"): boolean; + emit(event: "SIGCONT"): boolean; + emit(event: "SIGINT"): boolean; + emit(event: "SIGTSTP"): boolean; + emit(event: "exit"): boolean; + emit(event: "reset", context: Context): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'close', listener: () => void): this; - on(event: 'line', listener: (input: string) => void): this; - on(event: 'pause', listener: () => void): this; - on(event: 'resume', listener: () => void): this; - on(event: 'SIGCONT', listener: () => void): this; - on(event: 'SIGINT', listener: () => void): this; - on(event: 'SIGTSTP', listener: () => void): this; - on(event: 'exit', listener: () => void): this; - on(event: 'reset', listener: (context: Context) => void): this; + on(event: "close", listener: () => void): this; + on(event: "line", listener: (input: string) => void): this; + on(event: "pause", listener: () => void): this; + on(event: "resume", listener: () => void): this; + on(event: "SIGCONT", listener: () => void): this; + on(event: "SIGINT", listener: () => void): this; + on(event: "SIGTSTP", listener: () => void): this; + on(event: "exit", listener: () => void): this; + on(event: "reset", listener: (context: Context) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'line', listener: (input: string) => void): this; - once(event: 'pause', listener: () => void): this; - once(event: 'resume', listener: () => void): this; - once(event: 'SIGCONT', listener: () => void): this; - once(event: 'SIGINT', listener: () => void): this; - once(event: 'SIGTSTP', listener: () => void): this; - once(event: 'exit', listener: () => void): this; - once(event: 'reset', listener: (context: Context) => void): this; + once(event: "close", listener: () => void): this; + once(event: "line", listener: (input: string) => void): this; + once(event: "pause", listener: () => void): this; + once(event: "resume", listener: () => void): this; + once(event: "SIGCONT", listener: () => void): this; + once(event: "SIGINT", listener: () => void): this; + once(event: "SIGTSTP", listener: () => void): this; + once(event: "exit", listener: () => void): this; + once(event: "reset", listener: (context: Context) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'line', listener: (input: string) => void): this; - prependListener(event: 'pause', listener: () => void): this; - prependListener(event: 'resume', listener: () => void): this; - prependListener(event: 'SIGCONT', listener: () => void): this; - prependListener(event: 'SIGINT', listener: () => void): this; - prependListener(event: 'SIGTSTP', listener: () => void): this; - prependListener(event: 'exit', listener: () => void): this; - prependListener(event: 'reset', listener: (context: Context) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "line", listener: (input: string) => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; + prependListener(event: "SIGCONT", listener: () => void): this; + prependListener(event: "SIGINT", listener: () => void): this; + prependListener(event: "SIGTSTP", listener: () => void): this; + prependListener(event: "exit", listener: () => void): this; + prependListener(event: "reset", listener: (context: Context) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'line', listener: (input: string) => void): this; - prependOnceListener(event: 'pause', listener: () => void): this; - prependOnceListener(event: 'resume', listener: () => void): this; - prependOnceListener(event: 'SIGCONT', listener: () => void): this; - prependOnceListener(event: 'SIGINT', listener: () => void): this; - prependOnceListener(event: 'SIGTSTP', listener: () => void): this; - prependOnceListener(event: 'exit', listener: () => void): this; - prependOnceListener(event: 'reset', listener: (context: Context) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "line", listener: (input: string) => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; + prependOnceListener(event: "SIGCONT", listener: () => void): this; + prependOnceListener(event: "SIGINT", listener: () => void): this; + prependOnceListener(event: "SIGTSTP", listener: () => void): this; + prependOnceListener(event: "exit", listener: () => void): this; + prependOnceListener(event: "reset", listener: (context: Context) => void): this; } /** * A flag passed in the REPL options. Evaluates expressions in sloppy mode. @@ -401,7 +407,7 @@ declare module 'repl' { * If `options` is a string, then it specifies the input prompt: * * ```js - * const repl = require('repl'); + * const repl = require('node:repl'); * * // a Unix style prompt * repl.start('$ '); @@ -412,13 +418,13 @@ declare module 'repl' { /** * Indicates a recoverable error that a `REPLServer` can use to support multi-line input. * - * @see https://nodejs.org/dist/latest-v10.x/docs/api/repl.html#repl_recoverable_errors + * @see https://nodejs.org/dist/latest-v20.x/docs/api/repl.html#repl_recoverable_errors */ class Recoverable extends SyntaxError { err: Error; constructor(err: Error); } } -declare module 'node:repl' { - export * from 'repl'; +declare module "node:repl" { + export * from "repl"; } diff --git a/node_modules/@types/node/ts4.8/stream.d.ts b/node_modules/@types/node/ts4.8/stream.d.ts old mode 100755 new mode 100644 index 06c27bf..947a019 --- a/node_modules/@types/node/ts4.8/stream.d.ts +++ b/node_modules/@types/node/ts4.8/stream.d.ts @@ -1,32 +1,943 @@ /** * A stream is an abstract interface for working with streaming data in Node.js. - * The `stream` module provides an API for implementing the stream interface. + * The `node:stream` module provides an API for implementing the stream interface. * * There are many stream objects provided by Node.js. For instance, a `request to an HTTP server` and `process.stdout` are both stream instances. * * Streams can be readable, writable, or both. All streams are instances of `EventEmitter`. * - * To access the `stream` module: + * To access the `node:stream` module: * * ```js - * const stream = require('stream'); + * const stream = require('node:stream'); * ``` * - * The `stream` module is useful for creating new types of stream instances. It is - * usually not necessary to use the `stream` module to consume streams. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/stream.js) + * The `node:stream` module is useful for creating new types of stream instances. + * It is usually not necessary to use the `node:stream` module to consume streams. + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/stream.js) */ -declare module 'stream' { - import { EventEmitter, Abortable } from 'node:events'; - import * as streamPromises from 'node:stream/promises'; - import * as streamConsumers from 'node:stream/consumers'; +declare module "stream" { + import { Abortable, EventEmitter } from "node:events"; + import { Blob as NodeBlob } from "node:buffer"; + import * as streamPromises from "node:stream/promises"; + import * as streamConsumers from "node:stream/consumers"; + import * as streamWeb from "node:stream/web"; + + type ComposeFnParam = (source: any) => void; + class internal extends EventEmitter { pipe( destination: T, options?: { end?: boolean | undefined; - } + }, ): T; + compose( + stream: T | ComposeFnParam | Iterable | AsyncIterable, + options?: { signal: AbortSignal }, + ): T; + } + import Stream = internal.Stream; + import Readable = internal.Readable; + import ReadableOptions = internal.ReadableOptions; + interface ArrayOptions { + /** the maximum concurrent invocations of `fn` to call on the stream at once. **Default: 1**. */ + concurrency?: number; + /** allows destroying the stream if the signal is aborted. */ + signal?: AbortSignal; + } + class ReadableBase extends Stream implements NodeJS.ReadableStream { + /** + * A utility method for creating Readable Streams out of iterators. + */ + static from(iterable: Iterable | AsyncIterable, options?: ReadableOptions): Readable; + /** + * Returns whether the stream has been read from or cancelled. + * @since v16.8.0 + */ + static isDisturbed(stream: Readable | NodeJS.ReadableStream): boolean; + /** + * Returns whether the stream was destroyed or errored before emitting `'end'`. + * @since v16.8.0 + * @experimental + */ + readonly readableAborted: boolean; + /** + * Is `true` if it is safe to call `readable.read()`, which means + * the stream has not been destroyed or emitted `'error'` or `'end'`. + * @since v11.4.0 + */ + readable: boolean; + /** + * Returns whether `'data'` has been emitted. + * @since v16.7.0, v14.18.0 + * @experimental + */ + readonly readableDidRead: boolean; + /** + * Getter for the property `encoding` of a given `Readable` stream. The `encoding`property can be set using the `readable.setEncoding()` method. + * @since v12.7.0 + */ + readonly readableEncoding: BufferEncoding | null; + /** + * Becomes `true` when `'end'` event is emitted. + * @since v12.9.0 + */ + readonly readableEnded: boolean; + /** + * This property reflects the current state of a `Readable` stream as described + * in the `Three states` section. + * @since v9.4.0 + */ + readonly readableFlowing: boolean | null; + /** + * Returns the value of `highWaterMark` passed when creating this `Readable`. + * @since v9.3.0 + */ + readonly readableHighWaterMark: number; + /** + * This property contains the number of bytes (or objects) in the queue + * ready to be read. The value provides introspection data regarding + * the status of the `highWaterMark`. + * @since v9.4.0 + */ + readonly readableLength: number; + /** + * Getter for the property `objectMode` of a given `Readable` stream. + * @since v12.3.0 + */ + readonly readableObjectMode: boolean; + /** + * Is `true` after `readable.destroy()` has been called. + * @since v8.0.0 + */ + destroyed: boolean; + /** + * Is `true` after `'close'` has been emitted. + * @since v18.0.0 + */ + readonly closed: boolean; + /** + * Returns error if the stream has been destroyed with an error. + * @since v18.0.0 + */ + readonly errored: Error | null; + constructor(opts?: ReadableOptions); + _construct?(callback: (error?: Error | null) => void): void; + _read(size: number): void; + /** + * The `readable.read()` method reads data out of the internal buffer and + * returns it. If no data is available to be read, `null` is returned. By default, + * the data is returned as a `Buffer` object unless an encoding has been + * specified using the `readable.setEncoding()` method or the stream is operating + * in object mode. + * + * The optional `size` argument specifies a specific number of bytes to read. If`size` bytes are not available to be read, `null` will be returned _unless_the stream has ended, in which + * case all of the data remaining in the internal + * buffer will be returned. + * + * If the `size` argument is not specified, all of the data contained in the + * internal buffer will be returned. + * + * The `size` argument must be less than or equal to 1 GiB. + * + * The `readable.read()` method should only be called on `Readable` streams + * operating in paused mode. In flowing mode, `readable.read()` is called + * automatically until the internal buffer is fully drained. + * + * ```js + * const readable = getReadableStreamSomehow(); + * + * // 'readable' may be triggered multiple times as data is buffered in + * readable.on('readable', () => { + * let chunk; + * console.log('Stream is readable (new data received in buffer)'); + * // Use a loop to make sure we read all currently available data + * while (null !== (chunk = readable.read())) { + * console.log(`Read ${chunk.length} bytes of data...`); + * } + * }); + * + * // 'end' will be triggered once when there is no more data available + * readable.on('end', () => { + * console.log('Reached end of stream.'); + * }); + * ``` + * + * Each call to `readable.read()` returns a chunk of data, or `null`. The chunks + * are not concatenated. A `while` loop is necessary to consume all data + * currently in the buffer. When reading a large file `.read()` may return `null`, + * having consumed all buffered content so far, but there is still more data to + * come not yet buffered. In this case a new `'readable'` event will be emitted + * when there is more data in the buffer. Finally the `'end'` event will be + * emitted when there is no more data to come. + * + * Therefore to read a file's whole contents from a `readable`, it is necessary + * to collect chunks across multiple `'readable'` events: + * + * ```js + * const chunks = []; + * + * readable.on('readable', () => { + * let chunk; + * while (null !== (chunk = readable.read())) { + * chunks.push(chunk); + * } + * }); + * + * readable.on('end', () => { + * const content = chunks.join(''); + * }); + * ``` + * + * A `Readable` stream in object mode will always return a single item from + * a call to `readable.read(size)`, regardless of the value of the`size` argument. + * + * If the `readable.read()` method returns a chunk of data, a `'data'` event will + * also be emitted. + * + * Calling {@link read} after the `'end'` event has + * been emitted will return `null`. No runtime error will be raised. + * @since v0.9.4 + * @param size Optional argument to specify how much data to read. + */ + read(size?: number): any; + /** + * The `readable.setEncoding()` method sets the character encoding for + * data read from the `Readable` stream. + * + * By default, no encoding is assigned and stream data will be returned as`Buffer` objects. Setting an encoding causes the stream data + * to be returned as strings of the specified encoding rather than as `Buffer`objects. For instance, calling `readable.setEncoding('utf8')` will cause the + * output data to be interpreted as UTF-8 data, and passed as strings. Calling`readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal + * string format. + * + * The `Readable` stream will properly handle multi-byte characters delivered + * through the stream that would otherwise become improperly decoded if simply + * pulled from the stream as `Buffer` objects. + * + * ```js + * const readable = getReadableStreamSomehow(); + * readable.setEncoding('utf8'); + * readable.on('data', (chunk) => { + * assert.equal(typeof chunk, 'string'); + * console.log('Got %d characters of string data:', chunk.length); + * }); + * ``` + * @since v0.9.4 + * @param encoding The encoding to use. + */ + setEncoding(encoding: BufferEncoding): this; + /** + * The `readable.pause()` method will cause a stream in flowing mode to stop + * emitting `'data'` events, switching out of flowing mode. Any data that + * becomes available will remain in the internal buffer. + * + * ```js + * const readable = getReadableStreamSomehow(); + * readable.on('data', (chunk) => { + * console.log(`Received ${chunk.length} bytes of data.`); + * readable.pause(); + * console.log('There will be no additional data for 1 second.'); + * setTimeout(() => { + * console.log('Now data will start flowing again.'); + * readable.resume(); + * }, 1000); + * }); + * ``` + * + * The `readable.pause()` method has no effect if there is a `'readable'`event listener. + * @since v0.9.4 + */ + pause(): this; + /** + * The `readable.resume()` method causes an explicitly paused `Readable` stream to + * resume emitting `'data'` events, switching the stream into flowing mode. + * + * The `readable.resume()` method can be used to fully consume the data from a + * stream without actually processing any of that data: + * + * ```js + * getReadableStreamSomehow() + * .resume() + * .on('end', () => { + * console.log('Reached the end, but did not read anything.'); + * }); + * ``` + * + * The `readable.resume()` method has no effect if there is a `'readable'`event listener. + * @since v0.9.4 + */ + resume(): this; + /** + * The `readable.isPaused()` method returns the current operating state of the`Readable`. This is used primarily by the mechanism that underlies the`readable.pipe()` method. In most + * typical cases, there will be no reason to + * use this method directly. + * + * ```js + * const readable = new stream.Readable(); + * + * readable.isPaused(); // === false + * readable.pause(); + * readable.isPaused(); // === true + * readable.resume(); + * readable.isPaused(); // === false + * ``` + * @since v0.11.14 + */ + isPaused(): boolean; + /** + * The `readable.unpipe()` method detaches a `Writable` stream previously attached + * using the {@link pipe} method. + * + * If the `destination` is not specified, then _all_ pipes are detached. + * + * If the `destination` is specified, but no pipe is set up for it, then + * the method does nothing. + * + * ```js + * const fs = require('node:fs'); + * const readable = getReadableStreamSomehow(); + * const writable = fs.createWriteStream('file.txt'); + * // All the data from readable goes into 'file.txt', + * // but only for the first second. + * readable.pipe(writable); + * setTimeout(() => { + * console.log('Stop writing to file.txt.'); + * readable.unpipe(writable); + * console.log('Manually close the file stream.'); + * writable.end(); + * }, 1000); + * ``` + * @since v0.9.4 + * @param destination Optional specific stream to unpipe + */ + unpipe(destination?: NodeJS.WritableStream): this; + /** + * Passing `chunk` as `null` signals the end of the stream (EOF) and behaves the + * same as `readable.push(null)`, after which no more data can be written. The EOF + * signal is put at the end of the buffer and any buffered data will still be + * flushed. + * + * The `readable.unshift()` method pushes a chunk of data back into the internal + * buffer. This is useful in certain situations where a stream is being consumed by + * code that needs to "un-consume" some amount of data that it has optimistically + * pulled out of the source, so that the data can be passed on to some other party. + * + * The `stream.unshift(chunk)` method cannot be called after the `'end'` event + * has been emitted or a runtime error will be thrown. + * + * Developers using `stream.unshift()` often should consider switching to + * use of a `Transform` stream instead. See the `API for stream implementers` section for more information. + * + * ```js + * // Pull off a header delimited by \n\n. + * // Use unshift() if we get too much. + * // Call the callback with (error, header, stream). + * const { StringDecoder } = require('node:string_decoder'); + * function parseHeader(stream, callback) { + * stream.on('error', callback); + * stream.on('readable', onReadable); + * const decoder = new StringDecoder('utf8'); + * let header = ''; + * function onReadable() { + * let chunk; + * while (null !== (chunk = stream.read())) { + * const str = decoder.write(chunk); + * if (str.includes('\n\n')) { + * // Found the header boundary. + * const split = str.split(/\n\n/); + * header += split.shift(); + * const remaining = split.join('\n\n'); + * const buf = Buffer.from(remaining, 'utf8'); + * stream.removeListener('error', callback); + * // Remove the 'readable' listener before unshifting. + * stream.removeListener('readable', onReadable); + * if (buf.length) + * stream.unshift(buf); + * // Now the body of the message can be read from the stream. + * callback(null, header, stream); + * return; + * } + * // Still reading the header. + * header += str; + * } + * } + * } + * ``` + * + * Unlike {@link push}, `stream.unshift(chunk)` will not + * end the reading process by resetting the internal reading state of the stream. + * This can cause unexpected results if `readable.unshift()` is called during a + * read (i.e. from within a {@link _read} implementation on a + * custom stream). Following the call to `readable.unshift()` with an immediate {@link push} will reset the reading state appropriately, + * however it is best to simply avoid calling `readable.unshift()` while in the + * process of performing a read. + * @since v0.9.11 + * @param chunk Chunk of data to unshift onto the read queue. For streams not operating in object mode, `chunk` must be a string, `Buffer`, `Uint8Array`, or `null`. For object mode + * streams, `chunk` may be any JavaScript value. + * @param encoding Encoding of string chunks. Must be a valid `Buffer` encoding, such as `'utf8'` or `'ascii'`. + */ + unshift(chunk: any, encoding?: BufferEncoding): void; + /** + * Prior to Node.js 0.10, streams did not implement the entire `node:stream`module API as it is currently defined. (See `Compatibility` for more + * information.) + * + * When using an older Node.js library that emits `'data'` events and has a {@link pause} method that is advisory only, the`readable.wrap()` method can be used to create a `Readable` + * stream that uses + * the old stream as its data source. + * + * It will rarely be necessary to use `readable.wrap()` but the method has been + * provided as a convenience for interacting with older Node.js applications and + * libraries. + * + * ```js + * const { OldReader } = require('./old-api-module.js'); + * const { Readable } = require('node:stream'); + * const oreader = new OldReader(); + * const myReader = new Readable().wrap(oreader); + * + * myReader.on('readable', () => { + * myReader.read(); // etc. + * }); + * ``` + * @since v0.9.4 + * @param stream An "old style" readable stream + */ + wrap(stream: NodeJS.ReadableStream): this; + push(chunk: any, encoding?: BufferEncoding): boolean; + /** + * The iterator created by this method gives users the option to cancel the destruction + * of the stream if the `for await...of` loop is exited by `return`, `break`, or `throw`, + * or if the iterator should destroy the stream if the stream emitted an error during iteration. + * @since v16.3.0 + * @param options.destroyOnReturn When set to `false`, calling `return` on the async iterator, + * or exiting a `for await...of` iteration using a `break`, `return`, or `throw` will not destroy the stream. + * **Default: `true`**. + */ + iterator(options?: { destroyOnReturn?: boolean }): AsyncIterableIterator; + /** + * This method allows mapping over the stream. The *fn* function will be called for every chunk in the stream. + * If the *fn* function returns a promise - that promise will be `await`ed before being passed to the result stream. + * @since v17.4.0, v16.14.0 + * @param fn a function to map over every chunk in the stream. Async or not. + * @returns a stream mapped with the function *fn*. + */ + map(fn: (data: any, options?: Pick) => any, options?: ArrayOptions): Readable; + /** + * This method allows filtering the stream. For each chunk in the stream the *fn* function will be called + * and if it returns a truthy value, the chunk will be passed to the result stream. + * If the *fn* function returns a promise - that promise will be `await`ed. + * @since v17.4.0, v16.14.0 + * @param fn a function to filter chunks from the stream. Async or not. + * @returns a stream filtered with the predicate *fn*. + */ + filter( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Readable; + /** + * This method allows iterating a stream. For each chunk in the stream the *fn* function will be called. + * If the *fn* function returns a promise - that promise will be `await`ed. + * + * This method is different from `for await...of` loops in that it can optionally process chunks concurrently. + * In addition, a `forEach` iteration can only be stopped by having passed a `signal` option + * and aborting the related AbortController while `for await...of` can be stopped with `break` or `return`. + * In either case the stream will be destroyed. + * + * This method is different from listening to the `'data'` event in that it uses the `readable` event + * in the underlying machinary and can limit the number of concurrent *fn* calls. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise for when the stream has finished. + */ + forEach( + fn: (data: any, options?: Pick) => void | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method allows easily obtaining the contents of a stream. + * + * As this method reads the entire stream into memory, it negates the benefits of streams. It's intended + * for interoperability and convenience, not as the primary way to consume streams. + * @since v17.5.0 + * @returns a promise containing an array with the contents of the stream. + */ + toArray(options?: Pick): Promise; + /** + * This method is similar to `Array.prototype.some` and calls *fn* on each chunk in the stream + * until the awaited return value is `true` (or any truthy value). Once an *fn* call on a chunk + * `await`ed return value is truthy, the stream is destroyed and the promise is fulfilled with `true`. + * If none of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `false`. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise evaluating to `true` if *fn* returned a truthy value for at least one of the chunks. + */ + some( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method is similar to `Array.prototype.find` and calls *fn* on each chunk in the stream + * to find a chunk with a truthy value for *fn*. Once an *fn* call's awaited return value is truthy, + * the stream is destroyed and the promise is fulfilled with value for which *fn* returned a truthy value. + * If all of the *fn* calls on the chunks return a falsy value, the promise is fulfilled with `undefined`. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise evaluating to the first chunk for which *fn* evaluated with a truthy value, + * or `undefined` if no element was found. + */ + find( + fn: (data: any, options?: Pick) => data is T, + options?: ArrayOptions, + ): Promise; + find( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method is similar to `Array.prototype.every` and calls *fn* on each chunk in the stream + * to check if all awaited return values are truthy value for *fn*. Once an *fn* call on a chunk + * `await`ed return value is falsy, the stream is destroyed and the promise is fulfilled with `false`. + * If all of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `true`. + * @since v17.5.0 + * @param fn a function to call on each chunk of the stream. Async or not. + * @returns a promise evaluating to `true` if *fn* returned a truthy value for every one of the chunks. + */ + every( + fn: (data: any, options?: Pick) => boolean | Promise, + options?: ArrayOptions, + ): Promise; + /** + * This method returns a new stream by applying the given callback to each chunk of the stream + * and then flattening the result. + * + * It is possible to return a stream or another iterable or async iterable from *fn* and the result streams + * will be merged (flattened) into the returned stream. + * @since v17.5.0 + * @param fn a function to map over every chunk in the stream. May be async. May be a stream or generator. + * @returns a stream flat-mapped with the function *fn*. + */ + flatMap(fn: (data: any, options?: Pick) => any, options?: ArrayOptions): Readable; + /** + * This method returns a new stream with the first *limit* chunks dropped from the start. + * @since v17.5.0 + * @param limit the number of chunks to drop from the readable. + * @returns a stream with *limit* chunks dropped from the start. + */ + drop(limit: number, options?: Pick): Readable; + /** + * This method returns a new stream with the first *limit* chunks. + * @since v17.5.0 + * @param limit the number of chunks to take from the readable. + * @returns a stream with *limit* chunks taken. + */ + take(limit: number, options?: Pick): Readable; + /** + * This method returns a new stream with chunks of the underlying stream paired with a counter + * in the form `[index, chunk]`. The first index value is `0` and it increases by 1 for each chunk produced. + * @since v17.5.0 + * @returns a stream of indexed pairs. + */ + asIndexedPairs(options?: Pick): Readable; + /** + * This method calls *fn* on each chunk of the stream in order, passing it the result from the calculation + * on the previous element. It returns a promise for the final value of the reduction. + * + * If no *initial* value is supplied the first chunk of the stream is used as the initial value. + * If the stream is empty, the promise is rejected with a `TypeError` with the `ERR_INVALID_ARGS` code property. + * + * The reducer function iterates the stream element-by-element which means that there is no *concurrency* parameter + * or parallelism. To perform a reduce concurrently, you can extract the async function to `readable.map` method. + * @since v17.5.0 + * @param fn a reducer function to call over every chunk in the stream. Async or not. + * @param initial the initial value to use in the reduction. + * @returns a promise for the final value of the reduction. + */ + reduce( + fn: (previous: any, data: any, options?: Pick) => T, + initial?: undefined, + options?: Pick, + ): Promise; + reduce( + fn: (previous: T, data: any, options?: Pick) => T, + initial: T, + options?: Pick, + ): Promise; + _destroy(error: Error | null, callback: (error?: Error | null) => void): void; + /** + * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'`event (unless `emitClose` is set to `false`). After this call, the readable + * stream will release any internal resources and subsequent calls to `push()`will be ignored. + * + * Once `destroy()` has been called any further calls will be a no-op and no + * further errors except from `_destroy()` may be emitted as `'error'`. + * + * Implementors should not override this method, but instead implement `readable._destroy()`. + * @since v8.0.0 + * @param error Error which will be passed as payload in `'error'` event + */ + destroy(error?: Error): this; + /** + * Event emitter + * The defined events on documents including: + * 1. close + * 2. data + * 3. end + * 4. error + * 5. pause + * 6. readable + * 7. resume + */ + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: any) => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "readable", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; + addListener(event: string | symbol, listener: (...args: any[]) => void): this; + emit(event: "close"): boolean; + emit(event: "data", chunk: any): boolean; + emit(event: "end"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "pause"): boolean; + emit(event: "readable"): boolean; + emit(event: "resume"): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: any) => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "pause", listener: () => void): this; + on(event: "readable", listener: () => void): this; + on(event: "resume", listener: () => void): this; + on(event: string | symbol, listener: (...args: any[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: any) => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "pause", listener: () => void): this; + once(event: "readable", listener: () => void): this; + once(event: "resume", listener: () => void): this; + once(event: string | symbol, listener: (...args: any[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: any) => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "readable", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; + prependListener(event: string | symbol, listener: (...args: any[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: any) => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "readable", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; + prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "data", listener: (chunk: any) => void): this; + removeListener(event: "end", listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "pause", listener: () => void): this; + removeListener(event: "readable", listener: () => void): this; + removeListener(event: "resume", listener: () => void): this; + removeListener(event: string | symbol, listener: (...args: any[]) => void): this; + [Symbol.asyncIterator](): AsyncIterableIterator; + /** + * Calls `readable.destroy()` with an `AbortError` and returns a promise that fulfills when the stream is finished. + * @since v20.4.0 + */ + [Symbol.asyncDispose](): Promise; + } + import WritableOptions = internal.WritableOptions; + class WritableBase extends Stream implements NodeJS.WritableStream { + /** + * Is `true` if it is safe to call `writable.write()`, which means + * the stream has not been destroyed, errored, or ended. + * @since v11.4.0 + */ + readonly writable: boolean; + /** + * Is `true` after `writable.end()` has been called. This property + * does not indicate whether the data has been flushed, for this use `writable.writableFinished` instead. + * @since v12.9.0 + */ + readonly writableEnded: boolean; + /** + * Is set to `true` immediately before the `'finish'` event is emitted. + * @since v12.6.0 + */ + readonly writableFinished: boolean; + /** + * Return the value of `highWaterMark` passed when creating this `Writable`. + * @since v9.3.0 + */ + readonly writableHighWaterMark: number; + /** + * This property contains the number of bytes (or objects) in the queue + * ready to be written. The value provides introspection data regarding + * the status of the `highWaterMark`. + * @since v9.4.0 + */ + readonly writableLength: number; + /** + * Getter for the property `objectMode` of a given `Writable` stream. + * @since v12.3.0 + */ + readonly writableObjectMode: boolean; + /** + * Number of times `writable.uncork()` needs to be + * called in order to fully uncork the stream. + * @since v13.2.0, v12.16.0 + */ + readonly writableCorked: number; + /** + * Is `true` after `writable.destroy()` has been called. + * @since v8.0.0 + */ + destroyed: boolean; + /** + * Is `true` after `'close'` has been emitted. + * @since v18.0.0 + */ + readonly closed: boolean; + /** + * Returns error if the stream has been destroyed with an error. + * @since v18.0.0 + */ + readonly errored: Error | null; + /** + * Is `true` if the stream's buffer has been full and stream will emit `'drain'`. + * @since v15.2.0, v14.17.0 + */ + readonly writableNeedDrain: boolean; + constructor(opts?: WritableOptions); + _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; + _writev?( + chunks: Array<{ + chunk: any; + encoding: BufferEncoding; + }>, + callback: (error?: Error | null) => void, + ): void; + _construct?(callback: (error?: Error | null) => void): void; + _destroy(error: Error | null, callback: (error?: Error | null) => void): void; + _final(callback: (error?: Error | null) => void): void; + /** + * The `writable.write()` method writes some data to the stream, and calls the + * supplied `callback` once the data has been fully handled. If an error + * occurs, the `callback` will be called with the error as its + * first argument. The `callback` is called asynchronously and before `'error'` is + * emitted. + * + * The return value is `true` if the internal buffer is less than the`highWaterMark` configured when the stream was created after admitting `chunk`. + * If `false` is returned, further attempts to write data to the stream should + * stop until the `'drain'` event is emitted. + * + * While a stream is not draining, calls to `write()` will buffer `chunk`, and + * return false. Once all currently buffered chunks are drained (accepted for + * delivery by the operating system), the `'drain'` event will be emitted. + * Once `write()` returns false, do not write more chunks + * until the `'drain'` event is emitted. While calling `write()` on a stream that + * is not draining is allowed, Node.js will buffer all written chunks until + * maximum memory usage occurs, at which point it will abort unconditionally. + * Even before it aborts, high memory usage will cause poor garbage collector + * performance and high RSS (which is not typically released back to the system, + * even after the memory is no longer required). Since TCP sockets may never + * drain if the remote peer does not read the data, writing a socket that is + * not draining may lead to a remotely exploitable vulnerability. + * + * Writing data while the stream is not draining is particularly + * problematic for a `Transform`, because the `Transform` streams are paused + * by default until they are piped or a `'data'` or `'readable'` event handler + * is added. + * + * If the data to be written can be generated or fetched on demand, it is + * recommended to encapsulate the logic into a `Readable` and use {@link pipe}. However, if calling `write()` is preferred, it is + * possible to respect backpressure and avoid memory issues using the `'drain'` event: + * + * ```js + * function write(data, cb) { + * if (!stream.write(data)) { + * stream.once('drain', cb); + * } else { + * process.nextTick(cb); + * } + * } + * + * // Wait for cb to be called before doing any other write. + * write('hello', () => { + * console.log('Write completed, do more writes now.'); + * }); + * ``` + * + * A `Writable` stream in object mode will always ignore the `encoding` argument. + * @since v0.9.4 + * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a string, `Buffer` or `Uint8Array`. For object mode streams, `chunk` may be any + * JavaScript value other than `null`. + * @param [encoding='utf8'] The encoding, if `chunk` is a string. + * @param callback Callback for when this chunk of data is flushed. + * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. + */ + write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean; + write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean; + /** + * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream. + * @since v0.11.15 + * @param encoding The new default encoding + */ + setDefaultEncoding(encoding: BufferEncoding): this; + /** + * Calling the `writable.end()` method signals that no more data will be written + * to the `Writable`. The optional `chunk` and `encoding` arguments allow one + * final additional chunk of data to be written immediately before closing the + * stream. + * + * Calling the {@link write} method after calling {@link end} will raise an error. + * + * ```js + * // Write 'hello, ' and then end with 'world!'. + * const fs = require('node:fs'); + * const file = fs.createWriteStream('example.txt'); + * file.write('hello, '); + * file.end('world!'); + * // Writing more now is not allowed! + * ``` + * @since v0.9.4 + * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a string, `Buffer` or `Uint8Array`. For object mode streams, `chunk` may be any + * JavaScript value other than `null`. + * @param encoding The encoding if `chunk` is a string + * @param callback Callback for when the stream is finished. + */ + end(cb?: () => void): this; + end(chunk: any, cb?: () => void): this; + end(chunk: any, encoding: BufferEncoding, cb?: () => void): this; + /** + * The `writable.cork()` method forces all written data to be buffered in memory. + * The buffered data will be flushed when either the {@link uncork} or {@link end} methods are called. + * + * The primary intent of `writable.cork()` is to accommodate a situation in which + * several small chunks are written to the stream in rapid succession. Instead of + * immediately forwarding them to the underlying destination, `writable.cork()`buffers all the chunks until `writable.uncork()` is called, which will pass them + * all to `writable._writev()`, if present. This prevents a head-of-line blocking + * situation where data is being buffered while waiting for the first small chunk + * to be processed. However, use of `writable.cork()` without implementing`writable._writev()` may have an adverse effect on throughput. + * + * See also: `writable.uncork()`, `writable._writev()`. + * @since v0.11.2 + */ + cork(): void; + /** + * The `writable.uncork()` method flushes all data buffered since {@link cork} was called. + * + * When using `writable.cork()` and `writable.uncork()` to manage the buffering + * of writes to a stream, defer calls to `writable.uncork()` using`process.nextTick()`. Doing so allows batching of all`writable.write()` calls that occur within a given Node.js event + * loop phase. + * + * ```js + * stream.cork(); + * stream.write('some '); + * stream.write('data '); + * process.nextTick(() => stream.uncork()); + * ``` + * + * If the `writable.cork()` method is called multiple times on a stream, the + * same number of calls to `writable.uncork()` must be called to flush the buffered + * data. + * + * ```js + * stream.cork(); + * stream.write('some '); + * stream.cork(); + * stream.write('data '); + * process.nextTick(() => { + * stream.uncork(); + * // The data will not be flushed until uncork() is called a second time. + * stream.uncork(); + * }); + * ``` + * + * See also: `writable.cork()`. + * @since v0.11.2 + */ + uncork(): void; + /** + * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'`event (unless `emitClose` is set to `false`). After this call, the writable + * stream has ended and subsequent calls to `write()` or `end()` will result in + * an `ERR_STREAM_DESTROYED` error. + * This is a destructive and immediate way to destroy a stream. Previous calls to`write()` may not have drained, and may trigger an `ERR_STREAM_DESTROYED` error. + * Use `end()` instead of destroy if data should flush before close, or wait for + * the `'drain'` event before destroying the stream. + * + * Once `destroy()` has been called any further calls will be a no-op and no + * further errors except from `_destroy()` may be emitted as `'error'`. + * + * Implementors should not override this method, + * but instead implement `writable._destroy()`. + * @since v8.0.0 + * @param error Optional, an error to emit with `'error'` event. + */ + destroy(error?: Error): this; + /** + * Event emitter + * The defined events on documents including: + * 1. close + * 2. drain + * 3. error + * 4. finish + * 5. pipe + * 6. unpipe + */ + addListener(event: "close", listener: () => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "pipe", listener: (src: Readable) => void): this; + addListener(event: "unpipe", listener: (src: Readable) => void): this; + addListener(event: string | symbol, listener: (...args: any[]) => void): this; + emit(event: "close"): boolean; + emit(event: "drain"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "finish"): boolean; + emit(event: "pipe", src: Readable): boolean; + emit(event: "unpipe", src: Readable): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "close", listener: () => void): this; + on(event: "drain", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "pipe", listener: (src: Readable) => void): this; + on(event: "unpipe", listener: (src: Readable) => void): this; + on(event: string | symbol, listener: (...args: any[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "drain", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "pipe", listener: (src: Readable) => void): this; + once(event: "unpipe", listener: (src: Readable) => void): this; + once(event: string | symbol, listener: (...args: any[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "pipe", listener: (src: Readable) => void): this; + prependListener(event: "unpipe", listener: (src: Readable) => void): this; + prependListener(event: string | symbol, listener: (...args: any[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "pipe", listener: (src: Readable) => void): this; + prependOnceListener(event: "unpipe", listener: (src: Readable) => void): this; + prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "drain", listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "finish", listener: () => void): this; + removeListener(event: "pipe", listener: (src: Readable) => void): this; + removeListener(event: "unpipe", listener: (src: Readable) => void): this; + removeListener(event: string | symbol, listener: (...args: any[]) => void): this; } namespace internal { class Stream extends internal { @@ -37,7 +948,7 @@ declare module 'stream' { highWaterMark?: number | undefined; objectMode?: boolean | undefined; construct?(this: T, callback: (error?: Error | null) => void): void; - destroy?(this: T, error: Error | null, callback: (error: Error | null) => void): void; + destroy?(this: T, error: Error | null, callback: (error?: Error | null) => void): void; autoDestroy?: boolean | undefined; } interface ReadableOptions extends StreamOptions { @@ -47,726 +958,61 @@ declare module 'stream' { /** * @since v0.9.4 */ - class Readable extends Stream implements NodeJS.ReadableStream { + class Readable extends ReadableBase { /** - * A utility method for creating Readable Streams out of iterators. - */ - static from(iterable: Iterable | AsyncIterable, options?: ReadableOptions): Readable; - /** - * Returns whether the stream has been read from or cancelled. - * @since v16.8.0 - */ - static isDisturbed(stream: Readable | NodeJS.ReadableStream): boolean; - /** - * Returns whether the stream was destroyed or errored before emitting `'end'`. - * @since v16.8.0 + * A utility method for creating a `Readable` from a web `ReadableStream`. + * @since v17.0.0 * @experimental */ - readonly readableAborted: boolean; + static fromWeb( + readableStream: streamWeb.ReadableStream, + options?: Pick, + ): Readable; /** - * Is `true` if it is safe to call `readable.read()`, which means - * the stream has not been destroyed or emitted `'error'` or `'end'`. - * @since v11.4.0 - */ - readable: boolean; - /** - * Returns whether `'data'` has been emitted. - * @since v16.7.0 + * A utility method for creating a web `ReadableStream` from a `Readable`. + * @since v17.0.0 * @experimental */ - readonly readableDidRead: boolean; - /** - * Getter for the property `encoding` of a given `Readable` stream. The `encoding`property can be set using the `readable.setEncoding()` method. - * @since v12.7.0 - */ - readonly readableEncoding: BufferEncoding | null; - /** - * Becomes `true` when `'end'` event is emitted. - * @since v12.9.0 - */ - readonly readableEnded: boolean; - /** - * This property reflects the current state of a `Readable` stream as described - * in the `Three states` section. - * @since v9.4.0 - */ - readonly readableFlowing: boolean | null; - /** - * Returns the value of `highWaterMark` passed when creating this `Readable`. - * @since v9.3.0 - */ - readonly readableHighWaterMark: number; - /** - * This property contains the number of bytes (or objects) in the queue - * ready to be read. The value provides introspection data regarding - * the status of the `highWaterMark`. - * @since v9.4.0 - */ - readonly readableLength: number; - /** - * Getter for the property `objectMode` of a given `Readable` stream. - * @since v12.3.0 - */ - readonly readableObjectMode: boolean; - /** - * Is `true` after `readable.destroy()` has been called. - * @since v8.0.0 - */ - destroyed: boolean; - constructor(opts?: ReadableOptions); - _construct?(callback: (error?: Error | null) => void): void; - _read(size: number): void; - /** - * The `readable.read()` method pulls some data out of the internal buffer and - * returns it. If no data available to be read, `null` is returned. By default, - * the data will be returned as a `Buffer` object unless an encoding has been - * specified using the `readable.setEncoding()` method or the stream is operating - * in object mode. - * - * The optional `size` argument specifies a specific number of bytes to read. If`size` bytes are not available to be read, `null` will be returned _unless_the stream has ended, in which - * case all of the data remaining in the internal - * buffer will be returned. - * - * If the `size` argument is not specified, all of the data contained in the - * internal buffer will be returned. - * - * The `size` argument must be less than or equal to 1 GiB. - * - * The `readable.read()` method should only be called on `Readable` streams - * operating in paused mode. In flowing mode, `readable.read()` is called - * automatically until the internal buffer is fully drained. - * - * ```js - * const readable = getReadableStreamSomehow(); - * - * // 'readable' may be triggered multiple times as data is buffered in - * readable.on('readable', () => { - * let chunk; - * console.log('Stream is readable (new data received in buffer)'); - * // Use a loop to make sure we read all currently available data - * while (null !== (chunk = readable.read())) { - * console.log(`Read ${chunk.length} bytes of data...`); - * } - * }); - * - * // 'end' will be triggered once when there is no more data available - * readable.on('end', () => { - * console.log('Reached end of stream.'); - * }); - * ``` - * - * Each call to `readable.read()` returns a chunk of data, or `null`. The chunks - * are not concatenated. A `while` loop is necessary to consume all data - * currently in the buffer. When reading a large file `.read()` may return `null`, - * having consumed all buffered content so far, but there is still more data to - * come not yet buffered. In this case a new `'readable'` event will be emitted - * when there is more data in the buffer. Finally the `'end'` event will be - * emitted when there is no more data to come. - * - * Therefore to read a file's whole contents from a `readable`, it is necessary - * to collect chunks across multiple `'readable'` events: - * - * ```js - * const chunks = []; - * - * readable.on('readable', () => { - * let chunk; - * while (null !== (chunk = readable.read())) { - * chunks.push(chunk); - * } - * }); - * - * readable.on('end', () => { - * const content = chunks.join(''); - * }); - * ``` - * - * A `Readable` stream in object mode will always return a single item from - * a call to `readable.read(size)`, regardless of the value of the`size` argument. - * - * If the `readable.read()` method returns a chunk of data, a `'data'` event will - * also be emitted. - * - * Calling {@link read} after the `'end'` event has - * been emitted will return `null`. No runtime error will be raised. - * @since v0.9.4 - * @param size Optional argument to specify how much data to read. - */ - read(size?: number): any; - /** - * The `readable.setEncoding()` method sets the character encoding for - * data read from the `Readable` stream. - * - * By default, no encoding is assigned and stream data will be returned as`Buffer` objects. Setting an encoding causes the stream data - * to be returned as strings of the specified encoding rather than as `Buffer`objects. For instance, calling `readable.setEncoding('utf8')` will cause the - * output data to be interpreted as UTF-8 data, and passed as strings. Calling`readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal - * string format. - * - * The `Readable` stream will properly handle multi-byte characters delivered - * through the stream that would otherwise become improperly decoded if simply - * pulled from the stream as `Buffer` objects. - * - * ```js - * const readable = getReadableStreamSomehow(); - * readable.setEncoding('utf8'); - * readable.on('data', (chunk) => { - * assert.equal(typeof chunk, 'string'); - * console.log('Got %d characters of string data:', chunk.length); - * }); - * ``` - * @since v0.9.4 - * @param encoding The encoding to use. - */ - setEncoding(encoding: BufferEncoding): this; - /** - * The `readable.pause()` method will cause a stream in flowing mode to stop - * emitting `'data'` events, switching out of flowing mode. Any data that - * becomes available will remain in the internal buffer. - * - * ```js - * const readable = getReadableStreamSomehow(); - * readable.on('data', (chunk) => { - * console.log(`Received ${chunk.length} bytes of data.`); - * readable.pause(); - * console.log('There will be no additional data for 1 second.'); - * setTimeout(() => { - * console.log('Now data will start flowing again.'); - * readable.resume(); - * }, 1000); - * }); - * ``` - * - * The `readable.pause()` method has no effect if there is a `'readable'`event listener. - * @since v0.9.4 - */ - pause(): this; - /** - * The `readable.resume()` method causes an explicitly paused `Readable` stream to - * resume emitting `'data'` events, switching the stream into flowing mode. - * - * The `readable.resume()` method can be used to fully consume the data from a - * stream without actually processing any of that data: - * - * ```js - * getReadableStreamSomehow() - * .resume() - * .on('end', () => { - * console.log('Reached the end, but did not read anything.'); - * }); - * ``` - * - * The `readable.resume()` method has no effect if there is a `'readable'`event listener. - * @since v0.9.4 - */ - resume(): this; - /** - * The `readable.isPaused()` method returns the current operating state of the`Readable`. This is used primarily by the mechanism that underlies the`readable.pipe()` method. In most - * typical cases, there will be no reason to - * use this method directly. - * - * ```js - * const readable = new stream.Readable(); - * - * readable.isPaused(); // === false - * readable.pause(); - * readable.isPaused(); // === true - * readable.resume(); - * readable.isPaused(); // === false - * ``` - * @since v0.11.14 - */ - isPaused(): boolean; - /** - * The `readable.unpipe()` method detaches a `Writable` stream previously attached - * using the {@link pipe} method. - * - * If the `destination` is not specified, then _all_ pipes are detached. - * - * If the `destination` is specified, but no pipe is set up for it, then - * the method does nothing. - * - * ```js - * const fs = require('fs'); - * const readable = getReadableStreamSomehow(); - * const writable = fs.createWriteStream('file.txt'); - * // All the data from readable goes into 'file.txt', - * // but only for the first second. - * readable.pipe(writable); - * setTimeout(() => { - * console.log('Stop writing to file.txt.'); - * readable.unpipe(writable); - * console.log('Manually close the file stream.'); - * writable.end(); - * }, 1000); - * ``` - * @since v0.9.4 - * @param destination Optional specific stream to unpipe - */ - unpipe(destination?: NodeJS.WritableStream): this; - /** - * Passing `chunk` as `null` signals the end of the stream (EOF) and behaves the - * same as `readable.push(null)`, after which no more data can be written. The EOF - * signal is put at the end of the buffer and any buffered data will still be - * flushed. - * - * The `readable.unshift()` method pushes a chunk of data back into the internal - * buffer. This is useful in certain situations where a stream is being consumed by - * code that needs to "un-consume" some amount of data that it has optimistically - * pulled out of the source, so that the data can be passed on to some other party. - * - * The `stream.unshift(chunk)` method cannot be called after the `'end'` event - * has been emitted or a runtime error will be thrown. - * - * Developers using `stream.unshift()` often should consider switching to - * use of a `Transform` stream instead. See the `API for stream implementers` section for more information. - * - * ```js - * // Pull off a header delimited by \n\n. - * // Use unshift() if we get too much. - * // Call the callback with (error, header, stream). - * const { StringDecoder } = require('string_decoder'); - * function parseHeader(stream, callback) { - * stream.on('error', callback); - * stream.on('readable', onReadable); - * const decoder = new StringDecoder('utf8'); - * let header = ''; - * function onReadable() { - * let chunk; - * while (null !== (chunk = stream.read())) { - * const str = decoder.write(chunk); - * if (str.match(/\n\n/)) { - * // Found the header boundary. - * const split = str.split(/\n\n/); - * header += split.shift(); - * const remaining = split.join('\n\n'); - * const buf = Buffer.from(remaining, 'utf8'); - * stream.removeListener('error', callback); - * // Remove the 'readable' listener before unshifting. - * stream.removeListener('readable', onReadable); - * if (buf.length) - * stream.unshift(buf); - * // Now the body of the message can be read from the stream. - * callback(null, header, stream); - * } else { - * // Still reading the header. - * header += str; - * } - * } - * } - * } - * ``` - * - * Unlike {@link push}, `stream.unshift(chunk)` will not - * end the reading process by resetting the internal reading state of the stream. - * This can cause unexpected results if `readable.unshift()` is called during a - * read (i.e. from within a {@link _read} implementation on a - * custom stream). Following the call to `readable.unshift()` with an immediate {@link push} will reset the reading state appropriately, - * however it is best to simply avoid calling `readable.unshift()` while in the - * process of performing a read. - * @since v0.9.11 - * @param chunk Chunk of data to unshift onto the read queue. For streams not operating in object mode, `chunk` must be a string, `Buffer`, `Uint8Array` or `null`. For object mode - * streams, `chunk` may be any JavaScript value. - * @param encoding Encoding of string chunks. Must be a valid `Buffer` encoding, such as `'utf8'` or `'ascii'`. - */ - unshift(chunk: any, encoding?: BufferEncoding): void; - /** - * Prior to Node.js 0.10, streams did not implement the entire `stream` module API - * as it is currently defined. (See `Compatibility` for more information.) - * - * When using an older Node.js library that emits `'data'` events and has a {@link pause} method that is advisory only, the`readable.wrap()` method can be used to create a `Readable` - * stream that uses - * the old stream as its data source. - * - * It will rarely be necessary to use `readable.wrap()` but the method has been - * provided as a convenience for interacting with older Node.js applications and - * libraries. - * - * ```js - * const { OldReader } = require('./old-api-module.js'); - * const { Readable } = require('stream'); - * const oreader = new OldReader(); - * const myReader = new Readable().wrap(oreader); - * - * myReader.on('readable', () => { - * myReader.read(); // etc. - * }); - * ``` - * @since v0.9.4 - * @param stream An "old style" readable stream - */ - wrap(stream: NodeJS.ReadableStream): this; - push(chunk: any, encoding?: BufferEncoding): boolean; - _destroy(error: Error | null, callback: (error?: Error | null) => void): void; - /** - * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'`event (unless `emitClose` is set to `false`). After this call, the readable - * stream will release any internal resources and subsequent calls to `push()`will be ignored. - * - * Once `destroy()` has been called any further calls will be a no-op and no - * further errors except from `_destroy()` may be emitted as `'error'`. - * - * Implementors should not override this method, but instead implement `readable._destroy()`. - * @since v8.0.0 - * @param error Error which will be passed as payload in `'error'` event - */ - destroy(error?: Error): this; - /** - * Event emitter - * The defined events on documents including: - * 1. close - * 2. data - * 3. end - * 4. error - * 5. pause - * 6. readable - * 7. resume - */ - addListener(event: 'close', listener: () => void): this; - addListener(event: 'data', listener: (chunk: any) => void): this; - addListener(event: 'end', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'pause', listener: () => void): this; - addListener(event: 'readable', listener: () => void): this; - addListener(event: 'resume', listener: () => void): this; - addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'close'): boolean; - emit(event: 'data', chunk: any): boolean; - emit(event: 'end'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'pause'): boolean; - emit(event: 'readable'): boolean; - emit(event: 'resume'): boolean; - emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'close', listener: () => void): this; - on(event: 'data', listener: (chunk: any) => void): this; - on(event: 'end', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'pause', listener: () => void): this; - on(event: 'readable', listener: () => void): this; - on(event: 'resume', listener: () => void): this; - on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'data', listener: (chunk: any) => void): this; - once(event: 'end', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'pause', listener: () => void): this; - once(event: 'readable', listener: () => void): this; - once(event: 'resume', listener: () => void): this; - once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'data', listener: (chunk: any) => void): this; - prependListener(event: 'end', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'pause', listener: () => void): this; - prependListener(event: 'readable', listener: () => void): this; - prependListener(event: 'resume', listener: () => void): this; - prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'data', listener: (chunk: any) => void): this; - prependOnceListener(event: 'end', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'pause', listener: () => void): this; - prependOnceListener(event: 'readable', listener: () => void): this; - prependOnceListener(event: 'resume', listener: () => void): this; - prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; - removeListener(event: 'close', listener: () => void): this; - removeListener(event: 'data', listener: (chunk: any) => void): this; - removeListener(event: 'end', listener: () => void): this; - removeListener(event: 'error', listener: (err: Error) => void): this; - removeListener(event: 'pause', listener: () => void): this; - removeListener(event: 'readable', listener: () => void): this; - removeListener(event: 'resume', listener: () => void): this; - removeListener(event: string | symbol, listener: (...args: any[]) => void): this; - [Symbol.asyncIterator](): AsyncIterableIterator; + static toWeb(streamReadable: Readable): streamWeb.ReadableStream; } interface WritableOptions extends StreamOptions { decodeStrings?: boolean | undefined; defaultEncoding?: BufferEncoding | undefined; - write?(this: Writable, chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; + write?( + this: Writable, + chunk: any, + encoding: BufferEncoding, + callback: (error?: Error | null) => void, + ): void; writev?( this: Writable, chunks: Array<{ chunk: any; encoding: BufferEncoding; }>, - callback: (error?: Error | null) => void + callback: (error?: Error | null) => void, ): void; final?(this: Writable, callback: (error?: Error | null) => void): void; } /** * @since v0.9.4 */ - class Writable extends Stream implements NodeJS.WritableStream { + class Writable extends WritableBase { /** - * Is `true` if it is safe to call `writable.write()`, which means - * the stream has not been destroyed, errored or ended. - * @since v11.4.0 + * A utility method for creating a `Writable` from a web `WritableStream`. + * @since v17.0.0 + * @experimental */ - readonly writable: boolean; + static fromWeb( + writableStream: streamWeb.WritableStream, + options?: Pick, + ): Writable; /** - * Is `true` after `writable.end()` has been called. This property - * does not indicate whether the data has been flushed, for this use `writable.writableFinished` instead. - * @since v12.9.0 + * A utility method for creating a web `WritableStream` from a `Writable`. + * @since v17.0.0 + * @experimental */ - readonly writableEnded: boolean; - /** - * Is set to `true` immediately before the `'finish'` event is emitted. - * @since v12.6.0 - */ - readonly writableFinished: boolean; - /** - * Return the value of `highWaterMark` passed when creating this `Writable`. - * @since v9.3.0 - */ - readonly writableHighWaterMark: number; - /** - * This property contains the number of bytes (or objects) in the queue - * ready to be written. The value provides introspection data regarding - * the status of the `highWaterMark`. - * @since v9.4.0 - */ - readonly writableLength: number; - /** - * Getter for the property `objectMode` of a given `Writable` stream. - * @since v12.3.0 - */ - readonly writableObjectMode: boolean; - /** - * Number of times `writable.uncork()` needs to be - * called in order to fully uncork the stream. - * @since v13.2.0, v12.16.0 - */ - readonly writableCorked: number; - /** - * Is `true` after `writable.destroy()` has been called. - * @since v8.0.0 - */ - destroyed: boolean; - constructor(opts?: WritableOptions); - _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; - _writev?( - chunks: Array<{ - chunk: any; - encoding: BufferEncoding; - }>, - callback: (error?: Error | null) => void - ): void; - _construct?(callback: (error?: Error | null) => void): void; - _destroy(error: Error | null, callback: (error?: Error | null) => void): void; - _final(callback: (error?: Error | null) => void): void; - /** - * The `writable.write()` method writes some data to the stream, and calls the - * supplied `callback` once the data has been fully handled. If an error - * occurs, the `callback` will be called with the error as its - * first argument. The `callback` is called asynchronously and before `'error'` is - * emitted. - * - * The return value is `true` if the internal buffer is less than the`highWaterMark` configured when the stream was created after admitting `chunk`. - * If `false` is returned, further attempts to write data to the stream should - * stop until the `'drain'` event is emitted. - * - * While a stream is not draining, calls to `write()` will buffer `chunk`, and - * return false. Once all currently buffered chunks are drained (accepted for - * delivery by the operating system), the `'drain'` event will be emitted. - * It is recommended that once `write()` returns false, no more chunks be written - * until the `'drain'` event is emitted. While calling `write()` on a stream that - * is not draining is allowed, Node.js will buffer all written chunks until - * maximum memory usage occurs, at which point it will abort unconditionally. - * Even before it aborts, high memory usage will cause poor garbage collector - * performance and high RSS (which is not typically released back to the system, - * even after the memory is no longer required). Since TCP sockets may never - * drain if the remote peer does not read the data, writing a socket that is - * not draining may lead to a remotely exploitable vulnerability. - * - * Writing data while the stream is not draining is particularly - * problematic for a `Transform`, because the `Transform` streams are paused - * by default until they are piped or a `'data'` or `'readable'` event handler - * is added. - * - * If the data to be written can be generated or fetched on demand, it is - * recommended to encapsulate the logic into a `Readable` and use {@link pipe}. However, if calling `write()` is preferred, it is - * possible to respect backpressure and avoid memory issues using the `'drain'` event: - * - * ```js - * function write(data, cb) { - * if (!stream.write(data)) { - * stream.once('drain', cb); - * } else { - * process.nextTick(cb); - * } - * } - * - * // Wait for cb to be called before doing any other write. - * write('hello', () => { - * console.log('Write completed, do more writes now.'); - * }); - * ``` - * - * A `Writable` stream in object mode will always ignore the `encoding` argument. - * @since v0.9.4 - * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a string, `Buffer` or `Uint8Array`. For object mode streams, `chunk` may be any - * JavaScript value other than `null`. - * @param [encoding='utf8'] The encoding, if `chunk` is a string. - * @param callback Callback for when this chunk of data is flushed. - * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. - */ - write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean; - write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean; - /** - * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream. - * @since v0.11.15 - * @param encoding The new default encoding - */ - setDefaultEncoding(encoding: BufferEncoding): this; - /** - * Calling the `writable.end()` method signals that no more data will be written - * to the `Writable`. The optional `chunk` and `encoding` arguments allow one - * final additional chunk of data to be written immediately before closing the - * stream. - * - * Calling the {@link write} method after calling {@link end} will raise an error. - * - * ```js - * // Write 'hello, ' and then end with 'world!'. - * const fs = require('fs'); - * const file = fs.createWriteStream('example.txt'); - * file.write('hello, '); - * file.end('world!'); - * // Writing more now is not allowed! - * ``` - * @since v0.9.4 - * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a string, `Buffer` or `Uint8Array`. For object mode streams, `chunk` may be any - * JavaScript value other than `null`. - * @param encoding The encoding if `chunk` is a string - * @param callback Callback for when the stream is finished. - */ - end(cb?: () => void): this; - end(chunk: any, cb?: () => void): this; - end(chunk: any, encoding: BufferEncoding, cb?: () => void): this; - /** - * The `writable.cork()` method forces all written data to be buffered in memory. - * The buffered data will be flushed when either the {@link uncork} or {@link end} methods are called. - * - * The primary intent of `writable.cork()` is to accommodate a situation in which - * several small chunks are written to the stream in rapid succession. Instead of - * immediately forwarding them to the underlying destination, `writable.cork()`buffers all the chunks until `writable.uncork()` is called, which will pass them - * all to `writable._writev()`, if present. This prevents a head-of-line blocking - * situation where data is being buffered while waiting for the first small chunk - * to be processed. However, use of `writable.cork()` without implementing`writable._writev()` may have an adverse effect on throughput. - * - * See also: `writable.uncork()`, `writable._writev()`. - * @since v0.11.2 - */ - cork(): void; - /** - * The `writable.uncork()` method flushes all data buffered since {@link cork} was called. - * - * When using `writable.cork()` and `writable.uncork()` to manage the buffering - * of writes to a stream, it is recommended that calls to `writable.uncork()` be - * deferred using `process.nextTick()`. Doing so allows batching of all`writable.write()` calls that occur within a given Node.js event loop phase. - * - * ```js - * stream.cork(); - * stream.write('some '); - * stream.write('data '); - * process.nextTick(() => stream.uncork()); - * ``` - * - * If the `writable.cork()` method is called multiple times on a stream, the - * same number of calls to `writable.uncork()` must be called to flush the buffered - * data. - * - * ```js - * stream.cork(); - * stream.write('some '); - * stream.cork(); - * stream.write('data '); - * process.nextTick(() => { - * stream.uncork(); - * // The data will not be flushed until uncork() is called a second time. - * stream.uncork(); - * }); - * ``` - * - * See also: `writable.cork()`. - * @since v0.11.2 - */ - uncork(): void; - /** - * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'`event (unless `emitClose` is set to `false`). After this call, the writable - * stream has ended and subsequent calls to `write()` or `end()` will result in - * an `ERR_STREAM_DESTROYED` error. - * This is a destructive and immediate way to destroy a stream. Previous calls to`write()` may not have drained, and may trigger an `ERR_STREAM_DESTROYED` error. - * Use `end()` instead of destroy if data should flush before close, or wait for - * the `'drain'` event before destroying the stream. - * - * Once `destroy()` has been called any further calls will be a no-op and no - * further errors except from `_destroy()` may be emitted as `'error'`. - * - * Implementors should not override this method, - * but instead implement `writable._destroy()`. - * @since v8.0.0 - * @param error Optional, an error to emit with `'error'` event. - */ - destroy(error?: Error): this; - /** - * Event emitter - * The defined events on documents including: - * 1. close - * 2. drain - * 3. error - * 4. finish - * 5. pipe - * 6. unpipe - */ - addListener(event: 'close', listener: () => void): this; - addListener(event: 'drain', listener: () => void): this; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'finish', listener: () => void): this; - addListener(event: 'pipe', listener: (src: Readable) => void): this; - addListener(event: 'unpipe', listener: (src: Readable) => void): this; - addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'close'): boolean; - emit(event: 'drain'): boolean; - emit(event: 'error', err: Error): boolean; - emit(event: 'finish'): boolean; - emit(event: 'pipe', src: Readable): boolean; - emit(event: 'unpipe', src: Readable): boolean; - emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'close', listener: () => void): this; - on(event: 'drain', listener: () => void): this; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'finish', listener: () => void): this; - on(event: 'pipe', listener: (src: Readable) => void): this; - on(event: 'unpipe', listener: (src: Readable) => void): this; - on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'drain', listener: () => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'finish', listener: () => void): this; - once(event: 'pipe', listener: (src: Readable) => void): this; - once(event: 'unpipe', listener: (src: Readable) => void): this; - once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'drain', listener: () => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'finish', listener: () => void): this; - prependListener(event: 'pipe', listener: (src: Readable) => void): this; - prependListener(event: 'unpipe', listener: (src: Readable) => void): this; - prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'drain', listener: () => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'finish', listener: () => void): this; - prependOnceListener(event: 'pipe', listener: (src: Readable) => void): this; - prependOnceListener(event: 'unpipe', listener: (src: Readable) => void): this; - prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; - removeListener(event: 'close', listener: () => void): this; - removeListener(event: 'drain', listener: () => void): this; - removeListener(event: 'error', listener: (err: Error) => void): this; - removeListener(event: 'finish', listener: () => void): this; - removeListener(event: 'pipe', listener: (src: Readable) => void): this; - removeListener(event: 'unpipe', listener: (src: Readable) => void): this; - removeListener(event: string | symbol, listener: (...args: any[]) => void): this; + static toWeb(streamWritable: Writable): streamWeb.WritableStream; } interface DuplexOptions extends ReadableOptions, WritableOptions { allowHalfOpen?: boolean | undefined; @@ -784,10 +1030,10 @@ declare module 'stream' { chunk: any; encoding: BufferEncoding; }>, - callback: (error?: Error | null) => void + callback: (error?: Error | null) => void, ): void; final?(this: Duplex, callback: (error?: Error | null) => void): void; - destroy?(this: Duplex, error: Error | null, callback: (error: Error | null) => void): void; + destroy?(this: Duplex, error: Error | null, callback: (error?: Error | null) => void): void; } /** * Duplex streams are streams that implement both the `Readable` and `Writable` interfaces. @@ -799,7 +1045,7 @@ declare module 'stream' { * * `crypto streams` * @since v0.9.4 */ - class Duplex extends Readable implements Writable { + class Duplex extends ReadableBase implements WritableBase { readonly writable: boolean; readonly writableEnded: boolean; readonly writableFinished: boolean; @@ -807,10 +1053,13 @@ declare module 'stream' { readonly writableLength: number; readonly writableObjectMode: boolean; readonly writableCorked: number; + readonly writableNeedDrain: boolean; + readonly closed: boolean; + readonly errored: Error | null; /** * If `false` then the stream will automatically end the writable side when the * readable side ends. Set initially by the `allowHalfOpen` constructor option, - * which defaults to `false`. + * which defaults to `true`. * * This can be changed manually to change the half-open behavior of an existing`Duplex` stream instance, but must be changed before the `'end'` event is * emitted. @@ -839,16 +1088,27 @@ declare module 'stream' { * * @since v16.8.0 */ - static from(src: Stream | Blob | ArrayBuffer | string | Iterable | AsyncIterable | AsyncGeneratorFunction | Promise | Object): Duplex; + static from( + src: + | Stream + | NodeBlob + | ArrayBuffer + | string + | Iterable + | AsyncIterable + | AsyncGeneratorFunction + | Promise + | Object, + ): Duplex; _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; _writev?( chunks: Array<{ chunk: any; encoding: BufferEncoding; }>, - callback: (error?: Error | null) => void + callback: (error?: Error | null) => void, ): void; - _destroy(error: Error | null, callback: (error: Error | null) => void): void; + _destroy(error: Error | null, callback: (error?: Error | null) => void): void; _final(callback: (error?: Error | null) => void): void; write(chunk: any, encoding?: BufferEncoding, cb?: (error: Error | null | undefined) => void): boolean; write(chunk: any, cb?: (error: Error | null | undefined) => void): boolean; @@ -858,22 +1118,150 @@ declare module 'stream' { end(chunk: any, encoding?: BufferEncoding, cb?: () => void): this; cork(): void; uncork(): void; + /** + * A utility method for creating a web `ReadableStream` and `WritableStream` from a `Duplex`. + * @since v17.0.0 + * @experimental + */ + static toWeb(streamDuplex: Duplex): { + readable: streamWeb.ReadableStream; + writable: streamWeb.WritableStream; + }; + /** + * A utility method for creating a `Duplex` from a web `ReadableStream` and `WritableStream`. + * @since v17.0.0 + * @experimental + */ + static fromWeb( + duplexStream: { + readable: streamWeb.ReadableStream; + writable: streamWeb.WritableStream; + }, + options?: Pick< + DuplexOptions, + "allowHalfOpen" | "decodeStrings" | "encoding" | "highWaterMark" | "objectMode" | "signal" + >, + ): Duplex; + /** + * Event emitter + * The defined events on documents including: + * 1. close + * 2. data + * 3. drain + * 4. end + * 5. error + * 6. finish + * 7. pause + * 8. pipe + * 9. readable + * 10. resume + * 11. unpipe + */ + addListener(event: "close", listener: () => void): this; + addListener(event: "data", listener: (chunk: any) => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "end", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "pause", listener: () => void): this; + addListener(event: "pipe", listener: (src: Readable) => void): this; + addListener(event: "readable", listener: () => void): this; + addListener(event: "resume", listener: () => void): this; + addListener(event: "unpipe", listener: (src: Readable) => void): this; + addListener(event: string | symbol, listener: (...args: any[]) => void): this; + emit(event: "close"): boolean; + emit(event: "data", chunk: any): boolean; + emit(event: "drain"): boolean; + emit(event: "end"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "finish"): boolean; + emit(event: "pause"): boolean; + emit(event: "pipe", src: Readable): boolean; + emit(event: "readable"): boolean; + emit(event: "resume"): boolean; + emit(event: "unpipe", src: Readable): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "close", listener: () => void): this; + on(event: "data", listener: (chunk: any) => void): this; + on(event: "drain", listener: () => void): this; + on(event: "end", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "pause", listener: () => void): this; + on(event: "pipe", listener: (src: Readable) => void): this; + on(event: "readable", listener: () => void): this; + on(event: "resume", listener: () => void): this; + on(event: "unpipe", listener: (src: Readable) => void): this; + on(event: string | symbol, listener: (...args: any[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "data", listener: (chunk: any) => void): this; + once(event: "drain", listener: () => void): this; + once(event: "end", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "pause", listener: () => void): this; + once(event: "pipe", listener: (src: Readable) => void): this; + once(event: "readable", listener: () => void): this; + once(event: "resume", listener: () => void): this; + once(event: "unpipe", listener: (src: Readable) => void): this; + once(event: string | symbol, listener: (...args: any[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "data", listener: (chunk: any) => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "end", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "pause", listener: () => void): this; + prependListener(event: "pipe", listener: (src: Readable) => void): this; + prependListener(event: "readable", listener: () => void): this; + prependListener(event: "resume", listener: () => void): this; + prependListener(event: "unpipe", listener: (src: Readable) => void): this; + prependListener(event: string | symbol, listener: (...args: any[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "data", listener: (chunk: any) => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "end", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "pause", listener: () => void): this; + prependOnceListener(event: "pipe", listener: (src: Readable) => void): this; + prependOnceListener(event: "readable", listener: () => void): this; + prependOnceListener(event: "resume", listener: () => void): this; + prependOnceListener(event: "unpipe", listener: (src: Readable) => void): this; + prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "data", listener: (chunk: any) => void): this; + removeListener(event: "drain", listener: () => void): this; + removeListener(event: "end", listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "finish", listener: () => void): this; + removeListener(event: "pause", listener: () => void): this; + removeListener(event: "pipe", listener: (src: Readable) => void): this; + removeListener(event: "readable", listener: () => void): this; + removeListener(event: "resume", listener: () => void): this; + removeListener(event: "unpipe", listener: (src: Readable) => void): this; + removeListener(event: string | symbol, listener: (...args: any[]) => void): this; } type TransformCallback = (error?: Error | null, data?: any) => void; interface TransformOptions extends DuplexOptions { construct?(this: Transform, callback: (error?: Error | null) => void): void; read?(this: Transform, size: number): void; - write?(this: Transform, chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; + write?( + this: Transform, + chunk: any, + encoding: BufferEncoding, + callback: (error?: Error | null) => void, + ): void; writev?( this: Transform, chunks: Array<{ chunk: any; encoding: BufferEncoding; }>, - callback: (error?: Error | null) => void + callback: (error?: Error | null) => void, ): void; final?(this: Transform, callback: (error?: Error | null) => void): void; - destroy?(this: Transform, error: Error | null, callback: (error: Error | null) => void): void; + destroy?(this: Transform, error: Error | null, callback: (error?: Error | null) => void): void; transform?(this: Transform, chunk: any, encoding: BufferEncoding, callback: TransformCallback): void; flush?(this: Transform, callback: TransformCallback): void; } @@ -899,18 +1287,21 @@ declare module 'stream' { */ class PassThrough extends Transform {} /** + * A stream to attach a signal to. + * * Attaches an AbortSignal to a readable or writeable stream. This lets code * control stream destruction using an `AbortController`. * - * Calling `abort` on the `AbortController` corresponding to the passed`AbortSignal` will behave the same way as calling `.destroy(new AbortError())`on the stream. + * Calling `abort` on the `AbortController` corresponding to the passed`AbortSignal` will behave the same way as calling `.destroy(new AbortError())`on the stream, and `controller.error(new + * AbortError())` for webstreams. * * ```js - * const fs = require('fs'); + * const fs = require('node:fs'); * * const controller = new AbortController(); * const read = addAbortSignal( * controller.signal, - * fs.createReadStream(('object.json')) + * fs.createReadStream(('object.json')), * ); * // Later, abort the operation closing the stream * controller.abort(); @@ -923,7 +1314,7 @@ declare module 'stream' { * setTimeout(() => controller.abort(), 10_000); // set a timeout * const stream = addAbortSignal( * controller.signal, - * fs.createReadStream(('object.json')) + * fs.createReadStream(('object.json')), * ); * (async () => { * try { @@ -939,22 +1330,70 @@ declare module 'stream' { * } * })(); * ``` + * + * Or using an `AbortSignal` with a ReadableStream: + * + * ```js + * const controller = new AbortController(); + * const rs = new ReadableStream({ + * start(controller) { + * controller.enqueue('hello'); + * controller.enqueue('world'); + * controller.close(); + * }, + * }); + * + * addAbortSignal(controller.signal, rs); + * + * finished(rs, (err) => { + * if (err) { + * if (err.name === 'AbortError') { + * // The operation was cancelled + * } + * } + * }); + * + * const reader = rs.getReader(); + * + * reader.read().then(({ value, done }) => { + * console.log(value); // hello + * console.log(done); // false + * controller.abort(); + * }); + * ``` * @since v15.4.0 * @param signal A signal representing possible cancellation * @param stream a stream to attach a signal to */ function addAbortSignal(signal: AbortSignal, stream: T): T; + /** + * Returns the default highWaterMark used by streams. + * Defaults to `16384` (16 KiB), or `16` for `objectMode`. + * @since v19.9.0 + * @param objectMode + */ + function getDefaultHighWaterMark(objectMode: boolean): number; + /** + * Sets the default highWaterMark used by streams. + * @since v19.9.0 + * @param objectMode + * @param value highWaterMark value + */ + function setDefaultHighWaterMark(objectMode: boolean, value: number): void; interface FinishedOptions extends Abortable { error?: boolean | undefined; readable?: boolean | undefined; writable?: boolean | undefined; } /** + * A readable and/or writable stream/webstream. + * * A function to get notified when a stream is no longer readable, writable * or has experienced an error or a premature close event. * * ```js - * const { finished } = require('stream'); + * const { finished } = require('node:stream'); + * const fs = require('node:fs'); * * const rs = fs.createReadStream('archive.tar'); * @@ -972,21 +1411,7 @@ declare module 'stream' { * Especially useful in error handling scenarios where a stream is destroyed * prematurely (like an aborted HTTP request), and will not emit `'end'`or `'finish'`. * - * The `finished` API provides promise version: - * - * ```js - * const { finished } = require('stream/promises'); - * - * const rs = fs.createReadStream('archive.tar'); - * - * async function run() { - * await finished(rs); - * console.log('Stream is done reading.'); - * } - * - * run().catch(console.error); - * rs.resume(); // Drain the stream. - * ``` + * The `finished` API provides `promise version`. * * `stream.finished()` leaves dangling event listeners (in particular`'error'`, `'end'`, `'finish'` and `'close'`) after `callback` has been * invoked. The reason for this is so that unexpected `'error'` events (due to @@ -1005,37 +1430,55 @@ declare module 'stream' { * @param callback A callback function that takes an optional error argument. * @return A cleanup function which removes all registered listeners. */ - function finished(stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, options: FinishedOptions, callback: (err?: NodeJS.ErrnoException | null) => void): () => void; - function finished(stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, callback: (err?: NodeJS.ErrnoException | null) => void): () => void; + function finished( + stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, + options: FinishedOptions, + callback: (err?: NodeJS.ErrnoException | null) => void, + ): () => void; + function finished( + stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, + callback: (err?: NodeJS.ErrnoException | null) => void, + ): () => void; namespace finished { - function __promisify__(stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, options?: FinishedOptions): Promise; + function __promisify__( + stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, + options?: FinishedOptions, + ): Promise; } type PipelineSourceFunction = () => Iterable | AsyncIterable; type PipelineSource = Iterable | AsyncIterable | NodeJS.ReadableStream | PipelineSourceFunction; type PipelineTransform, U> = | NodeJS.ReadWriteStream - | ((source: S extends (...args: any[]) => Iterable | AsyncIterable ? AsyncIterable : S) => AsyncIterable); + | (( + source: S extends (...args: any[]) => Iterable | AsyncIterable ? AsyncIterable + : S, + ) => AsyncIterable); type PipelineTransformSource = PipelineSource | PipelineTransform; type PipelineDestinationIterableFunction = (source: AsyncIterable) => AsyncIterable; type PipelineDestinationPromiseFunction = (source: AsyncIterable) => Promise

; - type PipelineDestination, P> = S extends PipelineTransformSource - ? NodeJS.WritableStream | PipelineDestinationIterableFunction | PipelineDestinationPromiseFunction + type PipelineDestination, P> = S extends + PipelineTransformSource ? + | NodeJS.WritableStream + | PipelineDestinationIterableFunction + | PipelineDestinationPromiseFunction : never; - type PipelineCallback> = S extends PipelineDestinationPromiseFunction - ? (err: NodeJS.ErrnoException | null, value: P) => void + type PipelineCallback> = S extends + PipelineDestinationPromiseFunction ? (err: NodeJS.ErrnoException | null, value: P) => void : (err: NodeJS.ErrnoException | null) => void; - type PipelinePromise> = S extends PipelineDestinationPromiseFunction ? Promise

: Promise; + type PipelinePromise> = S extends + PipelineDestinationPromiseFunction ? Promise

: Promise; interface PipelineOptions { - signal: AbortSignal; + signal?: AbortSignal | undefined; + end?: boolean | undefined; } /** * A module method to pipe between streams and generators forwarding errors and * properly cleaning up and provide a callback when the pipeline is complete. * * ```js - * const { pipeline } = require('stream'); - * const fs = require('fs'); - * const zlib = require('zlib'); + * const { pipeline } = require('node:stream'); + * const fs = require('node:fs'); + * const zlib = require('node:zlib'); * * // Use the pipeline API to easily pipe a series of streams * // together and get notified when the pipeline is fully done. @@ -1052,95 +1495,11 @@ declare module 'stream' { * } else { * console.log('Pipeline succeeded.'); * } - * } + * }, * ); * ``` * - * The `pipeline` API provides a promise version, which can also - * receive an options argument as the last parameter with a`signal` `AbortSignal` property. When the signal is aborted,`destroy` will be called on the underlying pipeline, with - * an`AbortError`. - * - * ```js - * const { pipeline } = require('stream/promises'); - * - * async function run() { - * await pipeline( - * fs.createReadStream('archive.tar'), - * zlib.createGzip(), - * fs.createWriteStream('archive.tar.gz') - * ); - * console.log('Pipeline succeeded.'); - * } - * - * run().catch(console.error); - * ``` - * - * To use an `AbortSignal`, pass it inside an options object, - * as the last argument: - * - * ```js - * const { pipeline } = require('stream/promises'); - * - * async function run() { - * const ac = new AbortController(); - * const signal = ac.signal; - * - * setTimeout(() => ac.abort(), 1); - * await pipeline( - * fs.createReadStream('archive.tar'), - * zlib.createGzip(), - * fs.createWriteStream('archive.tar.gz'), - * { signal }, - * ); - * } - * - * run().catch(console.error); // AbortError - * ``` - * - * The `pipeline` API also supports async generators: - * - * ```js - * const { pipeline } = require('stream/promises'); - * const fs = require('fs'); - * - * async function run() { - * await pipeline( - * fs.createReadStream('lowercase.txt'), - * async function* (source, signal) { - * source.setEncoding('utf8'); // Work with strings rather than `Buffer`s. - * for await (const chunk of source) { - * yield await processChunk(chunk, { signal }); - * } - * }, - * fs.createWriteStream('uppercase.txt') - * ); - * console.log('Pipeline succeeded.'); - * } - * - * run().catch(console.error); - * ``` - * - * Remember to handle the `signal` argument passed into the async generator. - * Especially in the case where the async generator is the source for the - * pipeline (i.e. first argument) or the pipeline will never complete. - * - * ```js - * const { pipeline } = require('stream/promises'); - * const fs = require('fs'); - * - * async function run() { - * await pipeline( - * async function * (signal) { - * await someLongRunningfn({ signal }); - * yield 'asd'; - * }, - * fs.createWriteStream('uppercase.txt') - * ); - * console.log('Pipeline succeeded.'); - * } - * - * run().catch(console.error); - * ``` + * The `pipeline` API provides a `promise version`. * * `stream.pipeline()` will call `stream.destroy(err)` on all streams except: * @@ -1149,83 +1508,164 @@ declare module 'stream' { * * `stream.pipeline()` leaves dangling event listeners on the streams * after the `callback` has been invoked. In the case of reuse of streams after - * failure, this can cause event listener leaks and swallowed errors. + * failure, this can cause event listener leaks and swallowed errors. If the last + * stream is readable, dangling event listeners will be removed so that the last + * stream can be consumed later. + * + * `stream.pipeline()` closes all the streams when an error is raised. + * The `IncomingRequest` usage with `pipeline` could lead to an unexpected behavior + * once it would destroy the socket without sending the expected response. + * See the example below: + * + * ```js + * const fs = require('node:fs'); + * const http = require('node:http'); + * const { pipeline } = require('node:stream'); + * + * const server = http.createServer((req, res) => { + * const fileStream = fs.createReadStream('./fileNotExist.txt'); + * pipeline(fileStream, res, (err) => { + * if (err) { + * console.log(err); // No such file + * // this message can't be sent once `pipeline` already destroyed the socket + * return res.end('error!!!'); + * } + * }); + * }); + * ``` * @since v10.0.0 * @param callback Called when the pipeline is fully done. */ function pipeline, B extends PipelineDestination>( source: A, destination: B, - callback?: PipelineCallback + callback?: PipelineCallback, ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; - function pipeline, T1 extends PipelineTransform, B extends PipelineDestination>( + function pipeline< + A extends PipelineSource, + T1 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, destination: B, - callback?: PipelineCallback + callback?: PipelineCallback, ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; - function pipeline, T1 extends PipelineTransform, T2 extends PipelineTransform, B extends PipelineDestination>( + function pipeline< + A extends PipelineSource, + T1 extends PipelineTransform, + T2 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, transform2: T2, destination: B, - callback?: PipelineCallback + callback?: PipelineCallback, ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; function pipeline< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, destination: B, callback?: PipelineCallback): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + destination: B, + callback?: PipelineCallback, + ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; function pipeline< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, T4 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, transform4: T4, destination: B, callback?: PipelineCallback): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + transform4: T4, + destination: B, + callback?: PipelineCallback, + ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream; function pipeline( streams: ReadonlyArray, - callback?: (err: NodeJS.ErrnoException | null) => void + callback?: (err: NodeJS.ErrnoException | null) => void, ): NodeJS.WritableStream; function pipeline( stream1: NodeJS.ReadableStream, stream2: NodeJS.ReadWriteStream | NodeJS.WritableStream, - ...streams: Array void)> + ...streams: Array< + NodeJS.ReadWriteStream | NodeJS.WritableStream | ((err: NodeJS.ErrnoException | null) => void) + > ): NodeJS.WritableStream; namespace pipeline { - function __promisify__, B extends PipelineDestination>(source: A, destination: B, options?: PipelineOptions): PipelinePromise; - function __promisify__, T1 extends PipelineTransform, B extends PipelineDestination>( + function __promisify__, B extends PipelineDestination>( + source: A, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; + function __promisify__< + A extends PipelineSource, + T1 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, destination: B, - options?: PipelineOptions + options?: PipelineOptions, ): PipelinePromise; - function __promisify__, T1 extends PipelineTransform, T2 extends PipelineTransform, B extends PipelineDestination>( + function __promisify__< + A extends PipelineSource, + T1 extends PipelineTransform, + T2 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, transform2: T2, destination: B, - options?: PipelineOptions + options?: PipelineOptions, ): PipelinePromise; function __promisify__< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, destination: B, options?: PipelineOptions): PipelinePromise; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; function __promisify__< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, T4 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, transform4: T4, destination: B, options?: PipelineOptions): PipelinePromise; - function __promisify__(streams: ReadonlyArray, options?: PipelineOptions): Promise; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + transform4: T4, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; + function __promisify__( + streams: ReadonlyArray, + options?: PipelineOptions, + ): Promise; function __promisify__( stream1: NodeJS.ReadableStream, stream2: NodeJS.ReadWriteStream | NodeJS.WritableStream, @@ -1238,25 +1678,24 @@ declare module 'stream' { ref(): void; unref(): void; } - /** * Returns whether the stream has encountered an error. - * @since v16.14.0 + * @since v17.3.0, v16.14.0 + * @experimental */ function isErrored(stream: Readable | Writable | NodeJS.ReadableStream | NodeJS.WritableStream): boolean; - /** * Returns whether the stream is readable. - * @since v16.14.0 + * @since v17.4.0, v16.14.0 + * @experimental */ function isReadable(stream: Readable | NodeJS.ReadableStream): boolean; - const promises: typeof streamPromises; const consumers: typeof streamConsumers; } export = internal; } -declare module 'node:stream' { - import stream = require('stream'); +declare module "node:stream" { + import stream = require("stream"); export = stream; } diff --git a/node_modules/@types/node/ts4.8/stream/consumers.d.ts b/node_modules/@types/node/ts4.8/stream/consumers.d.ts old mode 100755 new mode 100644 index ce6c9bb..5ad9cba --- a/node_modules/@types/node/ts4.8/stream/consumers.d.ts +++ b/node_modules/@types/node/ts4.8/stream/consumers.d.ts @@ -1,24 +1,12 @@ -// Duplicates of interface in lib.dom.ts. -// Duplicated here rather than referencing lib.dom.ts because doing so causes lib.dom.ts to be loaded for "test-all" -// Which in turn causes tests to pass that shouldn't pass. -// -// This interface is not, and should not be, exported. -interface Blob { - readonly size: number; - readonly type: string; - arrayBuffer(): Promise; - slice(start?: number, end?: number, contentType?: string): Blob; - stream(): NodeJS.ReadableStream; - text(): Promise; +declare module "stream/consumers" { + import { Blob as NodeBlob } from "node:buffer"; + import { Readable } from "node:stream"; + function buffer(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; + function text(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; + function arrayBuffer(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; + function blob(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; + function json(stream: NodeJS.ReadableStream | Readable | AsyncIterable): Promise; } -declare module 'stream/consumers' { - import { Readable } from 'node:stream'; - function buffer(stream: NodeJS.ReadableStream | Readable | AsyncIterator): Promise; - function text(stream: NodeJS.ReadableStream | Readable | AsyncIterator): Promise; - function arrayBuffer(stream: NodeJS.ReadableStream | Readable | AsyncIterator): Promise; - function blob(stream: NodeJS.ReadableStream | Readable | AsyncIterator): Promise; - function json(stream: NodeJS.ReadableStream | Readable | AsyncIterator): Promise; -} -declare module 'node:stream/consumers' { - export * from 'stream/consumers'; +declare module "node:stream/consumers" { + export * from "stream/consumers"; } diff --git a/node_modules/@types/node/ts4.8/stream/promises.d.ts b/node_modules/@types/node/ts4.8/stream/promises.d.ts old mode 100755 new mode 100644 index b427073..6eac5b7 --- a/node_modules/@types/node/ts4.8/stream/promises.d.ts +++ b/node_modules/@types/node/ts4.8/stream/promises.d.ts @@ -1,42 +1,83 @@ -declare module 'stream/promises' { - import { FinishedOptions, PipelineSource, PipelineTransform, PipelineDestination, PipelinePromise, PipelineOptions } from 'node:stream'; - function finished(stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, options?: FinishedOptions): Promise; - function pipeline, B extends PipelineDestination>(source: A, destination: B, options?: PipelineOptions): PipelinePromise; - function pipeline, T1 extends PipelineTransform, B extends PipelineDestination>( +declare module "stream/promises" { + import { + FinishedOptions, + PipelineDestination, + PipelineOptions, + PipelinePromise, + PipelineSource, + PipelineTransform, + } from "node:stream"; + function finished( + stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream, + options?: FinishedOptions, + ): Promise; + function pipeline, B extends PipelineDestination>( + source: A, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; + function pipeline< + A extends PipelineSource, + T1 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, destination: B, - options?: PipelineOptions + options?: PipelineOptions, ): PipelinePromise; - function pipeline, T1 extends PipelineTransform, T2 extends PipelineTransform, B extends PipelineDestination>( + function pipeline< + A extends PipelineSource, + T1 extends PipelineTransform, + T2 extends PipelineTransform, + B extends PipelineDestination, + >( source: A, transform1: T1, transform2: T2, destination: B, - options?: PipelineOptions + options?: PipelineOptions, ): PipelinePromise; function pipeline< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, destination: B, options?: PipelineOptions): PipelinePromise; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; function pipeline< A extends PipelineSource, T1 extends PipelineTransform, T2 extends PipelineTransform, T3 extends PipelineTransform, T4 extends PipelineTransform, - B extends PipelineDestination - >(source: A, transform1: T1, transform2: T2, transform3: T3, transform4: T4, destination: B, options?: PipelineOptions): PipelinePromise; - function pipeline(streams: ReadonlyArray, options?: PipelineOptions): Promise; + B extends PipelineDestination, + >( + source: A, + transform1: T1, + transform2: T2, + transform3: T3, + transform4: T4, + destination: B, + options?: PipelineOptions, + ): PipelinePromise; + function pipeline( + streams: ReadonlyArray, + options?: PipelineOptions, + ): Promise; function pipeline( stream1: NodeJS.ReadableStream, stream2: NodeJS.ReadWriteStream | NodeJS.WritableStream, ...streams: Array ): Promise; } -declare module 'node:stream/promises' { - export * from 'stream/promises'; +declare module "node:stream/promises" { + export * from "stream/promises"; } diff --git a/node_modules/@types/node/ts4.8/stream/web.d.ts b/node_modules/@types/node/ts4.8/stream/web.d.ts old mode 100755 new mode 100644 index 666eed6..361594d --- a/node_modules/@types/node/ts4.8/stream/web.d.ts +++ b/node_modules/@types/node/ts4.8/stream/web.d.ts @@ -1,7 +1,6 @@ -declare module 'stream/web' { +declare module "stream/web" { // stub module, pending copy&paste from .d.ts or manual impl // copy from lib.dom.d.ts - interface ReadableWritablePair { readable: ReadableStream; /** @@ -15,7 +14,6 @@ declare module 'stream/web' { */ writable: WritableStream; } - interface StreamPipeOptions { preventAbort?: boolean; preventCancel?: boolean; @@ -63,17 +61,14 @@ declare module 'stream/web' { preventClose?: boolean; signal?: AbortSignal; } - interface ReadableStreamGenericReader { readonly closed: Promise; cancel(reason?: any): Promise; } - interface ReadableStreamDefaultReadValueResult { done: false; value: T; } - interface ReadableStreamDefaultReadDoneResult { done: true; value?: undefined; @@ -82,66 +77,61 @@ declare module 'stream/web' { type ReadableStreamDefaultReadResult = | ReadableStreamDefaultReadValueResult | ReadableStreamDefaultReadDoneResult; - + interface ReadableStreamReadValueResult { + done: false; + value: T; + } + interface ReadableStreamReadDoneResult { + done: true; + value?: T; + } + type ReadableStreamReadResult = ReadableStreamReadValueResult | ReadableStreamReadDoneResult; interface ReadableByteStreamControllerCallback { (controller: ReadableByteStreamController): void | PromiseLike; } - interface UnderlyingSinkAbortCallback { (reason?: any): void | PromiseLike; } - interface UnderlyingSinkCloseCallback { (): void | PromiseLike; } - interface UnderlyingSinkStartCallback { (controller: WritableStreamDefaultController): any; } - interface UnderlyingSinkWriteCallback { (chunk: W, controller: WritableStreamDefaultController): void | PromiseLike; } - interface UnderlyingSourceCancelCallback { (reason?: any): void | PromiseLike; } - interface UnderlyingSourcePullCallback { (controller: ReadableStreamController): void | PromiseLike; } - interface UnderlyingSourceStartCallback { (controller: ReadableStreamController): any; } - interface TransformerFlushCallback { (controller: TransformStreamDefaultController): void | PromiseLike; } - interface TransformerStartCallback { (controller: TransformStreamDefaultController): any; } - interface TransformerTransformCallback { (chunk: I, controller: TransformStreamDefaultController): void | PromiseLike; } - interface UnderlyingByteSource { autoAllocateChunkSize?: number; cancel?: ReadableStreamErrorCallback; pull?: ReadableByteStreamControllerCallback; start?: ReadableByteStreamControllerCallback; - type: 'bytes'; + type: "bytes"; } - interface UnderlyingSource { cancel?: UnderlyingSourceCancelCallback; pull?: UnderlyingSourcePullCallback; start?: UnderlyingSourceStartCallback; type?: undefined; } - interface UnderlyingSink { abort?: UnderlyingSinkAbortCallback; close?: UnderlyingSinkCloseCallback; @@ -149,45 +139,40 @@ declare module 'stream/web' { type?: undefined; write?: UnderlyingSinkWriteCallback; } - interface ReadableStreamErrorCallback { (reason: any): void | PromiseLike; } - /** This Streams API interface represents a readable stream of byte data. */ interface ReadableStream { readonly locked: boolean; cancel(reason?: any): Promise; getReader(): ReadableStreamDefaultReader; + getReader(options: { mode: "byob" }): ReadableStreamBYOBReader; pipeThrough(transform: ReadableWritablePair, options?: StreamPipeOptions): ReadableStream; pipeTo(destination: WritableStream, options?: StreamPipeOptions): Promise; tee(): [ReadableStream, ReadableStream]; values(options?: { preventCancel?: boolean }): AsyncIterableIterator; [Symbol.asyncIterator](): AsyncIterableIterator; } - const ReadableStream: { prototype: ReadableStream; - new ( - underlyingSource: UnderlyingByteSource, - strategy?: QueuingStrategy, - ): ReadableStream; - new (underlyingSource?: UnderlyingSource, strategy?: QueuingStrategy): ReadableStream; + new(underlyingSource: UnderlyingByteSource, strategy?: QueuingStrategy): ReadableStream; + new(underlyingSource?: UnderlyingSource, strategy?: QueuingStrategy): ReadableStream; }; - interface ReadableStreamDefaultReader extends ReadableStreamGenericReader { read(): Promise>; releaseLock(): void; } - + interface ReadableStreamBYOBReader extends ReadableStreamGenericReader { + read(view: T): Promise>; + releaseLock(): void; + } const ReadableStreamDefaultReader: { prototype: ReadableStreamDefaultReader; - new (stream: ReadableStream): ReadableStreamDefaultReader; + new(stream: ReadableStream): ReadableStreamDefaultReader; }; - const ReadableStreamBYOBReader: any; const ReadableStreamBYOBRequest: any; - interface ReadableByteStreamController { readonly byobRequest: undefined; readonly desiredSize: number | null; @@ -195,24 +180,20 @@ declare module 'stream/web' { enqueue(chunk: ArrayBufferView): void; error(error?: any): void; } - const ReadableByteStreamController: { prototype: ReadableByteStreamController; - new (): ReadableByteStreamController; + new(): ReadableByteStreamController; }; - interface ReadableStreamDefaultController { readonly desiredSize: number | null; close(): void; enqueue(chunk?: R): void; error(e?: any): void; } - const ReadableStreamDefaultController: { prototype: ReadableStreamDefaultController; - new (): ReadableStreamDefaultController; + new(): ReadableStreamDefaultController; }; - interface Transformer { flush?: TransformerFlushCallback; readableType?: undefined; @@ -220,33 +201,28 @@ declare module 'stream/web' { transform?: TransformerTransformCallback; writableType?: undefined; } - interface TransformStream { readonly readable: ReadableStream; readonly writable: WritableStream; } - const TransformStream: { prototype: TransformStream; - new ( + new( transformer?: Transformer, writableStrategy?: QueuingStrategy, readableStrategy?: QueuingStrategy, ): TransformStream; }; - interface TransformStreamDefaultController { readonly desiredSize: number | null; enqueue(chunk?: O): void; error(reason?: any): void; terminate(): void; } - const TransformStreamDefaultController: { prototype: TransformStreamDefaultController; - new (): TransformStreamDefaultController; + new(): TransformStreamDefaultController; }; - /** * This Streams API interface provides a standard abstraction for writing * streaming data to a destination, known as a sink. This object comes with @@ -258,12 +234,10 @@ declare module 'stream/web' { close(): Promise; getWriter(): WritableStreamDefaultWriter; } - const WritableStream: { prototype: WritableStream; - new (underlyingSink?: UnderlyingSink, strategy?: QueuingStrategy): WritableStream; + new(underlyingSink?: UnderlyingSink, strategy?: QueuingStrategy): WritableStream; }; - /** * This Streams API interface is the object returned by * WritableStream.getWriter() and once created locks the < writer to the @@ -279,12 +253,10 @@ declare module 'stream/web' { releaseLock(): void; write(chunk?: W): Promise; } - const WritableStreamDefaultWriter: { prototype: WritableStreamDefaultWriter; - new (stream: WritableStream): WritableStreamDefaultWriter; + new(stream: WritableStream): WritableStreamDefaultWriter; }; - /** * This Streams API interface represents a controller allowing control of a * WritableStream's state. When constructing a WritableStream, the @@ -294,21 +266,17 @@ declare module 'stream/web' { interface WritableStreamDefaultController { error(e?: any): void; } - const WritableStreamDefaultController: { prototype: WritableStreamDefaultController; - new (): WritableStreamDefaultController; + new(): WritableStreamDefaultController; }; - interface QueuingStrategy { highWaterMark?: number; size?: QueuingStrategySize; } - interface QueuingStrategySize { (chunk?: T): number; } - interface QueuingStrategyInit { /** * Creates a new ByteLengthQueuingStrategy with the provided high water @@ -321,7 +289,6 @@ declare module 'stream/web' { */ highWaterMark: number; } - /** * This Streams API interface provides a built-in byte length queuing * strategy that can be used when constructing streams. @@ -330,12 +297,10 @@ declare module 'stream/web' { readonly highWaterMark: number; readonly size: QueuingStrategySize; } - const ByteLengthQueuingStrategy: { prototype: ByteLengthQueuingStrategy; - new (init: QueuingStrategyInit): ByteLengthQueuingStrategy; + new(init: QueuingStrategyInit): ByteLengthQueuingStrategy; }; - /** * This Streams API interface provides a built-in byte length queuing * strategy that can be used when constructing streams. @@ -344,32 +309,26 @@ declare module 'stream/web' { readonly highWaterMark: number; readonly size: QueuingStrategySize; } - const CountQueuingStrategy: { prototype: CountQueuingStrategy; - new (init: QueuingStrategyInit): CountQueuingStrategy; + new(init: QueuingStrategyInit): CountQueuingStrategy; }; - interface TextEncoderStream { /** Returns "utf-8". */ - readonly encoding: 'utf-8'; + readonly encoding: "utf-8"; readonly readable: ReadableStream; readonly writable: WritableStream; readonly [Symbol.toStringTag]: string; } - const TextEncoderStream: { prototype: TextEncoderStream; - new (): TextEncoderStream; + new(): TextEncoderStream; }; - interface TextDecoderOptions { fatal?: boolean; ignoreBOM?: boolean; } - type BufferSource = ArrayBufferView | ArrayBuffer; - interface TextDecoderStream { /** Returns encoding's name, lower cased. */ readonly encoding: string; @@ -381,12 +340,27 @@ declare module 'stream/web' { readonly writable: WritableStream; readonly [Symbol.toStringTag]: string; } - const TextDecoderStream: { prototype: TextDecoderStream; - new (label?: string, options?: TextDecoderOptions): TextDecoderStream; + new(encoding?: string, options?: TextDecoderOptions): TextDecoderStream; + }; + interface CompressionStream { + readonly readable: ReadableStream; + readonly writable: WritableStream; + } + const CompressionStream: { + prototype: CompressionStream; + new(format: string): CompressionStream; + }; + interface DecompressionStream { + readonly readable: ReadableStream; + readonly writable: WritableStream; + } + const DecompressionStream: { + prototype: DecompressionStream; + new(format: string): DecompressionStream; }; } -declare module 'node:stream/web' { - export * from 'stream/web'; +declare module "node:stream/web" { + export * from "stream/web"; } diff --git a/node_modules/@types/node/ts4.8/string_decoder.d.ts b/node_modules/@types/node/ts4.8/string_decoder.d.ts old mode 100755 new mode 100644 index 584e0c5..b8691e1 --- a/node_modules/@types/node/ts4.8/string_decoder.d.ts +++ b/node_modules/@types/node/ts4.8/string_decoder.d.ts @@ -1,23 +1,23 @@ /** - * The `string_decoder` module provides an API for decoding `Buffer` objects into - * strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16 + * The `node:string_decoder` module provides an API for decoding `Buffer` objects + * into strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16 * characters. It can be accessed using: * * ```js - * const { StringDecoder } = require('string_decoder'); + * const { StringDecoder } = require('node:string_decoder'); * ``` * * The following example shows the basic use of the `StringDecoder` class. * * ```js - * const { StringDecoder } = require('string_decoder'); + * const { StringDecoder } = require('node:string_decoder'); * const decoder = new StringDecoder('utf8'); * * const cent = Buffer.from([0xC2, 0xA2]); - * console.log(decoder.write(cent)); + * console.log(decoder.write(cent)); // Prints: ¢ * * const euro = Buffer.from([0xE2, 0x82, 0xAC]); - * console.log(decoder.write(euro)); + * console.log(decoder.write(euro)); // Prints: € * ``` * * When a `Buffer` instance is written to the `StringDecoder` instance, an @@ -29,16 +29,16 @@ * symbol (`€`) are written over three separate operations: * * ```js - * const { StringDecoder } = require('string_decoder'); + * const { StringDecoder } = require('node:string_decoder'); * const decoder = new StringDecoder('utf8'); * * decoder.write(Buffer.from([0xE2])); * decoder.write(Buffer.from([0x82])); - * console.log(decoder.end(Buffer.from([0xAC]))); + * console.log(decoder.end(Buffer.from([0xAC]))); // Prints: € * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/string_decoder.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/string_decoder.js) */ -declare module 'string_decoder' { +declare module "string_decoder" { class StringDecoder { constructor(encoding?: BufferEncoding); /** @@ -46,7 +46,7 @@ declare module 'string_decoder' { * the end of the `Buffer`, or `TypedArray`, or `DataView` are omitted from the * returned string and stored in an internal buffer for the next call to`stringDecoder.write()` or `stringDecoder.end()`. * @since v0.1.99 - * @param buffer A `Buffer`, or `TypedArray`, or `DataView` containing the bytes to decode. + * @param buffer The bytes to decode. */ write(buffer: Buffer): string; /** @@ -57,11 +57,11 @@ declare module 'string_decoder' { * If the `buffer` argument is provided, one final call to `stringDecoder.write()`is performed before returning the remaining input. * After `end()` is called, the `stringDecoder` object can be reused for new input. * @since v0.9.3 - * @param buffer A `Buffer`, or `TypedArray`, or `DataView` containing the bytes to decode. + * @param buffer The bytes to decode. */ end(buffer?: Buffer): string; } } -declare module 'node:string_decoder' { - export * from 'string_decoder'; +declare module "node:string_decoder" { + export * from "string_decoder"; } diff --git a/node_modules/@types/node/ts4.8/test.d.ts b/node_modules/@types/node/ts4.8/test.d.ts old mode 100755 new mode 100644 index 1b870b9..149c9e0 --- a/node_modules/@types/node/ts4.8/test.d.ts +++ b/node_modules/@types/node/ts4.8/test.d.ts @@ -1,20 +1,120 @@ /** - * The `node:test` module provides a standalone testing module. - * @see [source](https://github.com/nodejs/node/blob/v16.17.0/lib/test.js) + * The `node:test` module facilitates the creation of JavaScript tests. + * To access it: + * + * ```js + * import test from 'node:test'; + * ``` + * + * This module is only available under the `node:` scheme. The following will not + * work: + * + * ```js + * import test from 'test'; + * ``` + * + * Tests created via the `test` module consist of a single function that is + * processed in one of three ways: + * + * 1. A synchronous function that is considered failing if it throws an exception, + * and is considered passing otherwise. + * 2. A function that returns a `Promise` that is considered failing if the`Promise` rejects, and is considered passing if the `Promise` fulfills. + * 3. A function that receives a callback function. If the callback receives any + * truthy value as its first argument, the test is considered failing. If a + * falsy value is passed as the first argument to the callback, the test is + * considered passing. If the test function receives a callback function and + * also returns a `Promise`, the test will fail. + * + * The following example illustrates how tests are written using the`test` module. + * + * ```js + * test('synchronous passing test', (t) => { + * // This test passes because it does not throw an exception. + * assert.strictEqual(1, 1); + * }); + * + * test('synchronous failing test', (t) => { + * // This test fails because it throws an exception. + * assert.strictEqual(1, 2); + * }); + * + * test('asynchronous passing test', async (t) => { + * // This test passes because the Promise returned by the async + * // function is settled and not rejected. + * assert.strictEqual(1, 1); + * }); + * + * test('asynchronous failing test', async (t) => { + * // This test fails because the Promise returned by the async + * // function is rejected. + * assert.strictEqual(1, 2); + * }); + * + * test('failing test using Promises', (t) => { + * // Promises can be used directly as well. + * return new Promise((resolve, reject) => { + * setImmediate(() => { + * reject(new Error('this will cause the test to fail')); + * }); + * }); + * }); + * + * test('callback passing test', (t, done) => { + * // done() is the callback function. When the setImmediate() runs, it invokes + * // done() with no arguments. + * setImmediate(done); + * }); + * + * test('callback failing test', (t, done) => { + * // When the setImmediate() runs, done() is invoked with an Error object and + * // the test fails. + * setImmediate(() => { + * done(new Error('callback failure')); + * }); + * }); + * ``` + * + * If any tests fail, the process exit code is set to `1`. + * @since v18.0.0, v16.17.0 + * @see [source](https://github.com/nodejs/node/blob/v20.4.0/lib/test.js) */ -declare module 'node:test' { +declare module "node:test" { + import { Readable } from "node:stream"; + import { AsyncResource } from "node:async_hooks"; /** - * The `test()` function is the value imported from the test module. Each invocation of this - * function results in the creation of a test point in the TAP output. + * **Note:**`shard` is used to horizontally parallelize test running across + * machines or processes, ideal for large-scale executions across varied + * environments. It's incompatible with `watch` mode, tailored for rapid + * code iteration by automatically rerunning tests on file changes. * - * The {@link TestContext} object passed to the fn argument can be used to perform actions - * related to the current test. Examples include skipping the test, adding additional TAP - * diagnostic information, or creating subtests. + * ```js + * import { tap } from 'node:test/reporters'; + * import { run } from 'node:test'; + * import process from 'node:process'; + * import path from 'node:path'; * - * `test()` returns a {@link Promise} that resolves once the test completes. The return value - * can usually be discarded for top level tests. However, the return value from subtests should - * be used to prevent the parent test from finishing first and cancelling the subtest as shown - * in the following example. + * run({ files: [path.resolve('./tests/test.js')] }) + * .compose(tap) + * .pipe(process.stdout); + * ``` + * @since v18.9.0, v16.19.0 + * @param options Configuration options for running tests. The following properties are supported: + */ + function run(options?: RunOptions): TestsStream; + /** + * The `test()` function is the value imported from the `test` module. Each + * invocation of this function results in reporting the test to the `TestsStream`. + * + * The `TestContext` object passed to the `fn` argument can be used to perform + * actions related to the current test. Examples include skipping the test, adding + * additional diagnostic information, or creating subtests. + * + * `test()` returns a `Promise` that fulfills once the test completes. + * if `test()` is called within a `describe()` block, it fulfills immediately. + * The return value can usually be discarded for top level tests. + * However, the return value from subtests should be used to prevent the parent + * test from finishing first and cancelling the subtest + * as shown in the following example. * * ```js * test('top level test', async (t) => { @@ -28,109 +128,381 @@ declare module 'node:test' { * }); * }); * ``` - * @since v16.17.0 - * @param name The name of the test, which is displayed when reporting test results. - * Default: The `name` property of fn, or `''` if `fn` does not have a name. - * @param options Configuration options for the test - * @param fn The function under test. The first argument to this function is a - * {@link TestContext} object. If the test uses callbacks, the callback function is - * passed as the second argument. Default: A no-op function. - * @returns A {@link Promise} resolved with `undefined` once the test completes. + * + * The `timeout` option can be used to fail the test if it takes longer than`timeout` milliseconds to complete. However, it is not a reliable mechanism for + * canceling tests because a running test might block the application thread and + * thus prevent the scheduled cancellation. + * @since v18.0.0, v16.17.0 + * @param [name='The name'] The name of the test, which is displayed when reporting test results. + * @param options Configuration options for the test. The following properties are supported: + * @param [fn='A no-op function'] The function under test. The first argument to this function is a {@link TestContext} object. If the test uses callbacks, the callback function is passed as the + * second argument. + * @return Fulfilled with `undefined` once the test completes, or immediately if the test runs within {@link describe}. */ function test(name?: string, fn?: TestFn): Promise; function test(name?: string, options?: TestOptions, fn?: TestFn): Promise; function test(options?: TestOptions, fn?: TestFn): Promise; function test(fn?: TestFn): Promise; - - /* - * @since v16.17.0 - * @param name The name of the suite, which is displayed when reporting suite results. - * Default: The `name` property of fn, or `''` if `fn` does not have a name. - * @param options Configuration options for the suite - * @param fn The function under suite. Default: A no-op function. + namespace test { + export { after, afterEach, before, beforeEach, describe, it, mock, only, run, skip, test, todo }; + } + /** + * The `describe()` function imported from the `node:test` module. Each + * invocation of this function results in the creation of a Subtest. + * After invocation of top level `describe` functions, + * all top level tests and suites will execute. + * @param [name='The name'] The name of the suite, which is displayed when reporting test results. + * @param options Configuration options for the suite. supports the same options as `test([name][, options][, fn])`. + * @param [fn='A no-op function'] The function under suite declaring all subtests and subsuites. The first argument to this function is a {@link SuiteContext} object. + * @return Immediately fulfilled with `undefined`. */ - function describe(name?: string, options?: TestOptions, fn?: SuiteFn): void; - function describe(name?: string, fn?: SuiteFn): void; - function describe(options?: TestOptions, fn?: SuiteFn): void; - function describe(fn?: SuiteFn): void; - - /* - * @since v16.17.0 - * @param name The name of the test, which is displayed when reporting test results. - * Default: The `name` property of fn, or `''` if `fn` does not have a name. - * @param options Configuration options for the test - * @param fn The function under test. If the test uses callbacks, the callback function is - * passed as the second argument. Default: A no-op function. + function describe(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function describe(name?: string, fn?: SuiteFn): Promise; + function describe(options?: TestOptions, fn?: SuiteFn): Promise; + function describe(fn?: SuiteFn): Promise; + namespace describe { + /** + * Shorthand for skipping a suite, same as `describe([name], { skip: true }[, fn])`. + */ + function skip(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function skip(name?: string, fn?: SuiteFn): Promise; + function skip(options?: TestOptions, fn?: SuiteFn): Promise; + function skip(fn?: SuiteFn): Promise; + /** + * Shorthand for marking a suite as `TODO`, same as `describe([name], { todo: true }[, fn])`. + */ + function todo(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function todo(name?: string, fn?: SuiteFn): Promise; + function todo(options?: TestOptions, fn?: SuiteFn): Promise; + function todo(fn?: SuiteFn): Promise; + /** + * Shorthand for marking a suite as `only`, same as `describe([name], { only: true }[, fn])`. + * @since v18.15.0 + */ + function only(name?: string, options?: TestOptions, fn?: SuiteFn): Promise; + function only(name?: string, fn?: SuiteFn): Promise; + function only(options?: TestOptions, fn?: SuiteFn): Promise; + function only(fn?: SuiteFn): Promise; + } + /** + * Shorthand for `test()`. + * + * The `it()` function is imported from the `node:test` module. + * @since v18.6.0, v16.17.0 */ - function it(name?: string, options?: TestOptions, fn?: ItFn): void; - function it(name?: string, fn?: ItFn): void; - function it(options?: TestOptions, fn?: ItFn): void; - function it(fn?: ItFn): void; - + function it(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function it(name?: string, fn?: TestFn): Promise; + function it(options?: TestOptions, fn?: TestFn): Promise; + function it(fn?: TestFn): Promise; + namespace it { + /** + * Shorthand for skipping a test, same as `it([name], { skip: true }[, fn])`. + */ + function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function skip(name?: string, fn?: TestFn): Promise; + function skip(options?: TestOptions, fn?: TestFn): Promise; + function skip(fn?: TestFn): Promise; + /** + * Shorthand for marking a test as `TODO`, same as `it([name], { todo: true }[, fn])`. + */ + function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function todo(name?: string, fn?: TestFn): Promise; + function todo(options?: TestOptions, fn?: TestFn): Promise; + function todo(fn?: TestFn): Promise; + /** + * Shorthand for marking a test as `only`, same as `it([name], { only: true }[, fn])`. + * @since v18.15.0 + */ + function only(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function only(name?: string, fn?: TestFn): Promise; + function only(options?: TestOptions, fn?: TestFn): Promise; + function only(fn?: TestFn): Promise; + } + /** + * Shorthand for skipping a test, same as `test([name], { skip: true }[, fn])`. + * @since v20.2.0 + */ + function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function skip(name?: string, fn?: TestFn): Promise; + function skip(options?: TestOptions, fn?: TestFn): Promise; + function skip(fn?: TestFn): Promise; + /** + * Shorthand for marking a test as `TODO`, same as `test([name], { todo: true }[, fn])`. + * @since v20.2.0 + */ + function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function todo(name?: string, fn?: TestFn): Promise; + function todo(options?: TestOptions, fn?: TestFn): Promise; + function todo(fn?: TestFn): Promise; + /** + * Shorthand for marking a test as `only`, same as `test([name], { only: true }[, fn])`. + * @since v20.2.0 + */ + function only(name?: string, options?: TestOptions, fn?: TestFn): Promise; + function only(name?: string, fn?: TestFn): Promise; + function only(options?: TestOptions, fn?: TestFn): Promise; + function only(fn?: TestFn): Promise; /** * The type of a function under test. The first argument to this function is a * {@link TestContext} object. If the test uses callbacks, the callback function is passed as * the second argument. */ - type TestFn = (t: TestContext, done: (result?: any) => void) => any; - + type TestFn = (t: TestContext, done: (result?: any) => void) => void | Promise; /** * The type of a function under Suite. - * If the test uses callbacks, the callback function is passed as an argument */ - type SuiteFn = (done: (result?: any) => void) => void; - - /** - * The type of a function under test. - * If the test uses callbacks, the callback function is passed as an argument - */ - type ItFn = (done: (result?: any) => void) => any; - - /** - * An instance of `TestContext` is passed to each test function in order to interact with the - * test runner. However, the `TestContext` constructor is not exposed as part of the API. - * @since v16.17.0 - */ - interface TestContext { + type SuiteFn = (s: SuiteContext) => void | Promise; + interface TestShard { /** - * This function is used to write TAP diagnostics to the output. Any diagnostic information is - * included at the end of the test's results. This function does not return a value. - * @param message Message to be displayed as a TAP diagnostic. - * @since v16.17.0 + * A positive integer between 1 and `` that specifies the index of the shard to run. + */ + index: number; + /** + * A positive integer that specifies the total number of shards to split the test files to. + */ + total: number; + } + interface RunOptions { + /** + * If a number is provided, then that many files would run in parallel. + * If truthy, it would run (number of cpu cores - 1) files in parallel. + * If falsy, it would only run one file at a time. + * If unspecified, subtests inherit this value from their parent. + * @default true + */ + concurrency?: number | boolean | undefined; + /** + * An array containing the list of files to run. + * If unspecified, the test runner execution model will be used. + */ + files?: readonly string[] | undefined; + /** + * Allows aborting an in-progress test execution. + * @default undefined + */ + signal?: AbortSignal | undefined; + /** + * A number of milliseconds the test will fail after. + * If unspecified, subtests inherit this value from their parent. + * @default Infinity + */ + timeout?: number | undefined; + /** + * Sets inspector port of test child process. + * If a nullish value is provided, each process gets its own port, + * incremented from the primary's `process.debugPort`. + */ + inspectPort?: number | (() => number) | undefined; + /** + * That can be used to only run tests whose name matches the provided pattern. + * Test name patterns are interpreted as JavaScript regular expressions. + * For each test that is executed, any corresponding test hooks, such as `beforeEach()`, are also run. + */ + testNamePatterns?: string | RegExp | string[] | RegExp[]; + /** + * If truthy, the test context will only run tests that have the `only` option set + */ + only?: boolean; + /** + * A function that accepts the TestsStream instance and can be used to setup listeners before any tests are run. + */ + setup?: (root: Test) => void | Promise; + /** + * Whether to run in watch mode or not. + * @default false + */ + watch?: boolean | undefined; + /** + * Running tests in a specific shard. + * @default undefined + */ + shard?: TestShard | undefined; + } + class Test extends AsyncResource { + concurrency: number; + nesting: number; + only: boolean; + reporter: TestsStream; + runOnlySubtests: boolean; + testNumber: number; + timeout: number | null; + } + /** + * A successful call to `run()` method will return a new `TestsStream` object, streaming a series of events representing the execution of the tests.`TestsStream` will emit events, in the + * order of the tests definition + * @since v18.9.0, v16.19.0 + */ + class TestsStream extends Readable implements NodeJS.ReadableStream { + addListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; + addListener(event: "test:fail", listener: (data: TestFail) => void): this; + addListener(event: "test:pass", listener: (data: TestPass) => void): this; + addListener(event: "test:plan", listener: (data: TestPlan) => void): this; + addListener(event: "test:start", listener: (data: TestStart) => void): this; + addListener(event: "test:stderr", listener: (data: TestStderr) => void): this; + addListener(event: "test:stdout", listener: (data: TestStdout) => void): this; + addListener(event: string, listener: (...args: any[]) => void): this; + emit(event: "test:diagnostic", data: DiagnosticData): boolean; + emit(event: "test:fail", data: TestFail): boolean; + emit(event: "test:pass", data: TestPass): boolean; + emit(event: "test:plan", data: TestPlan): boolean; + emit(event: "test:start", data: TestStart): boolean; + emit(event: "test:stderr", data: TestStderr): boolean; + emit(event: "test:stdout", data: TestStdout): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; + on(event: "test:fail", listener: (data: TestFail) => void): this; + on(event: "test:pass", listener: (data: TestPass) => void): this; + on(event: "test:plan", listener: (data: TestPlan) => void): this; + on(event: "test:start", listener: (data: TestStart) => void): this; + on(event: "test:stderr", listener: (data: TestStderr) => void): this; + on(event: "test:stdout", listener: (data: TestStdout) => void): this; + on(event: string, listener: (...args: any[]) => void): this; + once(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; + once(event: "test:fail", listener: (data: TestFail) => void): this; + once(event: "test:pass", listener: (data: TestPass) => void): this; + once(event: "test:plan", listener: (data: TestPlan) => void): this; + once(event: "test:start", listener: (data: TestStart) => void): this; + once(event: "test:stderr", listener: (data: TestStderr) => void): this; + once(event: "test:stdout", listener: (data: TestStdout) => void): this; + once(event: string, listener: (...args: any[]) => void): this; + prependListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; + prependListener(event: "test:fail", listener: (data: TestFail) => void): this; + prependListener(event: "test:pass", listener: (data: TestPass) => void): this; + prependListener(event: "test:plan", listener: (data: TestPlan) => void): this; + prependListener(event: "test:start", listener: (data: TestStart) => void): this; + prependListener(event: "test:stderr", listener: (data: TestStderr) => void): this; + prependListener(event: "test:stdout", listener: (data: TestStdout) => void): this; + prependListener(event: string, listener: (...args: any[]) => void): this; + prependOnceListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this; + prependOnceListener(event: "test:fail", listener: (data: TestFail) => void): this; + prependOnceListener(event: "test:pass", listener: (data: TestPass) => void): this; + prependOnceListener(event: "test:plan", listener: (data: TestPlan) => void): this; + prependOnceListener(event: "test:start", listener: (data: TestStart) => void): this; + prependOnceListener(event: "test:stderr", listener: (data: TestStderr) => void): this; + prependOnceListener(event: "test:stdout", listener: (data: TestStdout) => void): this; + prependOnceListener(event: string, listener: (...args: any[]) => void): this; + } + /** + * An instance of `TestContext` is passed to each test function in order to + * interact with the test runner. However, the `TestContext` constructor is not + * exposed as part of the API. + * @since v18.0.0, v16.17.0 + */ + class TestContext { + /** + * This function is used to create a hook running before subtest of the current test. + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as + * the second argument. Default: A no-op function. + * @param options Configuration options for the hook. + * @since v20.1.0 + */ + before: typeof before; + /** + * This function is used to create a hook running before each subtest of the current test. + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as + * the second argument. Default: A no-op function. + * @param options Configuration options for the hook. + * @since v18.8.0 + */ + beforeEach: typeof beforeEach; + /** + * This function is used to create a hook that runs after the current test finishes. + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as + * the second argument. Default: A no-op function. + * @param options Configuration options for the hook. + * @since v18.13.0 + */ + after: typeof after; + /** + * This function is used to create a hook running after each subtest of the current test. + * @param fn The hook function. If the hook uses callbacks, the callback function is passed as + * the second argument. Default: A no-op function. + * @param options Configuration options for the hook. + * @since v18.8.0 + */ + afterEach: typeof afterEach; + /** + * This function is used to write diagnostics to the output. Any diagnostic + * information is included at the end of the test's results. This function does + * not return a value. + * + * ```js + * test('top level test', (t) => { + * t.diagnostic('A diagnostic message'); + * }); + * ``` + * @since v18.0.0, v16.17.0 + * @param message Message to be reported. */ diagnostic(message: string): void; - /** - * If `shouldRunOnlyTests` is truthy, the test context will only run tests that have the `only` - * option set. Otherwise, all tests are run. If Node.js was not started with the `--test-only` - * command-line option, this function is a no-op. + * The name of the test. + * @since v18.8.0, v16.18.0 + */ + readonly name: string; + /** + * If `shouldRunOnlyTests` is truthy, the test context will only run tests that + * have the `only` option set. Otherwise, all tests are run. If Node.js was not + * started with the `--test-only` command-line option, this function is a + * no-op. + * + * ```js + * test('top level test', (t) => { + * // The test context can be set to run subtests with the 'only' option. + * t.runOnly(true); + * return Promise.all([ + * t.test('this subtest is now skipped'), + * t.test('this subtest is run', { only: true }), + * ]); + * }); + * ``` + * @since v18.0.0, v16.17.0 * @param shouldRunOnlyTests Whether or not to run `only` tests. - * @since v16.17.0 */ runOnly(shouldRunOnlyTests: boolean): void; - /** - * This function causes the test's output to indicate the test as skipped. If `message` is - * provided, it is included in the TAP output. Calling `skip()` does not terminate execution of - * the test function. This function does not return a value. - * @param message Optional skip message to be displayed in TAP output. - * @since v16.17.0 + * ```js + * test('top level test', async (t) => { + * await fetch('some/uri', { signal: t.signal }); + * }); + * ``` + * @since v18.7.0, v16.17.0 + */ + readonly signal: AbortSignal; + /** + * This function causes the test's output to indicate the test as skipped. If`message` is provided, it is included in the output. Calling `skip()` does + * not terminate execution of the test function. This function does not return a + * value. + * + * ```js + * test('top level test', (t) => { + * // Make sure to return here as well if the test contains additional logic. + * t.skip('this is skipped'); + * }); + * ``` + * @since v18.0.0, v16.17.0 + * @param message Optional skip message. */ skip(message?: string): void; - /** - * This function adds a `TODO` directive to the test's output. If `message` is provided, it is - * included in the TAP output. Calling `todo()` does not terminate execution of the test - * function. This function does not return a value. - * @param message Optional `TODO` message to be displayed in TAP output. - * @since v16.17.0 + * This function adds a `TODO` directive to the test's output. If `message` is + * provided, it is included in the output. Calling `todo()` does not terminate + * execution of the test function. This function does not return a value. + * + * ```js + * test('top level test', (t) => { + * // This test is marked as `TODO` + * t.todo('this is a todo'); + * }); + * ``` + * @since v18.0.0, v16.17.0 + * @param message Optional `TODO` message. */ todo(message?: string): void; - /** * This function is used to create subtests under the current test. This function behaves in * the same fashion as the top level {@link test} function. - * @since v16.17.0 + * @since v18.0.0 * @param name The name of the test, which is displayed when reporting test results. * Default: The `name` property of fn, or `''` if `fn` does not have a name. * @param options Configuration options for the test @@ -140,51 +512,954 @@ declare module 'node:test' { * @returns A {@link Promise} resolved with `undefined` once the test completes. */ test: typeof test; + /** + * Each test provides its own MockTracker instance. + */ + readonly mock: MockTracker; + } + /** + * An instance of `SuiteContext` is passed to each suite function in order to + * interact with the test runner. However, the `SuiteContext` constructor is not + * exposed as part of the API. + * @since v18.7.0, v16.17.0 + */ + class SuiteContext { + /** + * The name of the suite. + * @since v18.8.0, v16.18.0 + */ + readonly name: string; + /** + * Can be used to abort test subtasks when the test has been aborted. + * @since v18.7.0, v16.17.0 + */ + readonly signal: AbortSignal; } - interface TestOptions { /** - * The number of tests that can be run at the same time. If unspecified, subtests inherit this - * value from their parent. - * @default 1 + * If a number is provided, then that many tests would run in parallel. + * If truthy, it would run (number of cpu cores - 1) tests in parallel. + * For subtests, it will be `Infinity` tests in parallel. + * If falsy, it would only run one test at a time. + * If unspecified, subtests inherit this value from their parent. + * @default false */ - concurrency?: number; - + concurrency?: number | boolean | undefined; /** * If truthy, and the test context is configured to run `only` tests, then this test will be * run. Otherwise, the test is skipped. * @default false */ - only?: boolean; - + only?: boolean | undefined; /** * Allows aborting an in-progress test. - * @since v16.17.0 + * @since v18.8.0 */ - signal?: AbortSignal; - + signal?: AbortSignal | undefined; /** * If truthy, the test is skipped. If a string is provided, that string is displayed in the * test results as the reason for skipping the test. * @default false */ - skip?: boolean | string; - + skip?: boolean | string | undefined; /** * A number of milliseconds the test will fail after. If unspecified, subtests inherit this * value from their parent. * @default Infinity - * @since v16.17.0 + * @since v18.7.0 */ - timeout?: number; - + timeout?: number | undefined; /** * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in * the test results as the reason why the test is `TODO`. * @default false */ - todo?: boolean | string; + todo?: boolean | string | undefined; } + /** + * This function is used to create a hook running before running a suite. + * + * ```js + * describe('tests', async () => { + * before(() => console.log('about to run some test')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); + * }); + * ``` + * @since v18.8.0, v16.18.0 + * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. The following properties are supported: + */ + function before(fn?: HookFn, options?: HookOptions): void; + /** + * This function is used to create a hook running after running a suite. + * + * ```js + * describe('tests', async () => { + * after(() => console.log('finished running tests')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); + * }); + * ``` + * @since v18.8.0, v16.18.0 + * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. The following properties are supported: + */ + function after(fn?: HookFn, options?: HookOptions): void; + /** + * This function is used to create a hook running + * before each subtest of the current suite. + * + * ```js + * describe('tests', async () => { + * beforeEach(() => console.log('about to run a test')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); + * }); + * ``` + * @since v18.8.0, v16.18.0 + * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. The following properties are supported: + */ + function beforeEach(fn?: HookFn, options?: HookOptions): void; + /** + * This function is used to create a hook running + * after each subtest of the current test. + * + * ```js + * describe('tests', async () => { + * afterEach(() => console.log('finished running a test')); + * it('is a subtest', () => { + * assert.ok('some relevant assertion here'); + * }); + * }); + * ``` + * @since v18.8.0, v16.18.0 + * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument. + * @param options Configuration options for the hook. The following properties are supported: + */ + function afterEach(fn?: HookFn, options?: HookOptions): void; + /** + * The hook function. If the hook uses callbacks, the callback function is passed as the + * second argument. + */ + type HookFn = (s: SuiteContext, done: (result?: any) => void) => any; + /** + * Configuration options for hooks. + * @since v18.8.0 + */ + interface HookOptions { + /** + * Allows aborting an in-progress hook. + */ + signal?: AbortSignal | undefined; + /** + * A number of milliseconds the hook will fail after. If unspecified, subtests inherit this + * value from their parent. + * @default Infinity + */ + timeout?: number | undefined; + } + interface MockFunctionOptions { + /** + * The number of times that the mock will use the behavior of `implementation`. + * Once the mock function has been called `times` times, + * it will automatically restore the behavior of `original`. + * This value must be an integer greater than zero. + * @default Infinity + */ + times?: number | undefined; + } + interface MockMethodOptions extends MockFunctionOptions { + /** + * If `true`, `object[methodName]` is treated as a getter. + * This option cannot be used with the `setter` option. + */ + getter?: boolean | undefined; + /** + * If `true`, `object[methodName]` is treated as a setter. + * This option cannot be used with the `getter` option. + */ + setter?: boolean | undefined; + } + type Mock = F & { + mock: MockFunctionContext; + }; + type NoOpFunction = (...args: any[]) => undefined; + type FunctionPropertyNames = { + [K in keyof T]: T[K] extends Function ? K : never; + }[keyof T]; + /** + * The `MockTracker` class is used to manage mocking functionality. The test runner + * module provides a top level `mock` export which is a `MockTracker` instance. + * Each test also provides its own `MockTracker` instance via the test context's`mock` property. + * @since v19.1.0, v18.13.0 + */ + class MockTracker { + /** + * This function is used to create a mock function. + * + * The following example creates a mock function that increments a counter by one + * on each invocation. The `times` option is used to modify the mock behavior such + * that the first two invocations add two to the counter instead of one. + * + * ```js + * test('mocks a counting function', (t) => { + * let cnt = 0; + * + * function addOne() { + * cnt++; + * return cnt; + * } + * + * function addTwo() { + * cnt += 2; + * return cnt; + * } + * + * const fn = t.mock.fn(addOne, addTwo, { times: 2 }); + * + * assert.strictEqual(fn(), 2); + * assert.strictEqual(fn(), 4); + * assert.strictEqual(fn(), 5); + * assert.strictEqual(fn(), 6); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param [original='A no-op function'] An optional function to create a mock on. + * @param implementation An optional function used as the mock implementation for `original`. This is useful for creating mocks that exhibit one behavior for a specified number of calls and + * then restore the behavior of `original`. + * @param options Optional configuration options for the mock function. The following properties are supported: + * @return The mocked function. The mocked function contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the + * behavior of the mocked function. + */ + fn(original?: F, options?: MockFunctionOptions): Mock; + fn( + original?: F, + implementation?: Implementation, + options?: MockFunctionOptions, + ): Mock; + /** + * This function is used to create a mock on an existing object method. The + * following example demonstrates how a mock is created on an existing object + * method. + * + * ```js + * test('spies on an object method', (t) => { + * const number = { + * value: 5, + * subtract(a) { + * return this.value - a; + * }, + * }; + * + * t.mock.method(number, 'subtract'); + * assert.strictEqual(number.subtract.mock.calls.length, 0); + * assert.strictEqual(number.subtract(3), 2); + * assert.strictEqual(number.subtract.mock.calls.length, 1); + * + * const call = number.subtract.mock.calls[0]; + * + * assert.deepStrictEqual(call.arguments, [3]); + * assert.strictEqual(call.result, 2); + * assert.strictEqual(call.error, undefined); + * assert.strictEqual(call.target, undefined); + * assert.strictEqual(call.this, number); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param object The object whose method is being mocked. + * @param methodName The identifier of the method on `object` to mock. If `object[methodName]` is not a function, an error is thrown. + * @param implementation An optional function used as the mock implementation for `object[methodName]`. + * @param options Optional configuration options for the mock method. The following properties are supported: + * @return The mocked method. The mocked method contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the + * behavior of the mocked method. + */ + method< + MockedObject extends object, + MethodName extends FunctionPropertyNames, + >( + object: MockedObject, + methodName: MethodName, + options?: MockFunctionOptions, + ): MockedObject[MethodName] extends Function ? Mock + : never; + method< + MockedObject extends object, + MethodName extends FunctionPropertyNames, + Implementation extends Function, + >( + object: MockedObject, + methodName: MethodName, + implementation: Implementation, + options?: MockFunctionOptions, + ): MockedObject[MethodName] extends Function ? Mock + : never; + method( + object: MockedObject, + methodName: keyof MockedObject, + options: MockMethodOptions, + ): Mock; + method( + object: MockedObject, + methodName: keyof MockedObject, + implementation: Function, + options: MockMethodOptions, + ): Mock; - export { test as default, test, describe, it }; + /** + * This function is syntax sugar for `MockTracker.method` with `options.getter`set to `true`. + * @since v19.3.0, v18.13.0 + */ + getter< + MockedObject extends object, + MethodName extends keyof MockedObject, + >( + object: MockedObject, + methodName: MethodName, + options?: MockFunctionOptions, + ): Mock<() => MockedObject[MethodName]>; + getter< + MockedObject extends object, + MethodName extends keyof MockedObject, + Implementation extends Function, + >( + object: MockedObject, + methodName: MethodName, + implementation?: Implementation, + options?: MockFunctionOptions, + ): Mock<(() => MockedObject[MethodName]) | Implementation>; + /** + * This function is syntax sugar for `MockTracker.method` with `options.setter`set to `true`. + * @since v19.3.0, v18.13.0 + */ + setter< + MockedObject extends object, + MethodName extends keyof MockedObject, + >( + object: MockedObject, + methodName: MethodName, + options?: MockFunctionOptions, + ): Mock<(value: MockedObject[MethodName]) => void>; + setter< + MockedObject extends object, + MethodName extends keyof MockedObject, + Implementation extends Function, + >( + object: MockedObject, + methodName: MethodName, + implementation?: Implementation, + options?: MockFunctionOptions, + ): Mock<((value: MockedObject[MethodName]) => void) | Implementation>; + /** + * This function restores the default behavior of all mocks that were previously + * created by this `MockTracker` and disassociates the mocks from the`MockTracker` instance. Once disassociated, the mocks can still be used, but the`MockTracker` instance can no longer be + * used to reset their behavior or + * otherwise interact with them. + * + * After each test completes, this function is called on the test context's`MockTracker`. If the global `MockTracker` is used extensively, calling this + * function manually is recommended. + * @since v19.1.0, v18.13.0 + */ + reset(): void; + /** + * This function restores the default behavior of all mocks that were previously + * created by this `MockTracker`. Unlike `mock.reset()`, `mock.restoreAll()` does + * not disassociate the mocks from the `MockTracker` instance. + * @since v19.1.0, v18.13.0 + */ + restoreAll(): void; + timers: MockTimers; + } + const mock: MockTracker; + interface MockFunctionCall< + F extends Function, + ReturnType = F extends (...args: any) => infer T ? T + : F extends abstract new(...args: any) => infer T ? T + : unknown, + Args = F extends (...args: infer Y) => any ? Y + : F extends abstract new(...args: infer Y) => any ? Y + : unknown[], + > { + /** + * An array of the arguments passed to the mock function. + */ + arguments: Args; + /** + * If the mocked function threw then this property contains the thrown value. + */ + error: unknown | undefined; + /** + * The value returned by the mocked function. + * + * If the mocked function threw, it will be `undefined`. + */ + result: ReturnType | undefined; + /** + * An `Error` object whose stack can be used to determine the callsite of the mocked function invocation. + */ + stack: Error; + /** + * If the mocked function is a constructor, this field contains the class being constructed. + * Otherwise this will be `undefined`. + */ + target: F extends abstract new(...args: any) => any ? F : undefined; + /** + * The mocked function's `this` value. + */ + this: unknown; + } + /** + * The `MockFunctionContext` class is used to inspect or manipulate the behavior of + * mocks created via the `MockTracker` APIs. + * @since v19.1.0, v18.13.0 + */ + class MockFunctionContext { + /** + * A getter that returns a copy of the internal array used to track calls to the + * mock. Each entry in the array is an object with the following properties. + * @since v19.1.0, v18.13.0 + */ + readonly calls: Array>; + /** + * This function returns the number of times that this mock has been invoked. This + * function is more efficient than checking `ctx.calls.length` because `ctx.calls`is a getter that creates a copy of the internal call tracking array. + * @since v19.1.0, v18.13.0 + * @return The number of times that this mock has been invoked. + */ + callCount(): number; + /** + * This function is used to change the behavior of an existing mock. + * + * The following example creates a mock function using `t.mock.fn()`, calls the + * mock function, and then changes the mock implementation to a different function. + * + * ```js + * test('changes a mock behavior', (t) => { + * let cnt = 0; + * + * function addOne() { + * cnt++; + * return cnt; + * } + * + * function addTwo() { + * cnt += 2; + * return cnt; + * } + * + * const fn = t.mock.fn(addOne); + * + * assert.strictEqual(fn(), 1); + * fn.mock.mockImplementation(addTwo); + * assert.strictEqual(fn(), 3); + * assert.strictEqual(fn(), 5); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param implementation The function to be used as the mock's new implementation. + */ + mockImplementation(implementation: Function): void; + /** + * This function is used to change the behavior of an existing mock for a single + * invocation. Once invocation `onCall` has occurred, the mock will revert to + * whatever behavior it would have used had `mockImplementationOnce()` not been + * called. + * + * The following example creates a mock function using `t.mock.fn()`, calls the + * mock function, changes the mock implementation to a different function for the + * next invocation, and then resumes its previous behavior. + * + * ```js + * test('changes a mock behavior once', (t) => { + * let cnt = 0; + * + * function addOne() { + * cnt++; + * return cnt; + * } + * + * function addTwo() { + * cnt += 2; + * return cnt; + * } + * + * const fn = t.mock.fn(addOne); + * + * assert.strictEqual(fn(), 1); + * fn.mock.mockImplementationOnce(addTwo); + * assert.strictEqual(fn(), 3); + * assert.strictEqual(fn(), 4); + * }); + * ``` + * @since v19.1.0, v18.13.0 + * @param implementation The function to be used as the mock's implementation for the invocation number specified by `onCall`. + * @param onCall The invocation number that will use `implementation`. If the specified invocation has already occurred then an exception is thrown. + */ + mockImplementationOnce(implementation: Function, onCall?: number): void; + /** + * Resets the call history of the mock function. + * @since v19.3.0, v18.13.0 + */ + resetCalls(): void; + /** + * Resets the implementation of the mock function to its original behavior. The + * mock can still be used after calling this function. + * @since v19.1.0, v18.13.0 + */ + restore(): void; + } + type Timer = "setInterval" | "setTimeout" | "setImmediate" | "Date"; + + interface MockTimersOptions { + apis: Timer[]; + now?: number | Date; + } + /** + * Mocking timers is a technique commonly used in software testing to simulate and + * control the behavior of timers, such as `setInterval` and `setTimeout`, + * without actually waiting for the specified time intervals. + * + * The MockTimers API also allows for mocking of the `Date` constructor and + * `setImmediate`/`clearImmediate` functions. + * + * The `MockTracker` provides a top-level `timers` export + * which is a `MockTimers` instance. + * @since v20.4.0 + * @experimental + */ + class MockTimers { + /** + * Enables timer mocking for the specified timers. + * + * **Note:** When you enable mocking for a specific timer, its associated + * clear function will also be implicitly mocked. + * + * **Note:** Mocking `Date` will affect the behavior of the mocked timers + * as they use the same internal clock. + * + * Example usage without setting initial time: + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.enable({ apis: ['setInterval', 'Date'], now: 1234 }); + * ``` + * + * The above example enables mocking for the `Date` constructor, `setInterval` timer and + * implicitly mocks the `clearInterval` function. Only the `Date` constructor from `globalThis`, + * `setInterval` and `clearInterval` functions from `node:timers`,`node:timers/promises`, and `globalThis` will be mocked. + * + * Example usage with initial time set + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.enable({ apis: ['Date'], now: 1000 }); + * ``` + * + * Example usage with initial Date object as time set + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.enable({ apis: ['Date'], now: new Date() }); + * ``` + * + * Alternatively, if you call `mock.timers.enable()` without any parameters: + * + * All timers (`'setInterval'`, `'clearInterval'`, `'Date'`, `'setImmediate'`, `'clearImmediate'`, `'setTimeout'`, and `'clearTimeout'`) + * will be mocked. + * + * The `setInterval`, `clearInterval`, `setTimeout`, and `clearTimeout` functions from `node:timers`, `node:timers/promises`, + * and `globalThis` will be mocked. + * The `Date` constructor from `globalThis` will be mocked. + * + * If there is no initial epoch set, the initial date will be based on 0 in the Unix epoch. This is `January 1st, 1970, 00:00:00 UTC`. You can set an initial date by passing a now property to the `.enable()` method. This value will be used as the initial date for the mocked Date object. It can either be a positive integer, or another Date object. + * @since v20.4.0 + */ + enable(options?: MockTimersOptions): void; + /** + * You can use the `.setTime()` method to manually move the mocked date to another time. This method only accepts a positive integer. + * Note: This method will execute any mocked timers that are in the past from the new time. + * In the below example we are setting a new time for the mocked date. + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * test('sets the time of a date object', (context) => { + * // Optionally choose what to mock + * context.mock.timers.enable({ apis: ['Date'], now: 100 }); + * assert.strictEqual(Date.now(), 100); + * // Advance in time will also advance the date + * context.mock.timers.setTime(1000); + * context.mock.timers.tick(200); + * assert.strictEqual(Date.now(), 1200); + * }); + * ``` + */ + setTime(time: number): void; + /** + * This function restores the default behavior of all mocks that were previously + * created by this `MockTimers` instance and disassociates the mocks + * from the `MockTracker` instance. + * + * **Note:** After each test completes, this function is called on + * the test context's `MockTracker`. + * + * ```js + * import { mock } from 'node:test'; + * mock.timers.reset(); + * ``` + * @since v20.4.0 + */ + reset(): void; + /** + * Advances time for all mocked timers. + * + * **Note:** This diverges from how `setTimeout` in Node.js behaves and accepts + * only positive numbers. In Node.js, `setTimeout` with negative numbers is + * only supported for web compatibility reasons. + * + * The following example mocks a `setTimeout` function and + * by using `.tick` advances in + * time triggering all pending timers. + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { + * const fn = context.mock.fn(); + * + * context.mock.timers.enable({ apis: ['setTimeout'] }); + * + * setTimeout(fn, 9999); + * + * assert.strictEqual(fn.mock.callCount(), 0); + * + * // Advance in time + * context.mock.timers.tick(9999); + * + * assert.strictEqual(fn.mock.callCount(), 1); + * }); + * ``` + * + * Alternativelly, the `.tick` function can be called many times + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { + * const fn = context.mock.fn(); + * context.mock.timers.enable({ apis: ['setTimeout'] }); + * const nineSecs = 9000; + * setTimeout(fn, nineSecs); + * + * const twoSeconds = 3000; + * context.mock.timers.tick(twoSeconds); + * context.mock.timers.tick(twoSeconds); + * context.mock.timers.tick(twoSeconds); + * + * assert.strictEqual(fn.mock.callCount(), 1); + * }); + * ``` + * + * Advancing time using `.tick` will also advance the time for any `Date` object + * created after the mock was enabled (if `Date` was also set to be mocked). + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => { + * const fn = context.mock.fn(); + * + * context.mock.timers.enable({ apis: ['setTimeout', 'Date'] }); + * setTimeout(fn, 9999); + * + * assert.strictEqual(fn.mock.callCount(), 0); + * assert.strictEqual(Date.now(), 0); + * + * // Advance in time + * context.mock.timers.tick(9999); + * assert.strictEqual(fn.mock.callCount(), 1); + * assert.strictEqual(Date.now(), 9999); + * }); + * ``` + * @since v20.4.0 + */ + tick(milliseconds: number): void; + /** + * Triggers all pending mocked timers immediately. If the `Date` object is also + * mocked, it will also advance the `Date` object to the furthest timer's time. + * + * The example below triggers all pending timers immediately, + * causing them to execute without any delay. + * + * ```js + * import assert from 'node:assert'; + * import { test } from 'node:test'; + * + * test('runAll functions following the given order', (context) => { + * context.mock.timers.enable({ apis: ['setTimeout', 'Date'] }); + * const results = []; + * setTimeout(() => results.push(1), 9999); + * + * // Notice that if both timers have the same timeout, + * // the order of execution is guaranteed + * setTimeout(() => results.push(3), 8888); + * setTimeout(() => results.push(2), 8888); + * + * assert.deepStrictEqual(results, []); + * + * context.mock.timers.runAll(); + * assert.deepStrictEqual(results, [3, 2, 1]); + * // The Date object is also advanced to the furthest timer's time + * assert.strictEqual(Date.now(), 9999); + * }); + * ``` + * + * **Note:** The `runAll()` function is specifically designed for + * triggering timers in the context of timer mocking. + * It does not have any effect on real-time system + * clocks or actual timers outside of the mocking environment. + * @since v20.4.0 + */ + runAll(): void; + /** + * Calls {@link MockTimers.reset()}. + */ + [Symbol.dispose](): void; + } + export { + after, + afterEach, + before, + beforeEach, + describe, + it, + Mock, + mock, + only, + run, + skip, + test, + test as default, + todo, + }; +} + +interface TestLocationInfo { + /** + * The column number where the test is defined, or + * `undefined` if the test was run through the REPL. + */ + column?: number; + /** + * The path of the test file, `undefined` if test is not ran through a file. + */ + file?: string; + /** + * The line number where the test is defined, or + * `undefined` if the test was run through the REPL. + */ + line?: number; +} +interface DiagnosticData extends TestLocationInfo { + /** + * The diagnostic message. + */ + message: string; + /** + * The nesting level of the test. + */ + nesting: number; +} +interface TestFail extends TestLocationInfo { + /** + * Additional execution metadata. + */ + details: { + /** + * The duration of the test in milliseconds. + */ + duration_ms: number; + /** + * The error thrown by the test. + */ + error: Error; + /** + * The type of the test, used to denote whether this is a suite. + * @since 20.0.0, 19.9.0, 18.17.0 + */ + type?: "suite"; + }; + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The ordinal number of the test. + */ + testNumber: number; + /** + * Present if `context.todo` is called. + */ + todo?: string | boolean; + /** + * Present if `context.skip` is called. + */ + skip?: string | boolean; +} +interface TestPass extends TestLocationInfo { + /** + * Additional execution metadata. + */ + details: { + /** + * The duration of the test in milliseconds. + */ + duration_ms: number; + /** + * The type of the test, used to denote whether this is a suite. + * @since 20.0.0, 19.9.0, 18.17.0 + */ + type?: "suite"; + }; + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The ordinal number of the test. + */ + testNumber: number; + /** + * Present if `context.todo` is called. + */ + todo?: string | boolean; + /** + * Present if `context.skip` is called. + */ + skip?: string | boolean; +} +interface TestPlan extends TestLocationInfo { + /** + * The nesting level of the test. + */ + nesting: number; + /** + * The number of subtests that have ran. + */ + count: number; +} +interface TestStart extends TestLocationInfo { + /** + * The test name. + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; +} +interface TestStderr extends TestLocationInfo { + /** + * The message written to `stderr` + */ + message: string; +} +interface TestStdout extends TestLocationInfo { + /** + * The message written to `stdout` + */ + message: string; +} +interface TestEnqueue extends TestLocationInfo { + /** + * The test name + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; +} +interface TestDequeue extends TestLocationInfo { + /** + * The test name + */ + name: string; + /** + * The nesting level of the test. + */ + nesting: number; +} + +/** + * The `node:test/reporters` module exposes the builtin-reporters for `node:test`. + * To access it: + * + * ```js + * import test from 'node:test/reporters'; + * ``` + * + * This module is only available under the `node:` scheme. The following will not + * work: + * + * ```js + * import test from 'test/reporters'; + * ``` + * @since v19.9.0 + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/test/reporters.js) + */ +declare module "node:test/reporters" { + import { Transform, TransformOptions } from "node:stream"; + + type TestEvent = + | { type: "test:diagnostic"; data: DiagnosticData } + | { type: "test:fail"; data: TestFail } + | { type: "test:pass"; data: TestPass } + | { type: "test:plan"; data: TestPlan } + | { type: "test:start"; data: TestStart } + | { type: "test:stderr"; data: TestStderr } + | { type: "test:stdout"; data: TestStdout } + | { type: "test:enqueue"; data: TestEnqueue } + | { type: "test:dequeue"; data: TestDequeue } + | { type: "test:watch:drained" }; + type TestEventGenerator = AsyncGenerator; + + /** + * The `dot` reporter outputs the test results in a compact format, + * where each passing test is represented by a `.`, + * and each failing test is represented by a `X`. + */ + function dot(source: TestEventGenerator): AsyncGenerator<"\n" | "." | "X", void>; + /** + * The `tap` reporter outputs the test results in the [TAP](https://testanything.org/) format. + */ + function tap(source: TestEventGenerator): AsyncGenerator; + /** + * The `spec` reporter outputs the test results in a human-readable format. + */ + class Spec extends Transform { + constructor(); + } + /** + * The `junit` reporter outputs test results in a jUnit XML format + */ + function junit(source: TestEventGenerator): AsyncGenerator; + class Lcov extends Transform { + constructor(opts?: TransformOptions); + } + export { dot, junit, Lcov as lcov, Spec as spec, tap, TestEvent }; } diff --git a/node_modules/@types/node/ts4.8/timers.d.ts b/node_modules/@types/node/ts4.8/timers.d.ts old mode 100755 new mode 100644 index 4d14758..039f31f --- a/node_modules/@types/node/ts4.8/timers.d.ts +++ b/node_modules/@types/node/ts4.8/timers.d.ts @@ -1,16 +1,20 @@ /** * The `timer` module exposes a global API for scheduling functions to * be called at some future period of time. Because the timer functions are - * globals, there is no need to call `require('timers')` to use the API. + * globals, there is no need to call `require('node:timers')` to use the API. * * The timer functions within Node.js implement a similar API as the timers API * provided by Web Browsers but use a different internal implementation that is * built around the Node.js [Event Loop](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/#setimmediate-vs-settimeout). - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/timers.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/timers.js) */ -declare module 'timers' { - import { Abortable } from 'node:events'; - import { setTimeout as setTimeoutPromise, setImmediate as setImmediatePromise, setInterval as setIntervalPromise } from 'node:timers/promises'; +declare module "timers" { + import { Abortable } from "node:events"; + import { + setImmediate as setImmediatePromise, + setInterval as setIntervalPromise, + setTimeout as setTimeoutPromise, + } from "node:timers/promises"; interface TimerOptions extends Abortable { /** * Set to `false` to indicate that the scheduled `Timeout` @@ -33,15 +37,74 @@ declare module 'timers' { refresh(): this; [Symbol.toPrimitive](): number; } - interface Immediate extends RefCounted { + /** + * This object is created internally and is returned from `setImmediate()`. It + * can be passed to `clearImmediate()` in order to cancel the scheduled + * actions. + * + * By default, when an immediate is scheduled, the Node.js event loop will continue + * running as long as the immediate is active. The `Immediate` object returned by `setImmediate()` exports both `immediate.ref()` and `immediate.unref()`functions that can be used to + * control this default behavior. + */ + class Immediate implements RefCounted { + /** + * When called, requests that the Node.js event loop _not_ exit so long as the`Immediate` is active. Calling `immediate.ref()` multiple times will have no + * effect. + * + * By default, all `Immediate` objects are "ref'ed", making it normally unnecessary + * to call `immediate.ref()` unless `immediate.unref()` had been called previously. + * @since v9.7.0 + * @return a reference to `immediate` + */ + ref(): this; + /** + * When called, the active `Immediate` object will not require the Node.js event + * loop to remain active. If there is no other activity keeping the event loop + * running, the process may exit before the `Immediate` object's callback is + * invoked. Calling `immediate.unref()` multiple times will have no effect. + * @since v9.7.0 + * @return a reference to `immediate` + */ + unref(): this; /** * If true, the `Immediate` object will keep the Node.js event loop active. * @since v11.0.0 */ hasRef(): boolean; _onImmediate: Function; // to distinguish it from the Timeout class + /** + * Cancels the immediate. This is similar to calling `clearImmediate()`. + * @since v20.5.0 + */ + [Symbol.dispose](): void; } - interface Timeout extends Timer { + /** + * This object is created internally and is returned from `setTimeout()` and `setInterval()`. It can be passed to either `clearTimeout()` or `clearInterval()` in order to cancel the + * scheduled actions. + * + * By default, when a timer is scheduled using either `setTimeout()` or `setInterval()`, the Node.js event loop will continue running as long as the + * timer is active. Each of the `Timeout` objects returned by these functions + * export both `timeout.ref()` and `timeout.unref()` functions that can be used to + * control this default behavior. + */ + class Timeout implements Timer { + /** + * When called, requests that the Node.js event loop _not_ exit so long as the`Timeout` is active. Calling `timeout.ref()` multiple times will have no effect. + * + * By default, all `Timeout` objects are "ref'ed", making it normally unnecessary + * to call `timeout.ref()` unless `timeout.unref()` had been called previously. + * @since v0.9.1 + * @return a reference to `timeout` + */ + ref(): this; + /** + * When called, the active `Timeout` object will not require the Node.js event loop + * to remain active. If there is no other activity keeping the event loop running, + * the process may exit before the `Timeout` object's callback is invoked. Calling`timeout.unref()` multiple times will have no effect. + * @since v0.9.1 + * @return a reference to `timeout` + */ + unref(): this; /** * If true, the `Timeout` object will keep the Node.js event loop active. * @since v11.0.0 @@ -60,35 +123,118 @@ declare module 'timers' { */ refresh(): this; [Symbol.toPrimitive](): number; + /** + * Cancels the timeout. + * @since v20.5.0 + */ + [Symbol.dispose](): void; } } - function setTimeout(callback: (...args: TArgs) => void, ms?: number, ...args: TArgs): NodeJS.Timeout; + /** + * Schedules execution of a one-time `callback` after `delay` milliseconds. + * + * The `callback` will likely not be invoked in precisely `delay` milliseconds. + * Node.js makes no guarantees about the exact timing of when callbacks will fire, + * nor of their ordering. The callback will be called as close as possible to the + * time specified. + * + * When `delay` is larger than `2147483647` or less than `1`, the `delay`will be set to `1`. Non-integer delays are truncated to an integer. + * + * If `callback` is not a function, a `TypeError` will be thrown. + * + * This method has a custom variant for promises that is available using `timersPromises.setTimeout()`. + * @since v0.0.1 + * @param callback The function to call when the timer elapses. + * @param [delay=1] The number of milliseconds to wait before calling the `callback`. + * @param args Optional arguments to pass when the `callback` is called. + * @return for use with {@link clearTimeout} + */ + function setTimeout( + callback: (...args: TArgs) => void, + ms?: number, + ...args: TArgs + ): NodeJS.Timeout; // util.promisify no rest args compability - // tslint:disable-next-line void-return + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type function setTimeout(callback: (args: void) => void, ms?: number): NodeJS.Timeout; namespace setTimeout { const __promisify__: typeof setTimeoutPromise; } + /** + * Cancels a `Timeout` object created by `setTimeout()`. + * @since v0.0.1 + * @param timeout A `Timeout` object as returned by {@link setTimeout} or the `primitive` of the `Timeout` object as a string or a number. + */ function clearTimeout(timeoutId: NodeJS.Timeout | string | number | undefined): void; - function setInterval(callback: (...args: TArgs) => void, ms?: number, ...args: TArgs): NodeJS.Timer; + /** + * Schedules repeated execution of `callback` every `delay` milliseconds. + * + * When `delay` is larger than `2147483647` or less than `1`, the `delay` will be + * set to `1`. Non-integer delays are truncated to an integer. + * + * If `callback` is not a function, a `TypeError` will be thrown. + * + * This method has a custom variant for promises that is available using `timersPromises.setInterval()`. + * @since v0.0.1 + * @param callback The function to call when the timer elapses. + * @param [delay=1] The number of milliseconds to wait before calling the `callback`. + * @param args Optional arguments to pass when the `callback` is called. + * @return for use with {@link clearInterval} + */ + function setInterval( + callback: (...args: TArgs) => void, + ms?: number, + ...args: TArgs + ): NodeJS.Timeout; // util.promisify no rest args compability - // tslint:disable-next-line void-return - function setInterval(callback: (args: void) => void, ms?: number): NodeJS.Timer; + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type + function setInterval(callback: (args: void) => void, ms?: number): NodeJS.Timeout; namespace setInterval { const __promisify__: typeof setIntervalPromise; } + /** + * Cancels a `Timeout` object created by `setInterval()`. + * @since v0.0.1 + * @param timeout A `Timeout` object as returned by {@link setInterval} or the `primitive` of the `Timeout` object as a string or a number. + */ function clearInterval(intervalId: NodeJS.Timeout | string | number | undefined): void; - function setImmediate(callback: (...args: TArgs) => void, ...args: TArgs): NodeJS.Immediate; + /** + * Schedules the "immediate" execution of the `callback` after I/O events' + * callbacks. + * + * When multiple calls to `setImmediate()` are made, the `callback` functions are + * queued for execution in the order in which they are created. The entire callback + * queue is processed every event loop iteration. If an immediate timer is queued + * from inside an executing callback, that timer will not be triggered until the + * next event loop iteration. + * + * If `callback` is not a function, a `TypeError` will be thrown. + * + * This method has a custom variant for promises that is available using `timersPromises.setImmediate()`. + * @since v0.9.1 + * @param callback The function to call at the end of this turn of the Node.js `Event Loop` + * @param args Optional arguments to pass when the `callback` is called. + * @return for use with {@link clearImmediate} + */ + function setImmediate( + callback: (...args: TArgs) => void, + ...args: TArgs + ): NodeJS.Immediate; // util.promisify no rest args compability - // tslint:disable-next-line void-return + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type function setImmediate(callback: (args: void) => void): NodeJS.Immediate; namespace setImmediate { const __promisify__: typeof setImmediatePromise; } + /** + * Cancels an `Immediate` object created by `setImmediate()`. + * @since v0.9.1 + * @param immediate An `Immediate` object as returned by {@link setImmediate}. + */ function clearImmediate(immediateId: NodeJS.Immediate | undefined): void; function queueMicrotask(callback: () => void): void; } } -declare module 'node:timers' { - export * from 'timers'; +declare module "node:timers" { + export * from "timers"; } diff --git a/node_modules/@types/node/ts4.8/timers/promises.d.ts b/node_modules/@types/node/ts4.8/timers/promises.d.ts old mode 100755 new mode 100644 index fd77888..5a54dc7 --- a/node_modules/@types/node/ts4.8/timers/promises.d.ts +++ b/node_modules/@types/node/ts4.8/timers/promises.d.ts @@ -1,6 +1,6 @@ /** * The `timers/promises` API provides an alternative set of timer functions - * that return `Promise` objects. The API is accessible via`require('timers/promises')`. + * that return `Promise` objects. The API is accessible via`require('node:timers/promises')`. * * ```js * import { @@ -11,8 +11,8 @@ * ``` * @since v15.0.0 */ -declare module 'timers/promises' { - import { TimerOptions } from 'node:timers'; +declare module "timers/promises" { + import { TimerOptions } from "node:timers"; /** * ```js * import { @@ -44,6 +44,8 @@ declare module 'timers/promises' { function setImmediate(value?: T, options?: TimerOptions): Promise; /** * Returns an async iterator that generates values in an interval of `delay` ms. + * If `ref` is `true`, you need to call `next()` of async iterator explicitly + * or implicitly to keep the event loop alive. * * ```js * import { @@ -62,7 +64,30 @@ declare module 'timers/promises' { * @since v15.9.0 */ function setInterval(delay?: number, value?: T, options?: TimerOptions): AsyncIterable; + interface Scheduler { + /** + * ```js + * import { scheduler } from 'node:timers/promises'; + * + * await scheduler.wait(1000); // Wait one second before continuing + * ``` + * An experimental API defined by the Scheduling APIs draft specification being developed as a standard Web Platform API. + * Calling timersPromises.scheduler.wait(delay, options) is roughly equivalent to calling timersPromises.setTimeout(delay, undefined, options) except that the ref option is not supported. + * @since v16.14.0 + * @experimental + * @param [delay=1] The number of milliseconds to wait before fulfilling the promise. + */ + wait: (delay?: number, options?: TimerOptions) => Promise; + /** + * An experimental API defined by the Scheduling APIs draft specification being developed as a standard Web Platform API. + * Calling timersPromises.scheduler.yield() is equivalent to calling timersPromises.setImmediate() with no arguments. + * @since v16.14.0 + * @experimental + */ + yield: () => Promise; + } + const scheduler: Scheduler; } -declare module 'node:timers/promises' { - export * from 'timers/promises'; +declare module "node:timers/promises" { + export * from "timers/promises"; } diff --git a/node_modules/@types/node/ts4.8/tls.d.ts b/node_modules/@types/node/ts4.8/tls.d.ts old mode 100755 new mode 100644 index b013b26..b289e84 --- a/node_modules/@types/node/ts4.8/tls.d.ts +++ b/node_modules/@types/node/ts4.8/tls.d.ts @@ -1,16 +1,17 @@ /** - * The `tls` module provides an implementation of the Transport Layer Security + * The `node:tls` module provides an implementation of the Transport Layer Security * (TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL. * The module can be accessed using: * * ```js - * const tls = require('tls'); + * const tls = require('node:tls'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/tls.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/tls.js) */ -declare module 'tls' { - import { X509Certificate } from 'node:crypto'; - import * as net from 'node:net'; +declare module "tls" { + import { X509Certificate } from "node:crypto"; + import * as net from "node:net"; + import * as stream from "stream"; const CLIENT_RENEG_LIMIT: number; const CLIENT_RENEG_WINDOW: number; interface Certificate { @@ -40,21 +41,100 @@ declare module 'tls' { CN: string; } interface PeerCertificate { - subject: Certificate; - issuer: Certificate; - subjectaltname: string; - infoAccess: NodeJS.Dict; - modulus: string; - exponent: string; - valid_from: string; - valid_to: string; - fingerprint: string; - fingerprint256: string; - ext_key_usage: string[]; - serialNumber: string; + /** + * `true` if a Certificate Authority (CA), `false` otherwise. + * @since v18.13.0 + */ + ca: boolean; + /** + * The DER encoded X.509 certificate data. + */ raw: Buffer; + /** + * The certificate subject. + */ + subject: Certificate; + /** + * The certificate issuer, described in the same terms as the `subject`. + */ + issuer: Certificate; + /** + * The date-time the certificate is valid from. + */ + valid_from: string; + /** + * The date-time the certificate is valid to. + */ + valid_to: string; + /** + * The certificate serial number, as a hex string. + */ + serialNumber: string; + /** + * The SHA-1 digest of the DER encoded certificate. + * It is returned as a `:` separated hexadecimal string. + */ + fingerprint: string; + /** + * The SHA-256 digest of the DER encoded certificate. + * It is returned as a `:` separated hexadecimal string. + */ + fingerprint256: string; + /** + * The SHA-512 digest of the DER encoded certificate. + * It is returned as a `:` separated hexadecimal string. + */ + fingerprint512: string; + /** + * The extended key usage, a set of OIDs. + */ + ext_key_usage?: string[]; + /** + * A string containing concatenated names for the subject, + * an alternative to the `subject` names. + */ + subjectaltname?: string; + /** + * An array describing the AuthorityInfoAccess, used with OCSP. + */ + infoAccess?: NodeJS.Dict; + /** + * For RSA keys: The RSA bit size. + * + * For EC keys: The key size in bits. + */ + bits?: number; + /** + * The RSA exponent, as a string in hexadecimal number notation. + */ + exponent?: string; + /** + * The RSA modulus, as a hexadecimal string. + */ + modulus?: string; + /** + * The public key. + */ + pubkey?: Buffer; + /** + * The ASN.1 name of the OID of the elliptic curve. + * Well-known curves are identified by an OID. + * While it is unusual, it is possible that the curve + * is identified by its mathematical properties, + * in which case it will not have an OID. + */ + asn1Curve?: string; + /** + * The NIST name for the elliptic curve,if it has one + * (not all well-known curves have been assigned names by NIST). + */ + nistCurve?: string; } interface DetailedPeerCertificate extends PeerCertificate { + /** + * The issuer certificate object. + * For self-signed certificates, this may be a circular reference. + */ issuerCertificate: DetailedPeerCertificate; } interface CipherNameAndProtocol { @@ -132,7 +212,7 @@ declare module 'tls' { * * Instances of `tls.TLSSocket` implement the duplex `Stream` interface. * - * Methods that return TLS connection metadata (e.g.{@link TLSSocket.getPeerCertificate} will only return data while the + * Methods that return TLS connection metadata (e.g.{@link TLSSocket.getPeerCertificate}) will only return data while the * connection is open. * @since v0.11.4 */ @@ -142,8 +222,8 @@ declare module 'tls' { */ constructor(socket: net.Socket, options?: TLSSocketOptions); /** - * Returns `true` if the peer certificate was signed by one of the CAs specified - * when creating the `tls.TLSSocket` instance, otherwise `false`. + * This property is `true` if the peer certificate was signed by one of the CAs + * specified when creating the `tls.TLSSocket` instance, otherwise `false`. * @since v0.11.4 */ authorized: boolean; @@ -179,13 +259,13 @@ declare module 'tls' { /** * Returns an object containing information on the negotiated cipher suite. * - * For example: + * For example, a TLSv1.2 protocol with AES256-SHA cipher: * * ```json * { - * "name": "AES128-SHA256", - * "standardName": "TLS_RSA_WITH_AES_128_CBC_SHA256", - * "version": "TLSv1.2" + * "name": "AES256-SHA", + * "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA", + * "version": "SSLv3" * } * ``` * @@ -316,7 +396,7 @@ declare module 'tls' { rejectUnauthorized?: boolean | undefined; requestCert?: boolean | undefined; }, - callback: (err: Error | null) => void + callback: (err: Error | null) => void, ): undefined | boolean; /** * The `tlsSocket.setMaxSendFragment()` method sets the maximum TLS fragment size. @@ -342,9 +422,9 @@ declare module 'tls' { * When enabled, TLS packet trace information is written to `stderr`. This can be * used to debug TLS connection problems. * - * Note: The format of the output is identical to the output of `openssl s_client -trace` or `openssl s_server -trace`. While it is produced by OpenSSL's`SSL_trace()` function, the format is - * undocumented, can change without notice, - * and should not be relied on. + * The format of the output is identical to the output of`openssl s_client -trace` or `openssl s_server -trace`. While it is produced by + * OpenSSL's `SSL_trace()` function, the format is undocumented, can change + * without notice, and should not be relied on. * @since v12.2.0 */ enableTrace(): void; @@ -373,7 +453,7 @@ declare module 'tls' { * 128, * 'client finished'); * - * + * /* * Example return value of keyingMaterial: * void): this; - addListener(event: 'OCSPResponse', listener: (response: Buffer) => void): this; - addListener(event: 'secureConnect', listener: () => void): this; - addListener(event: 'session', listener: (session: Buffer) => void): this; - addListener(event: 'keylog', listener: (line: Buffer) => void): this; + addListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; + addListener(event: "secureConnect", listener: () => void): this; + addListener(event: "session", listener: (session: Buffer) => void): this; + addListener(event: "keylog", listener: (line: Buffer) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'OCSPResponse', response: Buffer): boolean; - emit(event: 'secureConnect'): boolean; - emit(event: 'session', session: Buffer): boolean; - emit(event: 'keylog', line: Buffer): boolean; + emit(event: "OCSPResponse", response: Buffer): boolean; + emit(event: "secureConnect"): boolean; + emit(event: "session", session: Buffer): boolean; + emit(event: "keylog", line: Buffer): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'OCSPResponse', listener: (response: Buffer) => void): this; - on(event: 'secureConnect', listener: () => void): this; - on(event: 'session', listener: (session: Buffer) => void): this; - on(event: 'keylog', listener: (line: Buffer) => void): this; + on(event: "OCSPResponse", listener: (response: Buffer) => void): this; + on(event: "secureConnect", listener: () => void): this; + on(event: "session", listener: (session: Buffer) => void): this; + on(event: "keylog", listener: (line: Buffer) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'OCSPResponse', listener: (response: Buffer) => void): this; - once(event: 'secureConnect', listener: () => void): this; - once(event: 'session', listener: (session: Buffer) => void): this; - once(event: 'keylog', listener: (line: Buffer) => void): this; + once(event: "OCSPResponse", listener: (response: Buffer) => void): this; + once(event: "secureConnect", listener: () => void): this; + once(event: "session", listener: (session: Buffer) => void): this; + once(event: "keylog", listener: (line: Buffer) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'OCSPResponse', listener: (response: Buffer) => void): this; - prependListener(event: 'secureConnect', listener: () => void): this; - prependListener(event: 'session', listener: (session: Buffer) => void): this; - prependListener(event: 'keylog', listener: (line: Buffer) => void): this; + prependListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; + prependListener(event: "secureConnect", listener: () => void): this; + prependListener(event: "session", listener: (session: Buffer) => void): this; + prependListener(event: "keylog", listener: (line: Buffer) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'OCSPResponse', listener: (response: Buffer) => void): this; - prependOnceListener(event: 'secureConnect', listener: () => void): this; - prependOnceListener(event: 'session', listener: (session: Buffer) => void): this; - prependOnceListener(event: 'keylog', listener: (line: Buffer) => void): this; + prependOnceListener(event: "OCSPResponse", listener: (response: Buffer) => void): this; + prependOnceListener(event: "secureConnect", listener: () => void): this; + prependOnceListener(event: "session", listener: (session: Buffer) => void): this; + prependOnceListener(event: "keylog", listener: (line: Buffer) => void): this; } interface CommonConnectionOptions { /** @@ -481,7 +561,6 @@ declare module 'tls' { */ ticketKeys?: Buffer | undefined; /** - * * @param socket * @param identity identity parameter sent from the client. * @return pre-shared key that must either be @@ -516,7 +595,7 @@ declare module 'tls' { host?: string | undefined; port?: number | undefined; path?: string | undefined; // Creates unix socket connection to path. If this option is specified, `host` and `port` are ignored. - socket?: net.Socket | undefined; // Establish secure connection on a given socket rather than creating a new socket + socket?: stream.Duplex | undefined; // Establish secure connection on a given socket rather than creating a new socket checkServerIdentity?: typeof checkServerIdentity | undefined; servername?: string | undefined; // SNI TLS Extension session?: Buffer | undefined; @@ -557,7 +636,8 @@ declare module 'tls' { * used. * @since v0.5.3 * @param hostname A SNI host name or wildcard (e.g. `'*'`) - * @param context An object containing any of the possible properties from the {@link createSecureContext} `options` arguments (e.g. `key`, `cert`, `ca`, etc). + * @param context An object containing any of the possible properties from the {@link createSecureContext} `options` arguments (e.g. `key`, `cert`, `ca`, etc), or a TLS context object created + * with {@link createSecureContext} itself. */ addContext(hostname: string, context: SecureContextOptions): void; /** @@ -596,47 +676,118 @@ declare module 'tls' { * 6. keylog */ addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: TLSSocket) => void): this; - addListener(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; - addListener(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; - addListener(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void): this; - addListener(event: 'secureConnection', listener: (tlsSocket: TLSSocket) => void): this; - addListener(event: 'keylog', listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; + addListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; + addListener( + event: "newSession", + listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void, + ): this; + addListener( + event: "OCSPRequest", + listener: ( + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ) => void, + ): this; + addListener( + event: "resumeSession", + listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void, + ): this; + addListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; + addListener(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'tlsClientError', err: Error, tlsSocket: TLSSocket): boolean; - emit(event: 'newSession', sessionId: Buffer, sessionData: Buffer, callback: () => void): boolean; - emit(event: 'OCSPRequest', certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void): boolean; - emit(event: 'resumeSession', sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void): boolean; - emit(event: 'secureConnection', tlsSocket: TLSSocket): boolean; - emit(event: 'keylog', line: Buffer, tlsSocket: TLSSocket): boolean; + emit(event: "tlsClientError", err: Error, tlsSocket: TLSSocket): boolean; + emit(event: "newSession", sessionId: Buffer, sessionData: Buffer, callback: () => void): boolean; + emit( + event: "OCSPRequest", + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ): boolean; + emit( + event: "resumeSession", + sessionId: Buffer, + callback: (err: Error | null, sessionData: Buffer | null) => void, + ): boolean; + emit(event: "secureConnection", tlsSocket: TLSSocket): boolean; + emit(event: "keylog", line: Buffer, tlsSocket: TLSSocket): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'tlsClientError', listener: (err: Error, tlsSocket: TLSSocket) => void): this; - on(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; - on(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; - on(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void): this; - on(event: 'secureConnection', listener: (tlsSocket: TLSSocket) => void): this; - on(event: 'keylog', listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; + on(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; + on(event: "newSession", listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; + on( + event: "OCSPRequest", + listener: ( + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ) => void, + ): this; + on( + event: "resumeSession", + listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void, + ): this; + on(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; + on(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'tlsClientError', listener: (err: Error, tlsSocket: TLSSocket) => void): this; - once(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; - once(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; - once(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void): this; - once(event: 'secureConnection', listener: (tlsSocket: TLSSocket) => void): this; - once(event: 'keylog', listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; + once(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; + once( + event: "newSession", + listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void, + ): this; + once( + event: "OCSPRequest", + listener: ( + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ) => void, + ): this; + once( + event: "resumeSession", + listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void, + ): this; + once(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; + once(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: TLSSocket) => void): this; - prependListener(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; - prependListener(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; - prependListener(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void): this; - prependListener(event: 'secureConnection', listener: (tlsSocket: TLSSocket) => void): this; - prependListener(event: 'keylog', listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; + prependListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; + prependListener( + event: "newSession", + listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void, + ): this; + prependListener( + event: "OCSPRequest", + listener: ( + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ) => void, + ): this; + prependListener( + event: "resumeSession", + listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void, + ): this; + prependListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; + prependListener(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'tlsClientError', listener: (err: Error, tlsSocket: TLSSocket) => void): this; - prependOnceListener(event: 'newSession', listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void): this; - prependOnceListener(event: 'OCSPRequest', listener: (certificate: Buffer, issuer: Buffer, callback: (err: Error | null, resp: Buffer) => void) => void): this; - prependOnceListener(event: 'resumeSession', listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void): this; - prependOnceListener(event: 'secureConnection', listener: (tlsSocket: TLSSocket) => void): this; - prependOnceListener(event: 'keylog', listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; + prependOnceListener(event: "tlsClientError", listener: (err: Error, tlsSocket: TLSSocket) => void): this; + prependOnceListener( + event: "newSession", + listener: (sessionId: Buffer, sessionData: Buffer, callback: () => void) => void, + ): this; + prependOnceListener( + event: "OCSPRequest", + listener: ( + certificate: Buffer, + issuer: Buffer, + callback: (err: Error | null, resp: Buffer) => void, + ) => void, + ): this; + prependOnceListener( + event: "resumeSession", + listener: (sessionId: Buffer, callback: (err: Error | null, sessionData: Buffer | null) => void) => void, + ): this; + prependOnceListener(event: "secureConnection", listener: (tlsSocket: TLSSocket) => void): this; + prependOnceListener(event: "keylog", listener: (line: Buffer, tlsSocket: TLSSocket) => void): this; } /** * @deprecated since v0.11.3 Use `tls.TLSSocket` instead. @@ -645,8 +796,19 @@ declare module 'tls' { encrypted: TLSSocket; cleartext: TLSSocket; } - type SecureVersion = 'TLSv1.3' | 'TLSv1.2' | 'TLSv1.1' | 'TLSv1'; + type SecureVersion = "TLSv1.3" | "TLSv1.2" | "TLSv1.1" | "TLSv1"; interface SecureContextOptions { + /** + * If set, this will be called when a client opens a connection using the ALPN extension. + * One argument will be passed to the callback: an object containing `servername` and `protocols` fields, + * respectively containing the server name from the SNI extension (if any) and an array of + * ALPN protocol name strings. The callback must return either one of the strings listed in `protocols`, + * which will be returned to the client as the selected ALPN protocol, or `undefined`, + * to reject the connection with a fatal alert. If a string is returned that does not match one of + * the client's ALPN protocols, an error will be thrown. + * This option cannot be used with the `ALPNProtocols` option, and setting both options will throw an error. + */ + ALPNCallback?: ((arg: { servername: string; protocols: string[] }) => string | undefined) | undefined; /** * Optionally override the trusted CA certificates. Default is to trust * the well-known CAs curated by Mozilla. Mozilla's CAs are completely @@ -688,12 +850,9 @@ declare module 'tls' { */ crl?: string | Buffer | Array | undefined; /** - * Diffie Hellman parameters, required for Perfect Forward Secrecy. Use - * openssl dhparam to create the parameters. The key length must be - * greater than or equal to 1024 bits or else an error will be thrown. - * Although 1024 bits is permissible, use 2048 bits or larger for - * stronger security. If omitted or invalid, the parameters are - * silently discarded and DHE ciphers will not be available. + * `'auto'` or custom Diffie-Hellman parameters, required for non-ECDHE perfect forward secrecy. + * If omitted or invalid, the parameters are silently discarded and DHE ciphers will not be available. + * ECDHE-based perfect forward secrecy will still be available. */ dhparam?: string | Buffer | undefined; /** @@ -722,7 +881,7 @@ declare module 'tls' { * object.passphrase is optional. Encrypted keys will be decrypted with * object.passphrase if provided, or options.passphrase if it is not. */ - key?: string | Buffer | Array | undefined; + key?: string | Buffer | Array | undefined; /** * Name of an OpenSSL engine to get private key from. Should be used * together with privateKeyIdentifier. @@ -813,13 +972,19 @@ declare module 'tls' { * Returns [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object, populating it with `reason`, `host`, and `cert` on * failure. On success, returns [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type). * - * This function can be overwritten by providing alternative function as part of - * the `options.checkServerIdentity` option passed to `tls.connect()`. The + * This function is intended to be used in combination with the`checkServerIdentity` option that can be passed to {@link connect} and as + * such operates on a `certificate object`. For other purposes, consider using `x509.checkHost()` instead. + * + * This function can be overwritten by providing an alternative function as the`options.checkServerIdentity` option that is passed to `tls.connect()`. The * overwriting function can call `tls.checkServerIdentity()` of course, to augment * the checks done with additional verification. * * This function is only called if the certificate passed all other checks, such as * being issued by trusted CA (`options.ca`). + * + * Earlier versions of Node.js incorrectly accepted certificates for a given`hostname` if a matching `uniformResourceIdentifier` subject alternative name + * was present (see [CVE-2021-44531](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44531)). Applications that wish to accept`uniformResourceIdentifier` subject alternative names can use + * a custom`options.checkServerIdentity` function that implements the desired behavior. * @since v0.8.4 * @param hostname The host name or IP address to verify the certificate against. * @param cert A `certificate object` representing the peer's certificate. @@ -829,14 +994,14 @@ declare module 'tls' { * Creates a new {@link Server}. The `secureConnectionListener`, if provided, is * automatically set as a listener for the `'secureConnection'` event. * - * The `ticketKeys` options is automatically shared between `cluster` module + * The `ticketKeys` options is automatically shared between `node:cluster` module * workers. * * The following illustrates a simple echo server: * * ```js - * const tls = require('tls'); - * const fs = require('fs'); + * const tls = require('node:tls'); + * const fs = require('node:fs'); * * const options = { * key: fs.readFileSync('server-key.pem'), @@ -846,7 +1011,7 @@ declare module 'tls' { * requestCert: true, * * // This is necessary only if the client uses a self-signed certificate. - * ca: [ fs.readFileSync('client-cert.pem') ] + * ca: [ fs.readFileSync('client-cert.pem') ], * }; * * const server = tls.createServer(options, (socket) => { @@ -881,8 +1046,8 @@ declare module 'tls' { * * ```js * // Assumes an echo server that is listening on port 8000. - * const tls = require('tls'); - * const fs = require('fs'); + * const tls = require('node:tls'); + * const fs = require('node:fs'); * * const options = { * // Necessary only if the server requires client certificate authentication. @@ -913,7 +1078,12 @@ declare module 'tls' { * @since v0.11.3 */ function connect(options: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; - function connect(port: number, host?: string, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; + function connect( + port: number, + host?: string, + options?: ConnectionOptions, + secureConnectListener?: () => void, + ): TLSSocket; function connect(port: number, options?: ConnectionOptions, secureConnectListener?: () => void): TLSSocket; /** * Creates a new secure pair object with two streams, one of which reads and writes @@ -948,7 +1118,12 @@ declare module 'tls' { * @param requestCert `true` to specify whether a server should request a certificate from a connecting client. Only applies when `isServer` is `true`. * @param rejectUnauthorized If not `false` a server automatically reject clients with invalid certificates. Only applies when `isServer` is `true`. */ - function createSecurePair(context?: SecureContext, isServer?: boolean, requestCert?: boolean, rejectUnauthorized?: boolean): SecurePair; + function createSecurePair( + context?: SecureContext, + isServer?: boolean, + requestCert?: boolean, + rejectUnauthorized?: boolean, + ): SecurePair; /** * {@link createServer} sets the default value of the `honorCipherOrder` option * to `true`, other APIs that create secure contexts leave it unset. @@ -958,12 +1133,19 @@ declare module 'tls' { * APIs that create secure contexts have no default value. * * The `tls.createSecureContext()` method creates a `SecureContext` object. It is - * usable as an argument to several `tls` APIs, such as {@link createServer} and `server.addContext()`, but has no public methods. + * usable as an argument to several `tls` APIs, such as `server.addContext()`, + * but has no public methods. The {@link Server} constructor and the {@link createServer} method do not support the `secureContext` option. * * A key is _required_ for ciphers that use certificates. Either `key` or`pfx` can be used to provide it. * * If the `ca` option is not given, then Node.js will default to using [Mozilla's publicly trusted list of * CAs](https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt). + * + * Custom DHE parameters are discouraged in favor of the new `dhparam: 'auto'`option. When set to `'auto'`, well-known DHE parameters of sufficient strength + * will be selected automatically. Otherwise, if necessary, `openssl dhparam` can + * be used to create custom parameters. The key length must be greater than or + * equal to 1024 bits or else an error will be thrown. Although 1024 bits is + * permissible, use 2048 bits or larger for stronger security. * @since v0.11.13 */ function createSecureContext(options?: SecureContextOptions): SecureContext; @@ -972,6 +1154,8 @@ declare module 'tls' { * lower-case for historical reasons, but must be uppercased to be used in * the `ciphers` option of {@link createSecureContext}. * + * Not all supported ciphers are enabled by default. See `Modifying the default TLS cipher suite`. + * * Cipher names that start with `'tls_'` are for TLSv1.3, all the others are for * TLSv1.2 and below. * @@ -1007,13 +1191,20 @@ declare module 'tls' { * are provided, the lowest minimum is used. */ let DEFAULT_MIN_VERSION: SecureVersion; + /** + * The default value of the ciphers option of tls.createSecureContext(). + * It can be assigned any of the supported OpenSSL ciphers. + * Defaults to the content of crypto.constants.defaultCoreCipherList, unless + * changed using CLI options using --tls-default-ciphers. + */ + let DEFAULT_CIPHERS: string; /** * An immutable array of strings representing the root certificates (in PEM * format) used for verifying peer certificates. This is the default value * of the ca option to tls.createSecureContext(). */ - const rootCertificates: ReadonlyArray; + const rootCertificates: readonly string[]; } -declare module 'node:tls' { - export * from 'tls'; +declare module "node:tls" { + export * from "tls"; } diff --git a/node_modules/@types/node/ts4.8/trace_events.d.ts b/node_modules/@types/node/ts4.8/trace_events.d.ts old mode 100755 new mode 100644 index 2976eb6..3361359 --- a/node_modules/@types/node/ts4.8/trace_events.d.ts +++ b/node_modules/@types/node/ts4.8/trace_events.d.ts @@ -1,9 +1,9 @@ /** - * The `trace_events` module provides a mechanism to centralize tracing information - * generated by V8, Node.js core, and userspace code. + * The `node:trace_events` module provides a mechanism to centralize tracing + * information generated by V8, Node.js core, and userspace code. * * Tracing can be enabled with the `--trace-event-categories` command-line flag - * or by using the `trace_events` module. The `--trace-event-categories` flag + * or by using the `node:trace_events` module. The `--trace-event-categories` flag * accepts a list of comma-separated category names. * * The available categories are: @@ -13,9 +13,19 @@ * The `async_hooks` events have a unique `asyncId` and a special `triggerId` `triggerAsyncId` property. * * `node.bootstrap`: Enables capture of Node.js bootstrap milestones. * * `node.console`: Enables capture of `console.time()` and `console.count()`output. + * * `node.threadpoolwork.sync`: Enables capture of trace data for threadpool + * synchronous operations, such as `blob`, `zlib`, `crypto` and `node_api`. + * * `node.threadpoolwork.async`: Enables capture of trace data for threadpool + * asynchronous operations, such as `blob`, `zlib`, `crypto` and `node_api`. * * `node.dns.native`: Enables capture of trace data for DNS queries. + * * `node.net.native`: Enables capture of trace data for network. * * `node.environment`: Enables capture of Node.js Environment milestones. * * `node.fs.sync`: Enables capture of trace data for file system sync methods. + * * `node.fs_dir.sync`: Enables capture of trace data for file system sync + * directory methods. + * * `node.fs.async`: Enables capture of trace data for file system async methods. + * * `node.fs_dir.async`: Enables capture of trace data for file system async + * directory methods. * * `node.perf`: Enables capture of `Performance API` measurements. * * `node.perf.usertiming`: Enables capture of only Performance API User Timing * measures and marks. @@ -23,8 +33,9 @@ * measurements. * * `node.promises.rejections`: Enables capture of trace data tracking the number * of unhandled Promise rejections and handled-after-rejections. - * * `node.vm.script`: Enables capture of trace data for the `vm` module's`runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. + * * `node.vm.script`: Enables capture of trace data for the `node:vm` module's`runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. * * `v8`: The `V8` events are GC, compiling, and execution related. + * * `node.http`: Enables capture of trace data for http request / response. * * By default the `node`, `node.async_hooks`, and `v8` categories are enabled. * @@ -43,10 +54,10 @@ * node --trace-event-categories v8,node,node.async_hooks * ``` * - * Alternatively, trace events may be enabled using the `trace_events` module: + * Alternatively, trace events may be enabled using the `node:trace_events` module: * * ```js - * const trace_events = require('trace_events'); + * const trace_events = require('node:trace_events'); * const tracing = trace_events.createTracing({ categories: ['node.perf'] }); * tracing.enable(); // Enable trace event capture for the 'node.perf' category * @@ -66,6 +77,16 @@ * node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js * ``` * + * To guarantee that the log file is properly generated after signal events like`SIGINT`, `SIGTERM`, or `SIGBREAK`, make sure to have the appropriate handlers + * in your code, such as: + * + * ```js + * process.on('SIGINT', function onSigint() { + * console.info('Received SIGINT.'); + * process.exit(130); // Or applicable exit code depending on OS and signal + * }); + * ``` + * * The tracing system uses the same time source * as the one used by `process.hrtime()`. * However the trace-event timestamps are expressed in microseconds, @@ -73,9 +94,9 @@ * * The features from this module are not available in `Worker` threads. * @experimental - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/trace_events.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/trace_events.js) */ -declare module 'trace_events' { +declare module "trace_events" { /** * The `Tracing` object is used to enable or disable tracing for sets of * categories. Instances are created using the @@ -122,7 +143,7 @@ declare module 'trace_events' { * Creates and returns a `Tracing` object for the given set of `categories`. * * ```js - * const trace_events = require('trace_events'); + * const trace_events = require('node:trace_events'); * const categories = ['node.perf', 'node.async_hooks']; * const tracing = trace_events.createTracing({ categories }); * tracing.enable(); @@ -142,7 +163,7 @@ declare module 'trace_events' { * Given the file `test.js` below, the command`node --trace-event-categories node.perf test.js` will print`'node.async_hooks,node.perf'` to the console. * * ```js - * const trace_events = require('trace_events'); + * const trace_events = require('node:trace_events'); * const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] }); * const t2 = trace_events.createTracing({ categories: ['node.perf'] }); * const t3 = trace_events.createTracing({ categories: ['v8'] }); @@ -156,6 +177,6 @@ declare module 'trace_events' { */ function getEnabledCategories(): string | undefined; } -declare module 'node:trace_events' { - export * from 'trace_events'; +declare module "node:trace_events" { + export * from "trace_events"; } diff --git a/node_modules/@types/node/ts4.8/tty.d.ts b/node_modules/@types/node/ts4.8/tty.d.ts old mode 100755 new mode 100644 index 3bce2d3..1c0dafd --- a/node_modules/@types/node/ts4.8/tty.d.ts +++ b/node_modules/@types/node/ts4.8/tty.d.ts @@ -1,10 +1,9 @@ /** - * The `tty` module provides the `tty.ReadStream` and `tty.WriteStream` classes. - * In most cases, it will not be necessary or possible to use this module directly. - * However, it can be accessed using: + * The `node:tty` module provides the `tty.ReadStream` and `tty.WriteStream`classes. In most cases, it will not be necessary or possible to use this module + * directly. However, it can be accessed using: * * ```js - * const tty = require('tty'); + * const tty = require('node:tty'); * ``` * * When Node.js detects that it is being run with a text terminal ("TTY") @@ -22,10 +21,10 @@ * * In most cases, there should be little to no reason for an application to * manually create instances of the `tty.ReadStream` and `tty.WriteStream`classes. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/tty.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/tty.js) */ -declare module 'tty' { - import * as net from 'node:net'; +declare module "tty" { + import * as net from "node:net"; /** * The `tty.isatty()` method returns `true` if the given `fd` is associated with * a TTY and `false` if it is not, including whenever `fd` is not a non-negative @@ -43,7 +42,10 @@ declare module 'tty' { constructor(fd: number, options?: net.SocketConstructorOpts); /** * A `boolean` that is `true` if the TTY is currently configured to operate as a - * raw device. Defaults to `false`. + * raw device. + * + * This flag is always `false` when a process starts, even if the terminal is + * operating in raw mode. Its value will change with subsequent calls to`setRawMode`. * @since v0.7.7 */ isRaw: boolean; @@ -52,7 +54,9 @@ declare module 'tty' { * * When in raw mode, input is always available character-by-character, not * including modifiers. Additionally, all special processing of characters by the - * terminal is disabled, including echoing input characters.Ctrl+C will no longer cause a `SIGINT` when in this mode. + * terminal is disabled, including echoing input + * characters. Ctrl+C will no longer cause a `SIGINT` when + * in this mode. * @since v0.7.7 * @param mode If `true`, configures the `tty.ReadStream` to operate as a raw device. If `false`, configures the `tty.ReadStream` to operate in its default mode. The `readStream.isRaw` * property will be set to the resulting mode. @@ -79,17 +83,17 @@ declare module 'tty' { class WriteStream extends net.Socket { constructor(fd: number); addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'resize', listener: () => void): this; + addListener(event: "resize", listener: () => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'resize'): boolean; + emit(event: "resize"): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'resize', listener: () => void): this; + on(event: "resize", listener: () => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'resize', listener: () => void): this; + once(event: "resize", listener: () => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'resize', listener: () => void): this; + prependListener(event: "resize", listener: () => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'resize', listener: () => void): this; + prependOnceListener(event: "resize", listener: () => void): this; /** * `writeStream.clearLine()` clears the current line of this `WriteStream` in a * direction identified by `dir`. @@ -199,6 +203,6 @@ declare module 'tty' { isTTY: boolean; } } -declare module 'node:tty' { - export * from 'tty'; +declare module "node:tty" { + export * from "tty"; } diff --git a/node_modules/@types/node/ts4.8/url.d.ts b/node_modules/@types/node/ts4.8/url.d.ts old mode 100755 new mode 100644 index e6272b5..20a5d85 --- a/node_modules/@types/node/ts4.8/url.d.ts +++ b/node_modules/@types/node/ts4.8/url.d.ts @@ -1,16 +1,16 @@ /** - * The `url` module provides utilities for URL resolution and parsing. It can be - * accessed using: + * The `node:url` module provides utilities for URL resolution and parsing. It can + * be accessed using: * * ```js - * import url from 'url'; + * import url from 'node:url'; * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/url.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/url.js) */ -declare module 'url' { - import { Blob } from 'node:buffer'; - import { ClientRequestArgs } from 'node:http'; - import { ParsedUrlQuery, ParsedUrlQueryInput } from 'node:querystring'; +declare module "url" { + import { Blob as NodeBlob } from "node:buffer"; + import { ClientRequestArgs } from "node:http"; + import { ParsedUrlQuery, ParsedUrlQueryInput } from "node:querystring"; // Input to `url.format` interface UrlObject { auth?: string | null | undefined; @@ -54,17 +54,11 @@ declare module 'url' { * * A `URIError` is thrown if the `auth` property is present but cannot be decoded. * - * Use of the legacy `url.parse()` method is discouraged. Users should - * use the WHATWG `URL` API. Because the `url.parse()` method uses a - * lenient, non-standard algorithm for parsing URL strings, security - * issues can be introduced. Specifically, issues with [host name spoofing](https://hackerone.com/reports/678487) and - * incorrect handling of usernames and passwords have been identified. - * - * Deprecation of this API has been shelved for now primarily due to the the - * inability of the [WHATWG API to parse relative URLs](https://github.com/nodejs/node/issues/12682#issuecomment-1154492373). - * [Discussions are ongoing](https://github.com/whatwg/url/issues/531) for the best way to resolve this. - * + * `url.parse()` uses a lenient, non-standard algorithm for parsing URL + * strings. It is prone to security issues such as [host name spoofing](https://hackerone.com/reports/678487) and incorrect handling of usernames and passwords. Do not use with untrusted + * input. CVEs are not issued for `url.parse()` vulnerabilities. Use the `WHATWG URL` API instead. * @since v0.1.25 + * @deprecated Use the WHATWG URL API instead. * @param urlString The URL string to parse. * @param [parseQueryString=false] If `true`, the `query` property will always be set to an object returned by the {@link querystring} module's `parse()` method. If `false`, the `query` property * on the returned URL object will be an unparsed, undecoded string. @@ -72,31 +66,75 @@ declare module 'url' { * result would be `{host: 'foo', pathname: '/bar'}` rather than `{pathname: '//foo/bar'}`. */ function parse(urlString: string): UrlWithStringQuery; - function parse(urlString: string, parseQueryString: false | undefined, slashesDenoteHost?: boolean): UrlWithStringQuery; + function parse( + urlString: string, + parseQueryString: false | undefined, + slashesDenoteHost?: boolean, + ): UrlWithStringQuery; function parse(urlString: string, parseQueryString: true, slashesDenoteHost?: boolean): UrlWithParsedQuery; function parse(urlString: string, parseQueryString: boolean, slashesDenoteHost?: boolean): Url; /** - * The URL object has both a `toString()` method and `href` property that return string serializations of the URL. - * These are not, however, customizable in any way. The `url.format(URL[, options])` method allows for basic - * customization of the output. - * Returns a customizable serialization of a URL `String` representation of a `WHATWG URL` object. + * The `url.format()` method returns a formatted URL string derived from`urlObject`. * * ```js - * import url from 'url'; - * const myURL = new URL('https://a:b@測試?abc#foo'); + * const url = require('node:url'); + * url.format({ + * protocol: 'https', + * hostname: 'example.com', + * pathname: '/some/path', + * query: { + * page: 1, + * format: 'json', + * }, + * }); * - * console.log(myURL.href); - * // Prints https://a:b@xn--g6w251d/?abc#foo - * - * console.log(myURL.toString()); - * // Prints https://a:b@xn--g6w251d/?abc#foo - * - * console.log(url.format(myURL, { fragment: false, unicode: true, auth: false })); - * // Prints 'https://測試/?abc' + * // => 'https://example.com/some/path?page=1&format=json' * ``` - * @since v7.6.0 - * @param urlObject A `WHATWG URL` object - * @param options + * + * If `urlObject` is not an object or a string, `url.format()` will throw a `TypeError`. + * + * The formatting process operates as follows: + * + * * A new empty string `result` is created. + * * If `urlObject.protocol` is a string, it is appended as-is to `result`. + * * Otherwise, if `urlObject.protocol` is not `undefined` and is not a string, an `Error` is thrown. + * * For all string values of `urlObject.protocol` that _do not end_ with an ASCII + * colon (`:`) character, the literal string `:` will be appended to `result`. + * * If either of the following conditions is true, then the literal string `//`will be appended to `result`: + * * `urlObject.slashes` property is true; + * * `urlObject.protocol` begins with `http`, `https`, `ftp`, `gopher`, or`file`; + * * If the value of the `urlObject.auth` property is truthy, and either`urlObject.host` or `urlObject.hostname` are not `undefined`, the value of`urlObject.auth` will be coerced into a string + * and appended to `result`followed by the literal string `@`. + * * If the `urlObject.host` property is `undefined` then: + * * If the `urlObject.hostname` is a string, it is appended to `result`. + * * Otherwise, if `urlObject.hostname` is not `undefined` and is not a string, + * an `Error` is thrown. + * * If the `urlObject.port` property value is truthy, and `urlObject.hostname`is not `undefined`: + * * The literal string `:` is appended to `result`, and + * * The value of `urlObject.port` is coerced to a string and appended to`result`. + * * Otherwise, if the `urlObject.host` property value is truthy, the value of`urlObject.host` is coerced to a string and appended to `result`. + * * If the `urlObject.pathname` property is a string that is not an empty string: + * * If the `urlObject.pathname`_does not start_ with an ASCII forward slash + * (`/`), then the literal string `'/'` is appended to `result`. + * * The value of `urlObject.pathname` is appended to `result`. + * * Otherwise, if `urlObject.pathname` is not `undefined` and is not a string, an `Error` is thrown. + * * If the `urlObject.search` property is `undefined` and if the `urlObject.query`property is an `Object`, the literal string `?` is appended to `result`followed by the output of calling the + * `querystring` module's `stringify()`method passing the value of `urlObject.query`. + * * Otherwise, if `urlObject.search` is a string: + * * If the value of `urlObject.search`_does not start_ with the ASCII question + * mark (`?`) character, the literal string `?` is appended to `result`. + * * The value of `urlObject.search` is appended to `result`. + * * Otherwise, if `urlObject.search` is not `undefined` and is not a string, an `Error` is thrown. + * * If the `urlObject.hash` property is a string: + * * If the value of `urlObject.hash`_does not start_ with the ASCII hash (`#`) + * character, the literal string `#` is appended to `result`. + * * The value of `urlObject.hash` is appended to `result`. + * * Otherwise, if the `urlObject.hash` property is not `undefined` and is not a + * string, an `Error` is thrown. + * * `result` is returned. + * @since v0.1.25 + * @legacy Use the WHATWG URL API instead. + * @param urlObject A URL object (as returned by `url.parse()` or constructed otherwise). If a string, it is converted to an object by passing it to `url.parse()`. */ function format(urlObject: URL, options?: URLFormatOptions): string; /** @@ -159,22 +197,22 @@ declare module 'url' { * string, an `Error` is thrown. * * `result` is returned. * @since v0.1.25 - * @deprecated Legacy: Use the WHATWG URL API instead. + * @legacy Use the WHATWG URL API instead. * @param urlObject A URL object (as returned by `url.parse()` or constructed otherwise). If a string, it is converted to an object by passing it to `url.parse()`. */ function format(urlObject: UrlObject | string): string; /** * The `url.resolve()` method resolves a target URL relative to a base URL in a - * manner similar to that of a Web browser resolving an anchor tag HREF. + * manner similar to that of a web browser resolving an anchor tag. * * ```js - * const url = require('url'); + * const url = require('node:url'); * url.resolve('/one/two/three', 'four'); // '/one/two/four' * url.resolve('http://example.com/', '/one'); // 'http://example.com/one' * url.resolve('http://example.com/one', '/two'); // 'http://example.com/two' * ``` * - * You can achieve the same result using the WHATWG URL API: + * To achieve the same result using the WHATWG URL API: * * ```js * function resolve(from, to) { @@ -192,9 +230,9 @@ declare module 'url' { * resolve('http://example.com/one', '/two'); // 'http://example.com/two' * ``` * @since v0.1.25 - * @deprecated Legacy: Use the WHATWG URL API instead. - * @param from The Base URL being resolved against. - * @param to The HREF URL being resolved. + * @legacy Use the WHATWG URL API instead. + * @param from The base URL to use if `to` is a relative URL. + * @param to The target URL to resolve. */ function resolve(from: string, to: string): string; /** @@ -203,10 +241,8 @@ declare module 'url' { * * It performs the inverse operation to {@link domainToUnicode}. * - * This feature is only available if the `node` executable was compiled with `ICU` enabled. If not, the domain names are passed through unchanged. - * * ```js - * import url from 'url'; + * import url from 'node:url'; * * console.log(url.domainToASCII('español.com')); * // Prints xn--espaol-zwa.com @@ -224,10 +260,8 @@ declare module 'url' { * * It performs the inverse operation to {@link domainToASCII}. * - * This feature is only available if the `node` executable was compiled with `ICU` enabled. If not, the domain names are passed through unchanged. - * * ```js - * import url from 'url'; + * import url from 'node:url'; * * console.log(url.domainToUnicode('xn--espaol-zwa.com')); * // Prints español.com @@ -244,7 +278,7 @@ declare module 'url' { * well as ensuring a cross-platform valid absolute path string. * * ```js - * import { fileURLToPath } from 'url'; + * import { fileURLToPath } from 'node:url'; * * const __filename = fileURLToPath(import.meta.url); * @@ -270,7 +304,7 @@ declare module 'url' { * control characters are correctly encoded when converting into a File URL. * * ```js - * import { pathToFileURL } from 'url'; + * import { pathToFileURL } from 'node:url'; * * new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1 * pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX) @@ -288,11 +322,11 @@ declare module 'url' { * expected by the `http.request()` and `https.request()` APIs. * * ```js - * import { urlToHttpOptions } from 'url'; + * import { urlToHttpOptions } from 'node:url'; * const myURL = new URL('https://a:b@測試?abc#foo'); * * console.log(urlToHttpOptions(myURL)); - * + * /* * { * protocol: 'https:', * hostname: 'xn--g6w251d', @@ -305,7 +339,7 @@ declare module 'url' { * } * * ``` - * @since v15.7.0 + * @since v15.7.0, v14.18.0 * @param url The `WHATWG URL` object to convert to an options object. * @return Options object */ @@ -336,7 +370,7 @@ declare module 'url' { * const { * Blob, * resolveObjectURL, - * } = require('buffer'); + * } = require('node:buffer'); * * const blob = new Blob(['hello']); * const id = URL.createObjectURL(blob); @@ -355,14 +389,29 @@ declare module 'url' { * @since v16.7.0 * @experimental */ - static createObjectURL(blob: Blob): string; + static createObjectURL(blob: NodeBlob): string; /** - * Removes the stored `Blob` identified by the given ID. + * Removes the stored `Blob` identified by the given ID. Attempting to revoke a + * ID that isn't registered will silently fail. * @since v16.7.0 * @experimental * @param id A `'blob:nodedata:...` URL string returned by a prior call to `URL.createObjectURL()`. */ static revokeObjectURL(objectUrl: string): void; + /** + * Checks if an `input` relative to the `base` can be parsed to a `URL`. + * + * ```js + * const isValid = URL.canParse('/foo', 'https://example.org/'); // true + * + * const isNotValid = URL.canParse('/foo'); // false + * ``` + * @since v19.9.0 + * @param input The absolute or relative input URL to parse. If `input` is relative, then `base` is required. If `input` is absolute, the `base` is ignored. If `input` is not a string, it is + * `converted to a string` first. + * @param base The base URL to resolve against if the `input` is not absolute. If `base` is not a string, it is `converted to a string` first. + */ + static canParse(input: string, base?: string): boolean; constructor(input: string, base?: string | URL); /** * Gets and sets the fragment portion of the URL. @@ -408,7 +457,7 @@ declare module 'url' { * // Prints example.org * * // Setting the hostname does not change the port - * myURL.hostname = 'example.com:82'; + * myURL.hostname = 'example.com'; * console.log(myURL.href); * // Prints https://example.com:81/foo * @@ -471,7 +520,7 @@ declare module 'url' { * * myURL.password = '123'; * console.log(myURL.href); - * // Prints https://abc:123@example.com + * // Prints https://abc:123@example.com/ * ``` * * Invalid URL characters included in the value assigned to the `password` property @@ -615,14 +664,14 @@ declare module 'url' { * character, while `URLSearchParams` will always encode it: * * ```js - * const myUrl = new URL('https://example.org/abc?foo=~bar'); + * const myURL = new URL('https://example.org/abc?foo=~bar'); * - * console.log(myUrl.search); // prints ?foo=~bar + * console.log(myURL.search); // prints ?foo=~bar * * // Modify the URL via searchParams... - * myUrl.searchParams.sort(); + * myURL.searchParams.sort(); * - * console.log(myUrl.search); // prints ?foo=%7Ebar + * console.log(myURL.search); // prints ?foo=%7Ebar * ``` */ readonly searchParams: URLSearchParams; @@ -711,15 +760,25 @@ declare module 'url' { * @since v7.5.0, v6.13.0 */ class URLSearchParams implements Iterable<[string, string]> { - constructor(init?: URLSearchParams | string | Record> | Iterable<[string, string]> | ReadonlyArray<[string, string]>); + constructor( + init?: + | URLSearchParams + | string + | Record + | Iterable<[string, string]> + | ReadonlyArray<[string, string]>, + ); /** * Append a new name-value pair to the query string. */ append(name: string, value: string): void; /** - * Remove all name-value pairs whose name is `name`. + * If `value` is provided, removes all name-value pairs + * where name is `name` and value is `value`.. + * + * If `value` is not provided, removes all name-value pairs whose name is `name`. */ - delete(name: string): void; + delete(name: string, value?: string): void; /** * Returns an ES6 `Iterator` over each of the name-value pairs in the query. * Each item of the iterator is a JavaScript `Array`. The first item of the `Array`is the `name`, the second item of the `Array` is the `value`. @@ -742,7 +801,10 @@ declare module 'url' { * @param fn Invoked for each name-value pair in the query * @param thisArg To be used as `this` value for when `fn` is called */ - forEach(callback: (this: TThis, value: string, name: string, searchParams: URLSearchParams) => void, thisArg?: TThis): void; + forEach( + callback: (this: TThis, value: string, name: string, searchParams: URLSearchParams) => void, + thisArg?: TThis, + ): void; /** * Returns the value of the first name-value pair whose name is `name`. If there * are no such pairs, `null` is returned. @@ -755,9 +817,15 @@ declare module 'url' { */ getAll(name: string): string[]; /** - * Returns `true` if there is at least one name-value pair whose name is `name`. + * Checks if the `URLSearchParams` object contains key-value pair(s) based on`name` and an optional `value` argument. + * + * If `value` is provided, returns `true` when name-value pair with + * same `name` and `value` exists. + * + * If `value` is not provided, returns `true` if there is at least one name-value + * pair whose name is `name`. */ - has(name: string): boolean; + has(name: string, value?: string): boolean; /** * Returns an ES6 `Iterator` over the names of each name-value pair. * @@ -792,6 +860,11 @@ declare module 'url' { * ``` */ set(name: string, value: string): void; + /** + * The total number of parameter entries. + * @since v19.8.0 + */ + readonly size: number; /** * Sort all existing name-value pairs in-place by their names. Sorting is done * with a [stable sorting algorithm](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability), so relative order between name-value pairs @@ -819,8 +892,7 @@ declare module 'url' { values(): IterableIterator; [Symbol.iterator](): IterableIterator<[string, string]>; } - - import { URL as _URL, URLSearchParams as _URLSearchParams } from 'url'; + import { URL as _URL, URLSearchParams as _URLSearchParams } from "url"; global { interface URLSearchParams extends _URLSearchParams {} interface URL extends _URL {} @@ -833,23 +905,23 @@ declare module 'url' { * https://nodejs.org/api/url.html#the-whatwg-url-api * @since v10.0.0 */ - var URL: - // For compatibility with "dom" and "webworker" URL declarations - typeof globalThis extends { onmessage: any, URL: infer URL } - ? URL - : typeof _URL; + var URL: typeof globalThis extends { + onmessage: any; + URL: infer T; + } ? T + : typeof _URL; /** - * `URLSearchParams` class is a global reference for `require('url').URLSearchParams`. + * `URLSearchParams` class is a global reference for `require('url').URLSearchParams` * https://nodejs.org/api/url.html#class-urlsearchparams * @since v10.0.0 */ - var URLSearchParams: - // For compatibility with "dom" and "webworker" URLSearchParams declarations - typeof globalThis extends { onmessage: any, URLSearchParams: infer URLSearchParams } - ? URLSearchParams - : typeof _URLSearchParams; + var URLSearchParams: typeof globalThis extends { + onmessage: any; + URLSearchParams: infer T; + } ? T + : typeof _URLSearchParams; } } -declare module 'node:url' { - export * from 'url'; +declare module "node:url" { + export * from "url"; } diff --git a/node_modules/@types/node/ts4.8/util.d.ts b/node_modules/@types/node/ts4.8/util.d.ts old mode 100755 new mode 100644 index d0f4c17..ac269ec --- a/node_modules/@types/node/ts4.8/util.d.ts +++ b/node_modules/@types/node/ts4.8/util.d.ts @@ -1,33 +1,49 @@ /** - * The `util` module supports the needs of Node.js internal APIs. Many of the + * The `node:util` module supports the needs of Node.js internal APIs. Many of the * utilities are useful for application and module developers as well. To access * it: * * ```js - * const util = require('util'); + * const util = require('node:util'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/util.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/util.js) */ -declare module 'util' { - import * as types from 'node:util/types'; +declare module "util" { + import * as types from "node:util/types"; export interface InspectOptions { /** - * If set to `true`, getters are going to be - * inspected as well. If set to `'get'` only getters without setter are going - * to be inspected. If set to `'set'` only getters having a corresponding - * setter are going to be inspected. This might cause side effects depending on - * the getter function. - * @default `false` + * If `true`, object's non-enumerable symbols and properties are included in the formatted result. + * `WeakMap` and `WeakSet` entries are also included as well as user defined prototype properties (excluding method properties). + * @default false */ - getters?: 'get' | 'set' | boolean | undefined; showHidden?: boolean | undefined; /** + * Specifies the number of times to recurse while formatting object. + * This is useful for inspecting large objects. + * To recurse up to the maximum call stack size pass `Infinity` or `null`. * @default 2 */ depth?: number | null | undefined; + /** + * If `true`, the output is styled with ANSI color codes. Colors are customizable. + */ colors?: boolean | undefined; + /** + * If `false`, `[util.inspect.custom](depth, opts, inspect)` functions are not invoked. + * @default true + */ customInspect?: boolean | undefined; + /** + * If `true`, `Proxy` inspection includes the target and handler objects. + * @default false + */ showProxy?: boolean | undefined; + /** + * Specifies the maximum number of `Array`, `TypedArray`, `WeakMap`, and `WeakSet` elements + * to include when formatting. Set to `null` or `Infinity` to show all elements. + * Set to `0` or negative to show no elements. + * @default 100 + */ maxArrayLength?: number | null | undefined; /** * Specifies the maximum number of characters to @@ -36,6 +52,12 @@ declare module 'util' { * @default 10000 */ maxStringLength?: number | null | undefined; + /** + * The length at which input values are split across multiple lines. + * Set to `Infinity` to format the input as a single line + * (in combination with `compact` set to `true` or any number >= `1`). + * @default 80 + */ breakLength?: number | undefined; /** * Setting this to `false` causes each object key @@ -45,13 +67,44 @@ declare module 'util' { * `breakLength`. Short array elements are also grouped together. Note that no * text will be reduced below 16 characters, no matter the `breakLength` size. * For more information, see the example below. - * @default `true` + * @default true */ compact?: boolean | number | undefined; + /** + * If set to `true` or a function, all properties of an object, and `Set` and `Map` + * entries are sorted in the resulting string. + * If set to `true` the default sort is used. + * If set to a function, it is used as a compare function. + */ sorted?: boolean | ((a: string, b: string) => number) | undefined; + /** + * If set to `true`, getters are going to be + * inspected as well. If set to `'get'` only getters without setter are going + * to be inspected. If set to `'set'` only getters having a corresponding + * setter are going to be inspected. This might cause side effects depending on + * the getter function. + * @default false + */ + getters?: "get" | "set" | boolean | undefined; + /** + * If set to `true`, an underscore is used to separate every three digits in all bigints and numbers. + * @default false + */ + numericSeparator?: boolean | undefined; } - export type Style = 'special' | 'number' | 'bigint' | 'boolean' | 'undefined' | 'null' | 'string' | 'symbol' | 'date' | 'regexp' | 'module'; - export type CustomInspectFunction = (depth: number, options: InspectOptionsStylized) => string; + export type Style = + | "special" + | "number" + | "bigint" + | "boolean" + | "undefined" + | "null" + | "string" + | "symbol" + | "date" + | "regexp" + | "module"; + export type CustomInspectFunction = (depth: number, options: InspectOptionsStylized) => any; // TODO: , inspect: inspect export interface InspectOptionsStylized extends InspectOptions { stylize(text: string, styleType: Style): string; } @@ -139,7 +192,7 @@ declare module 'util' { * console.error(name); // ENOENT * }); * ``` - * @since v16.0.0 + * @since v16.0.0, v14.17.0 */ export function getSystemErrorMap(): Map; /** @@ -147,7 +200,7 @@ declare module 'util' { * timestamp. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.log('Timestamped message.'); * ``` @@ -159,9 +212,55 @@ declare module 'util' { * Returns the `string` after replacing any surrogate code points * (or equivalently, any unpaired surrogate code units) with the * Unicode "replacement character" U+FFFD. - * @since v16.8.0 + * @since v16.8.0, v14.18.0 */ export function toUSVString(string: string): string; + /** + * Creates and returns an `AbortController` instance whose `AbortSignal` is marked + * as transferable and can be used with `structuredClone()` or `postMessage()`. + * @since v18.11.0 + * @experimental + * @returns A transferable AbortController + */ + export function transferableAbortController(): AbortController; + /** + * Marks the given `AbortSignal` as transferable so that it can be used with`structuredClone()` and `postMessage()`. + * + * ```js + * const signal = transferableAbortSignal(AbortSignal.timeout(100)); + * const channel = new MessageChannel(); + * channel.port2.postMessage(signal, [signal]); + * ``` + * @since v18.11.0 + * @experimental + * @param signal The AbortSignal + * @returns The same AbortSignal + */ + export function transferableAbortSignal(signal: AbortSignal): AbortSignal; + /** + * Listens to abort event on the provided `signal` and + * returns a promise that is fulfilled when the `signal` is + * aborted. If the passed `resource` is garbage collected before the `signal` is + * aborted, the returned promise shall remain pending indefinitely. + * + * ```js + * import { aborted } from 'node:util'; + * + * const dependent = obtainSomethingAbortable(); + * + * aborted(dependent.signal, dependent).then(() => { + * // Do something when dependent is aborted. + * }); + * + * dependent.on('event', () => { + * dependent.abort(); + * }); + * ``` + * @since v19.7.0 + * @experimental + * @param resource Any non-null entity, reference to which is held weakly. + */ + export function aborted(signal: AbortSignal, resource: any): Promise; /** * The `util.inspect()` method returns a string representation of `object` that is * intended for debugging. The output of `util.inspect` may change at any time @@ -188,7 +287,7 @@ declare module 'util' { * Circular references point to their anchor by using a reference index: * * ```js - * const { inspect } = require('util'); + * const { inspect } = require('node:util'); * * const obj = {}; * obj.a = [obj]; @@ -206,7 +305,7 @@ declare module 'util' { * The following example inspects all properties of the `util` object: * * ```js - * const util = require('util'); + * const util = require('node:util'); * * console.log(util.inspect(util, { showHidden: true, depth: null })); * ``` @@ -214,7 +313,7 @@ declare module 'util' { * The following example highlights the effect of the `compact` option: * * ```js - * const util = require('util'); + * const util = require('node:util'); * * const o = { * a: [1, 2, [[ @@ -222,7 +321,7 @@ declare module 'util' { * 'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.', * 'test', * 'foo']], 4], - * b: new Map([['za', 1], ['zb', 'test']]) + * b: new Map([['za', 1], ['zb', 'test']]), * }; * console.log(util.inspect(o, { compact: true, depth: 5, breakLength: 80 })); * @@ -271,7 +370,7 @@ declare module 'util' { * with no remaining strong references may be garbage collected at any time. * * ```js - * const { inspect } = require('util'); + * const { inspect } = require('node:util'); * * const obj = { a: 1 }; * const obj2 = { b: 2 }; @@ -285,13 +384,13 @@ declare module 'util' { * impact the result of `util.inspect()`. * * ```js - * const { inspect } = require('util'); - * const assert = require('assert'); + * const { inspect } = require('node:util'); + * const assert = require('node:assert'); * * const o1 = { * b: [2, 3, 1], * a: '`a` comes before `b`', - * c: new Set([2, 3, 1]) + * c: new Set([2, 3, 1]), * }; * console.log(inspect(o1, { sorted: true })); * // { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } } @@ -301,23 +400,44 @@ declare module 'util' { * const o2 = { * c: new Set([2, 1, 3]), * a: '`a` comes before `b`', - * b: [2, 3, 1] + * b: [2, 3, 1], * }; * assert.strict.equal( * inspect(o1, { sorted: true }), - * inspect(o2, { sorted: true }) + * inspect(o2, { sorted: true }), * ); * ``` * + * The `numericSeparator` option adds an underscore every three digits to all + * numbers. + * + * ```js + * const { inspect } = require('node:util'); + * + * const thousand = 1_000; + * const million = 1_000_000; + * const bigNumber = 123_456_789n; + * const bigDecimal = 1_234.123_45; + * + * console.log(inspect(thousand, { numericSeparator: true })); + * // 1_000 + * console.log(inspect(million, { numericSeparator: true })); + * // 1_000_000 + * console.log(inspect(bigNumber, { numericSeparator: true })); + * // 123_456_789n + * console.log(inspect(bigDecimal, { numericSeparator: true })); + * // 1_234.123_45 + * ``` + * * `util.inspect()` is a synchronous method intended for debugging. Its maximum - * output length is approximately 128 MB. Inputs that result in longer output will + * output length is approximately 128 MiB. Inputs that result in longer output will * be truncated. * @since v0.3.0 * @param object Any JavaScript primitive or `Object`. * @return The representation of `object`. */ export function inspect(object: any, showHidden?: boolean, depth?: number | null, color?: boolean): string; - export function inspect(object: any, options: InspectOptions): string; + export function inspect(object: any, options?: InspectOptions): string; export namespace inspect { let colors: NodeJS.Dict<[number, number]>; let styles: { @@ -339,7 +459,7 @@ declare module 'util' { * Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isArray([]); * // Returns: true @@ -356,7 +476,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `RegExp`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isRegExp(/some regexp/); * // Returns: true @@ -373,7 +493,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Date`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isDate(new Date()); * // Returns: true @@ -390,7 +510,7 @@ declare module 'util' { * Returns `true` if the given `object` is an `Error`. Otherwise, returns`false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isError(new Error()); * // Returns: true @@ -404,7 +524,7 @@ declare module 'util' { * possible to obtain an incorrect result when the `object` argument manipulates`@@toStringTag`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * const obj = { name: 'Error', message: 'an error occurred' }; * * util.isError(obj); @@ -429,8 +549,8 @@ declare module 'util' { * through the `constructor.super_` property. * * ```js - * const util = require('util'); - * const EventEmitter = require('events'); + * const util = require('node:util'); + * const EventEmitter = require('node:events'); * * function MyStream() { * EventEmitter.call(this); @@ -456,7 +576,7 @@ declare module 'util' { * ES6 example using `class` and `extends`: * * ```js - * const EventEmitter = require('events'); + * const EventEmitter = require('node:events'); * * class MyStream extends EventEmitter { * write(data) { @@ -472,7 +592,7 @@ declare module 'util' { * stream.write('With ES6'); * ``` * @since v0.3.0 - * @deprecated Legacy: Use ES2015 class syntax and `extends` keyword instead. + * @legacy Use ES2015 class syntax and `extends` keyword instead. */ export function inherits(constructor: unknown, superConstructor: unknown): void; export type DebugLoggerFunction = (msg: string, ...param: unknown[]) => void; @@ -485,7 +605,7 @@ declare module 'util' { * environment variable, then the returned function operates similar to `console.error()`. If not, then the returned function is a no-op. * * ```js - * const util = require('util'); + * const util = require('node:util'); * const debuglog = util.debuglog('foo'); * * debuglog('hello from foo [%d]', 123); @@ -504,7 +624,7 @@ declare module 'util' { * The `section` supports wildcard also: * * ```js - * const util = require('util'); + * const util = require('node:util'); * const debuglog = util.debuglog('foo-bar'); * * debuglog('hi there, it\'s foo-bar [%d]', 2333); @@ -524,7 +644,7 @@ declare module 'util' { * unnecessary wrapping. * * ```js - * const util = require('util'); + * const util = require('node:util'); * let debuglog = util.debuglog('internals', (debug) => { * // Replace with a logging function that optimizes out * // testing if the section is enabled @@ -542,7 +662,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isBoolean(1); * // Returns: false @@ -559,7 +679,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Buffer`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isBuffer({ length: 0 }); * // Returns: false @@ -576,7 +696,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Function`. Otherwise, returns`false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * function Foo() {} * const Bar = () => {}; @@ -596,7 +716,7 @@ declare module 'util' { * Returns `true` if the given `object` is strictly `null`. Otherwise, returns`false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isNull(0); * // Returns: false @@ -614,7 +734,7 @@ declare module 'util' { * returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isNullOrUndefined(0); * // Returns: false @@ -631,7 +751,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Number`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isNumber(false); * // Returns: false @@ -651,7 +771,7 @@ declare module 'util' { * Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isObject(5); * // Returns: false @@ -663,14 +783,14 @@ declare module 'util' { * // Returns: false * ``` * @since v0.11.5 - * @deprecated Since v4.0.0 - Deprecated: Use `value !== null && typeof value === 'object'` instead. + * @deprecated Since v4.0.0 - Use `value !== null && typeof value === 'object'` instead. */ export function isObject(object: unknown): boolean; /** * Returns `true` if the given `object` is a primitive type. Otherwise, returns`false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isPrimitive(5); * // Returns: true @@ -699,7 +819,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `string`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isString(''); * // Returns: true @@ -718,7 +838,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Symbol`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isSymbol(5); * // Returns: false @@ -735,7 +855,7 @@ declare module 'util' { * Returns `true` if the given `object` is `undefined`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * const foo = undefined; * util.isUndefined(5); @@ -754,7 +874,7 @@ declare module 'util' { * such a way that it is marked as deprecated. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * exports.obsoleteFunction = util.deprecate(() => { * // Do something here. @@ -770,7 +890,7 @@ declare module 'util' { * the warning will be emitted only once for that `code`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001'); * const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001'); @@ -824,7 +944,7 @@ declare module 'util' { * first argument will be the rejection reason (or `null` if the `Promise`resolved), and the second argument will be the resolved value. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * async function fn() { * return 'hello world'; @@ -859,56 +979,99 @@ declare module 'util' { * callbackFunction((err, ret) => { * // When the Promise was rejected with `null` it is wrapped with an Error and * // the original value is stored in `reason`. - * err && err.hasOwnProperty('reason') && err.reason === null; // true + * err && Object.hasOwn(err, 'reason') && err.reason === null; // true * }); * ``` * @since v8.2.0 - * @param original An `async` function + * @param fn An `async` function * @return a callback style function */ export function callbackify(fn: () => Promise): (callback: (err: NodeJS.ErrnoException) => void) => void; - export function callbackify(fn: () => Promise): (callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void; - export function callbackify(fn: (arg1: T1) => Promise): (arg1: T1, callback: (err: NodeJS.ErrnoException) => void) => void; - export function callbackify(fn: (arg1: T1) => Promise): (arg1: T1, callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void; - export function callbackify(fn: (arg1: T1, arg2: T2) => Promise): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException) => void) => void; - export function callbackify(fn: (arg1: T1, arg2: T2) => Promise): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; - export function callbackify(fn: (arg1: T1, arg2: T2, arg3: T3) => Promise): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException) => void) => void; + export function callbackify( + fn: () => Promise, + ): (callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void; + export function callbackify( + fn: (arg1: T1) => Promise, + ): (arg1: T1, callback: (err: NodeJS.ErrnoException) => void) => void; + export function callbackify( + fn: (arg1: T1) => Promise, + ): (arg1: T1, callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void; + export function callbackify( + fn: (arg1: T1, arg2: T2) => Promise, + ): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException) => void) => void; + export function callbackify( + fn: (arg1: T1, arg2: T2) => Promise, + ): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; + export function callbackify( + fn: (arg1: T1, arg2: T2, arg3: T3) => Promise, + ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException) => void) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3) => Promise + fn: (arg1: T1, arg2: T2, arg3: T3) => Promise, ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise, ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: NodeJS.ErrnoException) => void) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise - ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise, + ): ( + arg1: T1, + arg2: T2, + arg3: T3, + arg4: T4, + callback: (err: NodeJS.ErrnoException | null, result: TResult) => void, + ) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise, ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: NodeJS.ErrnoException) => void) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise - ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise, + ): ( + arg1: T1, + arg2: T2, + arg3: T3, + arg4: T4, + arg5: T5, + callback: (err: NodeJS.ErrnoException | null, result: TResult) => void, + ) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise - ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6, callback: (err: NodeJS.ErrnoException) => void) => void; + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise, + ): ( + arg1: T1, + arg2: T2, + arg3: T3, + arg4: T4, + arg5: T5, + arg6: T6, + callback: (err: NodeJS.ErrnoException) => void, + ) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise - ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise, + ): ( + arg1: T1, + arg2: T2, + arg3: T3, + arg4: T4, + arg5: T5, + arg6: T6, + callback: (err: NodeJS.ErrnoException | null, result: TResult) => void, + ) => void; export interface CustomPromisifyLegacy extends Function { __promisify__: TCustom; } export interface CustomPromisifySymbol extends Function { [promisify.custom]: TCustom; } - export type CustomPromisify = CustomPromisifySymbol | CustomPromisifyLegacy; + export type CustomPromisify = + | CustomPromisifySymbol + | CustomPromisifyLegacy; /** * Takes a function following the common error-first callback style, i.e. taking * an `(err, value) => ...` callback as the last argument, and returns a version * that returns promises. * * ```js - * const util = require('util'); - * const fs = require('fs'); + * const util = require('node:util'); + * const fs = require('node:fs'); * * const stat = util.promisify(fs.stat); * stat('.').then((stats) => { @@ -921,8 +1084,8 @@ declare module 'util' { * Or, equivalently using `async function`s: * * ```js - * const util = require('util'); - * const fs = require('fs'); + * const util = require('node:util'); + * const fs = require('node:fs'); * * const stat = util.promisify(fs.stat); * @@ -930,6 +1093,8 @@ declare module 'util' { * const stats = await stat('.'); * console.log(`This directory is owned by ${stats.uid}`); * } + * + * callStat(); * ``` * * If there is an `original[util.promisify.custom]` property present, `promisify`will return its value, see `Custom promisified functions`. @@ -943,7 +1108,7 @@ declare module 'util' { * work as expected unless handled specially: * * ```js - * const util = require('util'); + * const util = require('node:util'); * * class Foo { * constructor() { @@ -969,23 +1134,37 @@ declare module 'util' { * @since v8.0.0 */ export function promisify(fn: CustomPromisify): TCustom; - export function promisify(fn: (callback: (err: any, result: TResult) => void) => void): () => Promise; + export function promisify( + fn: (callback: (err: any, result: TResult) => void) => void, + ): () => Promise; export function promisify(fn: (callback: (err?: any) => void) => void): () => Promise; - export function promisify(fn: (arg1: T1, callback: (err: any, result: TResult) => void) => void): (arg1: T1) => Promise; + export function promisify( + fn: (arg1: T1, callback: (err: any, result: TResult) => void) => void, + ): (arg1: T1) => Promise; export function promisify(fn: (arg1: T1, callback: (err?: any) => void) => void): (arg1: T1) => Promise; - export function promisify(fn: (arg1: T1, arg2: T2, callback: (err: any, result: TResult) => void) => void): (arg1: T1, arg2: T2) => Promise; - export function promisify(fn: (arg1: T1, arg2: T2, callback: (err?: any) => void) => void): (arg1: T1, arg2: T2) => Promise; - export function promisify(fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err: any, result: TResult) => void) => void): (arg1: T1, arg2: T2, arg3: T3) => Promise; - export function promisify(fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err?: any) => void) => void): (arg1: T1, arg2: T2, arg3: T3) => Promise; + export function promisify( + fn: (arg1: T1, arg2: T2, callback: (err: any, result: TResult) => void) => void, + ): (arg1: T1, arg2: T2) => Promise; + export function promisify( + fn: (arg1: T1, arg2: T2, callback: (err?: any) => void) => void, + ): (arg1: T1, arg2: T2) => Promise; + export function promisify( + fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err: any, result: TResult) => void) => void, + ): (arg1: T1, arg2: T2, arg3: T3) => Promise; + export function promisify( + fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err?: any) => void) => void, + ): (arg1: T1, arg2: T2, arg3: T3) => Promise; export function promisify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: any, result: TResult) => void) => void + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: any, result: TResult) => void) => void, ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise; - export function promisify(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err?: any) => void) => void): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise; + export function promisify( + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err?: any) => void) => void, + ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise; export function promisify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: any, result: TResult) => void) => void + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: any, result: TResult) => void) => void, ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise; export function promisify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err?: any) => void) => void + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err?: any) => void) => void, ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise; export function promisify(fn: Function): Function; export namespace promisify { @@ -998,13 +1177,9 @@ declare module 'util' { * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextDecoder` API. * * ```js - * const decoder = new TextDecoder('shift_jis'); - * let string = ''; - * let buffer; - * while (buffer = getNextChunkSomehow()) { - * string += decoder.decode(buffer, { stream: true }); - * } - * string += decoder.decode(); // end-of-stream + * const decoder = new TextDecoder(); + * const u8arr = new Uint8Array([72, 101, 108, 108, 111]); + * console.log(decoder.decode(u8arr)); // Hello * ``` * @since v8.3.0 */ @@ -1028,7 +1203,7 @@ declare module 'util' { options?: { fatal?: boolean | undefined; ignoreBOM?: boolean | undefined; - } + }, ); /** * Decodes the `input` and returns a string. If `options.stream` is `true`, any @@ -1036,13 +1211,13 @@ declare module 'util' { * internally and emitted after the next call to `textDecoder.decode()`. * * If `textDecoder.fatal` is `true`, decoding errors that occur will result in a`TypeError` being thrown. - * @param input An `ArrayBuffer`, `DataView` or `TypedArray` instance containing the encoded data. + * @param input An `ArrayBuffer`, `DataView`, or `TypedArray` instance containing the encoded data. */ decode( input?: NodeJS.ArrayBufferView | ArrayBuffer | null, options?: { stream?: boolean | undefined; - } + }, ): string; } export interface EncodeIntoResult { @@ -1056,6 +1231,8 @@ declare module 'util' { written: number; } export { types }; + + //// TextEncoder/Decoder /** * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextEncoder` API. All * instances of `TextEncoder` only support UTF-8 encoding. @@ -1094,12 +1271,391 @@ declare module 'util' { */ encodeInto(src: string, dest: Uint8Array): EncodeIntoResult; } + import { TextDecoder as _TextDecoder, TextEncoder as _TextEncoder } from "util"; + global { + /** + * `TextDecoder` class is a global reference for `require('util').TextDecoder` + * https://nodejs.org/api/globals.html#textdecoder + * @since v11.0.0 + */ + var TextDecoder: typeof globalThis extends { + onmessage: any; + TextDecoder: infer TextDecoder; + } ? TextDecoder + : typeof _TextDecoder; + /** + * `TextEncoder` class is a global reference for `require('util').TextEncoder` + * https://nodejs.org/api/globals.html#textencoder + * @since v11.0.0 + */ + var TextEncoder: typeof globalThis extends { + onmessage: any; + TextEncoder: infer TextEncoder; + } ? TextEncoder + : typeof _TextEncoder; + } + + //// parseArgs + /** + * Provides a higher level API for command-line argument parsing than interacting + * with `process.argv` directly. Takes a specification for the expected arguments + * and returns a structured object with the parsed options and positionals. + * + * ```js + * import { parseArgs } from 'node:util'; + * const args = ['-f', '--bar', 'b']; + * const options = { + * foo: { + * type: 'boolean', + * short: 'f', + * }, + * bar: { + * type: 'string', + * }, + * }; + * const { + * values, + * positionals, + * } = parseArgs({ args, options }); + * console.log(values, positionals); + * // Prints: [Object: null prototype] { foo: true, bar: 'b' } [] + * ``` + * @since v18.3.0, v16.17.0 + * @param config Used to provide arguments for parsing and to configure the parser. `config` supports the following properties: + * @return The parsed command line arguments: + */ + export function parseArgs(config?: T): ParsedResults; + interface ParseArgsOptionConfig { + /** + * Type of argument. + */ + type: "string" | "boolean"; + /** + * Whether this option can be provided multiple times. + * If `true`, all values will be collected in an array. + * If `false`, values for the option are last-wins. + * @default false. + */ + multiple?: boolean | undefined; + /** + * A single character alias for the option. + */ + short?: string | undefined; + /** + * The default option value when it is not set by args. + * It must be of the same type as the the `type` property. + * When `multiple` is `true`, it must be an array. + * @since v18.11.0 + */ + default?: string | boolean | string[] | boolean[] | undefined; + } + interface ParseArgsOptionsConfig { + [longOption: string]: ParseArgsOptionConfig; + } + export interface ParseArgsConfig { + /** + * Array of argument strings. + */ + args?: string[] | undefined; + /** + * Used to describe arguments known to the parser. + */ + options?: ParseArgsOptionsConfig | undefined; + /** + * Should an error be thrown when unknown arguments are encountered, + * or when arguments are passed that do not match the `type` configured in `options`. + * @default true + */ + strict?: boolean | undefined; + /** + * Whether this command accepts positional arguments. + */ + allowPositionals?: boolean | undefined; + /** + * Return the parsed tokens. This is useful for extending the built-in behavior, + * from adding additional checks through to reprocessing the tokens in different ways. + * @default false + */ + tokens?: boolean | undefined; + } + /* + IfDefaultsTrue and IfDefaultsFalse are helpers to handle default values for missing boolean properties. + TypeScript does not have exact types for objects: https://github.com/microsoft/TypeScript/issues/12936 + This means it is impossible to distinguish between "field X is definitely not present" and "field X may or may not be present". + But we expect users to generally provide their config inline or `as const`, which means TS will always know whether a given field is present. + So this helper treats "not definitely present" (i.e., not `extends boolean`) as being "definitely not present", i.e. it should have its default value. + This is technically incorrect but is a much nicer UX for the common case. + The IfDefaultsTrue version is for things which default to true; the IfDefaultsFalse version is for things which default to false. + */ + type IfDefaultsTrue = T extends true ? IfTrue + : T extends false ? IfFalse + : IfTrue; + + // we put the `extends false` condition first here because `undefined` compares like `any` when `strictNullChecks: false` + type IfDefaultsFalse = T extends false ? IfFalse + : T extends true ? IfTrue + : IfFalse; + + type ExtractOptionValue = IfDefaultsTrue< + T["strict"], + O["type"] extends "string" ? string : O["type"] extends "boolean" ? boolean : string | boolean, + string | boolean + >; + + type ParsedValues = + & IfDefaultsTrue + & (T["options"] extends ParseArgsOptionsConfig ? { + -readonly [LongOption in keyof T["options"]]: IfDefaultsFalse< + T["options"][LongOption]["multiple"], + undefined | Array>, + undefined | ExtractOptionValue + >; + } + : {}); + + type ParsedPositionals = IfDefaultsTrue< + T["strict"], + IfDefaultsFalse, + IfDefaultsTrue + >; + + type PreciseTokenForOptions< + K extends string, + O extends ParseArgsOptionConfig, + > = O["type"] extends "string" ? { + kind: "option"; + index: number; + name: K; + rawName: string; + value: string; + inlineValue: boolean; + } + : O["type"] extends "boolean" ? { + kind: "option"; + index: number; + name: K; + rawName: string; + value: undefined; + inlineValue: undefined; + } + : OptionToken & { name: K }; + + type TokenForOptions< + T extends ParseArgsConfig, + K extends keyof T["options"] = keyof T["options"], + > = K extends unknown + ? T["options"] extends ParseArgsOptionsConfig ? PreciseTokenForOptions + : OptionToken + : never; + + type ParsedOptionToken = IfDefaultsTrue, OptionToken>; + + type ParsedPositionalToken = IfDefaultsTrue< + T["strict"], + IfDefaultsFalse, + IfDefaultsTrue + >; + + type ParsedTokens = Array< + ParsedOptionToken | ParsedPositionalToken | { kind: "option-terminator"; index: number } + >; + + type PreciseParsedResults = IfDefaultsFalse< + T["tokens"], + { + values: ParsedValues; + positionals: ParsedPositionals; + tokens: ParsedTokens; + }, + { + values: ParsedValues; + positionals: ParsedPositionals; + } + >; + + type OptionToken = + | { kind: "option"; index: number; name: string; rawName: string; value: string; inlineValue: boolean } + | { + kind: "option"; + index: number; + name: string; + rawName: string; + value: undefined; + inlineValue: undefined; + }; + + type Token = + | OptionToken + | { kind: "positional"; index: number; value: string } + | { kind: "option-terminator"; index: number }; + + // If ParseArgsConfig extends T, then the user passed config constructed elsewhere. + // So we can't rely on the `"not definitely present" implies "definitely not present"` assumption mentioned above. + type ParsedResults = ParseArgsConfig extends T ? { + values: { + [longOption: string]: undefined | string | boolean | Array; + }; + positionals: string[]; + tokens?: Token[]; + } + : PreciseParsedResults; + + /** + * An implementation of [the MIMEType class](https://bmeck.github.io/node-proposal-mime-api/). + * + * In accordance with browser conventions, all properties of `MIMEType` objects + * are implemented as getters and setters on the class prototype, rather than as + * data properties on the object itself. + * + * A MIME string is a structured string containing multiple meaningful + * components. When parsed, a `MIMEType` object is returned containing + * properties for each of these components. + * @since v19.1.0, v18.13.0 + * @experimental + */ + export class MIMEType { + /** + * Creates a new MIMEType object by parsing the input. + * + * A `TypeError` will be thrown if the `input` is not a valid MIME. + * Note that an effort will be made to coerce the given values into strings. + * @param input The input MIME to parse. + */ + constructor(input: string | { toString: () => string }); + + /** + * Gets and sets the type portion of the MIME. + * + * ```js + * import { MIMEType } from 'node:util'; + * + * const myMIME = new MIMEType('text/javascript'); + * console.log(myMIME.type); + * // Prints: text + * myMIME.type = 'application'; + * console.log(myMIME.type); + * // Prints: application + * console.log(String(myMIME)); + * // Prints: application/javascript + * ``` + */ + type: string; + /** + * Gets and sets the subtype portion of the MIME. + * + * ```js + * import { MIMEType } from 'node:util'; + * + * const myMIME = new MIMEType('text/ecmascript'); + * console.log(myMIME.subtype); + * // Prints: ecmascript + * myMIME.subtype = 'javascript'; + * console.log(myMIME.subtype); + * // Prints: javascript + * console.log(String(myMIME)); + * // Prints: text/javascript + * ``` + */ + subtype: string; + /** + * Gets the essence of the MIME. This property is read only. + * Use `mime.type` or `mime.subtype` to alter the MIME. + * + * ```js + * import { MIMEType } from 'node:util'; + * + * const myMIME = new MIMEType('text/javascript;key=value'); + * console.log(myMIME.essence); + * // Prints: text/javascript + * myMIME.type = 'application'; + * console.log(myMIME.essence); + * // Prints: application/javascript + * console.log(String(myMIME)); + * // Prints: application/javascript;key=value + * ``` + */ + readonly essence: string; + /** + * Gets the `MIMEParams` object representing the + * parameters of the MIME. This property is read-only. See `MIMEParams` documentation for details. + */ + readonly params: MIMEParams; + /** + * The `toString()` method on the `MIMEType` object returns the serialized MIME. + * + * Because of the need for standard compliance, this method does not allow users + * to customize the serialization process of the MIME. + */ + toString(): string; + } + /** + * The `MIMEParams` API provides read and write access to the parameters of a`MIMEType`. + * @since v19.1.0, v18.13.0 + */ + export class MIMEParams { + /** + * Remove all name-value pairs whose name is `name`. + */ + delete(name: string): void; + /** + * Returns an iterator over each of the name-value pairs in the parameters. + * Each item of the iterator is a JavaScript `Array`. The first item of the array + * is the `name`, the second item of the array is the `value`. + */ + entries(): IterableIterator<[string, string]>; + /** + * Returns the value of the first name-value pair whose name is `name`. If there + * are no such pairs, `null` is returned. + * @return or `null` if there is no name-value pair with the given `name`. + */ + get(name: string): string | null; + /** + * Returns `true` if there is at least one name-value pair whose name is `name`. + */ + has(name: string): boolean; + /** + * Returns an iterator over the names of each name-value pair. + * + * ```js + * import { MIMEType } from 'node:util'; + * + * const { params } = new MIMEType('text/plain;foo=0;bar=1'); + * for (const name of params.keys()) { + * console.log(name); + * } + * // Prints: + * // foo + * // bar + * ``` + */ + keys(): IterableIterator; + /** + * Sets the value in the `MIMEParams` object associated with `name` to`value`. If there are any pre-existing name-value pairs whose names are `name`, + * set the first such pair's value to `value`. + * + * ```js + * import { MIMEType } from 'node:util'; + * + * const { params } = new MIMEType('text/plain;foo=0;bar=1'); + * params.set('foo', 'def'); + * params.set('baz', 'xyz'); + * console.log(params.toString()); + * // Prints: foo=def;bar=1;baz=xyz + * ``` + */ + set(name: string, value: string): void; + /** + * Returns an iterator over the values of each name-value pair. + */ + values(): IterableIterator; + /** + * Returns an iterator over each of the name-value pairs in the parameters. + */ + [Symbol.iterator]: typeof MIMEParams.prototype.entries; + } } -declare module 'util/types' { - export * from 'util/types'; -} -declare module 'util/types' { - import { KeyObject, webcrypto } from 'node:crypto'; +declare module "util/types" { + import { KeyObject, webcrypto } from "node:crypto"; /** * Returns `true` if the value is a built-in [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) or * [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) instance. @@ -1365,7 +1921,10 @@ declare module 'util/types' { * ``` * @since v10.0.0 */ - function isMap(object: T | {}): object is T extends ReadonlyMap ? (unknown extends T ? never : ReadonlyMap) : Map; + function isMap( + object: T | {}, + ): object is T extends ReadonlyMap ? (unknown extends T ? never : ReadonlyMap) + : Map; /** * Returns `true` if the value is an iterator returned for a built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) instance. * @@ -1391,12 +1950,40 @@ declare module 'util/types' { */ function isModuleNamespaceObject(value: unknown): boolean; /** - * Returns `true` if the value is an instance of a built-in `Error` type. + * Returns `true` if the value was returned by the constructor of a [built-in `Error` type](https://tc39.es/ecma262/#sec-error-objects). * * ```js - * util.types.isNativeError(new Error()); // Returns true - * util.types.isNativeError(new TypeError()); // Returns true - * util.types.isNativeError(new RangeError()); // Returns true + * console.log(util.types.isNativeError(new Error())); // true + * console.log(util.types.isNativeError(new TypeError())); // true + * console.log(util.types.isNativeError(new RangeError())); // true + * ``` + * + * Subclasses of the native error types are also native errors: + * + * ```js + * class MyError extends Error {} + * console.log(util.types.isNativeError(new MyError())); // true + * ``` + * + * A value being `instanceof` a native error class is not equivalent to `isNativeError()`returning `true` for that value. `isNativeError()` returns `true` for errors + * which come from a different [realm](https://tc39.es/ecma262/#realm) while `instanceof Error` returns `false`for these errors: + * + * ```js + * const vm = require('node:vm'); + * const context = vm.createContext({}); + * const myError = vm.runInContext('new Error()', context); + * console.log(util.types.isNativeError(myError)); // true + * console.log(myError instanceof Error); // false + * ``` + * + * Conversely, `isNativeError()` returns `false` for all objects which were not + * returned by the constructor of a native error. That includes values + * which are `instanceof` native errors: + * + * ```js + * const myError = { __proto__: Error.prototype }; + * console.log(util.types.isNativeError(myError)); // false + * console.log(myError instanceof Error); // true * ``` * @since v10.0.0 */ @@ -1451,7 +2038,9 @@ declare module 'util/types' { * ``` * @since v10.0.0 */ - function isSet(object: T | {}): object is T extends ReadonlySet ? (unknown extends T ? never : ReadonlySet) : Set; + function isSet( + object: T | {}, + ): object is T extends ReadonlySet ? (unknown extends T ? never : ReadonlySet) : Set; /** * Returns `true` if the value is an iterator returned for a built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) instance. * @@ -1586,9 +2175,9 @@ declare module 'util/types' { */ function isCryptoKey(object: unknown): object is webcrypto.CryptoKey; } -declare module 'node:util' { - export * from 'util'; +declare module "node:util" { + export * from "util"; } -declare module 'node:util/types' { - export * from 'util/types'; +declare module "node:util/types" { + export * from "util/types"; } diff --git a/node_modules/@types/node/ts4.8/v8.d.ts b/node_modules/@types/node/ts4.8/v8.d.ts old mode 100755 new mode 100644 index f467fcc..6790e76 --- a/node_modules/@types/node/ts4.8/v8.d.ts +++ b/node_modules/@types/node/ts4.8/v8.d.ts @@ -1,13 +1,13 @@ /** - * The `v8` module exposes APIs that are specific to the version of [V8](https://developers.google.com/v8/) built into the Node.js binary. It can be accessed using: + * The `node:v8` module exposes APIs that are specific to the version of [V8](https://developers.google.com/v8/) built into the Node.js binary. It can be accessed using: * * ```js - * const v8 = require('v8'); + * const v8 = require('node:v8'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/v8.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/v8.js) */ -declare module 'v8' { - import { Readable } from 'node:stream'; +declare module "v8" { + import { Readable } from "node:stream"; interface HeapSpaceInfo { space_name: string; space_size: number; @@ -29,6 +29,9 @@ declare module 'v8' { does_zap_garbage: DoesZapCodeSpaceFlag; number_of_native_contexts: number; number_of_detached_contexts: number; + total_global_handles_size: number; + used_global_handles_size: number; + external_memory: number; } interface HeapCodeStatistics { code_and_metadata_size: number; @@ -68,6 +71,15 @@ declare module 'v8' { * of contexts that were detached and not yet garbage collected. This number * being non-zero indicates a potential memory leak. * + * `total_global_handles_size` The value of total\_global\_handles\_size is the + * total memory size of V8 global handles. + * + * `used_global_handles_size` The value of used\_global\_handles\_size is the + * used memory size of V8 global handles. + * + * `external_memory` The value of external\_memory is the memory size of array + * buffers and external strings. + * * ```js * { * total_heap_size: 7326976, @@ -80,7 +92,10 @@ declare module 'v8' { * peak_malloced_memory: 1127496, * does_zap_garbage: 0, * number_of_native_contexts: 1, - * number_of_detached_contexts: 0 + * number_of_detached_contexts: 0, + * total_global_handles_size: 8192, + * used_global_handles_size: 3296, + * external_memory: 318824 * } * ``` * @since v1.0.0 @@ -149,7 +164,7 @@ declare module 'v8' { * * ```js * // Print GC events to stdout for one minute. - * const v8 = require('v8'); + * const v8 = require('node:v8'); * v8.setFlagsFromString('--trace_gc'); * setTimeout(() => { v8.setFlagsFromString('--notrace_gc'); }, 60e3); * ``` @@ -163,14 +178,21 @@ declare module 'v8' { * Chrome DevTools. The JSON schema is undocumented and specific to the * V8 engine. Therefore, the schema may change from one version of V8 to the next. * + * Creating a heap snapshot requires memory about twice the size of the heap at + * the time the snapshot is created. This results in the risk of OOM killers + * terminating the process. + * + * Generating a snapshot is a synchronous operation which blocks the event loop + * for a duration depending on the heap size. + * * ```js * // Print heap snapshot to the console - * const v8 = require('v8'); + * const v8 = require('node:v8'); * const stream = v8.getHeapSnapshot(); * stream.pipe(process.stdout); * ``` * @since v11.13.0 - * @return A Readable Stream containing the V8 heap snapshot + * @return A Readable containing the V8 heap snapshot. */ function getHeapSnapshot(): Readable; /** @@ -182,13 +204,20 @@ declare module 'v8' { * A heap snapshot is specific to a single V8 isolate. When using `worker threads`, a heap snapshot generated from the main thread will * not contain any information about the workers, and vice versa. * + * Creating a heap snapshot requires memory about twice the size of the heap at + * the time the snapshot is created. This results in the risk of OOM killers + * terminating the process. + * + * Generating a snapshot is a synchronous operation which blocks the event loop + * for a duration depending on the heap size. + * * ```js - * const { writeHeapSnapshot } = require('v8'); + * const { writeHeapSnapshot } = require('node:v8'); * const { * Worker, * isMainThread, - * parentPort - * } = require('worker_threads'); + * parentPort, + * } = require('node:worker_threads'); * * if (isMainThread) { * const worker = new Worker(__filename); @@ -219,13 +248,16 @@ declare module 'v8' { */ function writeHeapSnapshot(filename?: string): string; /** - * Returns an object with the following properties: + * Get statistics about code and its metadata in the heap, see + * V8[`GetHeapCodeAndMetadataStatistics`](https://v8docs.nodesource.com/node-13.2/d5/dda/classv8_1_1_isolate.html#a6079122af17612ef54ef3348ce170866) API. Returns an object with the + * following properties: * * ```js * { * code_and_metadata_size: 212208, * bytecode_and_metadata_size: 161368, - * external_script_source_size: 1410794 + * external_script_source_size: 1410794, + * cpu_profiler_metadata_size: 0, * } * ``` * @since v12.8.0 @@ -275,7 +307,7 @@ declare module 'v8' { */ writeDouble(value: number): void; /** - * Write raw bytes into the serializer’s internal buffer. The deserializer + * Write raw bytes into the serializer's internal buffer. The deserializer * will require a way to compute the length of the buffer. * For use inside of a custom `serializer._writeHostObject()`. */ @@ -331,7 +363,7 @@ declare module 'v8' { */ readDouble(): number; /** - * Read raw bytes from the deserializer’s internal buffer. The `length` parameter + * Read raw bytes from the deserializer's internal buffer. The `length` parameter * must correspond to the length of the buffer that was passed to `serializer.writeRawBytes()`. * For use inside of a custom `deserializer._readHostObject()`. */ @@ -344,6 +376,10 @@ declare module 'v8' { class DefaultDeserializer extends Deserializer {} /** * Uses a `DefaultSerializer` to serialize `value` into a buffer. + * + * `ERR_BUFFER_TOO_LARGE` will be thrown when trying to + * serialize a huge object which requires buffer + * larger than `buffer.constants.MAX_LENGTH`. * @since v8.0.0 */ function serialize(value: any): Buffer; @@ -362,17 +398,238 @@ declare module 'v8' { * * When the process is about to exit, one last coverage will still be written to * disk unless {@link stopCoverage} is invoked before the process exits. - * @since v15.1.0, v12.22.0 + * @since v15.1.0, v14.18.0, v12.22.0 */ function takeCoverage(): void; /** * The `v8.stopCoverage()` method allows the user to stop the coverage collection * started by `NODE_V8_COVERAGE`, so that V8 can release the execution count * records and optimize code. This can be used in conjunction with {@link takeCoverage} if the user wants to collect the coverage on demand. - * @since v15.1.0, v12.22.0 + * @since v15.1.0, v14.18.0, v12.22.0 */ function stopCoverage(): void; + /** + * This API collects GC data in current thread. + * @since v19.6.0, v18.15.0 + */ + class GCProfiler { + /** + * Start collecting GC data. + * @since v19.6.0, v18.15.0 + */ + start(): void; + /** + * Stop collecting GC data and return an object.The content of object + * is as follows. + * + * ```json + * { + * "version": 1, + * "startTime": 1674059033862, + * "statistics": [ + * { + * "gcType": "Scavenge", + * "beforeGC": { + * "heapStatistics": { + * "totalHeapSize": 5005312, + * "totalHeapSizeExecutable": 524288, + * "totalPhysicalSize": 5226496, + * "totalAvailableSize": 4341325216, + * "totalGlobalHandlesSize": 8192, + * "usedGlobalHandlesSize": 2112, + * "usedHeapSize": 4883840, + * "heapSizeLimit": 4345298944, + * "mallocedMemory": 254128, + * "externalMemory": 225138, + * "peakMallocedMemory": 181760 + * }, + * "heapSpaceStatistics": [ + * { + * "spaceName": "read_only_space", + * "spaceSize": 0, + * "spaceUsedSize": 0, + * "spaceAvailableSize": 0, + * "physicalSpaceSize": 0 + * } + * ] + * }, + * "cost": 1574.14, + * "afterGC": { + * "heapStatistics": { + * "totalHeapSize": 6053888, + * "totalHeapSizeExecutable": 524288, + * "totalPhysicalSize": 5500928, + * "totalAvailableSize": 4341101384, + * "totalGlobalHandlesSize": 8192, + * "usedGlobalHandlesSize": 2112, + * "usedHeapSize": 4059096, + * "heapSizeLimit": 4345298944, + * "mallocedMemory": 254128, + * "externalMemory": 225138, + * "peakMallocedMemory": 181760 + * }, + * "heapSpaceStatistics": [ + * { + * "spaceName": "read_only_space", + * "spaceSize": 0, + * "spaceUsedSize": 0, + * "spaceAvailableSize": 0, + * "physicalSpaceSize": 0 + * } + * ] + * } + * } + * ], + * "endTime": 1674059036865 + * } + * ``` + * + * Here's an example. + * + * ```js + * const { GCProfiler } = require('v8'); + * const profiler = new GCProfiler(); + * profiler.start(); + * setTimeout(() => { + * console.log(profiler.stop()); + * }, 1000); + * ``` + * @since v19.6.0, v18.15.0 + */ + stop(): GCProfilerResult; + } + interface GCProfilerResult { + version: number; + startTime: number; + endTime: number; + statistics: Array<{ + gcType: string; + cost: number; + beforeGC: { + heapStatistics: HeapStatistics; + heapSpaceStatistics: HeapSpaceStatistics[]; + }; + afterGC: { + heapStatistics: HeapStatistics; + heapSpaceStatistics: HeapSpaceStatistics[]; + }; + }>; + } + interface HeapStatistics { + totalHeapSize: number; + totalHeapSizeExecutable: number; + totalPhysicalSize: number; + totalAvailableSize: number; + totalGlobalHandlesSize: number; + usedGlobalHandlesSize: number; + usedHeapSize: number; + heapSizeLimit: number; + mallocedMemory: number; + externalMemory: number; + peakMallocedMemory: number; + } + interface HeapSpaceStatistics { + spaceName: string; + spaceSize: number; + spaceUsedSize: number; + spaceAvailableSize: number; + physicalSpaceSize: number; + } + /** + * Called when a promise is constructed. This does not mean that corresponding before/after events will occur, only that the possibility exists. This will + * happen if a promise is created without ever getting a continuation. + * @since v17.1.0, v16.14.0 + * @param promise The promise being created. + * @param parent The promise continued from, if applicable. + */ + interface Init { + (promise: Promise, parent: Promise): void; + } + /** + * Called before a promise continuation executes. This can be in the form of `then()`, `catch()`, or `finally()` handlers or an await resuming. + * + * The before callback will be called 0 to N times. The before callback will typically be called 0 times if no continuation was ever made for the promise. + * The before callback may be called many times in the case where many continuations have been made from the same promise. + * @since v17.1.0, v16.14.0 + */ + interface Before { + (promise: Promise): void; + } + /** + * Called immediately after a promise continuation executes. This may be after a `then()`, `catch()`, or `finally()` handler or before an await after another await. + * @since v17.1.0, v16.14.0 + */ + interface After { + (promise: Promise): void; + } + /** + * Called when the promise receives a resolution or rejection value. This may occur synchronously in the case of {@link Promise.resolve()} or + * {@link Promise.reject()}. + * @since v17.1.0, v16.14.0 + */ + interface Settled { + (promise: Promise): void; + } + /** + * Key events in the lifetime of a promise have been categorized into four areas: creation of a promise, before/after a continuation handler is called or + * around an await, and when the promise resolves or rejects. + * + * Because promises are asynchronous resources whose lifecycle is tracked via the promise hooks mechanism, the `init()`, `before()`, `after()`, and + * `settled()` callbacks must not be async functions as they create more promises which would produce an infinite loop. + * @since v17.1.0, v16.14.0 + */ + interface HookCallbacks { + init?: Init; + before?: Before; + after?: After; + settled?: Settled; + } + interface PromiseHooks { + /** + * The `init` hook must be a plain function. Providing an async function will throw as it would produce an infinite microtask loop. + * @since v17.1.0, v16.14.0 + * @param init The {@link Init | `init` callback} to call when a promise is created. + * @return Call to stop the hook. + */ + onInit: (init: Init) => Function; + /** + * The `settled` hook must be a plain function. Providing an async function will throw as it would produce an infinite microtask loop. + * @since v17.1.0, v16.14.0 + * @param settled The {@link Settled | `settled` callback} to call when a promise is created. + * @return Call to stop the hook. + */ + onSettled: (settled: Settled) => Function; + /** + * The `before` hook must be a plain function. Providing an async function will throw as it would produce an infinite microtask loop. + * @since v17.1.0, v16.14.0 + * @param before The {@link Before | `before` callback} to call before a promise continuation executes. + * @return Call to stop the hook. + */ + onBefore: (before: Before) => Function; + /** + * The `after` hook must be a plain function. Providing an async function will throw as it would produce an infinite microtask loop. + * @since v17.1.0, v16.14.0 + * @param after The {@link After | `after` callback} to call after a promise continuation executes. + * @return Call to stop the hook. + */ + onAfter: (after: After) => Function; + /** + * Registers functions to be called for different lifetime events of each promise. + * The callbacks `init()`/`before()`/`after()`/`settled()` are called for the respective events during a promise's lifetime. + * All callbacks are optional. For example, if only promise creation needs to be tracked, then only the init callback needs to be passed. + * The hook callbacks must be plain functions. Providing async functions will throw as it would produce an infinite microtask loop. + * @since v17.1.0, v16.14.0 + * @param callbacks The {@link HookCallbacks | Hook Callbacks} to register + * @return Used for disabling hooks + */ + createHook: (callbacks: HookCallbacks) => Function; + } + /** + * The `promiseHooks` interface can be used to track promise lifecycle events. + * @since v17.1.0, v16.14.0 + */ + const promiseHooks: PromiseHooks; } -declare module 'node:v8' { - export * from 'v8'; +declare module "node:v8" { + export * from "v8"; } diff --git a/node_modules/@types/node/ts4.8/vm.d.ts b/node_modules/@types/node/ts4.8/vm.d.ts old mode 100755 new mode 100644 index a46b391..3a310cc --- a/node_modules/@types/node/ts4.8/vm.d.ts +++ b/node_modules/@types/node/ts4.8/vm.d.ts @@ -1,7 +1,9 @@ /** - * The `vm` module enables compiling and running code within V8 Virtual - * Machine contexts. **The `vm` module is not a security mechanism. Do** - * **not use it to run untrusted code.** + * The `node:vm` module enables compiling and running code within V8 Virtual + * Machine contexts. + * + * **The `node:vm` module is not a security** + * **mechanism. Do not use it to run untrusted code.** * * JavaScript code can be compiled and run immediately or * compiled, saved, and run later. @@ -15,7 +17,7 @@ * code are reflected in the context object. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * const x = 1; * @@ -32,9 +34,10 @@ * * console.log(x); // 1; y is not defined. * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/vm.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/vm.js) */ -declare module 'vm' { +declare module "vm" { + import { ImportAttributes } from "node:module"; interface Context extends NodeJS.Dict {} interface BaseOptions { /** @@ -54,11 +57,19 @@ declare module 'vm' { columnOffset?: number | undefined; } interface ScriptOptions extends BaseOptions { - displayErrors?: boolean | undefined; - timeout?: number | undefined; - cachedData?: Buffer | undefined; + /** + * V8's code cache data for the supplied source. + */ + cachedData?: Buffer | NodeJS.ArrayBufferView | undefined; /** @deprecated in favor of `script.createCachedData()` */ produceCachedData?: boolean | undefined; + /** + * Called during evaluation of this module when `import()` is called. + * If this option is not specified, calls to `import()` will reject with `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`. + */ + importModuleDynamically?: + | ((specifier: string, script: Script, importAttributes: ImportAttributes) => Module) + | undefined; } interface RunningScriptOptions extends BaseOptions { /** @@ -78,10 +89,31 @@ declare module 'vm' { * Default: `false`. */ breakOnSigint?: boolean | undefined; + } + interface RunningScriptInNewContextOptions extends RunningScriptOptions { + /** + * Human-readable name of the newly created context. + */ + contextName?: CreateContextOptions["name"]; + /** + * Origin corresponding to the newly created context for display purposes. The origin should be formatted like a URL, + * but with only the scheme, host, and port (if necessary), like the value of the `url.origin` property of a `URL` object. + * Most notably, this string should omit the trailing slash, as that denotes a path. + */ + contextOrigin?: CreateContextOptions["origin"]; + contextCodeGeneration?: CreateContextOptions["codeGeneration"]; /** * If set to `afterEvaluate`, microtasks will be run immediately after the script has run. */ - microtaskMode?: 'afterEvaluate' | undefined; + microtaskMode?: CreateContextOptions["microtaskMode"]; + } + interface RunningCodeOptions extends RunningScriptOptions { + cachedData?: ScriptOptions["cachedData"]; + importModuleDynamically?: ScriptOptions["importModuleDynamically"]; + } + interface RunningCodeInNewContextOptions extends RunningScriptInNewContextOptions { + cachedData?: ScriptOptions["cachedData"]; + importModuleDynamically?: ScriptOptions["importModuleDynamically"]; } interface CompileFunctionOptions extends BaseOptions { /** @@ -118,31 +150,34 @@ declare module 'vm' { origin?: string | undefined; codeGeneration?: | { - /** - * If set to false any calls to eval or function constructors (Function, GeneratorFunction, etc) - * will throw an EvalError. - * @default true - */ - strings?: boolean | undefined; - /** - * If set to false any attempt to compile a WebAssembly module will throw a WebAssembly.CompileError. - * @default true - */ - wasm?: boolean | undefined; - } + /** + * If set to false any calls to eval or function constructors (Function, GeneratorFunction, etc) + * will throw an EvalError. + * @default true + */ + strings?: boolean | undefined; + /** + * If set to false any attempt to compile a WebAssembly module will throw a WebAssembly.CompileError. + * @default true + */ + wasm?: boolean | undefined; + } | undefined; /** * If set to `afterEvaluate`, microtasks will be run immediately after the script has run. */ - microtaskMode?: 'afterEvaluate' | undefined; + microtaskMode?: "afterEvaluate" | undefined; } - type MeasureMemoryMode = 'summary' | 'detailed'; + type MeasureMemoryMode = "summary" | "detailed"; interface MeasureMemoryOptions { /** * @default 'summary' */ mode?: MeasureMemoryMode | undefined; - context?: Context | undefined; + /** + * @default 'default' + */ + execution?: "default" | "eager" | undefined; } interface MemoryMeasurement { total: { @@ -156,7 +191,7 @@ declare module 'vm' { * @since v0.3.1 */ class Script { - constructor(code: string, options?: ScriptOptions); + constructor(code: string, options?: ScriptOptions | string); /** * Runs the compiled code contained by the `vm.Script` object within the given`contextifiedObject` and returns the result. Running code does not have access * to local scope. @@ -166,11 +201,11 @@ declare module 'vm' { * The globals are contained in the `context` object. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * const context = { * animal: 'cat', - * count: 2 + * count: 2, * }; * * const script = new vm.Script('count += 1; name = "kitty";'); @@ -202,7 +237,7 @@ declare module 'vm' { * contained within each individual `context`. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * const script = new vm.Script('globalVar = "set"'); * @@ -218,16 +253,16 @@ declare module 'vm' { * @param contextObject An object that will be `contextified`. If `undefined`, a new object will be created. * @return the result of the very last statement executed in the script. */ - runInNewContext(contextObject?: Context, options?: RunningScriptOptions): any; + runInNewContext(contextObject?: Context, options?: RunningScriptInNewContextOptions): any; /** * Runs the compiled code contained by the `vm.Script` within the context of the - * current `global` object. Running code does not have access to local scope, but_does_ have access to the current `global` object. + * current `global` object. Running code does not have access to local scope, but _does_ have access to the current `global` object. * * The following example compiles code that increments a `global` variable then * executes that code multiple times: * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * global.globalVar = 0; * @@ -249,6 +284,16 @@ declare module 'vm' { * Creates a code cache that can be used with the `Script` constructor's`cachedData` option. Returns a `Buffer`. This method may be called at any * time and any number of times. * + * The code cache of the `Script` doesn't contain any JavaScript observable + * states. The code cache is safe to be saved along side the script source and + * used to construct new `Script` instances multiple times. + * + * Functions in the `Script` source can be marked as lazily compiled and they are + * not compiled at construction of the `Script`. These functions are going to be + * compiled when they are invoked the first time. The code cache serializes the + * metadata that V8 currently knows about the `Script` that it can use to speed up + * future compilations. + * * ```js * const script = new vm.Script(` * function add(a, b) { @@ -258,19 +303,46 @@ declare module 'vm' { * const x = add(1, 2); * `); * - * const cacheWithoutX = script.createCachedData(); + * const cacheWithoutAdd = script.createCachedData(); + * // In `cacheWithoutAdd` the function `add()` is marked for full compilation + * // upon invocation. * * script.runInThisContext(); * - * const cacheWithX = script.createCachedData(); + * const cacheWithAdd = script.createCachedData(); + * // `cacheWithAdd` contains fully compiled function `add()`. * ``` * @since v10.6.0 */ createCachedData(): Buffer; /** @deprecated in favor of `script.createCachedData()` */ cachedDataProduced?: boolean | undefined; + /** + * When `cachedData` is supplied to create the `vm.Script`, this value will be set + * to either `true` or `false` depending on acceptance of the data by V8\. + * Otherwise the value is `undefined`. + * @since v5.7.0 + */ cachedDataRejected?: boolean | undefined; cachedData?: Buffer | undefined; + /** + * When the script is compiled from a source that contains a source map magic + * comment, this property will be set to the URL of the source map. + * + * ```js + * import vm from 'node:vm'; + * + * const script = new vm.Script(` + * function myFunc() {} + * //# sourceMappingURL=sourcemap.json + * `); + * + * console.log(script.sourceMapURL); + * // Prints: sourcemap.json + * ``` + * @since v19.1.0, v18.13.0 + */ + sourceMapURL?: string | undefined; } /** * If given a `contextObject`, the `vm.createContext()` method will `prepare @@ -280,7 +352,7 @@ declare module 'vm' { * will remain unchanged. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * global.globalVar = 3; * @@ -327,7 +399,7 @@ declare module 'vm' { * The following example compiles and executes different scripts using a single `contextified` object: * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * const contextObject = { globalVar: 1 }; * vm.createContext(contextObject); @@ -343,7 +415,7 @@ declare module 'vm' { * @param contextifiedObject The `contextified` object that will be used as the `global` when the `code` is compiled and run. * @return the result of the very last statement executed in the script. */ - function runInContext(code: string, contextifiedObject: Context, options?: RunningScriptOptions | string): any; + function runInContext(code: string, contextifiedObject: Context, options?: RunningCodeOptions | string): any; /** * The `vm.runInNewContext()` first contextifies the given `contextObject` (or * creates a new `contextObject` if passed as `undefined`), compiles the `code`, @@ -356,11 +428,11 @@ declare module 'vm' { * variable and sets a new one. These globals are contained in the `contextObject`. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * const contextObject = { * animal: 'cat', - * count: 2 + * count: 2, * }; * * vm.runInNewContext('count += 1; name = "kitty"', contextObject); @@ -372,7 +444,11 @@ declare module 'vm' { * @param contextObject An object that will be `contextified`. If `undefined`, a new object will be created. * @return the result of the very last statement executed in the script. */ - function runInNewContext(code: string, contextObject?: Context, options?: RunningScriptOptions | string): any; + function runInNewContext( + code: string, + contextObject?: Context, + options?: RunningCodeInNewContextOptions | string, + ): any; /** * `vm.runInThisContext()` compiles `code`, runs it within the context of the * current `global` and returns the result. Running code does not have access to @@ -384,7 +460,7 @@ declare module 'vm' { * the JavaScript [`eval()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) function to run the same code: * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * let localVar = 'initial value'; * * const vmResult = vm.runInThisContext('localVar = "vm";'); @@ -405,17 +481,17 @@ declare module 'vm' { * When using either `script.runInThisContext()` or {@link runInThisContext}, the code is executed within the current V8 global * context. The code passed to this VM context will have its own isolated scope. * - * In order to run a simple web server using the `http` module the code passed to - * the context must either call `require('http')` on its own, or have a reference - * to the `http` module passed to it. For instance: + * In order to run a simple web server using the `node:http` module the code passed + * to the context must either call `require('node:http')` on its own, or have a + * reference to the `node:http` module passed to it. For instance: * * ```js * 'use strict'; - * const vm = require('vm'); + * const vm = require('node:vm'); * * const code = ` * ((require) => { - * const http = require('http'); + * const http = require('node:http'); * * http.createServer((request, response) => { * response.writeHead(200, { 'Content-Type': 'text/plain' }); @@ -435,7 +511,7 @@ declare module 'vm' { * @param code The JavaScript code to compile and run. * @return the result of the very last statement executed in the script. */ - function runInThisContext(code: string, options?: RunningScriptOptions | string): any; + function runInThisContext(code: string, options?: RunningCodeOptions | string): any; /** * Compiles the given code into the provided context (if no context is * supplied, the current context is used), and returns it wrapped inside a @@ -444,7 +520,15 @@ declare module 'vm' { * @param code The body of the function to compile. * @param params An array of strings containing all parameters for the function. */ - function compileFunction(code: string, params?: ReadonlyArray, options?: CompileFunctionOptions): Function; + function compileFunction( + code: string, + params?: readonly string[], + options?: CompileFunctionOptions, + ): Function & { + cachedData?: Script["cachedData"] | undefined; + cachedDataProduced?: Script["cachedDataProduced"] | undefined; + cachedDataRejected?: Script["cachedDataRejected"] | undefined; + }; /** * Measure the memory known to V8 and used by all contexts known to the * current V8 isolate, or the main context. @@ -458,7 +542,7 @@ declare module 'vm' { * the memory occupied by each heap space in the current V8 instance. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * // Measure the memory used by the main context. * vm.measureMemory({ mode: 'summary' }) * // This is the same as vm.measureMemory() @@ -501,7 +585,319 @@ declare module 'vm' { * @experimental */ function measureMemory(options?: MeasureMemoryOptions): Promise; + interface ModuleEvaluateOptions { + timeout?: RunningScriptOptions["timeout"] | undefined; + breakOnSigint?: RunningScriptOptions["breakOnSigint"] | undefined; + } + type ModuleLinker = ( + specifier: string, + referencingModule: Module, + extra: { + /** @deprecated Use `attributes` instead */ + assert: ImportAttributes; + attributes: ImportAttributes; + }, + ) => Module | Promise; + type ModuleStatus = "unlinked" | "linking" | "linked" | "evaluating" | "evaluated" | "errored"; + /** + * This feature is only available with the `--experimental-vm-modules` command + * flag enabled. + * + * The `vm.Module` class provides a low-level interface for using + * ECMAScript modules in VM contexts. It is the counterpart of the `vm.Script`class that closely mirrors [Module Record](https://262.ecma-international.org/14.0/#sec-abstract-module-records) s as + * defined in the ECMAScript + * specification. + * + * Unlike `vm.Script` however, every `vm.Module` object is bound to a context from + * its creation. Operations on `vm.Module` objects are intrinsically asynchronous, + * in contrast with the synchronous nature of `vm.Script` objects. The use of + * 'async' functions can help with manipulating `vm.Module` objects. + * + * Using a `vm.Module` object requires three distinct steps: creation/parsing, + * linking, and evaluation. These three steps are illustrated in the following + * example. + * + * This implementation lies at a lower level than the `ECMAScript Module + * loader`. There is also no way to interact with the Loader yet, though + * support is planned. + * + * ```js + * import vm from 'node:vm'; + * + * const contextifiedObject = vm.createContext({ + * secret: 42, + * print: console.log, + * }); + * + * // Step 1 + * // + * // Create a Module by constructing a new `vm.SourceTextModule` object. This + * // parses the provided source text, throwing a `SyntaxError` if anything goes + * // wrong. By default, a Module is created in the top context. But here, we + * // specify `contextifiedObject` as the context this Module belongs to. + * // + * // Here, we attempt to obtain the default export from the module "foo", and + * // put it into local binding "secret". + * + * const bar = new vm.SourceTextModule(` + * import s from 'foo'; + * s; + * print(s); + * `, { context: contextifiedObject }); + * + * // Step 2 + * // + * // "Link" the imported dependencies of this Module to it. + * // + * // The provided linking callback (the "linker") accepts two arguments: the + * // parent module (`bar` in this case) and the string that is the specifier of + * // the imported module. The callback is expected to return a Module that + * // corresponds to the provided specifier, with certain requirements documented + * // in `module.link()`. + * // + * // If linking has not started for the returned Module, the same linker + * // callback will be called on the returned Module. + * // + * // Even top-level Modules without dependencies must be explicitly linked. The + * // callback provided would never be called, however. + * // + * // The link() method returns a Promise that will be resolved when all the + * // Promises returned by the linker resolve. + * // + * // Note: This is a contrived example in that the linker function creates a new + * // "foo" module every time it is called. In a full-fledged module system, a + * // cache would probably be used to avoid duplicated modules. + * + * async function linker(specifier, referencingModule) { + * if (specifier === 'foo') { + * return new vm.SourceTextModule(` + * // The "secret" variable refers to the global variable we added to + * // "contextifiedObject" when creating the context. + * export default secret; + * `, { context: referencingModule.context }); + * + * // Using `contextifiedObject` instead of `referencingModule.context` + * // here would work as well. + * } + * throw new Error(`Unable to resolve dependency: ${specifier}`); + * } + * await bar.link(linker); + * + * // Step 3 + * // + * // Evaluate the Module. The evaluate() method returns a promise which will + * // resolve after the module has finished evaluating. + * + * // Prints 42. + * await bar.evaluate(); + * ``` + * @since v13.0.0, v12.16.0 + * @experimental + */ + class Module { + /** + * The specifiers of all dependencies of this module. The returned array is frozen + * to disallow any changes to it. + * + * Corresponds to the `[[RequestedModules]]` field of [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records) s in + * the ECMAScript specification. + */ + dependencySpecifiers: readonly string[]; + /** + * If the `module.status` is `'errored'`, this property contains the exception + * thrown by the module during evaluation. If the status is anything else, + * accessing this property will result in a thrown exception. + * + * The value `undefined` cannot be used for cases where there is not a thrown + * exception due to possible ambiguity with `throw undefined;`. + * + * Corresponds to the `[[EvaluationError]]` field of [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records) s + * in the ECMAScript specification. + */ + error: any; + /** + * The identifier of the current module, as set in the constructor. + */ + identifier: string; + context: Context; + /** + * The namespace object of the module. This is only available after linking + * (`module.link()`) has completed. + * + * Corresponds to the [GetModuleNamespace](https://tc39.es/ecma262/#sec-getmodulenamespace) abstract operation in the ECMAScript + * specification. + */ + namespace: Object; + /** + * The current status of the module. Will be one of: + * + * * `'unlinked'`: `module.link()` has not yet been called. + * * `'linking'`: `module.link()` has been called, but not all Promises returned + * by the linker function have been resolved yet. + * * `'linked'`: The module has been linked successfully, and all of its + * dependencies are linked, but `module.evaluate()` has not yet been called. + * * `'evaluating'`: The module is being evaluated through a `module.evaluate()` on + * itself or a parent module. + * * `'evaluated'`: The module has been successfully evaluated. + * * `'errored'`: The module has been evaluated, but an exception was thrown. + * + * Other than `'errored'`, this status string corresponds to the specification's [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records)'s `[[Status]]` field. `'errored'` + * corresponds to`'evaluated'` in the specification, but with `[[EvaluationError]]` set to a + * value that is not `undefined`. + */ + status: ModuleStatus; + /** + * Evaluate the module. + * + * This must be called after the module has been linked; otherwise it will reject. + * It could be called also when the module has already been evaluated, in which + * case it will either do nothing if the initial evaluation ended in success + * (`module.status` is `'evaluated'`) or it will re-throw the exception that the + * initial evaluation resulted in (`module.status` is `'errored'`). + * + * This method cannot be called while the module is being evaluated + * (`module.status` is `'evaluating'`). + * + * Corresponds to the [Evaluate() concrete method](https://tc39.es/ecma262/#sec-moduleevaluation) field of [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records) s in the + * ECMAScript specification. + * @return Fulfills with `undefined` upon success. + */ + evaluate(options?: ModuleEvaluateOptions): Promise; + /** + * Link module dependencies. This method must be called before evaluation, and + * can only be called once per module. + * + * The function is expected to return a `Module` object or a `Promise` that + * eventually resolves to a `Module` object. The returned `Module` must satisfy the + * following two invariants: + * + * * It must belong to the same context as the parent `Module`. + * * Its `status` must not be `'errored'`. + * + * If the returned `Module`'s `status` is `'unlinked'`, this method will be + * recursively called on the returned `Module` with the same provided `linker`function. + * + * `link()` returns a `Promise` that will either get resolved when all linking + * instances resolve to a valid `Module`, or rejected if the linker function either + * throws an exception or returns an invalid `Module`. + * + * The linker function roughly corresponds to the implementation-defined [HostResolveImportedModule](https://tc39.es/ecma262/#sec-hostresolveimportedmodule) abstract operation in the + * ECMAScript + * specification, with a few key differences: + * + * * The linker function is allowed to be asynchronous while [HostResolveImportedModule](https://tc39.es/ecma262/#sec-hostresolveimportedmodule) is synchronous. + * + * The actual [HostResolveImportedModule](https://tc39.es/ecma262/#sec-hostresolveimportedmodule) implementation used during module + * linking is one that returns the modules linked during linking. Since at + * that point all modules would have been fully linked already, the [HostResolveImportedModule](https://tc39.es/ecma262/#sec-hostresolveimportedmodule) implementation is fully synchronous per + * specification. + * + * Corresponds to the [Link() concrete method](https://tc39.es/ecma262/#sec-moduledeclarationlinking) field of [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records) s in + * the ECMAScript specification. + */ + link(linker: ModuleLinker): Promise; + } + interface SourceTextModuleOptions { + /** + * String used in stack traces. + * @default 'vm:module(i)' where i is a context-specific ascending index. + */ + identifier?: string | undefined; + cachedData?: ScriptOptions["cachedData"] | undefined; + context?: Context | undefined; + lineOffset?: BaseOptions["lineOffset"] | undefined; + columnOffset?: BaseOptions["columnOffset"] | undefined; + /** + * Called during evaluation of this module to initialize the `import.meta`. + */ + initializeImportMeta?: ((meta: ImportMeta, module: SourceTextModule) => void) | undefined; + importModuleDynamically?: ScriptOptions["importModuleDynamically"] | undefined; + } + /** + * This feature is only available with the `--experimental-vm-modules` command + * flag enabled. + * + * The `vm.SourceTextModule` class provides the [Source Text Module Record](https://tc39.es/ecma262/#sec-source-text-module-records) as + * defined in the ECMAScript specification. + * @since v9.6.0 + * @experimental + */ + class SourceTextModule extends Module { + /** + * Creates a new `SourceTextModule` instance. + * @param code JavaScript Module code to parse + */ + constructor(code: string, options?: SourceTextModuleOptions); + } + interface SyntheticModuleOptions { + /** + * String used in stack traces. + * @default 'vm:module(i)' where i is a context-specific ascending index. + */ + identifier?: string | undefined; + /** + * The contextified object as returned by the `vm.createContext()` method, to compile and evaluate this module in. + */ + context?: Context | undefined; + } + /** + * This feature is only available with the `--experimental-vm-modules` command + * flag enabled. + * + * The `vm.SyntheticModule` class provides the [Synthetic Module Record](https://heycam.github.io/webidl/#synthetic-module-records) as + * defined in the WebIDL specification. The purpose of synthetic modules is to + * provide a generic interface for exposing non-JavaScript sources to ECMAScript + * module graphs. + * + * ```js + * const vm = require('node:vm'); + * + * const source = '{ "a": 1 }'; + * const module = new vm.SyntheticModule(['default'], function() { + * const obj = JSON.parse(source); + * this.setExport('default', obj); + * }); + * + * // Use `module` in linking... + * ``` + * @since v13.0.0, v12.16.0 + * @experimental + */ + class SyntheticModule extends Module { + /** + * Creates a new `SyntheticModule` instance. + * @param exportNames Array of names that will be exported from the module. + * @param evaluateCallback Called when the module is evaluated. + */ + constructor( + exportNames: string[], + evaluateCallback: (this: SyntheticModule) => void, + options?: SyntheticModuleOptions, + ); + /** + * This method is used after the module is linked to set the values of exports. If + * it is called before the module is linked, an `ERR_VM_MODULE_STATUS` error + * will be thrown. + * + * ```js + * import vm from 'node:vm'; + * + * const m = new vm.SyntheticModule(['x'], () => { + * m.setExport('x', 1); + * }); + * + * await m.link(() => {}); + * await m.evaluate(); + * + * assert.strictEqual(m.namespace.x, 1); + * ``` + * @since v13.0.0, v12.16.0 + * @param name Name of the export to set. + * @param value The value to set the export to. + */ + setExport(name: string, value: any): void; + } } -declare module 'node:vm' { - export * from 'vm'; +declare module "node:vm" { + export * from "vm"; } diff --git a/node_modules/@types/node/ts4.8/wasi.d.ts b/node_modules/@types/node/ts4.8/wasi.d.ts old mode 100755 new mode 100644 index dfcf957..337c074 --- a/node_modules/@types/node/ts4.8/wasi.d.ts +++ b/node_modules/@types/node/ts4.8/wasi.d.ts @@ -1,28 +1,30 @@ /** - * The WASI API provides an implementation of the [WebAssembly System Interface](https://wasi.dev/) specification. WASI gives sandboxed WebAssembly applications access to the - * underlying operating system via a collection of POSIX-like functions. + * **The `node:wasi` module does not currently provide the** + * **comprehensive file system security properties provided by some WASI runtimes.** + * **Full support for secure file system sandboxing may or may not be implemented in** + * **future. In the mean time, do not rely on it to run untrusted code.** + * + * The WASI API provides an implementation of the [WebAssembly System Interface](https://wasi.dev/) specification. WASI gives WebAssembly applications access to the underlying + * operating system via a collection of POSIX-like functions. * * ```js - * import { readFile } from 'fs/promises'; + * import { readFile } from 'node:fs/promises'; * import { WASI } from 'wasi'; - * import { argv, env } from 'process'; + * import { argv, env } from 'node:process'; * * const wasi = new WASI({ + * version: 'preview1', * args: argv, * env, * preopens: { - * '/sandbox': '/some/real/path/that/wasm/can/access' - * } + * '/local': '/some/real/path/that/wasm/can/access', + * }, * }); * - * // Some WASI binaries require: - * // const importObject = { wasi_unstable: wasi.wasiImport }; - * const importObject = { wasi_snapshot_preview1: wasi.wasiImport }; - * * const wasm = await WebAssembly.compile( - * await readFile(new URL('./demo.wasm', import.meta.url)) + * await readFile(new URL('./demo.wasm', import.meta.url)), * ); - * const instance = await WebAssembly.instantiate(wasm, importObject); + * const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject()); * * wasi.start(instance); * ``` @@ -61,16 +63,13 @@ * * Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm` * - * ```console - * $ wat2wasm demo.wat + * ```bash + * wat2wasm demo.wat * ``` - * - * The `--experimental-wasi-unstable-preview1` CLI argument is needed for this - * example to run. * @experimental - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/wasi.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/wasi.js) */ -declare module 'wasi' { +declare module "wasi" { interface WASIOptions { /** * An array of strings that the WebAssembly application will @@ -91,11 +90,11 @@ declare module 'wasi' { */ preopens?: NodeJS.Dict | undefined; /** - * By default, WASI applications terminate the Node.js - * process via the `__wasi_proc_exit()` function. Setting this option to `true` - * causes `wasi.start()` to return the exit code rather than terminate the - * process. - * @default false + * By default, when WASI applications call `__wasi_proc_exit()` + * `wasi.start()` will return with the exit code specified rather than terminatng the process. + * Setting this option to `false` will cause the Node.js process to exit with + * the specified exit code instead. + * @default true */ returnOnExit?: boolean | undefined; /** @@ -113,12 +112,17 @@ declare module 'wasi' { * @default 2 */ stderr?: number | undefined; + /** + * The version of WASI requested. + * Currently the only supported versions are `'unstable'` and `'preview1'`. + * @since v20.0.0 + */ + version: string; } /** * The `WASI` class provides the WASI system call API and additional convenience * methods for working with WASI-based applications. Each `WASI` instance - * represents a distinct sandbox environment. For security purposes, each `WASI`instance must have its command-line arguments, environment variables, and - * sandbox directory structure configured explicitly. + * represents a distinct environment. * @since v13.3.0, v12.16.0 */ class WASI { @@ -133,7 +137,7 @@ declare module 'wasi' { * If `start()` is called more than once, an exception is thrown. * @since v13.3.0, v12.16.0 */ - start(instance: object): void; // TODO: avoid DOM dependency until WASM moved to own lib. + start(instance: object): number; // TODO: avoid DOM dependency until WASM moved to own lib. /** * Attempt to initialize `instance` as a WASI reactor by invoking its`_initialize()` export, if it is present. If `instance` contains a `_start()`export, then an exception is thrown. * @@ -153,6 +157,6 @@ declare module 'wasi' { readonly wasiImport: NodeJS.Dict; // TODO: Narrow to DOM types } } -declare module 'node:wasi' { - export * from 'wasi'; +declare module "node:wasi" { + export * from "wasi"; } diff --git a/node_modules/@types/node/ts4.8/worker_threads.d.ts b/node_modules/@types/node/ts4.8/worker_threads.d.ts old mode 100755 new mode 100644 index 419d044..e3e5048 --- a/node_modules/@types/node/ts4.8/worker_threads.d.ts +++ b/node_modules/@types/node/ts4.8/worker_threads.d.ts @@ -1,9 +1,9 @@ /** - * The `worker_threads` module enables the use of threads that execute JavaScript - * in parallel. To access it: + * The `node:worker_threads` module enables the use of threads that execute + * JavaScript in parallel. To access it: * * ```js - * const worker = require('worker_threads'); + * const worker = require('node:worker_threads'); * ``` * * Workers (threads) are useful for performing CPU-intensive JavaScript operations. @@ -15,14 +15,14 @@ * * ```js * const { - * Worker, isMainThread, parentPort, workerData - * } = require('worker_threads'); + * Worker, isMainThread, parentPort, workerData, + * } = require('node:worker_threads'); * * if (isMainThread) { * module.exports = function parseJSAsync(script) { * return new Promise((resolve, reject) => { * const worker = new Worker(__filename, { - * workerData: script + * workerData: script, * }); * worker.on('message', resolve); * worker.on('error', reject); @@ -39,7 +39,7 @@ * } * ``` * - * The above example spawns a Worker thread for each `parse()` call. In actual + * The above example spawns a Worker thread for each `parseJSAsync()` call. In * practice, use a pool of Workers for these kinds of tasks. Otherwise, the * overhead of creating Workers would likely exceed their benefit. * @@ -49,17 +49,17 @@ * * Worker threads inherit non-process-specific options by default. Refer to `Worker constructor options` to know how to customize worker thread options, * specifically `argv` and `execArgv` options. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/worker_threads.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/worker_threads.js) */ -declare module 'worker_threads' { - import { Blob } from 'node:buffer'; - import { Context } from 'node:vm'; - import { EventEmitter } from 'node:events'; - import { EventLoopUtilityFunction } from 'node:perf_hooks'; - import { FileHandle } from 'node:fs/promises'; - import { Readable, Writable } from 'node:stream'; - import { URL } from 'node:url'; - import { X509Certificate } from 'node:crypto'; +declare module "worker_threads" { + import { Blob } from "node:buffer"; + import { Context } from "node:vm"; + import { EventEmitter } from "node:events"; + import { EventLoopUtilityFunction } from "node:perf_hooks"; + import { FileHandle } from "node:fs/promises"; + import { Readable, Writable } from "node:stream"; + import { URL } from "node:url"; + import { X509Certificate } from "node:crypto"; const isMainThread: boolean; const parentPort: null | MessagePort; const resourceLimits: ResourceLimits; @@ -72,7 +72,7 @@ declare module 'worker_threads' { * The `MessageChannel` has no methods of its own. `new MessageChannel()`yields an object with `port1` and `port2` properties, which refer to linked `MessagePort` instances. * * ```js - * const { MessageChannel } = require('worker_threads'); + * const { MessageChannel } = require('node:worker_threads'); * * const { port1, port2 } = new MessageChannel(); * port1.on('message', (message) => console.log('received', message)); @@ -121,7 +121,7 @@ declare module 'worker_threads' { * * `value` may not contain native (C++-backed) objects other than: * * ```js - * const { MessageChannel } = require('worker_threads'); + * const { MessageChannel } = require('node:worker_threads'); * const { port1, port2 } = new MessageChannel(); * * port1.on('message', (message) => console.log(message)); @@ -132,7 +132,7 @@ declare module 'worker_threads' { * port2.postMessage(circularData); * ``` * - * `transferList` may be a list of [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), `MessagePort` and `FileHandle` objects. + * `transferList` may be a list of [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), `MessagePort`, and `FileHandle` objects. * After transferring, they are not usable on the sending side of the channel * anymore (even if they are not contained in `value`). Unlike with `child processes`, transferring handles such as network sockets is currently * not supported. @@ -143,7 +143,7 @@ declare module 'worker_threads' { * `value` may still contain `ArrayBuffer` instances that are not in`transferList`; in that case, the underlying memory is copied rather than moved. * * ```js - * const { MessageChannel } = require('worker_threads'); + * const { MessageChannel } = require('node:worker_threads'); * const { port1, port2 } = new MessageChannel(); * * port1.on('message', (message) => console.log(message)); @@ -170,12 +170,12 @@ declare module 'worker_threads' { * posting without having side effects. * * For more information on the serialization and deserialization mechanisms - * behind this API, see the `serialization API of the v8 module`. + * behind this API, see the `serialization API of the node:v8 module`. * @since v10.5.0 */ - postMessage(value: any, transferList?: ReadonlyArray): void; + postMessage(value: any, transferList?: readonly TransferListItem[]): void; /** - * Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed port does_not_ let the program exit if it's the only active handle left (the default + * Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed port does _not_ let the program exit if it's the only active handle left (the default * behavior). If the port is `ref()`ed, calling `ref()` again has no effect. * * If listeners are attached or removed using `.on('message')`, the port @@ -205,37 +205,37 @@ declare module 'worker_threads' { * @since v10.5.0 */ start(): void; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'message', listener: (value: any) => void): this; - addListener(event: 'messageerror', listener: (error: Error) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "message", listener: (value: any) => void): this; + addListener(event: "messageerror", listener: (error: Error) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'close'): boolean; - emit(event: 'message', value: any): boolean; - emit(event: 'messageerror', error: Error): boolean; + emit(event: "close"): boolean; + emit(event: "message", value: any): boolean; + emit(event: "messageerror", error: Error): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'close', listener: () => void): this; - on(event: 'message', listener: (value: any) => void): this; - on(event: 'messageerror', listener: (error: Error) => void): this; + on(event: "close", listener: () => void): this; + on(event: "message", listener: (value: any) => void): this; + on(event: "messageerror", listener: (error: Error) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'message', listener: (value: any) => void): this; - once(event: 'messageerror', listener: (error: Error) => void): this; + once(event: "close", listener: () => void): this; + once(event: "message", listener: (value: any) => void): this; + once(event: "messageerror", listener: (error: Error) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'message', listener: (value: any) => void): this; - prependListener(event: 'messageerror', listener: (error: Error) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "message", listener: (value: any) => void): this; + prependListener(event: "messageerror", listener: (error: Error) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'message', listener: (value: any) => void): this; - prependOnceListener(event: 'messageerror', listener: (error: Error) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "message", listener: (value: any) => void): this; + prependOnceListener(event: "messageerror", listener: (error: Error) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; - removeListener(event: 'close', listener: () => void): this; - removeListener(event: 'message', listener: (value: any) => void): this; - removeListener(event: 'messageerror', listener: (error: Error) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "message", listener: (value: any) => void): this; + removeListener(event: "messageerror", listener: (error: Error) => void): this; removeListener(event: string | symbol, listener: (...args: any[]) => void): this; - off(event: 'close', listener: () => void): this; - off(event: 'message', listener: (value: any) => void): this; - off(event: 'messageerror', listener: (error: Error) => void): this; + off(event: "close", listener: () => void): this; + off(event: "message", listener: (value: any) => void): this; + off(event: "messageerror", listener: (error: Error) => void): this; off(event: string | symbol, listener: (...args: any[]) => void): this; } interface WorkerOptions { @@ -262,6 +262,12 @@ declare module 'worker_threads' { * @default true */ trackUnmanagedFds?: boolean | undefined; + /** + * An optional `name` to be appended to the worker title + * for debuggin/identification purposes, making the final title as + * `[worker ${id}] ${name}`. + */ + name?: string | undefined; } interface ResourceLimits { /** @@ -288,16 +294,17 @@ declare module 'worker_threads' { * * Notable differences inside a Worker environment are: * - * * The `process.stdin`, `process.stdout` and `process.stderr` may be redirected by the parent thread. - * * The `require('worker_threads').isMainThread` property is set to `false`. - * * The `require('worker_threads').parentPort` message port is available. + * * The `process.stdin`, `process.stdout`, and `process.stderr` streams may be redirected by the parent thread. + * * The `require('node:worker_threads').isMainThread` property is set to `false`. + * * The `require('node:worker_threads').parentPort` message port is available. * * `process.exit()` does not stop the whole program, just the single thread, * and `process.abort()` is not available. * * `process.chdir()` and `process` methods that set group or user ids * are not available. * * `process.env` is a copy of the parent thread's environment variables, * unless otherwise specified. Changes to one copy are not visible in other - * threads, and are not visible to native add-ons (unless `worker.SHARE_ENV` is passed as the `env` option to the `Worker` constructor). + * threads, and are not visible to native add-ons (unless `worker.SHARE_ENV` is passed as the `env` option to the `Worker` constructor). On Windows, unlike the main thread, a copy of the + * environment variables operates in a case-sensitive manner. * * `process.title` cannot be modified. * * Signals are not delivered through `process.on('...')`. * * Execution may stop at any point as a result of `worker.terminate()` being invoked. @@ -307,11 +314,11 @@ declare module 'worker_threads' { * * Creating `Worker` instances inside of other `Worker`s is possible. * - * Like [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) and the `cluster module`, two-way communication can be - * achieved through inter-thread message passing. Internally, a `Worker` has a - * built-in pair of `MessagePort` s that are already associated with each other - * when the `Worker` is created. While the `MessagePort` object on the parent side - * is not directly exposed, its functionalities are exposed through `worker.postMessage()` and the `worker.on('message')` event + * Like [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) and the `node:cluster module`, two-way communication + * can be achieved through inter-thread message passing. Internally, a `Worker` has + * a built-in pair of `MessagePort` s that are already associated with each + * other when the `Worker` is created. While the `MessagePort` object on the parent + * side is not directly exposed, its functionalities are exposed through `worker.postMessage()` and the `worker.on('message')` event * on the `Worker` object for the parent thread. * * To create custom messaging channels (which is encouraged over using the default @@ -324,10 +331,10 @@ declare module 'worker_threads' { * the thread barrier. * * ```js - * const assert = require('assert'); + * const assert = require('node:assert'); * const { - * Worker, MessageChannel, MessagePort, isMainThread, parentPort - * } = require('worker_threads'); + * Worker, MessageChannel, MessagePort, isMainThread, parentPort, + * } = require('node:worker_threads'); * if (isMainThread) { * const worker = new Worker(__filename); * const subChannel = new MessageChannel(); @@ -367,7 +374,7 @@ declare module 'worker_threads' { readonly stderr: Readable; /** * An integer identifier for the referenced thread. Inside the worker thread, - * it is available as `require('worker_threads').threadId`. + * it is available as `require('node:worker_threads').threadId`. * This value is unique for each `Worker` instance inside a single process. * @since v10.5.0 */ @@ -384,7 +391,7 @@ declare module 'worker_threads' { /** * An object that can be used to query performance information from a worker * instance. Similar to `perf_hooks.performance`. - * @since v15.1.0, v12.22.0 + * @since v15.1.0, v14.17.0, v12.22.0 */ readonly performance: WorkerPerformance; /** @@ -394,13 +401,13 @@ declare module 'worker_threads' { */ constructor(filename: string | URL, options?: WorkerOptions); /** - * Send a message to the worker that is received via `require('worker_threads').parentPort.on('message')`. + * Send a message to the worker that is received via `require('node:worker_threads').parentPort.on('message')`. * See `port.postMessage()` for more details. * @since v10.5.0 */ - postMessage(value: any, transferList?: ReadonlyArray): void; + postMessage(value: any, transferList?: readonly TransferListItem[]): void; /** - * Opposite of `unref()`, calling `ref()` on a previously `unref()`ed worker does_not_ let the program exit if it's the only active handle left (the default + * Opposite of `unref()`, calling `ref()` on a previously `unref()`ed worker does _not_ let the program exit if it's the only active handle left (the default * behavior). If the worker is `ref()`ed, calling `ref()` again has * no effect. * @since v10.5.0 @@ -428,53 +435,53 @@ declare module 'worker_threads' { * @return A promise for a Readable Stream containing a V8 heap snapshot */ getHeapSnapshot(): Promise; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'exit', listener: (exitCode: number) => void): this; - addListener(event: 'message', listener: (value: any) => void): this; - addListener(event: 'messageerror', listener: (error: Error) => void): this; - addListener(event: 'online', listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "exit", listener: (exitCode: number) => void): this; + addListener(event: "message", listener: (value: any) => void): this; + addListener(event: "messageerror", listener: (error: Error) => void): this; + addListener(event: "online", listener: () => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'error', err: Error): boolean; - emit(event: 'exit', exitCode: number): boolean; - emit(event: 'message', value: any): boolean; - emit(event: 'messageerror', error: Error): boolean; - emit(event: 'online'): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "exit", exitCode: number): boolean; + emit(event: "message", value: any): boolean; + emit(event: "messageerror", error: Error): boolean; + emit(event: "online"): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'exit', listener: (exitCode: number) => void): this; - on(event: 'message', listener: (value: any) => void): this; - on(event: 'messageerror', listener: (error: Error) => void): this; - on(event: 'online', listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "exit", listener: (exitCode: number) => void): this; + on(event: "message", listener: (value: any) => void): this; + on(event: "messageerror", listener: (error: Error) => void): this; + on(event: "online", listener: () => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'exit', listener: (exitCode: number) => void): this; - once(event: 'message', listener: (value: any) => void): this; - once(event: 'messageerror', listener: (error: Error) => void): this; - once(event: 'online', listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "exit", listener: (exitCode: number) => void): this; + once(event: "message", listener: (value: any) => void): this; + once(event: "messageerror", listener: (error: Error) => void): this; + once(event: "online", listener: () => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'exit', listener: (exitCode: number) => void): this; - prependListener(event: 'message', listener: (value: any) => void): this; - prependListener(event: 'messageerror', listener: (error: Error) => void): this; - prependListener(event: 'online', listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "exit", listener: (exitCode: number) => void): this; + prependListener(event: "message", listener: (value: any) => void): this; + prependListener(event: "messageerror", listener: (error: Error) => void): this; + prependListener(event: "online", listener: () => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'exit', listener: (exitCode: number) => void): this; - prependOnceListener(event: 'message', listener: (value: any) => void): this; - prependOnceListener(event: 'messageerror', listener: (error: Error) => void): this; - prependOnceListener(event: 'online', listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "exit", listener: (exitCode: number) => void): this; + prependOnceListener(event: "message", listener: (value: any) => void): this; + prependOnceListener(event: "messageerror", listener: (error: Error) => void): this; + prependOnceListener(event: "online", listener: () => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; - removeListener(event: 'error', listener: (err: Error) => void): this; - removeListener(event: 'exit', listener: (exitCode: number) => void): this; - removeListener(event: 'message', listener: (value: any) => void): this; - removeListener(event: 'messageerror', listener: (error: Error) => void): this; - removeListener(event: 'online', listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "exit", listener: (exitCode: number) => void): this; + removeListener(event: "message", listener: (value: any) => void): this; + removeListener(event: "messageerror", listener: (error: Error) => void): this; + removeListener(event: "online", listener: () => void): this; removeListener(event: string | symbol, listener: (...args: any[]) => void): this; - off(event: 'error', listener: (err: Error) => void): this; - off(event: 'exit', listener: (exitCode: number) => void): this; - off(event: 'message', listener: (value: any) => void): this; - off(event: 'messageerror', listener: (error: Error) => void): this; - off(event: 'online', listener: () => void): this; + off(event: "error", listener: (err: Error) => void): this; + off(event: "exit", listener: (exitCode: number) => void): this; + off(event: "message", listener: (value: any) => void): this; + off(event: "messageerror", listener: (error: Error) => void): this; + off(event: "online", listener: () => void): this; off(event: string | symbol, listener: (...args: any[]) => void): this; } interface BroadcastChannel extends NodeJS.RefCounted {} @@ -488,8 +495,8 @@ declare module 'worker_threads' { * const { * isMainThread, * BroadcastChannel, - * Worker - * } = require('worker_threads'); + * Worker, + * } = require('node:worker_threads'); * * const bc = new BroadcastChannel('hello'); * @@ -507,7 +514,6 @@ declare module 'worker_threads' { * } * ``` * @since v15.4.0 - * @experimental */ class BroadcastChannel { readonly name: string; @@ -544,7 +550,7 @@ declare module 'worker_threads' { * This operation cannot be undone. * * ```js - * const { MessageChannel, markAsUntransferable } = require('worker_threads'); + * const { MessageChannel, markAsUntransferable } = require('node:worker_threads'); * * const pooledBuffer = new ArrayBuffer(8); * const typedArray1 = new Uint8Array(pooledBuffer); @@ -586,10 +592,10 @@ declare module 'worker_threads' { function moveMessagePortToContext(port: MessagePort, contextifiedSandbox: Context): MessagePort; /** * Receive a single message from a given `MessagePort`. If no message is available,`undefined` is returned, otherwise an object with a single `message` property - * that contains the message payload, corresponding to the oldest message in the`MessagePort`’s queue. + * that contains the message payload, corresponding to the oldest message in the`MessagePort`'s queue. * * ```js - * const { MessageChannel, receiveMessageOnPort } = require('worker_threads'); + * const { MessageChannel, receiveMessageOnPort } = require('node:worker_threads'); * const { port1, port2 } = new MessageChannel(); * port1.postMessage({ hello: 'world' }); * @@ -604,8 +610,8 @@ declare module 'worker_threads' { */ function receiveMessageOnPort(port: MessagePort): | { - message: any; - } + message: any; + } | undefined; type Serializable = string | object | number | boolean | bigint; /** @@ -620,7 +626,7 @@ declare module 'worker_threads' { * isMainThread, * setEnvironmentData, * getEnvironmentData, - * } = require('worker_threads'); + * } = require('node:worker_threads'); * * if (isMainThread) { * setEnvironmentData('Hello', 'World!'); @@ -629,21 +635,57 @@ declare module 'worker_threads' { * console.log(getEnvironmentData('Hello')); // Prints 'World!'. * } * ``` - * @since v15.12.0 - * @experimental + * @since v15.12.0, v14.18.0 * @param key Any arbitrary, cloneable JavaScript value that can be used as a {Map} key. */ function getEnvironmentData(key: Serializable): Serializable; /** * The `worker.setEnvironmentData()` API sets the content of`worker.getEnvironmentData()` in the current thread and all new `Worker`instances spawned from the current context. - * @since v15.12.0 - * @experimental + * @since v15.12.0, v14.18.0 * @param key Any arbitrary, cloneable JavaScript value that can be used as a {Map} key. * @param value Any arbitrary, cloneable JavaScript value that will be cloned and passed automatically to all new `Worker` instances. If `value` is passed as `undefined`, any previously set value * for the `key` will be deleted. */ function setEnvironmentData(key: Serializable, value: Serializable): void; + + import { + BroadcastChannel as _BroadcastChannel, + MessageChannel as _MessageChannel, + MessagePort as _MessagePort, + } from "worker_threads"; + global { + /** + * `BroadcastChannel` class is a global reference for `require('worker_threads').BroadcastChannel` + * https://nodejs.org/api/globals.html#broadcastchannel + * @since v18.0.0 + */ + var BroadcastChannel: typeof globalThis extends { + onmessage: any; + BroadcastChannel: infer T; + } ? T + : typeof _BroadcastChannel; + /** + * `MessageChannel` class is a global reference for `require('worker_threads').MessageChannel` + * https://nodejs.org/api/globals.html#messagechannel + * @since v15.0.0 + */ + var MessageChannel: typeof globalThis extends { + onmessage: any; + MessageChannel: infer T; + } ? T + : typeof _MessageChannel; + /** + * `MessagePort` class is a global reference for `require('worker_threads').MessagePort` + * https://nodejs.org/api/globals.html#messageport + * @since v15.0.0 + */ + var MessagePort: typeof globalThis extends { + onmessage: any; + MessagePort: infer T; + } ? T + : typeof _MessagePort; + } } -declare module 'node:worker_threads' { - export * from 'worker_threads'; +declare module "node:worker_threads" { + export * from "worker_threads"; } diff --git a/node_modules/@types/node/ts4.8/zlib.d.ts b/node_modules/@types/node/ts4.8/zlib.d.ts old mode 100755 new mode 100644 index 8cfa145..6b944b8 --- a/node_modules/@types/node/ts4.8/zlib.d.ts +++ b/node_modules/@types/node/ts4.8/zlib.d.ts @@ -1,11 +1,11 @@ /** - * The `zlib` module provides compression functionality implemented using Gzip, - * Deflate/Inflate, and Brotli. + * The `node:zlib` module provides compression functionality implemented using + * Gzip, Deflate/Inflate, and Brotli. * * To access it: * * ```js - * const zlib = require('zlib'); + * const zlib = require('node:zlib'); * ``` * * Compression and decompression are built around the Node.js `Streams API`. @@ -15,12 +15,12 @@ * stream: * * ```js - * const { createGzip } = require('zlib'); - * const { pipeline } = require('stream'); + * const { createGzip } = require('node:zlib'); + * const { pipeline } = require('node:stream'); * const { * createReadStream, - * createWriteStream - * } = require('fs'); + * createWriteStream, + * } = require('node:fs'); * * const gzip = createGzip(); * const source = createReadStream('input.txt'); @@ -35,7 +35,7 @@ * * // Or, Promisified * - * const { promisify } = require('util'); + * const { promisify } = require('node:util'); * const pipe = promisify(pipeline); * * async function do_gzip(input, output) { @@ -55,7 +55,7 @@ * It is also possible to compress or decompress data in a single step: * * ```js - * const { deflate, unzip } = require('zlib'); + * const { deflate, unzip } = require('node:zlib'); * * const input = '.................................'; * deflate(input, (err, buffer) => { @@ -77,7 +77,7 @@ * * // Or, Promisified * - * const { promisify } = require('util'); + * const { promisify } = require('node:util'); * const do_unzip = promisify(unzip); * * do_unzip(buffer) @@ -88,10 +88,10 @@ * }); * ``` * @since v0.5.8 - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/zlib.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/zlib.js) */ -declare module 'zlib' { - import * as stream from 'node:stream'; +declare module "zlib" { + import * as stream from "node:stream"; interface ZlibOptions { /** * @default constants.Z_NO_FLUSH @@ -128,11 +128,11 @@ declare module 'zlib' { chunkSize?: number | undefined; params?: | { - /** - * Each key is a `constants.BROTLI_*` constant. - */ - [key: number]: boolean | number; - } + /** + * Each key is a `constants.BROTLI_*` constant. + */ + [key: number]: boolean | number; + } | undefined; maxOutputLength?: number | undefined; } @@ -512,6 +512,6 @@ declare module 'zlib' { /** @deprecated */ const Z_DEFLATED: number; } -declare module 'node:zlib' { - export * from 'zlib'; +declare module "node:zlib" { + export * from "zlib"; } diff --git a/node_modules/@types/node/tty.d.ts b/node_modules/@types/node/tty.d.ts old mode 100755 new mode 100644 index 3bce2d3..1c0dafd --- a/node_modules/@types/node/tty.d.ts +++ b/node_modules/@types/node/tty.d.ts @@ -1,10 +1,9 @@ /** - * The `tty` module provides the `tty.ReadStream` and `tty.WriteStream` classes. - * In most cases, it will not be necessary or possible to use this module directly. - * However, it can be accessed using: + * The `node:tty` module provides the `tty.ReadStream` and `tty.WriteStream`classes. In most cases, it will not be necessary or possible to use this module + * directly. However, it can be accessed using: * * ```js - * const tty = require('tty'); + * const tty = require('node:tty'); * ``` * * When Node.js detects that it is being run with a text terminal ("TTY") @@ -22,10 +21,10 @@ * * In most cases, there should be little to no reason for an application to * manually create instances of the `tty.ReadStream` and `tty.WriteStream`classes. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/tty.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/tty.js) */ -declare module 'tty' { - import * as net from 'node:net'; +declare module "tty" { + import * as net from "node:net"; /** * The `tty.isatty()` method returns `true` if the given `fd` is associated with * a TTY and `false` if it is not, including whenever `fd` is not a non-negative @@ -43,7 +42,10 @@ declare module 'tty' { constructor(fd: number, options?: net.SocketConstructorOpts); /** * A `boolean` that is `true` if the TTY is currently configured to operate as a - * raw device. Defaults to `false`. + * raw device. + * + * This flag is always `false` when a process starts, even if the terminal is + * operating in raw mode. Its value will change with subsequent calls to`setRawMode`. * @since v0.7.7 */ isRaw: boolean; @@ -52,7 +54,9 @@ declare module 'tty' { * * When in raw mode, input is always available character-by-character, not * including modifiers. Additionally, all special processing of characters by the - * terminal is disabled, including echoing input characters.Ctrl+C will no longer cause a `SIGINT` when in this mode. + * terminal is disabled, including echoing input + * characters. Ctrl+C will no longer cause a `SIGINT` when + * in this mode. * @since v0.7.7 * @param mode If `true`, configures the `tty.ReadStream` to operate as a raw device. If `false`, configures the `tty.ReadStream` to operate in its default mode. The `readStream.isRaw` * property will be set to the resulting mode. @@ -79,17 +83,17 @@ declare module 'tty' { class WriteStream extends net.Socket { constructor(fd: number); addListener(event: string, listener: (...args: any[]) => void): this; - addListener(event: 'resize', listener: () => void): this; + addListener(event: "resize", listener: () => void): this; emit(event: string | symbol, ...args: any[]): boolean; - emit(event: 'resize'): boolean; + emit(event: "resize"): boolean; on(event: string, listener: (...args: any[]) => void): this; - on(event: 'resize', listener: () => void): this; + on(event: "resize", listener: () => void): this; once(event: string, listener: (...args: any[]) => void): this; - once(event: 'resize', listener: () => void): this; + once(event: "resize", listener: () => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; - prependListener(event: 'resize', listener: () => void): this; + prependListener(event: "resize", listener: () => void): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'resize', listener: () => void): this; + prependOnceListener(event: "resize", listener: () => void): this; /** * `writeStream.clearLine()` clears the current line of this `WriteStream` in a * direction identified by `dir`. @@ -199,6 +203,6 @@ declare module 'tty' { isTTY: boolean; } } -declare module 'node:tty' { - export * from 'tty'; +declare module "node:tty" { + export * from "tty"; } diff --git a/node_modules/@types/node/url.d.ts b/node_modules/@types/node/url.d.ts old mode 100755 new mode 100644 index e6272b5..20a5d85 --- a/node_modules/@types/node/url.d.ts +++ b/node_modules/@types/node/url.d.ts @@ -1,16 +1,16 @@ /** - * The `url` module provides utilities for URL resolution and parsing. It can be - * accessed using: + * The `node:url` module provides utilities for URL resolution and parsing. It can + * be accessed using: * * ```js - * import url from 'url'; + * import url from 'node:url'; * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/url.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/url.js) */ -declare module 'url' { - import { Blob } from 'node:buffer'; - import { ClientRequestArgs } from 'node:http'; - import { ParsedUrlQuery, ParsedUrlQueryInput } from 'node:querystring'; +declare module "url" { + import { Blob as NodeBlob } from "node:buffer"; + import { ClientRequestArgs } from "node:http"; + import { ParsedUrlQuery, ParsedUrlQueryInput } from "node:querystring"; // Input to `url.format` interface UrlObject { auth?: string | null | undefined; @@ -54,17 +54,11 @@ declare module 'url' { * * A `URIError` is thrown if the `auth` property is present but cannot be decoded. * - * Use of the legacy `url.parse()` method is discouraged. Users should - * use the WHATWG `URL` API. Because the `url.parse()` method uses a - * lenient, non-standard algorithm for parsing URL strings, security - * issues can be introduced. Specifically, issues with [host name spoofing](https://hackerone.com/reports/678487) and - * incorrect handling of usernames and passwords have been identified. - * - * Deprecation of this API has been shelved for now primarily due to the the - * inability of the [WHATWG API to parse relative URLs](https://github.com/nodejs/node/issues/12682#issuecomment-1154492373). - * [Discussions are ongoing](https://github.com/whatwg/url/issues/531) for the best way to resolve this. - * + * `url.parse()` uses a lenient, non-standard algorithm for parsing URL + * strings. It is prone to security issues such as [host name spoofing](https://hackerone.com/reports/678487) and incorrect handling of usernames and passwords. Do not use with untrusted + * input. CVEs are not issued for `url.parse()` vulnerabilities. Use the `WHATWG URL` API instead. * @since v0.1.25 + * @deprecated Use the WHATWG URL API instead. * @param urlString The URL string to parse. * @param [parseQueryString=false] If `true`, the `query` property will always be set to an object returned by the {@link querystring} module's `parse()` method. If `false`, the `query` property * on the returned URL object will be an unparsed, undecoded string. @@ -72,31 +66,75 @@ declare module 'url' { * result would be `{host: 'foo', pathname: '/bar'}` rather than `{pathname: '//foo/bar'}`. */ function parse(urlString: string): UrlWithStringQuery; - function parse(urlString: string, parseQueryString: false | undefined, slashesDenoteHost?: boolean): UrlWithStringQuery; + function parse( + urlString: string, + parseQueryString: false | undefined, + slashesDenoteHost?: boolean, + ): UrlWithStringQuery; function parse(urlString: string, parseQueryString: true, slashesDenoteHost?: boolean): UrlWithParsedQuery; function parse(urlString: string, parseQueryString: boolean, slashesDenoteHost?: boolean): Url; /** - * The URL object has both a `toString()` method and `href` property that return string serializations of the URL. - * These are not, however, customizable in any way. The `url.format(URL[, options])` method allows for basic - * customization of the output. - * Returns a customizable serialization of a URL `String` representation of a `WHATWG URL` object. + * The `url.format()` method returns a formatted URL string derived from`urlObject`. * * ```js - * import url from 'url'; - * const myURL = new URL('https://a:b@測試?abc#foo'); + * const url = require('node:url'); + * url.format({ + * protocol: 'https', + * hostname: 'example.com', + * pathname: '/some/path', + * query: { + * page: 1, + * format: 'json', + * }, + * }); * - * console.log(myURL.href); - * // Prints https://a:b@xn--g6w251d/?abc#foo - * - * console.log(myURL.toString()); - * // Prints https://a:b@xn--g6w251d/?abc#foo - * - * console.log(url.format(myURL, { fragment: false, unicode: true, auth: false })); - * // Prints 'https://測試/?abc' + * // => 'https://example.com/some/path?page=1&format=json' * ``` - * @since v7.6.0 - * @param urlObject A `WHATWG URL` object - * @param options + * + * If `urlObject` is not an object or a string, `url.format()` will throw a `TypeError`. + * + * The formatting process operates as follows: + * + * * A new empty string `result` is created. + * * If `urlObject.protocol` is a string, it is appended as-is to `result`. + * * Otherwise, if `urlObject.protocol` is not `undefined` and is not a string, an `Error` is thrown. + * * For all string values of `urlObject.protocol` that _do not end_ with an ASCII + * colon (`:`) character, the literal string `:` will be appended to `result`. + * * If either of the following conditions is true, then the literal string `//`will be appended to `result`: + * * `urlObject.slashes` property is true; + * * `urlObject.protocol` begins with `http`, `https`, `ftp`, `gopher`, or`file`; + * * If the value of the `urlObject.auth` property is truthy, and either`urlObject.host` or `urlObject.hostname` are not `undefined`, the value of`urlObject.auth` will be coerced into a string + * and appended to `result`followed by the literal string `@`. + * * If the `urlObject.host` property is `undefined` then: + * * If the `urlObject.hostname` is a string, it is appended to `result`. + * * Otherwise, if `urlObject.hostname` is not `undefined` and is not a string, + * an `Error` is thrown. + * * If the `urlObject.port` property value is truthy, and `urlObject.hostname`is not `undefined`: + * * The literal string `:` is appended to `result`, and + * * The value of `urlObject.port` is coerced to a string and appended to`result`. + * * Otherwise, if the `urlObject.host` property value is truthy, the value of`urlObject.host` is coerced to a string and appended to `result`. + * * If the `urlObject.pathname` property is a string that is not an empty string: + * * If the `urlObject.pathname`_does not start_ with an ASCII forward slash + * (`/`), then the literal string `'/'` is appended to `result`. + * * The value of `urlObject.pathname` is appended to `result`. + * * Otherwise, if `urlObject.pathname` is not `undefined` and is not a string, an `Error` is thrown. + * * If the `urlObject.search` property is `undefined` and if the `urlObject.query`property is an `Object`, the literal string `?` is appended to `result`followed by the output of calling the + * `querystring` module's `stringify()`method passing the value of `urlObject.query`. + * * Otherwise, if `urlObject.search` is a string: + * * If the value of `urlObject.search`_does not start_ with the ASCII question + * mark (`?`) character, the literal string `?` is appended to `result`. + * * The value of `urlObject.search` is appended to `result`. + * * Otherwise, if `urlObject.search` is not `undefined` and is not a string, an `Error` is thrown. + * * If the `urlObject.hash` property is a string: + * * If the value of `urlObject.hash`_does not start_ with the ASCII hash (`#`) + * character, the literal string `#` is appended to `result`. + * * The value of `urlObject.hash` is appended to `result`. + * * Otherwise, if the `urlObject.hash` property is not `undefined` and is not a + * string, an `Error` is thrown. + * * `result` is returned. + * @since v0.1.25 + * @legacy Use the WHATWG URL API instead. + * @param urlObject A URL object (as returned by `url.parse()` or constructed otherwise). If a string, it is converted to an object by passing it to `url.parse()`. */ function format(urlObject: URL, options?: URLFormatOptions): string; /** @@ -159,22 +197,22 @@ declare module 'url' { * string, an `Error` is thrown. * * `result` is returned. * @since v0.1.25 - * @deprecated Legacy: Use the WHATWG URL API instead. + * @legacy Use the WHATWG URL API instead. * @param urlObject A URL object (as returned by `url.parse()` or constructed otherwise). If a string, it is converted to an object by passing it to `url.parse()`. */ function format(urlObject: UrlObject | string): string; /** * The `url.resolve()` method resolves a target URL relative to a base URL in a - * manner similar to that of a Web browser resolving an anchor tag HREF. + * manner similar to that of a web browser resolving an anchor tag. * * ```js - * const url = require('url'); + * const url = require('node:url'); * url.resolve('/one/two/three', 'four'); // '/one/two/four' * url.resolve('http://example.com/', '/one'); // 'http://example.com/one' * url.resolve('http://example.com/one', '/two'); // 'http://example.com/two' * ``` * - * You can achieve the same result using the WHATWG URL API: + * To achieve the same result using the WHATWG URL API: * * ```js * function resolve(from, to) { @@ -192,9 +230,9 @@ declare module 'url' { * resolve('http://example.com/one', '/two'); // 'http://example.com/two' * ``` * @since v0.1.25 - * @deprecated Legacy: Use the WHATWG URL API instead. - * @param from The Base URL being resolved against. - * @param to The HREF URL being resolved. + * @legacy Use the WHATWG URL API instead. + * @param from The base URL to use if `to` is a relative URL. + * @param to The target URL to resolve. */ function resolve(from: string, to: string): string; /** @@ -203,10 +241,8 @@ declare module 'url' { * * It performs the inverse operation to {@link domainToUnicode}. * - * This feature is only available if the `node` executable was compiled with `ICU` enabled. If not, the domain names are passed through unchanged. - * * ```js - * import url from 'url'; + * import url from 'node:url'; * * console.log(url.domainToASCII('español.com')); * // Prints xn--espaol-zwa.com @@ -224,10 +260,8 @@ declare module 'url' { * * It performs the inverse operation to {@link domainToASCII}. * - * This feature is only available if the `node` executable was compiled with `ICU` enabled. If not, the domain names are passed through unchanged. - * * ```js - * import url from 'url'; + * import url from 'node:url'; * * console.log(url.domainToUnicode('xn--espaol-zwa.com')); * // Prints español.com @@ -244,7 +278,7 @@ declare module 'url' { * well as ensuring a cross-platform valid absolute path string. * * ```js - * import { fileURLToPath } from 'url'; + * import { fileURLToPath } from 'node:url'; * * const __filename = fileURLToPath(import.meta.url); * @@ -270,7 +304,7 @@ declare module 'url' { * control characters are correctly encoded when converting into a File URL. * * ```js - * import { pathToFileURL } from 'url'; + * import { pathToFileURL } from 'node:url'; * * new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1 * pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX) @@ -288,11 +322,11 @@ declare module 'url' { * expected by the `http.request()` and `https.request()` APIs. * * ```js - * import { urlToHttpOptions } from 'url'; + * import { urlToHttpOptions } from 'node:url'; * const myURL = new URL('https://a:b@測試?abc#foo'); * * console.log(urlToHttpOptions(myURL)); - * + * /* * { * protocol: 'https:', * hostname: 'xn--g6w251d', @@ -305,7 +339,7 @@ declare module 'url' { * } * * ``` - * @since v15.7.0 + * @since v15.7.0, v14.18.0 * @param url The `WHATWG URL` object to convert to an options object. * @return Options object */ @@ -336,7 +370,7 @@ declare module 'url' { * const { * Blob, * resolveObjectURL, - * } = require('buffer'); + * } = require('node:buffer'); * * const blob = new Blob(['hello']); * const id = URL.createObjectURL(blob); @@ -355,14 +389,29 @@ declare module 'url' { * @since v16.7.0 * @experimental */ - static createObjectURL(blob: Blob): string; + static createObjectURL(blob: NodeBlob): string; /** - * Removes the stored `Blob` identified by the given ID. + * Removes the stored `Blob` identified by the given ID. Attempting to revoke a + * ID that isn't registered will silently fail. * @since v16.7.0 * @experimental * @param id A `'blob:nodedata:...` URL string returned by a prior call to `URL.createObjectURL()`. */ static revokeObjectURL(objectUrl: string): void; + /** + * Checks if an `input` relative to the `base` can be parsed to a `URL`. + * + * ```js + * const isValid = URL.canParse('/foo', 'https://example.org/'); // true + * + * const isNotValid = URL.canParse('/foo'); // false + * ``` + * @since v19.9.0 + * @param input The absolute or relative input URL to parse. If `input` is relative, then `base` is required. If `input` is absolute, the `base` is ignored. If `input` is not a string, it is + * `converted to a string` first. + * @param base The base URL to resolve against if the `input` is not absolute. If `base` is not a string, it is `converted to a string` first. + */ + static canParse(input: string, base?: string): boolean; constructor(input: string, base?: string | URL); /** * Gets and sets the fragment portion of the URL. @@ -408,7 +457,7 @@ declare module 'url' { * // Prints example.org * * // Setting the hostname does not change the port - * myURL.hostname = 'example.com:82'; + * myURL.hostname = 'example.com'; * console.log(myURL.href); * // Prints https://example.com:81/foo * @@ -471,7 +520,7 @@ declare module 'url' { * * myURL.password = '123'; * console.log(myURL.href); - * // Prints https://abc:123@example.com + * // Prints https://abc:123@example.com/ * ``` * * Invalid URL characters included in the value assigned to the `password` property @@ -615,14 +664,14 @@ declare module 'url' { * character, while `URLSearchParams` will always encode it: * * ```js - * const myUrl = new URL('https://example.org/abc?foo=~bar'); + * const myURL = new URL('https://example.org/abc?foo=~bar'); * - * console.log(myUrl.search); // prints ?foo=~bar + * console.log(myURL.search); // prints ?foo=~bar * * // Modify the URL via searchParams... - * myUrl.searchParams.sort(); + * myURL.searchParams.sort(); * - * console.log(myUrl.search); // prints ?foo=%7Ebar + * console.log(myURL.search); // prints ?foo=%7Ebar * ``` */ readonly searchParams: URLSearchParams; @@ -711,15 +760,25 @@ declare module 'url' { * @since v7.5.0, v6.13.0 */ class URLSearchParams implements Iterable<[string, string]> { - constructor(init?: URLSearchParams | string | Record> | Iterable<[string, string]> | ReadonlyArray<[string, string]>); + constructor( + init?: + | URLSearchParams + | string + | Record + | Iterable<[string, string]> + | ReadonlyArray<[string, string]>, + ); /** * Append a new name-value pair to the query string. */ append(name: string, value: string): void; /** - * Remove all name-value pairs whose name is `name`. + * If `value` is provided, removes all name-value pairs + * where name is `name` and value is `value`.. + * + * If `value` is not provided, removes all name-value pairs whose name is `name`. */ - delete(name: string): void; + delete(name: string, value?: string): void; /** * Returns an ES6 `Iterator` over each of the name-value pairs in the query. * Each item of the iterator is a JavaScript `Array`. The first item of the `Array`is the `name`, the second item of the `Array` is the `value`. @@ -742,7 +801,10 @@ declare module 'url' { * @param fn Invoked for each name-value pair in the query * @param thisArg To be used as `this` value for when `fn` is called */ - forEach(callback: (this: TThis, value: string, name: string, searchParams: URLSearchParams) => void, thisArg?: TThis): void; + forEach( + callback: (this: TThis, value: string, name: string, searchParams: URLSearchParams) => void, + thisArg?: TThis, + ): void; /** * Returns the value of the first name-value pair whose name is `name`. If there * are no such pairs, `null` is returned. @@ -755,9 +817,15 @@ declare module 'url' { */ getAll(name: string): string[]; /** - * Returns `true` if there is at least one name-value pair whose name is `name`. + * Checks if the `URLSearchParams` object contains key-value pair(s) based on`name` and an optional `value` argument. + * + * If `value` is provided, returns `true` when name-value pair with + * same `name` and `value` exists. + * + * If `value` is not provided, returns `true` if there is at least one name-value + * pair whose name is `name`. */ - has(name: string): boolean; + has(name: string, value?: string): boolean; /** * Returns an ES6 `Iterator` over the names of each name-value pair. * @@ -792,6 +860,11 @@ declare module 'url' { * ``` */ set(name: string, value: string): void; + /** + * The total number of parameter entries. + * @since v19.8.0 + */ + readonly size: number; /** * Sort all existing name-value pairs in-place by their names. Sorting is done * with a [stable sorting algorithm](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability), so relative order between name-value pairs @@ -819,8 +892,7 @@ declare module 'url' { values(): IterableIterator; [Symbol.iterator](): IterableIterator<[string, string]>; } - - import { URL as _URL, URLSearchParams as _URLSearchParams } from 'url'; + import { URL as _URL, URLSearchParams as _URLSearchParams } from "url"; global { interface URLSearchParams extends _URLSearchParams {} interface URL extends _URL {} @@ -833,23 +905,23 @@ declare module 'url' { * https://nodejs.org/api/url.html#the-whatwg-url-api * @since v10.0.0 */ - var URL: - // For compatibility with "dom" and "webworker" URL declarations - typeof globalThis extends { onmessage: any, URL: infer URL } - ? URL - : typeof _URL; + var URL: typeof globalThis extends { + onmessage: any; + URL: infer T; + } ? T + : typeof _URL; /** - * `URLSearchParams` class is a global reference for `require('url').URLSearchParams`. + * `URLSearchParams` class is a global reference for `require('url').URLSearchParams` * https://nodejs.org/api/url.html#class-urlsearchparams * @since v10.0.0 */ - var URLSearchParams: - // For compatibility with "dom" and "webworker" URLSearchParams declarations - typeof globalThis extends { onmessage: any, URLSearchParams: infer URLSearchParams } - ? URLSearchParams - : typeof _URLSearchParams; + var URLSearchParams: typeof globalThis extends { + onmessage: any; + URLSearchParams: infer T; + } ? T + : typeof _URLSearchParams; } } -declare module 'node:url' { - export * from 'url'; +declare module "node:url" { + export * from "url"; } diff --git a/node_modules/@types/node/util.d.ts b/node_modules/@types/node/util.d.ts old mode 100755 new mode 100644 index d0f4c17..08712f5 --- a/node_modules/@types/node/util.d.ts +++ b/node_modules/@types/node/util.d.ts @@ -1,33 +1,49 @@ /** - * The `util` module supports the needs of Node.js internal APIs. Many of the + * The `node:util` module supports the needs of Node.js internal APIs. Many of the * utilities are useful for application and module developers as well. To access * it: * * ```js - * const util = require('util'); + * const util = require('node:util'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/util.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/util.js) */ -declare module 'util' { - import * as types from 'node:util/types'; +declare module "util" { + import * as types from "node:util/types"; export interface InspectOptions { /** - * If set to `true`, getters are going to be - * inspected as well. If set to `'get'` only getters without setter are going - * to be inspected. If set to `'set'` only getters having a corresponding - * setter are going to be inspected. This might cause side effects depending on - * the getter function. - * @default `false` + * If `true`, object's non-enumerable symbols and properties are included in the formatted result. + * `WeakMap` and `WeakSet` entries are also included as well as user defined prototype properties (excluding method properties). + * @default false */ - getters?: 'get' | 'set' | boolean | undefined; showHidden?: boolean | undefined; /** + * Specifies the number of times to recurse while formatting object. + * This is useful for inspecting large objects. + * To recurse up to the maximum call stack size pass `Infinity` or `null`. * @default 2 */ depth?: number | null | undefined; + /** + * If `true`, the output is styled with ANSI color codes. Colors are customizable. + */ colors?: boolean | undefined; + /** + * If `false`, `[util.inspect.custom](depth, opts, inspect)` functions are not invoked. + * @default true + */ customInspect?: boolean | undefined; + /** + * If `true`, `Proxy` inspection includes the target and handler objects. + * @default false + */ showProxy?: boolean | undefined; + /** + * Specifies the maximum number of `Array`, `TypedArray`, `WeakMap`, and `WeakSet` elements + * to include when formatting. Set to `null` or `Infinity` to show all elements. + * Set to `0` or negative to show no elements. + * @default 100 + */ maxArrayLength?: number | null | undefined; /** * Specifies the maximum number of characters to @@ -36,6 +52,12 @@ declare module 'util' { * @default 10000 */ maxStringLength?: number | null | undefined; + /** + * The length at which input values are split across multiple lines. + * Set to `Infinity` to format the input as a single line + * (in combination with `compact` set to `true` or any number >= `1`). + * @default 80 + */ breakLength?: number | undefined; /** * Setting this to `false` causes each object key @@ -45,13 +67,44 @@ declare module 'util' { * `breakLength`. Short array elements are also grouped together. Note that no * text will be reduced below 16 characters, no matter the `breakLength` size. * For more information, see the example below. - * @default `true` + * @default true */ compact?: boolean | number | undefined; + /** + * If set to `true` or a function, all properties of an object, and `Set` and `Map` + * entries are sorted in the resulting string. + * If set to `true` the default sort is used. + * If set to a function, it is used as a compare function. + */ sorted?: boolean | ((a: string, b: string) => number) | undefined; + /** + * If set to `true`, getters are going to be + * inspected as well. If set to `'get'` only getters without setter are going + * to be inspected. If set to `'set'` only getters having a corresponding + * setter are going to be inspected. This might cause side effects depending on + * the getter function. + * @default false + */ + getters?: "get" | "set" | boolean | undefined; + /** + * If set to `true`, an underscore is used to separate every three digits in all bigints and numbers. + * @default false + */ + numericSeparator?: boolean | undefined; } - export type Style = 'special' | 'number' | 'bigint' | 'boolean' | 'undefined' | 'null' | 'string' | 'symbol' | 'date' | 'regexp' | 'module'; - export type CustomInspectFunction = (depth: number, options: InspectOptionsStylized) => string; + export type Style = + | "special" + | "number" + | "bigint" + | "boolean" + | "undefined" + | "null" + | "string" + | "symbol" + | "date" + | "regexp" + | "module"; + export type CustomInspectFunction = (depth: number, options: InspectOptionsStylized) => any; // TODO: , inspect: inspect export interface InspectOptionsStylized extends InspectOptions { stylize(text: string, styleType: Style): string; } @@ -139,7 +192,7 @@ declare module 'util' { * console.error(name); // ENOENT * }); * ``` - * @since v16.0.0 + * @since v16.0.0, v14.17.0 */ export function getSystemErrorMap(): Map; /** @@ -147,7 +200,7 @@ declare module 'util' { * timestamp. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.log('Timestamped message.'); * ``` @@ -159,9 +212,55 @@ declare module 'util' { * Returns the `string` after replacing any surrogate code points * (or equivalently, any unpaired surrogate code units) with the * Unicode "replacement character" U+FFFD. - * @since v16.8.0 + * @since v16.8.0, v14.18.0 */ export function toUSVString(string: string): string; + /** + * Creates and returns an `AbortController` instance whose `AbortSignal` is marked + * as transferable and can be used with `structuredClone()` or `postMessage()`. + * @since v18.11.0 + * @experimental + * @returns A transferable AbortController + */ + export function transferableAbortController(): AbortController; + /** + * Marks the given `AbortSignal` as transferable so that it can be used with`structuredClone()` and `postMessage()`. + * + * ```js + * const signal = transferableAbortSignal(AbortSignal.timeout(100)); + * const channel = new MessageChannel(); + * channel.port2.postMessage(signal, [signal]); + * ``` + * @since v18.11.0 + * @experimental + * @param signal The AbortSignal + * @returns The same AbortSignal + */ + export function transferableAbortSignal(signal: AbortSignal): AbortSignal; + /** + * Listens to abort event on the provided `signal` and + * returns a promise that is fulfilled when the `signal` is + * aborted. If the passed `resource` is garbage collected before the `signal` is + * aborted, the returned promise shall remain pending indefinitely. + * + * ```js + * import { aborted } from 'node:util'; + * + * const dependent = obtainSomethingAbortable(); + * + * aborted(dependent.signal, dependent).then(() => { + * // Do something when dependent is aborted. + * }); + * + * dependent.on('event', () => { + * dependent.abort(); + * }); + * ``` + * @since v19.7.0 + * @experimental + * @param resource Any non-null entity, reference to which is held weakly. + */ + export function aborted(signal: AbortSignal, resource: any): Promise; /** * The `util.inspect()` method returns a string representation of `object` that is * intended for debugging. The output of `util.inspect` may change at any time @@ -188,7 +287,7 @@ declare module 'util' { * Circular references point to their anchor by using a reference index: * * ```js - * const { inspect } = require('util'); + * const { inspect } = require('node:util'); * * const obj = {}; * obj.a = [obj]; @@ -206,7 +305,7 @@ declare module 'util' { * The following example inspects all properties of the `util` object: * * ```js - * const util = require('util'); + * const util = require('node:util'); * * console.log(util.inspect(util, { showHidden: true, depth: null })); * ``` @@ -214,7 +313,7 @@ declare module 'util' { * The following example highlights the effect of the `compact` option: * * ```js - * const util = require('util'); + * const util = require('node:util'); * * const o = { * a: [1, 2, [[ @@ -222,7 +321,7 @@ declare module 'util' { * 'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.', * 'test', * 'foo']], 4], - * b: new Map([['za', 1], ['zb', 'test']]) + * b: new Map([['za', 1], ['zb', 'test']]), * }; * console.log(util.inspect(o, { compact: true, depth: 5, breakLength: 80 })); * @@ -271,7 +370,7 @@ declare module 'util' { * with no remaining strong references may be garbage collected at any time. * * ```js - * const { inspect } = require('util'); + * const { inspect } = require('node:util'); * * const obj = { a: 1 }; * const obj2 = { b: 2 }; @@ -285,13 +384,13 @@ declare module 'util' { * impact the result of `util.inspect()`. * * ```js - * const { inspect } = require('util'); - * const assert = require('assert'); + * const { inspect } = require('node:util'); + * const assert = require('node:assert'); * * const o1 = { * b: [2, 3, 1], * a: '`a` comes before `b`', - * c: new Set([2, 3, 1]) + * c: new Set([2, 3, 1]), * }; * console.log(inspect(o1, { sorted: true })); * // { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } } @@ -301,23 +400,44 @@ declare module 'util' { * const o2 = { * c: new Set([2, 1, 3]), * a: '`a` comes before `b`', - * b: [2, 3, 1] + * b: [2, 3, 1], * }; * assert.strict.equal( * inspect(o1, { sorted: true }), - * inspect(o2, { sorted: true }) + * inspect(o2, { sorted: true }), * ); * ``` * + * The `numericSeparator` option adds an underscore every three digits to all + * numbers. + * + * ```js + * const { inspect } = require('node:util'); + * + * const thousand = 1_000; + * const million = 1_000_000; + * const bigNumber = 123_456_789n; + * const bigDecimal = 1_234.123_45; + * + * console.log(inspect(thousand, { numericSeparator: true })); + * // 1_000 + * console.log(inspect(million, { numericSeparator: true })); + * // 1_000_000 + * console.log(inspect(bigNumber, { numericSeparator: true })); + * // 123_456_789n + * console.log(inspect(bigDecimal, { numericSeparator: true })); + * // 1_234.123_45 + * ``` + * * `util.inspect()` is a synchronous method intended for debugging. Its maximum - * output length is approximately 128 MB. Inputs that result in longer output will + * output length is approximately 128 MiB. Inputs that result in longer output will * be truncated. * @since v0.3.0 * @param object Any JavaScript primitive or `Object`. * @return The representation of `object`. */ export function inspect(object: any, showHidden?: boolean, depth?: number | null, color?: boolean): string; - export function inspect(object: any, options: InspectOptions): string; + export function inspect(object: any, options?: InspectOptions): string; export namespace inspect { let colors: NodeJS.Dict<[number, number]>; let styles: { @@ -339,7 +459,7 @@ declare module 'util' { * Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isArray([]); * // Returns: true @@ -356,7 +476,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `RegExp`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isRegExp(/some regexp/); * // Returns: true @@ -373,7 +493,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Date`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isDate(new Date()); * // Returns: true @@ -390,7 +510,7 @@ declare module 'util' { * Returns `true` if the given `object` is an `Error`. Otherwise, returns`false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isError(new Error()); * // Returns: true @@ -404,7 +524,7 @@ declare module 'util' { * possible to obtain an incorrect result when the `object` argument manipulates`@@toStringTag`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * const obj = { name: 'Error', message: 'an error occurred' }; * * util.isError(obj); @@ -429,8 +549,8 @@ declare module 'util' { * through the `constructor.super_` property. * * ```js - * const util = require('util'); - * const EventEmitter = require('events'); + * const util = require('node:util'); + * const EventEmitter = require('node:events'); * * function MyStream() { * EventEmitter.call(this); @@ -456,7 +576,7 @@ declare module 'util' { * ES6 example using `class` and `extends`: * * ```js - * const EventEmitter = require('events'); + * const EventEmitter = require('node:events'); * * class MyStream extends EventEmitter { * write(data) { @@ -472,7 +592,7 @@ declare module 'util' { * stream.write('With ES6'); * ``` * @since v0.3.0 - * @deprecated Legacy: Use ES2015 class syntax and `extends` keyword instead. + * @legacy Use ES2015 class syntax and `extends` keyword instead. */ export function inherits(constructor: unknown, superConstructor: unknown): void; export type DebugLoggerFunction = (msg: string, ...param: unknown[]) => void; @@ -485,7 +605,7 @@ declare module 'util' { * environment variable, then the returned function operates similar to `console.error()`. If not, then the returned function is a no-op. * * ```js - * const util = require('util'); + * const util = require('node:util'); * const debuglog = util.debuglog('foo'); * * debuglog('hello from foo [%d]', 123); @@ -504,7 +624,7 @@ declare module 'util' { * The `section` supports wildcard also: * * ```js - * const util = require('util'); + * const util = require('node:util'); * const debuglog = util.debuglog('foo-bar'); * * debuglog('hi there, it\'s foo-bar [%d]', 2333); @@ -524,7 +644,7 @@ declare module 'util' { * unnecessary wrapping. * * ```js - * const util = require('util'); + * const util = require('node:util'); * let debuglog = util.debuglog('internals', (debug) => { * // Replace with a logging function that optimizes out * // testing if the section is enabled @@ -542,7 +662,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isBoolean(1); * // Returns: false @@ -559,7 +679,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Buffer`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isBuffer({ length: 0 }); * // Returns: false @@ -576,7 +696,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Function`. Otherwise, returns`false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * function Foo() {} * const Bar = () => {}; @@ -596,7 +716,7 @@ declare module 'util' { * Returns `true` if the given `object` is strictly `null`. Otherwise, returns`false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isNull(0); * // Returns: false @@ -614,7 +734,7 @@ declare module 'util' { * returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isNullOrUndefined(0); * // Returns: false @@ -631,7 +751,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Number`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isNumber(false); * // Returns: false @@ -651,7 +771,7 @@ declare module 'util' { * Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isObject(5); * // Returns: false @@ -663,14 +783,14 @@ declare module 'util' { * // Returns: false * ``` * @since v0.11.5 - * @deprecated Since v4.0.0 - Deprecated: Use `value !== null && typeof value === 'object'` instead. + * @deprecated Since v4.0.0 - Use `value !== null && typeof value === 'object'` instead. */ export function isObject(object: unknown): boolean; /** * Returns `true` if the given `object` is a primitive type. Otherwise, returns`false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isPrimitive(5); * // Returns: true @@ -699,7 +819,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `string`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isString(''); * // Returns: true @@ -718,7 +838,7 @@ declare module 'util' { * Returns `true` if the given `object` is a `Symbol`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * util.isSymbol(5); * // Returns: false @@ -735,7 +855,7 @@ declare module 'util' { * Returns `true` if the given `object` is `undefined`. Otherwise, returns `false`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * const foo = undefined; * util.isUndefined(5); @@ -754,7 +874,7 @@ declare module 'util' { * such a way that it is marked as deprecated. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * exports.obsoleteFunction = util.deprecate(() => { * // Do something here. @@ -770,7 +890,7 @@ declare module 'util' { * the warning will be emitted only once for that `code`. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001'); * const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001'); @@ -824,7 +944,7 @@ declare module 'util' { * first argument will be the rejection reason (or `null` if the `Promise`resolved), and the second argument will be the resolved value. * * ```js - * const util = require('util'); + * const util = require('node:util'); * * async function fn() { * return 'hello world'; @@ -859,56 +979,99 @@ declare module 'util' { * callbackFunction((err, ret) => { * // When the Promise was rejected with `null` it is wrapped with an Error and * // the original value is stored in `reason`. - * err && err.hasOwnProperty('reason') && err.reason === null; // true + * err && Object.hasOwn(err, 'reason') && err.reason === null; // true * }); * ``` * @since v8.2.0 - * @param original An `async` function + * @param fn An `async` function * @return a callback style function */ export function callbackify(fn: () => Promise): (callback: (err: NodeJS.ErrnoException) => void) => void; - export function callbackify(fn: () => Promise): (callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void; - export function callbackify(fn: (arg1: T1) => Promise): (arg1: T1, callback: (err: NodeJS.ErrnoException) => void) => void; - export function callbackify(fn: (arg1: T1) => Promise): (arg1: T1, callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void; - export function callbackify(fn: (arg1: T1, arg2: T2) => Promise): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException) => void) => void; - export function callbackify(fn: (arg1: T1, arg2: T2) => Promise): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; - export function callbackify(fn: (arg1: T1, arg2: T2, arg3: T3) => Promise): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException) => void) => void; + export function callbackify( + fn: () => Promise, + ): (callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void; + export function callbackify( + fn: (arg1: T1) => Promise, + ): (arg1: T1, callback: (err: NodeJS.ErrnoException) => void) => void; + export function callbackify( + fn: (arg1: T1) => Promise, + ): (arg1: T1, callback: (err: NodeJS.ErrnoException, result: TResult) => void) => void; + export function callbackify( + fn: (arg1: T1, arg2: T2) => Promise, + ): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException) => void) => void; + export function callbackify( + fn: (arg1: T1, arg2: T2) => Promise, + ): (arg1: T1, arg2: T2, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; + export function callbackify( + fn: (arg1: T1, arg2: T2, arg3: T3) => Promise, + ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException) => void) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3) => Promise + fn: (arg1: T1, arg2: T2, arg3: T3) => Promise, ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise, ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: NodeJS.ErrnoException) => void) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise - ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise, + ): ( + arg1: T1, + arg2: T2, + arg3: T3, + arg4: T4, + callback: (err: NodeJS.ErrnoException | null, result: TResult) => void, + ) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise, ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: NodeJS.ErrnoException) => void) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise - ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise, + ): ( + arg1: T1, + arg2: T2, + arg3: T3, + arg4: T4, + arg5: T5, + callback: (err: NodeJS.ErrnoException | null, result: TResult) => void, + ) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise - ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6, callback: (err: NodeJS.ErrnoException) => void) => void; + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise, + ): ( + arg1: T1, + arg2: T2, + arg3: T3, + arg4: T4, + arg5: T5, + arg6: T6, + callback: (err: NodeJS.ErrnoException) => void, + ) => void; export function callbackify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise - ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6, callback: (err: NodeJS.ErrnoException | null, result: TResult) => void) => void; + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise, + ): ( + arg1: T1, + arg2: T2, + arg3: T3, + arg4: T4, + arg5: T5, + arg6: T6, + callback: (err: NodeJS.ErrnoException | null, result: TResult) => void, + ) => void; export interface CustomPromisifyLegacy extends Function { __promisify__: TCustom; } export interface CustomPromisifySymbol extends Function { [promisify.custom]: TCustom; } - export type CustomPromisify = CustomPromisifySymbol | CustomPromisifyLegacy; + export type CustomPromisify = + | CustomPromisifySymbol + | CustomPromisifyLegacy; /** * Takes a function following the common error-first callback style, i.e. taking * an `(err, value) => ...` callback as the last argument, and returns a version * that returns promises. * * ```js - * const util = require('util'); - * const fs = require('fs'); + * const util = require('node:util'); + * const fs = require('node:fs'); * * const stat = util.promisify(fs.stat); * stat('.').then((stats) => { @@ -921,8 +1084,8 @@ declare module 'util' { * Or, equivalently using `async function`s: * * ```js - * const util = require('util'); - * const fs = require('fs'); + * const util = require('node:util'); + * const fs = require('node:fs'); * * const stat = util.promisify(fs.stat); * @@ -930,6 +1093,8 @@ declare module 'util' { * const stats = await stat('.'); * console.log(`This directory is owned by ${stats.uid}`); * } + * + * callStat(); * ``` * * If there is an `original[util.promisify.custom]` property present, `promisify`will return its value, see `Custom promisified functions`. @@ -943,7 +1108,7 @@ declare module 'util' { * work as expected unless handled specially: * * ```js - * const util = require('util'); + * const util = require('node:util'); * * class Foo { * constructor() { @@ -969,23 +1134,37 @@ declare module 'util' { * @since v8.0.0 */ export function promisify(fn: CustomPromisify): TCustom; - export function promisify(fn: (callback: (err: any, result: TResult) => void) => void): () => Promise; + export function promisify( + fn: (callback: (err: any, result: TResult) => void) => void, + ): () => Promise; export function promisify(fn: (callback: (err?: any) => void) => void): () => Promise; - export function promisify(fn: (arg1: T1, callback: (err: any, result: TResult) => void) => void): (arg1: T1) => Promise; + export function promisify( + fn: (arg1: T1, callback: (err: any, result: TResult) => void) => void, + ): (arg1: T1) => Promise; export function promisify(fn: (arg1: T1, callback: (err?: any) => void) => void): (arg1: T1) => Promise; - export function promisify(fn: (arg1: T1, arg2: T2, callback: (err: any, result: TResult) => void) => void): (arg1: T1, arg2: T2) => Promise; - export function promisify(fn: (arg1: T1, arg2: T2, callback: (err?: any) => void) => void): (arg1: T1, arg2: T2) => Promise; - export function promisify(fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err: any, result: TResult) => void) => void): (arg1: T1, arg2: T2, arg3: T3) => Promise; - export function promisify(fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err?: any) => void) => void): (arg1: T1, arg2: T2, arg3: T3) => Promise; + export function promisify( + fn: (arg1: T1, arg2: T2, callback: (err: any, result: TResult) => void) => void, + ): (arg1: T1, arg2: T2) => Promise; + export function promisify( + fn: (arg1: T1, arg2: T2, callback: (err?: any) => void) => void, + ): (arg1: T1, arg2: T2) => Promise; + export function promisify( + fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err: any, result: TResult) => void) => void, + ): (arg1: T1, arg2: T2, arg3: T3) => Promise; + export function promisify( + fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err?: any) => void) => void, + ): (arg1: T1, arg2: T2, arg3: T3) => Promise; export function promisify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: any, result: TResult) => void) => void + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err: any, result: TResult) => void) => void, ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise; - export function promisify(fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err?: any) => void) => void): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise; + export function promisify( + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, callback: (err?: any) => void) => void, + ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise; export function promisify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: any, result: TResult) => void) => void + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err: any, result: TResult) => void) => void, ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise; export function promisify( - fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err?: any) => void) => void + fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, callback: (err?: any) => void) => void, ): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise; export function promisify(fn: Function): Function; export namespace promisify { @@ -998,13 +1177,9 @@ declare module 'util' { * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextDecoder` API. * * ```js - * const decoder = new TextDecoder('shift_jis'); - * let string = ''; - * let buffer; - * while (buffer = getNextChunkSomehow()) { - * string += decoder.decode(buffer, { stream: true }); - * } - * string += decoder.decode(); // end-of-stream + * const decoder = new TextDecoder(); + * const u8arr = new Uint8Array([72, 101, 108, 108, 111]); + * console.log(decoder.decode(u8arr)); // Hello * ``` * @since v8.3.0 */ @@ -1028,7 +1203,7 @@ declare module 'util' { options?: { fatal?: boolean | undefined; ignoreBOM?: boolean | undefined; - } + }, ); /** * Decodes the `input` and returns a string. If `options.stream` is `true`, any @@ -1036,13 +1211,13 @@ declare module 'util' { * internally and emitted after the next call to `textDecoder.decode()`. * * If `textDecoder.fatal` is `true`, decoding errors that occur will result in a`TypeError` being thrown. - * @param input An `ArrayBuffer`, `DataView` or `TypedArray` instance containing the encoded data. + * @param input An `ArrayBuffer`, `DataView`, or `TypedArray` instance containing the encoded data. */ decode( input?: NodeJS.ArrayBufferView | ArrayBuffer | null, options?: { stream?: boolean | undefined; - } + }, ): string; } export interface EncodeIntoResult { @@ -1056,6 +1231,8 @@ declare module 'util' { written: number; } export { types }; + + //// TextEncoder/Decoder /** * An implementation of the [WHATWG Encoding Standard](https://encoding.spec.whatwg.org/) `TextEncoder` API. All * instances of `TextEncoder` only support UTF-8 encoding. @@ -1094,12 +1271,391 @@ declare module 'util' { */ encodeInto(src: string, dest: Uint8Array): EncodeIntoResult; } + import { TextDecoder as _TextDecoder, TextEncoder as _TextEncoder } from "util"; + global { + /** + * `TextDecoder` class is a global reference for `require('util').TextDecoder` + * https://nodejs.org/api/globals.html#textdecoder + * @since v11.0.0 + */ + var TextDecoder: typeof globalThis extends { + onmessage: any; + TextDecoder: infer TextDecoder; + } ? TextDecoder + : typeof _TextDecoder; + /** + * `TextEncoder` class is a global reference for `require('util').TextEncoder` + * https://nodejs.org/api/globals.html#textencoder + * @since v11.0.0 + */ + var TextEncoder: typeof globalThis extends { + onmessage: any; + TextEncoder: infer TextEncoder; + } ? TextEncoder + : typeof _TextEncoder; + } + + //// parseArgs + /** + * Provides a higher level API for command-line argument parsing than interacting + * with `process.argv` directly. Takes a specification for the expected arguments + * and returns a structured object with the parsed options and positionals. + * + * ```js + * import { parseArgs } from 'node:util'; + * const args = ['-f', '--bar', 'b']; + * const options = { + * foo: { + * type: 'boolean', + * short: 'f', + * }, + * bar: { + * type: 'string', + * }, + * }; + * const { + * values, + * positionals, + * } = parseArgs({ args, options }); + * console.log(values, positionals); + * // Prints: [Object: null prototype] { foo: true, bar: 'b' } [] + * ``` + * @since v18.3.0, v16.17.0 + * @param config Used to provide arguments for parsing and to configure the parser. `config` supports the following properties: + * @return The parsed command line arguments: + */ + export function parseArgs(config?: T): ParsedResults; + interface ParseArgsOptionConfig { + /** + * Type of argument. + */ + type: "string" | "boolean"; + /** + * Whether this option can be provided multiple times. + * If `true`, all values will be collected in an array. + * If `false`, values for the option are last-wins. + * @default false. + */ + multiple?: boolean | undefined; + /** + * A single character alias for the option. + */ + short?: string | undefined; + /** + * The default option value when it is not set by args. + * It must be of the same type as the the `type` property. + * When `multiple` is `true`, it must be an array. + * @since v18.11.0 + */ + default?: string | boolean | string[] | boolean[] | undefined; + } + interface ParseArgsOptionsConfig { + [longOption: string]: ParseArgsOptionConfig; + } + export interface ParseArgsConfig { + /** + * Array of argument strings. + */ + args?: string[] | undefined; + /** + * Used to describe arguments known to the parser. + */ + options?: ParseArgsOptionsConfig | undefined; + /** + * Should an error be thrown when unknown arguments are encountered, + * or when arguments are passed that do not match the `type` configured in `options`. + * @default true + */ + strict?: boolean | undefined; + /** + * Whether this command accepts positional arguments. + */ + allowPositionals?: boolean | undefined; + /** + * Return the parsed tokens. This is useful for extending the built-in behavior, + * from adding additional checks through to reprocessing the tokens in different ways. + * @default false + */ + tokens?: boolean | undefined; + } + /* + IfDefaultsTrue and IfDefaultsFalse are helpers to handle default values for missing boolean properties. + TypeScript does not have exact types for objects: https://github.com/microsoft/TypeScript/issues/12936 + This means it is impossible to distinguish between "field X is definitely not present" and "field X may or may not be present". + But we expect users to generally provide their config inline or `as const`, which means TS will always know whether a given field is present. + So this helper treats "not definitely present" (i.e., not `extends boolean`) as being "definitely not present", i.e. it should have its default value. + This is technically incorrect but is a much nicer UX for the common case. + The IfDefaultsTrue version is for things which default to true; the IfDefaultsFalse version is for things which default to false. + */ + type IfDefaultsTrue = T extends true ? IfTrue + : T extends false ? IfFalse + : IfTrue; + + // we put the `extends false` condition first here because `undefined` compares like `any` when `strictNullChecks: false` + type IfDefaultsFalse = T extends false ? IfFalse + : T extends true ? IfTrue + : IfFalse; + + type ExtractOptionValue = IfDefaultsTrue< + T["strict"], + O["type"] extends "string" ? string : O["type"] extends "boolean" ? boolean : string | boolean, + string | boolean + >; + + type ParsedValues = + & IfDefaultsTrue + & (T["options"] extends ParseArgsOptionsConfig ? { + -readonly [LongOption in keyof T["options"]]: IfDefaultsFalse< + T["options"][LongOption]["multiple"], + undefined | Array>, + undefined | ExtractOptionValue + >; + } + : {}); + + type ParsedPositionals = IfDefaultsTrue< + T["strict"], + IfDefaultsFalse, + IfDefaultsTrue + >; + + type PreciseTokenForOptions< + K extends string, + O extends ParseArgsOptionConfig, + > = O["type"] extends "string" ? { + kind: "option"; + index: number; + name: K; + rawName: string; + value: string; + inlineValue: boolean; + } + : O["type"] extends "boolean" ? { + kind: "option"; + index: number; + name: K; + rawName: string; + value: undefined; + inlineValue: undefined; + } + : OptionToken & { name: K }; + + type TokenForOptions< + T extends ParseArgsConfig, + K extends keyof T["options"] = keyof T["options"], + > = K extends unknown + ? T["options"] extends ParseArgsOptionsConfig ? PreciseTokenForOptions + : OptionToken + : never; + + type ParsedOptionToken = IfDefaultsTrue, OptionToken>; + + type ParsedPositionalToken = IfDefaultsTrue< + T["strict"], + IfDefaultsFalse, + IfDefaultsTrue + >; + + type ParsedTokens = Array< + ParsedOptionToken | ParsedPositionalToken | { kind: "option-terminator"; index: number } + >; + + type PreciseParsedResults = IfDefaultsFalse< + T["tokens"], + { + values: ParsedValues; + positionals: ParsedPositionals; + tokens: ParsedTokens; + }, + { + values: ParsedValues; + positionals: ParsedPositionals; + } + >; + + type OptionToken = + | { kind: "option"; index: number; name: string; rawName: string; value: string; inlineValue: boolean } + | { + kind: "option"; + index: number; + name: string; + rawName: string; + value: undefined; + inlineValue: undefined; + }; + + type Token = + | OptionToken + | { kind: "positional"; index: number; value: string } + | { kind: "option-terminator"; index: number }; + + // If ParseArgsConfig extends T, then the user passed config constructed elsewhere. + // So we can't rely on the `"not definitely present" implies "definitely not present"` assumption mentioned above. + type ParsedResults = ParseArgsConfig extends T ? { + values: { + [longOption: string]: undefined | string | boolean | Array; + }; + positionals: string[]; + tokens?: Token[]; + } + : PreciseParsedResults; + + /** + * An implementation of [the MIMEType class](https://bmeck.github.io/node-proposal-mime-api/). + * + * In accordance with browser conventions, all properties of `MIMEType` objects + * are implemented as getters and setters on the class prototype, rather than as + * data properties on the object itself. + * + * A MIME string is a structured string containing multiple meaningful + * components. When parsed, a `MIMEType` object is returned containing + * properties for each of these components. + * @since v19.1.0, v18.13.0 + * @experimental + */ + export class MIMEType { + /** + * Creates a new MIMEType object by parsing the input. + * + * A `TypeError` will be thrown if the `input` is not a valid MIME. + * Note that an effort will be made to coerce the given values into strings. + * @param input The input MIME to parse. + */ + constructor(input: string | { toString: () => string }); + + /** + * Gets and sets the type portion of the MIME. + * + * ```js + * import { MIMEType } from 'node:util'; + * + * const myMIME = new MIMEType('text/javascript'); + * console.log(myMIME.type); + * // Prints: text + * myMIME.type = 'application'; + * console.log(myMIME.type); + * // Prints: application + * console.log(String(myMIME)); + * // Prints: application/javascript + * ``` + */ + type: string; + /** + * Gets and sets the subtype portion of the MIME. + * + * ```js + * import { MIMEType } from 'node:util'; + * + * const myMIME = new MIMEType('text/ecmascript'); + * console.log(myMIME.subtype); + * // Prints: ecmascript + * myMIME.subtype = 'javascript'; + * console.log(myMIME.subtype); + * // Prints: javascript + * console.log(String(myMIME)); + * // Prints: text/javascript + * ``` + */ + subtype: string; + /** + * Gets the essence of the MIME. This property is read only. + * Use `mime.type` or `mime.subtype` to alter the MIME. + * + * ```js + * import { MIMEType } from 'node:util'; + * + * const myMIME = new MIMEType('text/javascript;key=value'); + * console.log(myMIME.essence); + * // Prints: text/javascript + * myMIME.type = 'application'; + * console.log(myMIME.essence); + * // Prints: application/javascript + * console.log(String(myMIME)); + * // Prints: application/javascript;key=value + * ``` + */ + readonly essence: string; + /** + * Gets the `MIMEParams` object representing the + * parameters of the MIME. This property is read-only. See `MIMEParams` documentation for details. + */ + readonly params: MIMEParams; + /** + * The `toString()` method on the `MIMEType` object returns the serialized MIME. + * + * Because of the need for standard compliance, this method does not allow users + * to customize the serialization process of the MIME. + */ + toString(): string; + } + /** + * The `MIMEParams` API provides read and write access to the parameters of a`MIMEType`. + * @since v19.1.0, v18.13.0 + */ + export class MIMEParams { + /** + * Remove all name-value pairs whose name is `name`. + */ + delete(name: string): void; + /** + * Returns an iterator over each of the name-value pairs in the parameters. + * Each item of the iterator is a JavaScript `Array`. The first item of the array + * is the `name`, the second item of the array is the `value`. + */ + entries(): IterableIterator<[name: string, value: string]>; + /** + * Returns the value of the first name-value pair whose name is `name`. If there + * are no such pairs, `null` is returned. + * @return or `null` if there is no name-value pair with the given `name`. + */ + get(name: string): string | null; + /** + * Returns `true` if there is at least one name-value pair whose name is `name`. + */ + has(name: string): boolean; + /** + * Returns an iterator over the names of each name-value pair. + * + * ```js + * import { MIMEType } from 'node:util'; + * + * const { params } = new MIMEType('text/plain;foo=0;bar=1'); + * for (const name of params.keys()) { + * console.log(name); + * } + * // Prints: + * // foo + * // bar + * ``` + */ + keys(): IterableIterator; + /** + * Sets the value in the `MIMEParams` object associated with `name` to`value`. If there are any pre-existing name-value pairs whose names are `name`, + * set the first such pair's value to `value`. + * + * ```js + * import { MIMEType } from 'node:util'; + * + * const { params } = new MIMEType('text/plain;foo=0;bar=1'); + * params.set('foo', 'def'); + * params.set('baz', 'xyz'); + * console.log(params.toString()); + * // Prints: foo=def;bar=1;baz=xyz + * ``` + */ + set(name: string, value: string): void; + /** + * Returns an iterator over the values of each name-value pair. + */ + values(): IterableIterator; + /** + * Returns an iterator over each of the name-value pairs in the parameters. + */ + [Symbol.iterator]: typeof MIMEParams.prototype.entries; + } } -declare module 'util/types' { - export * from 'util/types'; -} -declare module 'util/types' { - import { KeyObject, webcrypto } from 'node:crypto'; +declare module "util/types" { + import { KeyObject, webcrypto } from "node:crypto"; /** * Returns `true` if the value is a built-in [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) or * [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) instance. @@ -1365,7 +1921,10 @@ declare module 'util/types' { * ``` * @since v10.0.0 */ - function isMap(object: T | {}): object is T extends ReadonlyMap ? (unknown extends T ? never : ReadonlyMap) : Map; + function isMap( + object: T | {}, + ): object is T extends ReadonlyMap ? (unknown extends T ? never : ReadonlyMap) + : Map; /** * Returns `true` if the value is an iterator returned for a built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) instance. * @@ -1391,12 +1950,40 @@ declare module 'util/types' { */ function isModuleNamespaceObject(value: unknown): boolean; /** - * Returns `true` if the value is an instance of a built-in `Error` type. + * Returns `true` if the value was returned by the constructor of a [built-in `Error` type](https://tc39.es/ecma262/#sec-error-objects). * * ```js - * util.types.isNativeError(new Error()); // Returns true - * util.types.isNativeError(new TypeError()); // Returns true - * util.types.isNativeError(new RangeError()); // Returns true + * console.log(util.types.isNativeError(new Error())); // true + * console.log(util.types.isNativeError(new TypeError())); // true + * console.log(util.types.isNativeError(new RangeError())); // true + * ``` + * + * Subclasses of the native error types are also native errors: + * + * ```js + * class MyError extends Error {} + * console.log(util.types.isNativeError(new MyError())); // true + * ``` + * + * A value being `instanceof` a native error class is not equivalent to `isNativeError()`returning `true` for that value. `isNativeError()` returns `true` for errors + * which come from a different [realm](https://tc39.es/ecma262/#realm) while `instanceof Error` returns `false`for these errors: + * + * ```js + * const vm = require('node:vm'); + * const context = vm.createContext({}); + * const myError = vm.runInContext('new Error()', context); + * console.log(util.types.isNativeError(myError)); // true + * console.log(myError instanceof Error); // false + * ``` + * + * Conversely, `isNativeError()` returns `false` for all objects which were not + * returned by the constructor of a native error. That includes values + * which are `instanceof` native errors: + * + * ```js + * const myError = { __proto__: Error.prototype }; + * console.log(util.types.isNativeError(myError)); // false + * console.log(myError instanceof Error); // true * ``` * @since v10.0.0 */ @@ -1451,7 +2038,9 @@ declare module 'util/types' { * ``` * @since v10.0.0 */ - function isSet(object: T | {}): object is T extends ReadonlySet ? (unknown extends T ? never : ReadonlySet) : Set; + function isSet( + object: T | {}, + ): object is T extends ReadonlySet ? (unknown extends T ? never : ReadonlySet) : Set; /** * Returns `true` if the value is an iterator returned for a built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) instance. * @@ -1586,9 +2175,9 @@ declare module 'util/types' { */ function isCryptoKey(object: unknown): object is webcrypto.CryptoKey; } -declare module 'node:util' { - export * from 'util'; +declare module "node:util" { + export * from "util"; } -declare module 'node:util/types' { - export * from 'util/types'; +declare module "node:util/types" { + export * from "util/types"; } diff --git a/node_modules/@types/node/v8.d.ts b/node_modules/@types/node/v8.d.ts old mode 100755 new mode 100644 index f467fcc..6790e76 --- a/node_modules/@types/node/v8.d.ts +++ b/node_modules/@types/node/v8.d.ts @@ -1,13 +1,13 @@ /** - * The `v8` module exposes APIs that are specific to the version of [V8](https://developers.google.com/v8/) built into the Node.js binary. It can be accessed using: + * The `node:v8` module exposes APIs that are specific to the version of [V8](https://developers.google.com/v8/) built into the Node.js binary. It can be accessed using: * * ```js - * const v8 = require('v8'); + * const v8 = require('node:v8'); * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/v8.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/v8.js) */ -declare module 'v8' { - import { Readable } from 'node:stream'; +declare module "v8" { + import { Readable } from "node:stream"; interface HeapSpaceInfo { space_name: string; space_size: number; @@ -29,6 +29,9 @@ declare module 'v8' { does_zap_garbage: DoesZapCodeSpaceFlag; number_of_native_contexts: number; number_of_detached_contexts: number; + total_global_handles_size: number; + used_global_handles_size: number; + external_memory: number; } interface HeapCodeStatistics { code_and_metadata_size: number; @@ -68,6 +71,15 @@ declare module 'v8' { * of contexts that were detached and not yet garbage collected. This number * being non-zero indicates a potential memory leak. * + * `total_global_handles_size` The value of total\_global\_handles\_size is the + * total memory size of V8 global handles. + * + * `used_global_handles_size` The value of used\_global\_handles\_size is the + * used memory size of V8 global handles. + * + * `external_memory` The value of external\_memory is the memory size of array + * buffers and external strings. + * * ```js * { * total_heap_size: 7326976, @@ -80,7 +92,10 @@ declare module 'v8' { * peak_malloced_memory: 1127496, * does_zap_garbage: 0, * number_of_native_contexts: 1, - * number_of_detached_contexts: 0 + * number_of_detached_contexts: 0, + * total_global_handles_size: 8192, + * used_global_handles_size: 3296, + * external_memory: 318824 * } * ``` * @since v1.0.0 @@ -149,7 +164,7 @@ declare module 'v8' { * * ```js * // Print GC events to stdout for one minute. - * const v8 = require('v8'); + * const v8 = require('node:v8'); * v8.setFlagsFromString('--trace_gc'); * setTimeout(() => { v8.setFlagsFromString('--notrace_gc'); }, 60e3); * ``` @@ -163,14 +178,21 @@ declare module 'v8' { * Chrome DevTools. The JSON schema is undocumented and specific to the * V8 engine. Therefore, the schema may change from one version of V8 to the next. * + * Creating a heap snapshot requires memory about twice the size of the heap at + * the time the snapshot is created. This results in the risk of OOM killers + * terminating the process. + * + * Generating a snapshot is a synchronous operation which blocks the event loop + * for a duration depending on the heap size. + * * ```js * // Print heap snapshot to the console - * const v8 = require('v8'); + * const v8 = require('node:v8'); * const stream = v8.getHeapSnapshot(); * stream.pipe(process.stdout); * ``` * @since v11.13.0 - * @return A Readable Stream containing the V8 heap snapshot + * @return A Readable containing the V8 heap snapshot. */ function getHeapSnapshot(): Readable; /** @@ -182,13 +204,20 @@ declare module 'v8' { * A heap snapshot is specific to a single V8 isolate. When using `worker threads`, a heap snapshot generated from the main thread will * not contain any information about the workers, and vice versa. * + * Creating a heap snapshot requires memory about twice the size of the heap at + * the time the snapshot is created. This results in the risk of OOM killers + * terminating the process. + * + * Generating a snapshot is a synchronous operation which blocks the event loop + * for a duration depending on the heap size. + * * ```js - * const { writeHeapSnapshot } = require('v8'); + * const { writeHeapSnapshot } = require('node:v8'); * const { * Worker, * isMainThread, - * parentPort - * } = require('worker_threads'); + * parentPort, + * } = require('node:worker_threads'); * * if (isMainThread) { * const worker = new Worker(__filename); @@ -219,13 +248,16 @@ declare module 'v8' { */ function writeHeapSnapshot(filename?: string): string; /** - * Returns an object with the following properties: + * Get statistics about code and its metadata in the heap, see + * V8[`GetHeapCodeAndMetadataStatistics`](https://v8docs.nodesource.com/node-13.2/d5/dda/classv8_1_1_isolate.html#a6079122af17612ef54ef3348ce170866) API. Returns an object with the + * following properties: * * ```js * { * code_and_metadata_size: 212208, * bytecode_and_metadata_size: 161368, - * external_script_source_size: 1410794 + * external_script_source_size: 1410794, + * cpu_profiler_metadata_size: 0, * } * ``` * @since v12.8.0 @@ -275,7 +307,7 @@ declare module 'v8' { */ writeDouble(value: number): void; /** - * Write raw bytes into the serializer’s internal buffer. The deserializer + * Write raw bytes into the serializer's internal buffer. The deserializer * will require a way to compute the length of the buffer. * For use inside of a custom `serializer._writeHostObject()`. */ @@ -331,7 +363,7 @@ declare module 'v8' { */ readDouble(): number; /** - * Read raw bytes from the deserializer’s internal buffer. The `length` parameter + * Read raw bytes from the deserializer's internal buffer. The `length` parameter * must correspond to the length of the buffer that was passed to `serializer.writeRawBytes()`. * For use inside of a custom `deserializer._readHostObject()`. */ @@ -344,6 +376,10 @@ declare module 'v8' { class DefaultDeserializer extends Deserializer {} /** * Uses a `DefaultSerializer` to serialize `value` into a buffer. + * + * `ERR_BUFFER_TOO_LARGE` will be thrown when trying to + * serialize a huge object which requires buffer + * larger than `buffer.constants.MAX_LENGTH`. * @since v8.0.0 */ function serialize(value: any): Buffer; @@ -362,17 +398,238 @@ declare module 'v8' { * * When the process is about to exit, one last coverage will still be written to * disk unless {@link stopCoverage} is invoked before the process exits. - * @since v15.1.0, v12.22.0 + * @since v15.1.0, v14.18.0, v12.22.0 */ function takeCoverage(): void; /** * The `v8.stopCoverage()` method allows the user to stop the coverage collection * started by `NODE_V8_COVERAGE`, so that V8 can release the execution count * records and optimize code. This can be used in conjunction with {@link takeCoverage} if the user wants to collect the coverage on demand. - * @since v15.1.0, v12.22.0 + * @since v15.1.0, v14.18.0, v12.22.0 */ function stopCoverage(): void; + /** + * This API collects GC data in current thread. + * @since v19.6.0, v18.15.0 + */ + class GCProfiler { + /** + * Start collecting GC data. + * @since v19.6.0, v18.15.0 + */ + start(): void; + /** + * Stop collecting GC data and return an object.The content of object + * is as follows. + * + * ```json + * { + * "version": 1, + * "startTime": 1674059033862, + * "statistics": [ + * { + * "gcType": "Scavenge", + * "beforeGC": { + * "heapStatistics": { + * "totalHeapSize": 5005312, + * "totalHeapSizeExecutable": 524288, + * "totalPhysicalSize": 5226496, + * "totalAvailableSize": 4341325216, + * "totalGlobalHandlesSize": 8192, + * "usedGlobalHandlesSize": 2112, + * "usedHeapSize": 4883840, + * "heapSizeLimit": 4345298944, + * "mallocedMemory": 254128, + * "externalMemory": 225138, + * "peakMallocedMemory": 181760 + * }, + * "heapSpaceStatistics": [ + * { + * "spaceName": "read_only_space", + * "spaceSize": 0, + * "spaceUsedSize": 0, + * "spaceAvailableSize": 0, + * "physicalSpaceSize": 0 + * } + * ] + * }, + * "cost": 1574.14, + * "afterGC": { + * "heapStatistics": { + * "totalHeapSize": 6053888, + * "totalHeapSizeExecutable": 524288, + * "totalPhysicalSize": 5500928, + * "totalAvailableSize": 4341101384, + * "totalGlobalHandlesSize": 8192, + * "usedGlobalHandlesSize": 2112, + * "usedHeapSize": 4059096, + * "heapSizeLimit": 4345298944, + * "mallocedMemory": 254128, + * "externalMemory": 225138, + * "peakMallocedMemory": 181760 + * }, + * "heapSpaceStatistics": [ + * { + * "spaceName": "read_only_space", + * "spaceSize": 0, + * "spaceUsedSize": 0, + * "spaceAvailableSize": 0, + * "physicalSpaceSize": 0 + * } + * ] + * } + * } + * ], + * "endTime": 1674059036865 + * } + * ``` + * + * Here's an example. + * + * ```js + * const { GCProfiler } = require('v8'); + * const profiler = new GCProfiler(); + * profiler.start(); + * setTimeout(() => { + * console.log(profiler.stop()); + * }, 1000); + * ``` + * @since v19.6.0, v18.15.0 + */ + stop(): GCProfilerResult; + } + interface GCProfilerResult { + version: number; + startTime: number; + endTime: number; + statistics: Array<{ + gcType: string; + cost: number; + beforeGC: { + heapStatistics: HeapStatistics; + heapSpaceStatistics: HeapSpaceStatistics[]; + }; + afterGC: { + heapStatistics: HeapStatistics; + heapSpaceStatistics: HeapSpaceStatistics[]; + }; + }>; + } + interface HeapStatistics { + totalHeapSize: number; + totalHeapSizeExecutable: number; + totalPhysicalSize: number; + totalAvailableSize: number; + totalGlobalHandlesSize: number; + usedGlobalHandlesSize: number; + usedHeapSize: number; + heapSizeLimit: number; + mallocedMemory: number; + externalMemory: number; + peakMallocedMemory: number; + } + interface HeapSpaceStatistics { + spaceName: string; + spaceSize: number; + spaceUsedSize: number; + spaceAvailableSize: number; + physicalSpaceSize: number; + } + /** + * Called when a promise is constructed. This does not mean that corresponding before/after events will occur, only that the possibility exists. This will + * happen if a promise is created without ever getting a continuation. + * @since v17.1.0, v16.14.0 + * @param promise The promise being created. + * @param parent The promise continued from, if applicable. + */ + interface Init { + (promise: Promise, parent: Promise): void; + } + /** + * Called before a promise continuation executes. This can be in the form of `then()`, `catch()`, or `finally()` handlers or an await resuming. + * + * The before callback will be called 0 to N times. The before callback will typically be called 0 times if no continuation was ever made for the promise. + * The before callback may be called many times in the case where many continuations have been made from the same promise. + * @since v17.1.0, v16.14.0 + */ + interface Before { + (promise: Promise): void; + } + /** + * Called immediately after a promise continuation executes. This may be after a `then()`, `catch()`, or `finally()` handler or before an await after another await. + * @since v17.1.0, v16.14.0 + */ + interface After { + (promise: Promise): void; + } + /** + * Called when the promise receives a resolution or rejection value. This may occur synchronously in the case of {@link Promise.resolve()} or + * {@link Promise.reject()}. + * @since v17.1.0, v16.14.0 + */ + interface Settled { + (promise: Promise): void; + } + /** + * Key events in the lifetime of a promise have been categorized into four areas: creation of a promise, before/after a continuation handler is called or + * around an await, and when the promise resolves or rejects. + * + * Because promises are asynchronous resources whose lifecycle is tracked via the promise hooks mechanism, the `init()`, `before()`, `after()`, and + * `settled()` callbacks must not be async functions as they create more promises which would produce an infinite loop. + * @since v17.1.0, v16.14.0 + */ + interface HookCallbacks { + init?: Init; + before?: Before; + after?: After; + settled?: Settled; + } + interface PromiseHooks { + /** + * The `init` hook must be a plain function. Providing an async function will throw as it would produce an infinite microtask loop. + * @since v17.1.0, v16.14.0 + * @param init The {@link Init | `init` callback} to call when a promise is created. + * @return Call to stop the hook. + */ + onInit: (init: Init) => Function; + /** + * The `settled` hook must be a plain function. Providing an async function will throw as it would produce an infinite microtask loop. + * @since v17.1.0, v16.14.0 + * @param settled The {@link Settled | `settled` callback} to call when a promise is created. + * @return Call to stop the hook. + */ + onSettled: (settled: Settled) => Function; + /** + * The `before` hook must be a plain function. Providing an async function will throw as it would produce an infinite microtask loop. + * @since v17.1.0, v16.14.0 + * @param before The {@link Before | `before` callback} to call before a promise continuation executes. + * @return Call to stop the hook. + */ + onBefore: (before: Before) => Function; + /** + * The `after` hook must be a plain function. Providing an async function will throw as it would produce an infinite microtask loop. + * @since v17.1.0, v16.14.0 + * @param after The {@link After | `after` callback} to call after a promise continuation executes. + * @return Call to stop the hook. + */ + onAfter: (after: After) => Function; + /** + * Registers functions to be called for different lifetime events of each promise. + * The callbacks `init()`/`before()`/`after()`/`settled()` are called for the respective events during a promise's lifetime. + * All callbacks are optional. For example, if only promise creation needs to be tracked, then only the init callback needs to be passed. + * The hook callbacks must be plain functions. Providing async functions will throw as it would produce an infinite microtask loop. + * @since v17.1.0, v16.14.0 + * @param callbacks The {@link HookCallbacks | Hook Callbacks} to register + * @return Used for disabling hooks + */ + createHook: (callbacks: HookCallbacks) => Function; + } + /** + * The `promiseHooks` interface can be used to track promise lifecycle events. + * @since v17.1.0, v16.14.0 + */ + const promiseHooks: PromiseHooks; } -declare module 'node:v8' { - export * from 'v8'; +declare module "node:v8" { + export * from "v8"; } diff --git a/node_modules/@types/node/vm.d.ts b/node_modules/@types/node/vm.d.ts old mode 100755 new mode 100644 index a46b391..3a310cc --- a/node_modules/@types/node/vm.d.ts +++ b/node_modules/@types/node/vm.d.ts @@ -1,7 +1,9 @@ /** - * The `vm` module enables compiling and running code within V8 Virtual - * Machine contexts. **The `vm` module is not a security mechanism. Do** - * **not use it to run untrusted code.** + * The `node:vm` module enables compiling and running code within V8 Virtual + * Machine contexts. + * + * **The `node:vm` module is not a security** + * **mechanism. Do not use it to run untrusted code.** * * JavaScript code can be compiled and run immediately or * compiled, saved, and run later. @@ -15,7 +17,7 @@ * code are reflected in the context object. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * const x = 1; * @@ -32,9 +34,10 @@ * * console.log(x); // 1; y is not defined. * ``` - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/vm.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/vm.js) */ -declare module 'vm' { +declare module "vm" { + import { ImportAttributes } from "node:module"; interface Context extends NodeJS.Dict {} interface BaseOptions { /** @@ -54,11 +57,19 @@ declare module 'vm' { columnOffset?: number | undefined; } interface ScriptOptions extends BaseOptions { - displayErrors?: boolean | undefined; - timeout?: number | undefined; - cachedData?: Buffer | undefined; + /** + * V8's code cache data for the supplied source. + */ + cachedData?: Buffer | NodeJS.ArrayBufferView | undefined; /** @deprecated in favor of `script.createCachedData()` */ produceCachedData?: boolean | undefined; + /** + * Called during evaluation of this module when `import()` is called. + * If this option is not specified, calls to `import()` will reject with `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`. + */ + importModuleDynamically?: + | ((specifier: string, script: Script, importAttributes: ImportAttributes) => Module) + | undefined; } interface RunningScriptOptions extends BaseOptions { /** @@ -78,10 +89,31 @@ declare module 'vm' { * Default: `false`. */ breakOnSigint?: boolean | undefined; + } + interface RunningScriptInNewContextOptions extends RunningScriptOptions { + /** + * Human-readable name of the newly created context. + */ + contextName?: CreateContextOptions["name"]; + /** + * Origin corresponding to the newly created context for display purposes. The origin should be formatted like a URL, + * but with only the scheme, host, and port (if necessary), like the value of the `url.origin` property of a `URL` object. + * Most notably, this string should omit the trailing slash, as that denotes a path. + */ + contextOrigin?: CreateContextOptions["origin"]; + contextCodeGeneration?: CreateContextOptions["codeGeneration"]; /** * If set to `afterEvaluate`, microtasks will be run immediately after the script has run. */ - microtaskMode?: 'afterEvaluate' | undefined; + microtaskMode?: CreateContextOptions["microtaskMode"]; + } + interface RunningCodeOptions extends RunningScriptOptions { + cachedData?: ScriptOptions["cachedData"]; + importModuleDynamically?: ScriptOptions["importModuleDynamically"]; + } + interface RunningCodeInNewContextOptions extends RunningScriptInNewContextOptions { + cachedData?: ScriptOptions["cachedData"]; + importModuleDynamically?: ScriptOptions["importModuleDynamically"]; } interface CompileFunctionOptions extends BaseOptions { /** @@ -118,31 +150,34 @@ declare module 'vm' { origin?: string | undefined; codeGeneration?: | { - /** - * If set to false any calls to eval or function constructors (Function, GeneratorFunction, etc) - * will throw an EvalError. - * @default true - */ - strings?: boolean | undefined; - /** - * If set to false any attempt to compile a WebAssembly module will throw a WebAssembly.CompileError. - * @default true - */ - wasm?: boolean | undefined; - } + /** + * If set to false any calls to eval or function constructors (Function, GeneratorFunction, etc) + * will throw an EvalError. + * @default true + */ + strings?: boolean | undefined; + /** + * If set to false any attempt to compile a WebAssembly module will throw a WebAssembly.CompileError. + * @default true + */ + wasm?: boolean | undefined; + } | undefined; /** * If set to `afterEvaluate`, microtasks will be run immediately after the script has run. */ - microtaskMode?: 'afterEvaluate' | undefined; + microtaskMode?: "afterEvaluate" | undefined; } - type MeasureMemoryMode = 'summary' | 'detailed'; + type MeasureMemoryMode = "summary" | "detailed"; interface MeasureMemoryOptions { /** * @default 'summary' */ mode?: MeasureMemoryMode | undefined; - context?: Context | undefined; + /** + * @default 'default' + */ + execution?: "default" | "eager" | undefined; } interface MemoryMeasurement { total: { @@ -156,7 +191,7 @@ declare module 'vm' { * @since v0.3.1 */ class Script { - constructor(code: string, options?: ScriptOptions); + constructor(code: string, options?: ScriptOptions | string); /** * Runs the compiled code contained by the `vm.Script` object within the given`contextifiedObject` and returns the result. Running code does not have access * to local scope. @@ -166,11 +201,11 @@ declare module 'vm' { * The globals are contained in the `context` object. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * const context = { * animal: 'cat', - * count: 2 + * count: 2, * }; * * const script = new vm.Script('count += 1; name = "kitty";'); @@ -202,7 +237,7 @@ declare module 'vm' { * contained within each individual `context`. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * const script = new vm.Script('globalVar = "set"'); * @@ -218,16 +253,16 @@ declare module 'vm' { * @param contextObject An object that will be `contextified`. If `undefined`, a new object will be created. * @return the result of the very last statement executed in the script. */ - runInNewContext(contextObject?: Context, options?: RunningScriptOptions): any; + runInNewContext(contextObject?: Context, options?: RunningScriptInNewContextOptions): any; /** * Runs the compiled code contained by the `vm.Script` within the context of the - * current `global` object. Running code does not have access to local scope, but_does_ have access to the current `global` object. + * current `global` object. Running code does not have access to local scope, but _does_ have access to the current `global` object. * * The following example compiles code that increments a `global` variable then * executes that code multiple times: * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * global.globalVar = 0; * @@ -249,6 +284,16 @@ declare module 'vm' { * Creates a code cache that can be used with the `Script` constructor's`cachedData` option. Returns a `Buffer`. This method may be called at any * time and any number of times. * + * The code cache of the `Script` doesn't contain any JavaScript observable + * states. The code cache is safe to be saved along side the script source and + * used to construct new `Script` instances multiple times. + * + * Functions in the `Script` source can be marked as lazily compiled and they are + * not compiled at construction of the `Script`. These functions are going to be + * compiled when they are invoked the first time. The code cache serializes the + * metadata that V8 currently knows about the `Script` that it can use to speed up + * future compilations. + * * ```js * const script = new vm.Script(` * function add(a, b) { @@ -258,19 +303,46 @@ declare module 'vm' { * const x = add(1, 2); * `); * - * const cacheWithoutX = script.createCachedData(); + * const cacheWithoutAdd = script.createCachedData(); + * // In `cacheWithoutAdd` the function `add()` is marked for full compilation + * // upon invocation. * * script.runInThisContext(); * - * const cacheWithX = script.createCachedData(); + * const cacheWithAdd = script.createCachedData(); + * // `cacheWithAdd` contains fully compiled function `add()`. * ``` * @since v10.6.0 */ createCachedData(): Buffer; /** @deprecated in favor of `script.createCachedData()` */ cachedDataProduced?: boolean | undefined; + /** + * When `cachedData` is supplied to create the `vm.Script`, this value will be set + * to either `true` or `false` depending on acceptance of the data by V8\. + * Otherwise the value is `undefined`. + * @since v5.7.0 + */ cachedDataRejected?: boolean | undefined; cachedData?: Buffer | undefined; + /** + * When the script is compiled from a source that contains a source map magic + * comment, this property will be set to the URL of the source map. + * + * ```js + * import vm from 'node:vm'; + * + * const script = new vm.Script(` + * function myFunc() {} + * //# sourceMappingURL=sourcemap.json + * `); + * + * console.log(script.sourceMapURL); + * // Prints: sourcemap.json + * ``` + * @since v19.1.0, v18.13.0 + */ + sourceMapURL?: string | undefined; } /** * If given a `contextObject`, the `vm.createContext()` method will `prepare @@ -280,7 +352,7 @@ declare module 'vm' { * will remain unchanged. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * global.globalVar = 3; * @@ -327,7 +399,7 @@ declare module 'vm' { * The following example compiles and executes different scripts using a single `contextified` object: * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * const contextObject = { globalVar: 1 }; * vm.createContext(contextObject); @@ -343,7 +415,7 @@ declare module 'vm' { * @param contextifiedObject The `contextified` object that will be used as the `global` when the `code` is compiled and run. * @return the result of the very last statement executed in the script. */ - function runInContext(code: string, contextifiedObject: Context, options?: RunningScriptOptions | string): any; + function runInContext(code: string, contextifiedObject: Context, options?: RunningCodeOptions | string): any; /** * The `vm.runInNewContext()` first contextifies the given `contextObject` (or * creates a new `contextObject` if passed as `undefined`), compiles the `code`, @@ -356,11 +428,11 @@ declare module 'vm' { * variable and sets a new one. These globals are contained in the `contextObject`. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * * const contextObject = { * animal: 'cat', - * count: 2 + * count: 2, * }; * * vm.runInNewContext('count += 1; name = "kitty"', contextObject); @@ -372,7 +444,11 @@ declare module 'vm' { * @param contextObject An object that will be `contextified`. If `undefined`, a new object will be created. * @return the result of the very last statement executed in the script. */ - function runInNewContext(code: string, contextObject?: Context, options?: RunningScriptOptions | string): any; + function runInNewContext( + code: string, + contextObject?: Context, + options?: RunningCodeInNewContextOptions | string, + ): any; /** * `vm.runInThisContext()` compiles `code`, runs it within the context of the * current `global` and returns the result. Running code does not have access to @@ -384,7 +460,7 @@ declare module 'vm' { * the JavaScript [`eval()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) function to run the same code: * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * let localVar = 'initial value'; * * const vmResult = vm.runInThisContext('localVar = "vm";'); @@ -405,17 +481,17 @@ declare module 'vm' { * When using either `script.runInThisContext()` or {@link runInThisContext}, the code is executed within the current V8 global * context. The code passed to this VM context will have its own isolated scope. * - * In order to run a simple web server using the `http` module the code passed to - * the context must either call `require('http')` on its own, or have a reference - * to the `http` module passed to it. For instance: + * In order to run a simple web server using the `node:http` module the code passed + * to the context must either call `require('node:http')` on its own, or have a + * reference to the `node:http` module passed to it. For instance: * * ```js * 'use strict'; - * const vm = require('vm'); + * const vm = require('node:vm'); * * const code = ` * ((require) => { - * const http = require('http'); + * const http = require('node:http'); * * http.createServer((request, response) => { * response.writeHead(200, { 'Content-Type': 'text/plain' }); @@ -435,7 +511,7 @@ declare module 'vm' { * @param code The JavaScript code to compile and run. * @return the result of the very last statement executed in the script. */ - function runInThisContext(code: string, options?: RunningScriptOptions | string): any; + function runInThisContext(code: string, options?: RunningCodeOptions | string): any; /** * Compiles the given code into the provided context (if no context is * supplied, the current context is used), and returns it wrapped inside a @@ -444,7 +520,15 @@ declare module 'vm' { * @param code The body of the function to compile. * @param params An array of strings containing all parameters for the function. */ - function compileFunction(code: string, params?: ReadonlyArray, options?: CompileFunctionOptions): Function; + function compileFunction( + code: string, + params?: readonly string[], + options?: CompileFunctionOptions, + ): Function & { + cachedData?: Script["cachedData"] | undefined; + cachedDataProduced?: Script["cachedDataProduced"] | undefined; + cachedDataRejected?: Script["cachedDataRejected"] | undefined; + }; /** * Measure the memory known to V8 and used by all contexts known to the * current V8 isolate, or the main context. @@ -458,7 +542,7 @@ declare module 'vm' { * the memory occupied by each heap space in the current V8 instance. * * ```js - * const vm = require('vm'); + * const vm = require('node:vm'); * // Measure the memory used by the main context. * vm.measureMemory({ mode: 'summary' }) * // This is the same as vm.measureMemory() @@ -501,7 +585,319 @@ declare module 'vm' { * @experimental */ function measureMemory(options?: MeasureMemoryOptions): Promise; + interface ModuleEvaluateOptions { + timeout?: RunningScriptOptions["timeout"] | undefined; + breakOnSigint?: RunningScriptOptions["breakOnSigint"] | undefined; + } + type ModuleLinker = ( + specifier: string, + referencingModule: Module, + extra: { + /** @deprecated Use `attributes` instead */ + assert: ImportAttributes; + attributes: ImportAttributes; + }, + ) => Module | Promise; + type ModuleStatus = "unlinked" | "linking" | "linked" | "evaluating" | "evaluated" | "errored"; + /** + * This feature is only available with the `--experimental-vm-modules` command + * flag enabled. + * + * The `vm.Module` class provides a low-level interface for using + * ECMAScript modules in VM contexts. It is the counterpart of the `vm.Script`class that closely mirrors [Module Record](https://262.ecma-international.org/14.0/#sec-abstract-module-records) s as + * defined in the ECMAScript + * specification. + * + * Unlike `vm.Script` however, every `vm.Module` object is bound to a context from + * its creation. Operations on `vm.Module` objects are intrinsically asynchronous, + * in contrast with the synchronous nature of `vm.Script` objects. The use of + * 'async' functions can help with manipulating `vm.Module` objects. + * + * Using a `vm.Module` object requires three distinct steps: creation/parsing, + * linking, and evaluation. These three steps are illustrated in the following + * example. + * + * This implementation lies at a lower level than the `ECMAScript Module + * loader`. There is also no way to interact with the Loader yet, though + * support is planned. + * + * ```js + * import vm from 'node:vm'; + * + * const contextifiedObject = vm.createContext({ + * secret: 42, + * print: console.log, + * }); + * + * // Step 1 + * // + * // Create a Module by constructing a new `vm.SourceTextModule` object. This + * // parses the provided source text, throwing a `SyntaxError` if anything goes + * // wrong. By default, a Module is created in the top context. But here, we + * // specify `contextifiedObject` as the context this Module belongs to. + * // + * // Here, we attempt to obtain the default export from the module "foo", and + * // put it into local binding "secret". + * + * const bar = new vm.SourceTextModule(` + * import s from 'foo'; + * s; + * print(s); + * `, { context: contextifiedObject }); + * + * // Step 2 + * // + * // "Link" the imported dependencies of this Module to it. + * // + * // The provided linking callback (the "linker") accepts two arguments: the + * // parent module (`bar` in this case) and the string that is the specifier of + * // the imported module. The callback is expected to return a Module that + * // corresponds to the provided specifier, with certain requirements documented + * // in `module.link()`. + * // + * // If linking has not started for the returned Module, the same linker + * // callback will be called on the returned Module. + * // + * // Even top-level Modules without dependencies must be explicitly linked. The + * // callback provided would never be called, however. + * // + * // The link() method returns a Promise that will be resolved when all the + * // Promises returned by the linker resolve. + * // + * // Note: This is a contrived example in that the linker function creates a new + * // "foo" module every time it is called. In a full-fledged module system, a + * // cache would probably be used to avoid duplicated modules. + * + * async function linker(specifier, referencingModule) { + * if (specifier === 'foo') { + * return new vm.SourceTextModule(` + * // The "secret" variable refers to the global variable we added to + * // "contextifiedObject" when creating the context. + * export default secret; + * `, { context: referencingModule.context }); + * + * // Using `contextifiedObject` instead of `referencingModule.context` + * // here would work as well. + * } + * throw new Error(`Unable to resolve dependency: ${specifier}`); + * } + * await bar.link(linker); + * + * // Step 3 + * // + * // Evaluate the Module. The evaluate() method returns a promise which will + * // resolve after the module has finished evaluating. + * + * // Prints 42. + * await bar.evaluate(); + * ``` + * @since v13.0.0, v12.16.0 + * @experimental + */ + class Module { + /** + * The specifiers of all dependencies of this module. The returned array is frozen + * to disallow any changes to it. + * + * Corresponds to the `[[RequestedModules]]` field of [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records) s in + * the ECMAScript specification. + */ + dependencySpecifiers: readonly string[]; + /** + * If the `module.status` is `'errored'`, this property contains the exception + * thrown by the module during evaluation. If the status is anything else, + * accessing this property will result in a thrown exception. + * + * The value `undefined` cannot be used for cases where there is not a thrown + * exception due to possible ambiguity with `throw undefined;`. + * + * Corresponds to the `[[EvaluationError]]` field of [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records) s + * in the ECMAScript specification. + */ + error: any; + /** + * The identifier of the current module, as set in the constructor. + */ + identifier: string; + context: Context; + /** + * The namespace object of the module. This is only available after linking + * (`module.link()`) has completed. + * + * Corresponds to the [GetModuleNamespace](https://tc39.es/ecma262/#sec-getmodulenamespace) abstract operation in the ECMAScript + * specification. + */ + namespace: Object; + /** + * The current status of the module. Will be one of: + * + * * `'unlinked'`: `module.link()` has not yet been called. + * * `'linking'`: `module.link()` has been called, but not all Promises returned + * by the linker function have been resolved yet. + * * `'linked'`: The module has been linked successfully, and all of its + * dependencies are linked, but `module.evaluate()` has not yet been called. + * * `'evaluating'`: The module is being evaluated through a `module.evaluate()` on + * itself or a parent module. + * * `'evaluated'`: The module has been successfully evaluated. + * * `'errored'`: The module has been evaluated, but an exception was thrown. + * + * Other than `'errored'`, this status string corresponds to the specification's [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records)'s `[[Status]]` field. `'errored'` + * corresponds to`'evaluated'` in the specification, but with `[[EvaluationError]]` set to a + * value that is not `undefined`. + */ + status: ModuleStatus; + /** + * Evaluate the module. + * + * This must be called after the module has been linked; otherwise it will reject. + * It could be called also when the module has already been evaluated, in which + * case it will either do nothing if the initial evaluation ended in success + * (`module.status` is `'evaluated'`) or it will re-throw the exception that the + * initial evaluation resulted in (`module.status` is `'errored'`). + * + * This method cannot be called while the module is being evaluated + * (`module.status` is `'evaluating'`). + * + * Corresponds to the [Evaluate() concrete method](https://tc39.es/ecma262/#sec-moduleevaluation) field of [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records) s in the + * ECMAScript specification. + * @return Fulfills with `undefined` upon success. + */ + evaluate(options?: ModuleEvaluateOptions): Promise; + /** + * Link module dependencies. This method must be called before evaluation, and + * can only be called once per module. + * + * The function is expected to return a `Module` object or a `Promise` that + * eventually resolves to a `Module` object. The returned `Module` must satisfy the + * following two invariants: + * + * * It must belong to the same context as the parent `Module`. + * * Its `status` must not be `'errored'`. + * + * If the returned `Module`'s `status` is `'unlinked'`, this method will be + * recursively called on the returned `Module` with the same provided `linker`function. + * + * `link()` returns a `Promise` that will either get resolved when all linking + * instances resolve to a valid `Module`, or rejected if the linker function either + * throws an exception or returns an invalid `Module`. + * + * The linker function roughly corresponds to the implementation-defined [HostResolveImportedModule](https://tc39.es/ecma262/#sec-hostresolveimportedmodule) abstract operation in the + * ECMAScript + * specification, with a few key differences: + * + * * The linker function is allowed to be asynchronous while [HostResolveImportedModule](https://tc39.es/ecma262/#sec-hostresolveimportedmodule) is synchronous. + * + * The actual [HostResolveImportedModule](https://tc39.es/ecma262/#sec-hostresolveimportedmodule) implementation used during module + * linking is one that returns the modules linked during linking. Since at + * that point all modules would have been fully linked already, the [HostResolveImportedModule](https://tc39.es/ecma262/#sec-hostresolveimportedmodule) implementation is fully synchronous per + * specification. + * + * Corresponds to the [Link() concrete method](https://tc39.es/ecma262/#sec-moduledeclarationlinking) field of [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records) s in + * the ECMAScript specification. + */ + link(linker: ModuleLinker): Promise; + } + interface SourceTextModuleOptions { + /** + * String used in stack traces. + * @default 'vm:module(i)' where i is a context-specific ascending index. + */ + identifier?: string | undefined; + cachedData?: ScriptOptions["cachedData"] | undefined; + context?: Context | undefined; + lineOffset?: BaseOptions["lineOffset"] | undefined; + columnOffset?: BaseOptions["columnOffset"] | undefined; + /** + * Called during evaluation of this module to initialize the `import.meta`. + */ + initializeImportMeta?: ((meta: ImportMeta, module: SourceTextModule) => void) | undefined; + importModuleDynamically?: ScriptOptions["importModuleDynamically"] | undefined; + } + /** + * This feature is only available with the `--experimental-vm-modules` command + * flag enabled. + * + * The `vm.SourceTextModule` class provides the [Source Text Module Record](https://tc39.es/ecma262/#sec-source-text-module-records) as + * defined in the ECMAScript specification. + * @since v9.6.0 + * @experimental + */ + class SourceTextModule extends Module { + /** + * Creates a new `SourceTextModule` instance. + * @param code JavaScript Module code to parse + */ + constructor(code: string, options?: SourceTextModuleOptions); + } + interface SyntheticModuleOptions { + /** + * String used in stack traces. + * @default 'vm:module(i)' where i is a context-specific ascending index. + */ + identifier?: string | undefined; + /** + * The contextified object as returned by the `vm.createContext()` method, to compile and evaluate this module in. + */ + context?: Context | undefined; + } + /** + * This feature is only available with the `--experimental-vm-modules` command + * flag enabled. + * + * The `vm.SyntheticModule` class provides the [Synthetic Module Record](https://heycam.github.io/webidl/#synthetic-module-records) as + * defined in the WebIDL specification. The purpose of synthetic modules is to + * provide a generic interface for exposing non-JavaScript sources to ECMAScript + * module graphs. + * + * ```js + * const vm = require('node:vm'); + * + * const source = '{ "a": 1 }'; + * const module = new vm.SyntheticModule(['default'], function() { + * const obj = JSON.parse(source); + * this.setExport('default', obj); + * }); + * + * // Use `module` in linking... + * ``` + * @since v13.0.0, v12.16.0 + * @experimental + */ + class SyntheticModule extends Module { + /** + * Creates a new `SyntheticModule` instance. + * @param exportNames Array of names that will be exported from the module. + * @param evaluateCallback Called when the module is evaluated. + */ + constructor( + exportNames: string[], + evaluateCallback: (this: SyntheticModule) => void, + options?: SyntheticModuleOptions, + ); + /** + * This method is used after the module is linked to set the values of exports. If + * it is called before the module is linked, an `ERR_VM_MODULE_STATUS` error + * will be thrown. + * + * ```js + * import vm from 'node:vm'; + * + * const m = new vm.SyntheticModule(['x'], () => { + * m.setExport('x', 1); + * }); + * + * await m.link(() => {}); + * await m.evaluate(); + * + * assert.strictEqual(m.namespace.x, 1); + * ``` + * @since v13.0.0, v12.16.0 + * @param name Name of the export to set. + * @param value The value to set the export to. + */ + setExport(name: string, value: any): void; + } } -declare module 'node:vm' { - export * from 'vm'; +declare module "node:vm" { + export * from "vm"; } diff --git a/node_modules/@types/node/wasi.d.ts b/node_modules/@types/node/wasi.d.ts old mode 100755 new mode 100644 index dfcf957..337c074 --- a/node_modules/@types/node/wasi.d.ts +++ b/node_modules/@types/node/wasi.d.ts @@ -1,28 +1,30 @@ /** - * The WASI API provides an implementation of the [WebAssembly System Interface](https://wasi.dev/) specification. WASI gives sandboxed WebAssembly applications access to the - * underlying operating system via a collection of POSIX-like functions. + * **The `node:wasi` module does not currently provide the** + * **comprehensive file system security properties provided by some WASI runtimes.** + * **Full support for secure file system sandboxing may or may not be implemented in** + * **future. In the mean time, do not rely on it to run untrusted code.** + * + * The WASI API provides an implementation of the [WebAssembly System Interface](https://wasi.dev/) specification. WASI gives WebAssembly applications access to the underlying + * operating system via a collection of POSIX-like functions. * * ```js - * import { readFile } from 'fs/promises'; + * import { readFile } from 'node:fs/promises'; * import { WASI } from 'wasi'; - * import { argv, env } from 'process'; + * import { argv, env } from 'node:process'; * * const wasi = new WASI({ + * version: 'preview1', * args: argv, * env, * preopens: { - * '/sandbox': '/some/real/path/that/wasm/can/access' - * } + * '/local': '/some/real/path/that/wasm/can/access', + * }, * }); * - * // Some WASI binaries require: - * // const importObject = { wasi_unstable: wasi.wasiImport }; - * const importObject = { wasi_snapshot_preview1: wasi.wasiImport }; - * * const wasm = await WebAssembly.compile( - * await readFile(new URL('./demo.wasm', import.meta.url)) + * await readFile(new URL('./demo.wasm', import.meta.url)), * ); - * const instance = await WebAssembly.instantiate(wasm, importObject); + * const instance = await WebAssembly.instantiate(wasm, wasi.getImportObject()); * * wasi.start(instance); * ``` @@ -61,16 +63,13 @@ * * Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm` * - * ```console - * $ wat2wasm demo.wat + * ```bash + * wat2wasm demo.wat * ``` - * - * The `--experimental-wasi-unstable-preview1` CLI argument is needed for this - * example to run. * @experimental - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/wasi.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/wasi.js) */ -declare module 'wasi' { +declare module "wasi" { interface WASIOptions { /** * An array of strings that the WebAssembly application will @@ -91,11 +90,11 @@ declare module 'wasi' { */ preopens?: NodeJS.Dict | undefined; /** - * By default, WASI applications terminate the Node.js - * process via the `__wasi_proc_exit()` function. Setting this option to `true` - * causes `wasi.start()` to return the exit code rather than terminate the - * process. - * @default false + * By default, when WASI applications call `__wasi_proc_exit()` + * `wasi.start()` will return with the exit code specified rather than terminatng the process. + * Setting this option to `false` will cause the Node.js process to exit with + * the specified exit code instead. + * @default true */ returnOnExit?: boolean | undefined; /** @@ -113,12 +112,17 @@ declare module 'wasi' { * @default 2 */ stderr?: number | undefined; + /** + * The version of WASI requested. + * Currently the only supported versions are `'unstable'` and `'preview1'`. + * @since v20.0.0 + */ + version: string; } /** * The `WASI` class provides the WASI system call API and additional convenience * methods for working with WASI-based applications. Each `WASI` instance - * represents a distinct sandbox environment. For security purposes, each `WASI`instance must have its command-line arguments, environment variables, and - * sandbox directory structure configured explicitly. + * represents a distinct environment. * @since v13.3.0, v12.16.0 */ class WASI { @@ -133,7 +137,7 @@ declare module 'wasi' { * If `start()` is called more than once, an exception is thrown. * @since v13.3.0, v12.16.0 */ - start(instance: object): void; // TODO: avoid DOM dependency until WASM moved to own lib. + start(instance: object): number; // TODO: avoid DOM dependency until WASM moved to own lib. /** * Attempt to initialize `instance` as a WASI reactor by invoking its`_initialize()` export, if it is present. If `instance` contains a `_start()`export, then an exception is thrown. * @@ -153,6 +157,6 @@ declare module 'wasi' { readonly wasiImport: NodeJS.Dict; // TODO: Narrow to DOM types } } -declare module 'node:wasi' { - export * from 'wasi'; +declare module "node:wasi" { + export * from "wasi"; } diff --git a/node_modules/@types/node/worker_threads.d.ts b/node_modules/@types/node/worker_threads.d.ts old mode 100755 new mode 100644 index 419d044..e3e5048 --- a/node_modules/@types/node/worker_threads.d.ts +++ b/node_modules/@types/node/worker_threads.d.ts @@ -1,9 +1,9 @@ /** - * The `worker_threads` module enables the use of threads that execute JavaScript - * in parallel. To access it: + * The `node:worker_threads` module enables the use of threads that execute + * JavaScript in parallel. To access it: * * ```js - * const worker = require('worker_threads'); + * const worker = require('node:worker_threads'); * ``` * * Workers (threads) are useful for performing CPU-intensive JavaScript operations. @@ -15,14 +15,14 @@ * * ```js * const { - * Worker, isMainThread, parentPort, workerData - * } = require('worker_threads'); + * Worker, isMainThread, parentPort, workerData, + * } = require('node:worker_threads'); * * if (isMainThread) { * module.exports = function parseJSAsync(script) { * return new Promise((resolve, reject) => { * const worker = new Worker(__filename, { - * workerData: script + * workerData: script, * }); * worker.on('message', resolve); * worker.on('error', reject); @@ -39,7 +39,7 @@ * } * ``` * - * The above example spawns a Worker thread for each `parse()` call. In actual + * The above example spawns a Worker thread for each `parseJSAsync()` call. In * practice, use a pool of Workers for these kinds of tasks. Otherwise, the * overhead of creating Workers would likely exceed their benefit. * @@ -49,17 +49,17 @@ * * Worker threads inherit non-process-specific options by default. Refer to `Worker constructor options` to know how to customize worker thread options, * specifically `argv` and `execArgv` options. - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/worker_threads.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/worker_threads.js) */ -declare module 'worker_threads' { - import { Blob } from 'node:buffer'; - import { Context } from 'node:vm'; - import { EventEmitter } from 'node:events'; - import { EventLoopUtilityFunction } from 'node:perf_hooks'; - import { FileHandle } from 'node:fs/promises'; - import { Readable, Writable } from 'node:stream'; - import { URL } from 'node:url'; - import { X509Certificate } from 'node:crypto'; +declare module "worker_threads" { + import { Blob } from "node:buffer"; + import { Context } from "node:vm"; + import { EventEmitter } from "node:events"; + import { EventLoopUtilityFunction } from "node:perf_hooks"; + import { FileHandle } from "node:fs/promises"; + import { Readable, Writable } from "node:stream"; + import { URL } from "node:url"; + import { X509Certificate } from "node:crypto"; const isMainThread: boolean; const parentPort: null | MessagePort; const resourceLimits: ResourceLimits; @@ -72,7 +72,7 @@ declare module 'worker_threads' { * The `MessageChannel` has no methods of its own. `new MessageChannel()`yields an object with `port1` and `port2` properties, which refer to linked `MessagePort` instances. * * ```js - * const { MessageChannel } = require('worker_threads'); + * const { MessageChannel } = require('node:worker_threads'); * * const { port1, port2 } = new MessageChannel(); * port1.on('message', (message) => console.log('received', message)); @@ -121,7 +121,7 @@ declare module 'worker_threads' { * * `value` may not contain native (C++-backed) objects other than: * * ```js - * const { MessageChannel } = require('worker_threads'); + * const { MessageChannel } = require('node:worker_threads'); * const { port1, port2 } = new MessageChannel(); * * port1.on('message', (message) => console.log(message)); @@ -132,7 +132,7 @@ declare module 'worker_threads' { * port2.postMessage(circularData); * ``` * - * `transferList` may be a list of [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), `MessagePort` and `FileHandle` objects. + * `transferList` may be a list of [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), `MessagePort`, and `FileHandle` objects. * After transferring, they are not usable on the sending side of the channel * anymore (even if they are not contained in `value`). Unlike with `child processes`, transferring handles such as network sockets is currently * not supported. @@ -143,7 +143,7 @@ declare module 'worker_threads' { * `value` may still contain `ArrayBuffer` instances that are not in`transferList`; in that case, the underlying memory is copied rather than moved. * * ```js - * const { MessageChannel } = require('worker_threads'); + * const { MessageChannel } = require('node:worker_threads'); * const { port1, port2 } = new MessageChannel(); * * port1.on('message', (message) => console.log(message)); @@ -170,12 +170,12 @@ declare module 'worker_threads' { * posting without having side effects. * * For more information on the serialization and deserialization mechanisms - * behind this API, see the `serialization API of the v8 module`. + * behind this API, see the `serialization API of the node:v8 module`. * @since v10.5.0 */ - postMessage(value: any, transferList?: ReadonlyArray): void; + postMessage(value: any, transferList?: readonly TransferListItem[]): void; /** - * Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed port does_not_ let the program exit if it's the only active handle left (the default + * Opposite of `unref()`. Calling `ref()` on a previously `unref()`ed port does _not_ let the program exit if it's the only active handle left (the default * behavior). If the port is `ref()`ed, calling `ref()` again has no effect. * * If listeners are attached or removed using `.on('message')`, the port @@ -205,37 +205,37 @@ declare module 'worker_threads' { * @since v10.5.0 */ start(): void; - addListener(event: 'close', listener: () => void): this; - addListener(event: 'message', listener: (value: any) => void): this; - addListener(event: 'messageerror', listener: (error: Error) => void): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "message", listener: (value: any) => void): this; + addListener(event: "messageerror", listener: (error: Error) => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'close'): boolean; - emit(event: 'message', value: any): boolean; - emit(event: 'messageerror', error: Error): boolean; + emit(event: "close"): boolean; + emit(event: "message", value: any): boolean; + emit(event: "messageerror", error: Error): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'close', listener: () => void): this; - on(event: 'message', listener: (value: any) => void): this; - on(event: 'messageerror', listener: (error: Error) => void): this; + on(event: "close", listener: () => void): this; + on(event: "message", listener: (value: any) => void): this; + on(event: "messageerror", listener: (error: Error) => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'close', listener: () => void): this; - once(event: 'message', listener: (value: any) => void): this; - once(event: 'messageerror', listener: (error: Error) => void): this; + once(event: "close", listener: () => void): this; + once(event: "message", listener: (value: any) => void): this; + once(event: "messageerror", listener: (error: Error) => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'close', listener: () => void): this; - prependListener(event: 'message', listener: (value: any) => void): this; - prependListener(event: 'messageerror', listener: (error: Error) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "message", listener: (value: any) => void): this; + prependListener(event: "messageerror", listener: (error: Error) => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'close', listener: () => void): this; - prependOnceListener(event: 'message', listener: (value: any) => void): this; - prependOnceListener(event: 'messageerror', listener: (error: Error) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "message", listener: (value: any) => void): this; + prependOnceListener(event: "messageerror", listener: (error: Error) => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; - removeListener(event: 'close', listener: () => void): this; - removeListener(event: 'message', listener: (value: any) => void): this; - removeListener(event: 'messageerror', listener: (error: Error) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "message", listener: (value: any) => void): this; + removeListener(event: "messageerror", listener: (error: Error) => void): this; removeListener(event: string | symbol, listener: (...args: any[]) => void): this; - off(event: 'close', listener: () => void): this; - off(event: 'message', listener: (value: any) => void): this; - off(event: 'messageerror', listener: (error: Error) => void): this; + off(event: "close", listener: () => void): this; + off(event: "message", listener: (value: any) => void): this; + off(event: "messageerror", listener: (error: Error) => void): this; off(event: string | symbol, listener: (...args: any[]) => void): this; } interface WorkerOptions { @@ -262,6 +262,12 @@ declare module 'worker_threads' { * @default true */ trackUnmanagedFds?: boolean | undefined; + /** + * An optional `name` to be appended to the worker title + * for debuggin/identification purposes, making the final title as + * `[worker ${id}] ${name}`. + */ + name?: string | undefined; } interface ResourceLimits { /** @@ -288,16 +294,17 @@ declare module 'worker_threads' { * * Notable differences inside a Worker environment are: * - * * The `process.stdin`, `process.stdout` and `process.stderr` may be redirected by the parent thread. - * * The `require('worker_threads').isMainThread` property is set to `false`. - * * The `require('worker_threads').parentPort` message port is available. + * * The `process.stdin`, `process.stdout`, and `process.stderr` streams may be redirected by the parent thread. + * * The `require('node:worker_threads').isMainThread` property is set to `false`. + * * The `require('node:worker_threads').parentPort` message port is available. * * `process.exit()` does not stop the whole program, just the single thread, * and `process.abort()` is not available. * * `process.chdir()` and `process` methods that set group or user ids * are not available. * * `process.env` is a copy of the parent thread's environment variables, * unless otherwise specified. Changes to one copy are not visible in other - * threads, and are not visible to native add-ons (unless `worker.SHARE_ENV` is passed as the `env` option to the `Worker` constructor). + * threads, and are not visible to native add-ons (unless `worker.SHARE_ENV` is passed as the `env` option to the `Worker` constructor). On Windows, unlike the main thread, a copy of the + * environment variables operates in a case-sensitive manner. * * `process.title` cannot be modified. * * Signals are not delivered through `process.on('...')`. * * Execution may stop at any point as a result of `worker.terminate()` being invoked. @@ -307,11 +314,11 @@ declare module 'worker_threads' { * * Creating `Worker` instances inside of other `Worker`s is possible. * - * Like [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) and the `cluster module`, two-way communication can be - * achieved through inter-thread message passing. Internally, a `Worker` has a - * built-in pair of `MessagePort` s that are already associated with each other - * when the `Worker` is created. While the `MessagePort` object on the parent side - * is not directly exposed, its functionalities are exposed through `worker.postMessage()` and the `worker.on('message')` event + * Like [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) and the `node:cluster module`, two-way communication + * can be achieved through inter-thread message passing. Internally, a `Worker` has + * a built-in pair of `MessagePort` s that are already associated with each + * other when the `Worker` is created. While the `MessagePort` object on the parent + * side is not directly exposed, its functionalities are exposed through `worker.postMessage()` and the `worker.on('message')` event * on the `Worker` object for the parent thread. * * To create custom messaging channels (which is encouraged over using the default @@ -324,10 +331,10 @@ declare module 'worker_threads' { * the thread barrier. * * ```js - * const assert = require('assert'); + * const assert = require('node:assert'); * const { - * Worker, MessageChannel, MessagePort, isMainThread, parentPort - * } = require('worker_threads'); + * Worker, MessageChannel, MessagePort, isMainThread, parentPort, + * } = require('node:worker_threads'); * if (isMainThread) { * const worker = new Worker(__filename); * const subChannel = new MessageChannel(); @@ -367,7 +374,7 @@ declare module 'worker_threads' { readonly stderr: Readable; /** * An integer identifier for the referenced thread. Inside the worker thread, - * it is available as `require('worker_threads').threadId`. + * it is available as `require('node:worker_threads').threadId`. * This value is unique for each `Worker` instance inside a single process. * @since v10.5.0 */ @@ -384,7 +391,7 @@ declare module 'worker_threads' { /** * An object that can be used to query performance information from a worker * instance. Similar to `perf_hooks.performance`. - * @since v15.1.0, v12.22.0 + * @since v15.1.0, v14.17.0, v12.22.0 */ readonly performance: WorkerPerformance; /** @@ -394,13 +401,13 @@ declare module 'worker_threads' { */ constructor(filename: string | URL, options?: WorkerOptions); /** - * Send a message to the worker that is received via `require('worker_threads').parentPort.on('message')`. + * Send a message to the worker that is received via `require('node:worker_threads').parentPort.on('message')`. * See `port.postMessage()` for more details. * @since v10.5.0 */ - postMessage(value: any, transferList?: ReadonlyArray): void; + postMessage(value: any, transferList?: readonly TransferListItem[]): void; /** - * Opposite of `unref()`, calling `ref()` on a previously `unref()`ed worker does_not_ let the program exit if it's the only active handle left (the default + * Opposite of `unref()`, calling `ref()` on a previously `unref()`ed worker does _not_ let the program exit if it's the only active handle left (the default * behavior). If the worker is `ref()`ed, calling `ref()` again has * no effect. * @since v10.5.0 @@ -428,53 +435,53 @@ declare module 'worker_threads' { * @return A promise for a Readable Stream containing a V8 heap snapshot */ getHeapSnapshot(): Promise; - addListener(event: 'error', listener: (err: Error) => void): this; - addListener(event: 'exit', listener: (exitCode: number) => void): this; - addListener(event: 'message', listener: (value: any) => void): this; - addListener(event: 'messageerror', listener: (error: Error) => void): this; - addListener(event: 'online', listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "exit", listener: (exitCode: number) => void): this; + addListener(event: "message", listener: (value: any) => void): this; + addListener(event: "messageerror", listener: (error: Error) => void): this; + addListener(event: "online", listener: () => void): this; addListener(event: string | symbol, listener: (...args: any[]) => void): this; - emit(event: 'error', err: Error): boolean; - emit(event: 'exit', exitCode: number): boolean; - emit(event: 'message', value: any): boolean; - emit(event: 'messageerror', error: Error): boolean; - emit(event: 'online'): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "exit", exitCode: number): boolean; + emit(event: "message", value: any): boolean; + emit(event: "messageerror", error: Error): boolean; + emit(event: "online"): boolean; emit(event: string | symbol, ...args: any[]): boolean; - on(event: 'error', listener: (err: Error) => void): this; - on(event: 'exit', listener: (exitCode: number) => void): this; - on(event: 'message', listener: (value: any) => void): this; - on(event: 'messageerror', listener: (error: Error) => void): this; - on(event: 'online', listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "exit", listener: (exitCode: number) => void): this; + on(event: "message", listener: (value: any) => void): this; + on(event: "messageerror", listener: (error: Error) => void): this; + on(event: "online", listener: () => void): this; on(event: string | symbol, listener: (...args: any[]) => void): this; - once(event: 'error', listener: (err: Error) => void): this; - once(event: 'exit', listener: (exitCode: number) => void): this; - once(event: 'message', listener: (value: any) => void): this; - once(event: 'messageerror', listener: (error: Error) => void): this; - once(event: 'online', listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "exit", listener: (exitCode: number) => void): this; + once(event: "message", listener: (value: any) => void): this; + once(event: "messageerror", listener: (error: Error) => void): this; + once(event: "online", listener: () => void): this; once(event: string | symbol, listener: (...args: any[]) => void): this; - prependListener(event: 'error', listener: (err: Error) => void): this; - prependListener(event: 'exit', listener: (exitCode: number) => void): this; - prependListener(event: 'message', listener: (value: any) => void): this; - prependListener(event: 'messageerror', listener: (error: Error) => void): this; - prependListener(event: 'online', listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "exit", listener: (exitCode: number) => void): this; + prependListener(event: "message", listener: (value: any) => void): this; + prependListener(event: "messageerror", listener: (error: Error) => void): this; + prependListener(event: "online", listener: () => void): this; prependListener(event: string | symbol, listener: (...args: any[]) => void): this; - prependOnceListener(event: 'error', listener: (err: Error) => void): this; - prependOnceListener(event: 'exit', listener: (exitCode: number) => void): this; - prependOnceListener(event: 'message', listener: (value: any) => void): this; - prependOnceListener(event: 'messageerror', listener: (error: Error) => void): this; - prependOnceListener(event: 'online', listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "exit", listener: (exitCode: number) => void): this; + prependOnceListener(event: "message", listener: (value: any) => void): this; + prependOnceListener(event: "messageerror", listener: (error: Error) => void): this; + prependOnceListener(event: "online", listener: () => void): this; prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; - removeListener(event: 'error', listener: (err: Error) => void): this; - removeListener(event: 'exit', listener: (exitCode: number) => void): this; - removeListener(event: 'message', listener: (value: any) => void): this; - removeListener(event: 'messageerror', listener: (error: Error) => void): this; - removeListener(event: 'online', listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "exit", listener: (exitCode: number) => void): this; + removeListener(event: "message", listener: (value: any) => void): this; + removeListener(event: "messageerror", listener: (error: Error) => void): this; + removeListener(event: "online", listener: () => void): this; removeListener(event: string | symbol, listener: (...args: any[]) => void): this; - off(event: 'error', listener: (err: Error) => void): this; - off(event: 'exit', listener: (exitCode: number) => void): this; - off(event: 'message', listener: (value: any) => void): this; - off(event: 'messageerror', listener: (error: Error) => void): this; - off(event: 'online', listener: () => void): this; + off(event: "error", listener: (err: Error) => void): this; + off(event: "exit", listener: (exitCode: number) => void): this; + off(event: "message", listener: (value: any) => void): this; + off(event: "messageerror", listener: (error: Error) => void): this; + off(event: "online", listener: () => void): this; off(event: string | symbol, listener: (...args: any[]) => void): this; } interface BroadcastChannel extends NodeJS.RefCounted {} @@ -488,8 +495,8 @@ declare module 'worker_threads' { * const { * isMainThread, * BroadcastChannel, - * Worker - * } = require('worker_threads'); + * Worker, + * } = require('node:worker_threads'); * * const bc = new BroadcastChannel('hello'); * @@ -507,7 +514,6 @@ declare module 'worker_threads' { * } * ``` * @since v15.4.0 - * @experimental */ class BroadcastChannel { readonly name: string; @@ -544,7 +550,7 @@ declare module 'worker_threads' { * This operation cannot be undone. * * ```js - * const { MessageChannel, markAsUntransferable } = require('worker_threads'); + * const { MessageChannel, markAsUntransferable } = require('node:worker_threads'); * * const pooledBuffer = new ArrayBuffer(8); * const typedArray1 = new Uint8Array(pooledBuffer); @@ -586,10 +592,10 @@ declare module 'worker_threads' { function moveMessagePortToContext(port: MessagePort, contextifiedSandbox: Context): MessagePort; /** * Receive a single message from a given `MessagePort`. If no message is available,`undefined` is returned, otherwise an object with a single `message` property - * that contains the message payload, corresponding to the oldest message in the`MessagePort`’s queue. + * that contains the message payload, corresponding to the oldest message in the`MessagePort`'s queue. * * ```js - * const { MessageChannel, receiveMessageOnPort } = require('worker_threads'); + * const { MessageChannel, receiveMessageOnPort } = require('node:worker_threads'); * const { port1, port2 } = new MessageChannel(); * port1.postMessage({ hello: 'world' }); * @@ -604,8 +610,8 @@ declare module 'worker_threads' { */ function receiveMessageOnPort(port: MessagePort): | { - message: any; - } + message: any; + } | undefined; type Serializable = string | object | number | boolean | bigint; /** @@ -620,7 +626,7 @@ declare module 'worker_threads' { * isMainThread, * setEnvironmentData, * getEnvironmentData, - * } = require('worker_threads'); + * } = require('node:worker_threads'); * * if (isMainThread) { * setEnvironmentData('Hello', 'World!'); @@ -629,21 +635,57 @@ declare module 'worker_threads' { * console.log(getEnvironmentData('Hello')); // Prints 'World!'. * } * ``` - * @since v15.12.0 - * @experimental + * @since v15.12.0, v14.18.0 * @param key Any arbitrary, cloneable JavaScript value that can be used as a {Map} key. */ function getEnvironmentData(key: Serializable): Serializable; /** * The `worker.setEnvironmentData()` API sets the content of`worker.getEnvironmentData()` in the current thread and all new `Worker`instances spawned from the current context. - * @since v15.12.0 - * @experimental + * @since v15.12.0, v14.18.0 * @param key Any arbitrary, cloneable JavaScript value that can be used as a {Map} key. * @param value Any arbitrary, cloneable JavaScript value that will be cloned and passed automatically to all new `Worker` instances. If `value` is passed as `undefined`, any previously set value * for the `key` will be deleted. */ function setEnvironmentData(key: Serializable, value: Serializable): void; + + import { + BroadcastChannel as _BroadcastChannel, + MessageChannel as _MessageChannel, + MessagePort as _MessagePort, + } from "worker_threads"; + global { + /** + * `BroadcastChannel` class is a global reference for `require('worker_threads').BroadcastChannel` + * https://nodejs.org/api/globals.html#broadcastchannel + * @since v18.0.0 + */ + var BroadcastChannel: typeof globalThis extends { + onmessage: any; + BroadcastChannel: infer T; + } ? T + : typeof _BroadcastChannel; + /** + * `MessageChannel` class is a global reference for `require('worker_threads').MessageChannel` + * https://nodejs.org/api/globals.html#messagechannel + * @since v15.0.0 + */ + var MessageChannel: typeof globalThis extends { + onmessage: any; + MessageChannel: infer T; + } ? T + : typeof _MessageChannel; + /** + * `MessagePort` class is a global reference for `require('worker_threads').MessagePort` + * https://nodejs.org/api/globals.html#messageport + * @since v15.0.0 + */ + var MessagePort: typeof globalThis extends { + onmessage: any; + MessagePort: infer T; + } ? T + : typeof _MessagePort; + } } -declare module 'node:worker_threads' { - export * from 'worker_threads'; +declare module "node:worker_threads" { + export * from "worker_threads"; } diff --git a/node_modules/@types/node/zlib.d.ts b/node_modules/@types/node/zlib.d.ts old mode 100755 new mode 100644 index 8cfa145..6b944b8 --- a/node_modules/@types/node/zlib.d.ts +++ b/node_modules/@types/node/zlib.d.ts @@ -1,11 +1,11 @@ /** - * The `zlib` module provides compression functionality implemented using Gzip, - * Deflate/Inflate, and Brotli. + * The `node:zlib` module provides compression functionality implemented using + * Gzip, Deflate/Inflate, and Brotli. * * To access it: * * ```js - * const zlib = require('zlib'); + * const zlib = require('node:zlib'); * ``` * * Compression and decompression are built around the Node.js `Streams API`. @@ -15,12 +15,12 @@ * stream: * * ```js - * const { createGzip } = require('zlib'); - * const { pipeline } = require('stream'); + * const { createGzip } = require('node:zlib'); + * const { pipeline } = require('node:stream'); * const { * createReadStream, - * createWriteStream - * } = require('fs'); + * createWriteStream, + * } = require('node:fs'); * * const gzip = createGzip(); * const source = createReadStream('input.txt'); @@ -35,7 +35,7 @@ * * // Or, Promisified * - * const { promisify } = require('util'); + * const { promisify } = require('node:util'); * const pipe = promisify(pipeline); * * async function do_gzip(input, output) { @@ -55,7 +55,7 @@ * It is also possible to compress or decompress data in a single step: * * ```js - * const { deflate, unzip } = require('zlib'); + * const { deflate, unzip } = require('node:zlib'); * * const input = '.................................'; * deflate(input, (err, buffer) => { @@ -77,7 +77,7 @@ * * // Or, Promisified * - * const { promisify } = require('util'); + * const { promisify } = require('node:util'); * const do_unzip = promisify(unzip); * * do_unzip(buffer) @@ -88,10 +88,10 @@ * }); * ``` * @since v0.5.8 - * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/zlib.js) + * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/zlib.js) */ -declare module 'zlib' { - import * as stream from 'node:stream'; +declare module "zlib" { + import * as stream from "node:stream"; interface ZlibOptions { /** * @default constants.Z_NO_FLUSH @@ -128,11 +128,11 @@ declare module 'zlib' { chunkSize?: number | undefined; params?: | { - /** - * Each key is a `constants.BROTLI_*` constant. - */ - [key: number]: boolean | number; - } + /** + * Each key is a `constants.BROTLI_*` constant. + */ + [key: number]: boolean | number; + } | undefined; maxOutputLength?: number | undefined; } @@ -512,6 +512,6 @@ declare module 'zlib' { /** @deprecated */ const Z_DEFLATED: number; } -declare module 'node:zlib' { - export * from 'zlib'; +declare module "node:zlib" { + export * from "zlib"; } diff --git a/node_modules/undici-types/README.md b/node_modules/undici-types/README.md new file mode 100644 index 0000000..20a721c --- /dev/null +++ b/node_modules/undici-types/README.md @@ -0,0 +1,6 @@ +# undici-types + +This package is a dual-publish of the [undici](https://www.npmjs.com/package/undici) library types. The `undici` package **still contains types**. This package is for users who _only_ need undici types (such as for `@types/node`). It is published alongside every release of `undici`, so you can always use the same version. + +- [GitHub nodejs/undici](https://github.com/nodejs/undici) +- [Undici Documentation](https://undici.nodejs.org/#/) diff --git a/node_modules/undici-types/agent.d.ts b/node_modules/undici-types/agent.d.ts new file mode 100644 index 0000000..58081ce --- /dev/null +++ b/node_modules/undici-types/agent.d.ts @@ -0,0 +1,31 @@ +import { URL } from 'url' +import Pool from './pool' +import Dispatcher from "./dispatcher"; + +export default Agent + +declare class Agent extends Dispatcher{ + constructor(opts?: Agent.Options) + /** `true` after `dispatcher.close()` has been called. */ + closed: boolean; + /** `true` after `dispatcher.destroyed()` has been called or `dispatcher.close()` has been called and the dispatcher shutdown has completed. */ + destroyed: boolean; + /** Dispatches a request. */ + dispatch(options: Agent.DispatchOptions, handler: Dispatcher.DispatchHandlers): boolean; +} + +declare namespace Agent { + export interface Options extends Pool.Options { + /** Default: `(origin, opts) => new Pool(origin, opts)`. */ + factory?(origin: string | URL, opts: Object): Dispatcher; + /** Integer. Default: `0` */ + maxRedirections?: number; + + interceptors?: { Agent?: readonly Dispatcher.DispatchInterceptor[] } & Pool.Options["interceptors"] + } + + export interface DispatchOptions extends Dispatcher.DispatchOptions { + /** Integer. */ + maxRedirections?: number; + } +} diff --git a/node_modules/undici-types/api.d.ts b/node_modules/undici-types/api.d.ts new file mode 100644 index 0000000..400341d --- /dev/null +++ b/node_modules/undici-types/api.d.ts @@ -0,0 +1,43 @@ +import { URL, UrlObject } from 'url' +import { Duplex } from 'stream' +import Dispatcher from './dispatcher' + +export { + request, + stream, + pipeline, + connect, + upgrade, +} + +/** Performs an HTTP request. */ +declare function request( + url: string | URL | UrlObject, + options?: { dispatcher?: Dispatcher } & Omit & Partial>, +): Promise; + +/** A faster version of `request`. */ +declare function stream( + url: string | URL | UrlObject, + options: { dispatcher?: Dispatcher } & Omit, + factory: Dispatcher.StreamFactory +): Promise; + +/** For easy use with `stream.pipeline`. */ +declare function pipeline( + url: string | URL | UrlObject, + options: { dispatcher?: Dispatcher } & Omit, + handler: Dispatcher.PipelineHandler +): Duplex; + +/** Starts two-way communications with the requested resource. */ +declare function connect( + url: string | URL | UrlObject, + options?: { dispatcher?: Dispatcher } & Omit +): Promise; + +/** Upgrade to a different protocol. */ +declare function upgrade( + url: string | URL | UrlObject, + options?: { dispatcher?: Dispatcher } & Omit +): Promise; diff --git a/node_modules/undici-types/balanced-pool.d.ts b/node_modules/undici-types/balanced-pool.d.ts new file mode 100644 index 0000000..d1e9375 --- /dev/null +++ b/node_modules/undici-types/balanced-pool.d.ts @@ -0,0 +1,18 @@ +import Pool from './pool' +import Dispatcher from './dispatcher' +import { URL } from 'url' + +export default BalancedPool + +declare class BalancedPool extends Dispatcher { + constructor(url: string | string[] | URL | URL[], options?: Pool.Options); + + addUpstream(upstream: string | URL): BalancedPool; + removeUpstream(upstream: string | URL): BalancedPool; + upstreams: Array; + + /** `true` after `pool.close()` has been called. */ + closed: boolean; + /** `true` after `pool.destroyed()` has been called or `pool.close()` has been called and the pool shutdown has completed. */ + destroyed: boolean; +} diff --git a/node_modules/undici-types/cache.d.ts b/node_modules/undici-types/cache.d.ts new file mode 100644 index 0000000..4c33335 --- /dev/null +++ b/node_modules/undici-types/cache.d.ts @@ -0,0 +1,36 @@ +import type { RequestInfo, Response, Request } from './fetch' + +export interface CacheStorage { + match (request: RequestInfo, options?: MultiCacheQueryOptions): Promise, + has (cacheName: string): Promise, + open (cacheName: string): Promise, + delete (cacheName: string): Promise, + keys (): Promise +} + +declare const CacheStorage: { + prototype: CacheStorage + new(): CacheStorage +} + +export interface Cache { + match (request: RequestInfo, options?: CacheQueryOptions): Promise, + matchAll (request?: RequestInfo, options?: CacheQueryOptions): Promise, + add (request: RequestInfo): Promise, + addAll (requests: RequestInfo[]): Promise, + put (request: RequestInfo, response: Response): Promise, + delete (request: RequestInfo, options?: CacheQueryOptions): Promise, + keys (request?: RequestInfo, options?: CacheQueryOptions): Promise +} + +export interface CacheQueryOptions { + ignoreSearch?: boolean, + ignoreMethod?: boolean, + ignoreVary?: boolean +} + +export interface MultiCacheQueryOptions extends CacheQueryOptions { + cacheName?: string +} + +export declare const caches: CacheStorage diff --git a/node_modules/undici-types/client.d.ts b/node_modules/undici-types/client.d.ts new file mode 100644 index 0000000..74948b1 --- /dev/null +++ b/node_modules/undici-types/client.d.ts @@ -0,0 +1,97 @@ +import { URL } from 'url' +import { TlsOptions } from 'tls' +import Dispatcher from './dispatcher' +import buildConnector from "./connector"; + +/** + * A basic HTTP/1.1 client, mapped on top a single TCP/TLS connection. Pipelining is disabled by default. + */ +export class Client extends Dispatcher { + constructor(url: string | URL, options?: Client.Options); + /** Property to get and set the pipelining factor. */ + pipelining: number; + /** `true` after `client.close()` has been called. */ + closed: boolean; + /** `true` after `client.destroyed()` has been called or `client.close()` has been called and the client shutdown has completed. */ + destroyed: boolean; +} + +export declare namespace Client { + export interface OptionsInterceptors { + Client: readonly Dispatcher.DispatchInterceptor[]; + } + export interface Options { + /** TODO */ + interceptors?: OptionsInterceptors; + /** The maximum length of request headers in bytes. Default: Node.js' `--max-http-header-size` or `16384` (16KiB). */ + maxHeaderSize?: number; + /** The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers (Node 14 and above only). Default: `300e3` milliseconds (300s). */ + headersTimeout?: number; + /** @deprecated unsupported socketTimeout, use headersTimeout & bodyTimeout instead */ + socketTimeout?: never; + /** @deprecated unsupported requestTimeout, use headersTimeout & bodyTimeout instead */ + requestTimeout?: never; + /** TODO */ + connectTimeout?: number; + /** The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use `0` to disable it entirely. Default: `300e3` milliseconds (300s). */ + bodyTimeout?: number; + /** @deprecated unsupported idleTimeout, use keepAliveTimeout instead */ + idleTimeout?: never; + /** @deprecated unsupported keepAlive, use pipelining=0 instead */ + keepAlive?: never; + /** the timeout, in milliseconds, after which a socket without active requests will time out. Monitors time between activity on a connected socket. This value may be overridden by *keep-alive* hints from the server. Default: `4e3` milliseconds (4s). */ + keepAliveTimeout?: number; + /** @deprecated unsupported maxKeepAliveTimeout, use keepAliveMaxTimeout instead */ + maxKeepAliveTimeout?: never; + /** the maximum allowed `idleTimeout`, in milliseconds, when overridden by *keep-alive* hints from the server. Default: `600e3` milliseconds (10min). */ + keepAliveMaxTimeout?: number; + /** A number of milliseconds subtracted from server *keep-alive* hints when overriding `idleTimeout` to account for timing inaccuracies caused by e.g. transport latency. Default: `1e3` milliseconds (1s). */ + keepAliveTimeoutThreshold?: number; + /** TODO */ + socketPath?: string; + /** The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Default: `1`. */ + pipelining?: number; + /** @deprecated use the connect option instead */ + tls?: never; + /** If `true`, an error is thrown when the request content-length header doesn't match the length of the request body. Default: `true`. */ + strictContentLength?: boolean; + /** TODO */ + maxCachedSessions?: number; + /** TODO */ + maxRedirections?: number; + /** TODO */ + connect?: buildConnector.BuildOptions | buildConnector.connector; + /** TODO */ + maxRequestsPerClient?: number; + /** TODO */ + localAddress?: string; + /** Max response body size in bytes, -1 is disabled */ + maxResponseSize?: number; + /** Enables a family autodetection algorithm that loosely implements section 5 of RFC 8305. */ + autoSelectFamily?: boolean; + /** The amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the `autoSelectFamily` option. */ + autoSelectFamilyAttemptTimeout?: number; + /** + * @description Enables support for H2 if the server has assigned bigger priority to it through ALPN negotiation. + * @default false + */ + allowH2?: boolean; + /** + * @description Dictates the maximum number of concurrent streams for a single H2 session. It can be overriden by a SETTINGS remote frame. + * @default 100 + */ + maxConcurrentStreams?: number + } + export interface SocketInfo { + localAddress?: string + localPort?: number + remoteAddress?: string + remotePort?: number + remoteFamily?: string + timeout?: number + bytesWritten?: number + bytesRead?: number + } +} + +export default Client; diff --git a/node_modules/undici-types/connector.d.ts b/node_modules/undici-types/connector.d.ts new file mode 100644 index 0000000..bd92433 --- /dev/null +++ b/node_modules/undici-types/connector.d.ts @@ -0,0 +1,34 @@ +import { TLSSocket, ConnectionOptions } from 'tls' +import { IpcNetConnectOpts, Socket, TcpNetConnectOpts } from 'net' + +export default buildConnector +declare function buildConnector (options?: buildConnector.BuildOptions): buildConnector.connector + +declare namespace buildConnector { + export type BuildOptions = (ConnectionOptions | TcpNetConnectOpts | IpcNetConnectOpts) & { + allowH2?: boolean; + maxCachedSessions?: number | null; + socketPath?: string | null; + timeout?: number | null; + port?: number; + keepAlive?: boolean | null; + keepAliveInitialDelay?: number | null; + } + + export interface Options { + hostname: string + host?: string + protocol: string + port: string + servername?: string + localAddress?: string | null + httpSocket?: Socket + } + + export type Callback = (...args: CallbackArgs) => void + type CallbackArgs = [null, Socket | TLSSocket] | [Error, null] + + export interface connector { + (options: buildConnector.Options, callback: buildConnector.Callback): void + } +} diff --git a/node_modules/undici-types/content-type.d.ts b/node_modules/undici-types/content-type.d.ts new file mode 100644 index 0000000..f2a87f1 --- /dev/null +++ b/node_modules/undici-types/content-type.d.ts @@ -0,0 +1,21 @@ +/// + +interface MIMEType { + type: string + subtype: string + parameters: Map + essence: string +} + +/** + * Parse a string to a {@link MIMEType} object. Returns `failure` if the string + * couldn't be parsed. + * @see https://mimesniff.spec.whatwg.org/#parse-a-mime-type + */ +export function parseMIMEType (input: string): 'failure' | MIMEType + +/** + * Convert a MIMEType object to a string. + * @see https://mimesniff.spec.whatwg.org/#serialize-a-mime-type + */ +export function serializeAMimeType (mimeType: MIMEType): string diff --git a/node_modules/undici-types/cookies.d.ts b/node_modules/undici-types/cookies.d.ts new file mode 100644 index 0000000..aa38cae --- /dev/null +++ b/node_modules/undici-types/cookies.d.ts @@ -0,0 +1,28 @@ +/// + +import type { Headers } from './fetch' + +export interface Cookie { + name: string + value: string + expires?: Date | number + maxAge?: number + domain?: string + path?: string + secure?: boolean + httpOnly?: boolean + sameSite?: 'Strict' | 'Lax' | 'None' + unparsed?: string[] +} + +export function deleteCookie ( + headers: Headers, + name: string, + attributes?: { name?: string, domain?: string } +): void + +export function getCookies (headers: Headers): Record + +export function getSetCookies (headers: Headers): Cookie[] + +export function setCookie (headers: Headers, cookie: Cookie): void diff --git a/node_modules/undici-types/diagnostics-channel.d.ts b/node_modules/undici-types/diagnostics-channel.d.ts new file mode 100644 index 0000000..85d4482 --- /dev/null +++ b/node_modules/undici-types/diagnostics-channel.d.ts @@ -0,0 +1,67 @@ +import { Socket } from "net"; +import { URL } from "url"; +import Connector from "./connector"; +import Dispatcher from "./dispatcher"; + +declare namespace DiagnosticsChannel { + interface Request { + origin?: string | URL; + completed: boolean; + method?: Dispatcher.HttpMethod; + path: string; + headers: string; + addHeader(key: string, value: string): Request; + } + interface Response { + statusCode: number; + statusText: string; + headers: Array; + } + type Error = unknown; + interface ConnectParams { + host: URL["host"]; + hostname: URL["hostname"]; + protocol: URL["protocol"]; + port: URL["port"]; + servername: string | null; + } + type Connector = Connector.connector; + export interface RequestCreateMessage { + request: Request; + } + export interface RequestBodySentMessage { + request: Request; + } + export interface RequestHeadersMessage { + request: Request; + response: Response; + } + export interface RequestTrailersMessage { + request: Request; + trailers: Array; + } + export interface RequestErrorMessage { + request: Request; + error: Error; + } + export interface ClientSendHeadersMessage { + request: Request; + headers: string; + socket: Socket; + } + export interface ClientBeforeConnectMessage { + connectParams: ConnectParams; + connector: Connector; + } + export interface ClientConnectedMessage { + socket: Socket; + connectParams: ConnectParams; + connector: Connector; + } + export interface ClientConnectErrorMessage { + error: Error; + socket: Socket; + connectParams: ConnectParams; + connector: Connector; + } +} diff --git a/node_modules/undici-types/dispatcher.d.ts b/node_modules/undici-types/dispatcher.d.ts new file mode 100644 index 0000000..816db19 --- /dev/null +++ b/node_modules/undici-types/dispatcher.d.ts @@ -0,0 +1,241 @@ +import { URL } from 'url' +import { Duplex, Readable, Writable } from 'stream' +import { EventEmitter } from 'events' +import { Blob } from 'buffer' +import { IncomingHttpHeaders } from './header' +import BodyReadable from './readable' +import { FormData } from './formdata' +import Errors from './errors' + +type AbortSignal = unknown; + +export default Dispatcher + +/** Dispatcher is the core API used to dispatch requests. */ +declare class Dispatcher extends EventEmitter { + /** Dispatches a request. This API is expected to evolve through semver-major versions and is less stable than the preceding higher level APIs. It is primarily intended for library developers who implement higher level APIs on top of this. */ + dispatch(options: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandlers): boolean; + /** Starts two-way communications with the requested resource. */ + connect(options: Dispatcher.ConnectOptions): Promise; + connect(options: Dispatcher.ConnectOptions, callback: (err: Error | null, data: Dispatcher.ConnectData) => void): void; + /** Performs an HTTP request. */ + request(options: Dispatcher.RequestOptions): Promise; + request(options: Dispatcher.RequestOptions, callback: (err: Error | null, data: Dispatcher.ResponseData) => void): void; + /** For easy use with `stream.pipeline`. */ + pipeline(options: Dispatcher.PipelineOptions, handler: Dispatcher.PipelineHandler): Duplex; + /** A faster version of `Dispatcher.request`. */ + stream(options: Dispatcher.RequestOptions, factory: Dispatcher.StreamFactory): Promise; + stream(options: Dispatcher.RequestOptions, factory: Dispatcher.StreamFactory, callback: (err: Error | null, data: Dispatcher.StreamData) => void): void; + /** Upgrade to a different protocol. */ + upgrade(options: Dispatcher.UpgradeOptions): Promise; + upgrade(options: Dispatcher.UpgradeOptions, callback: (err: Error | null, data: Dispatcher.UpgradeData) => void): void; + /** Closes the client and gracefully waits for enqueued requests to complete before invoking the callback (or returning a promise if no callback is provided). */ + close(): Promise; + close(callback: () => void): void; + /** Destroy the client abruptly with the given err. All the pending and running requests will be asynchronously aborted and error. Waits until socket is closed before invoking the callback (or returning a promise if no callback is provided). Since this operation is asynchronously dispatched there might still be some progress on dispatched requests. */ + destroy(): Promise; + destroy(err: Error | null): Promise; + destroy(callback: () => void): void; + destroy(err: Error | null, callback: () => void): void; + + on(eventName: 'connect', callback: (origin: URL, targets: readonly Dispatcher[]) => void): this; + on(eventName: 'disconnect', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + on(eventName: 'connectionError', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + on(eventName: 'drain', callback: (origin: URL) => void): this; + + + once(eventName: 'connect', callback: (origin: URL, targets: readonly Dispatcher[]) => void): this; + once(eventName: 'disconnect', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + once(eventName: 'connectionError', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + once(eventName: 'drain', callback: (origin: URL) => void): this; + + + off(eventName: 'connect', callback: (origin: URL, targets: readonly Dispatcher[]) => void): this; + off(eventName: 'disconnect', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + off(eventName: 'connectionError', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + off(eventName: 'drain', callback: (origin: URL) => void): this; + + + addListener(eventName: 'connect', callback: (origin: URL, targets: readonly Dispatcher[]) => void): this; + addListener(eventName: 'disconnect', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + addListener(eventName: 'connectionError', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + addListener(eventName: 'drain', callback: (origin: URL) => void): this; + + removeListener(eventName: 'connect', callback: (origin: URL, targets: readonly Dispatcher[]) => void): this; + removeListener(eventName: 'disconnect', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + removeListener(eventName: 'connectionError', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + removeListener(eventName: 'drain', callback: (origin: URL) => void): this; + + prependListener(eventName: 'connect', callback: (origin: URL, targets: readonly Dispatcher[]) => void): this; + prependListener(eventName: 'disconnect', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + prependListener(eventName: 'connectionError', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + prependListener(eventName: 'drain', callback: (origin: URL) => void): this; + + prependOnceListener(eventName: 'connect', callback: (origin: URL, targets: readonly Dispatcher[]) => void): this; + prependOnceListener(eventName: 'disconnect', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + prependOnceListener(eventName: 'connectionError', callback: (origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void): this; + prependOnceListener(eventName: 'drain', callback: (origin: URL) => void): this; + + listeners(eventName: 'connect'): ((origin: URL, targets: readonly Dispatcher[]) => void)[] + listeners(eventName: 'disconnect'): ((origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void)[]; + listeners(eventName: 'connectionError'): ((origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void)[]; + listeners(eventName: 'drain'): ((origin: URL) => void)[]; + + rawListeners(eventName: 'connect'): ((origin: URL, targets: readonly Dispatcher[]) => void)[] + rawListeners(eventName: 'disconnect'): ((origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void)[]; + rawListeners(eventName: 'connectionError'): ((origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError) => void)[]; + rawListeners(eventName: 'drain'): ((origin: URL) => void)[]; + + emit(eventName: 'connect', origin: URL, targets: readonly Dispatcher[]): boolean; + emit(eventName: 'disconnect', origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError): boolean; + emit(eventName: 'connectionError', origin: URL, targets: readonly Dispatcher[], error: Errors.UndiciError): boolean; + emit(eventName: 'drain', origin: URL): boolean; +} + +declare namespace Dispatcher { + export interface DispatchOptions { + origin?: string | URL; + path: string; + method: HttpMethod; + /** Default: `null` */ + body?: string | Buffer | Uint8Array | Readable | null | FormData; + /** Default: `null` */ + headers?: IncomingHttpHeaders | string[] | null; + /** Query string params to be embedded in the request URL. Default: `null` */ + query?: Record; + /** Whether the requests can be safely retried or not. If `false` the request won't be sent until all preceding requests in the pipeline have completed. Default: `true` if `method` is `HEAD` or `GET`. */ + idempotent?: boolean; + /** Whether the response is expected to take a long time and would end up blocking the pipeline. When this is set to `true` further pipelining will be avoided on the same connection until headers have been received. */ + blocking?: boolean; + /** Upgrade the request. Should be used to specify the kind of upgrade i.e. `'Websocket'`. Default: `method === 'CONNECT' || null`. */ + upgrade?: boolean | string | null; + /** The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers. Defaults to 300 seconds. */ + headersTimeout?: number | null; + /** The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use 0 to disable it entirely. Defaults to 300 seconds. */ + bodyTimeout?: number | null; + /** Whether the request should stablish a keep-alive or not. Default `false` */ + reset?: boolean; + /** Whether Undici should throw an error upon receiving a 4xx or 5xx response from the server. Defaults to false */ + throwOnError?: boolean; + /** For H2, it appends the expect: 100-continue header, and halts the request body until a 100-continue is received from the remote server*/ + expectContinue?: boolean; + } + export interface ConnectOptions { + path: string; + /** Default: `null` */ + headers?: IncomingHttpHeaders | string[] | null; + /** Default: `null` */ + signal?: AbortSignal | EventEmitter | null; + /** This argument parameter is passed through to `ConnectData` */ + opaque?: unknown; + /** Default: 0 */ + maxRedirections?: number; + /** Default: `null` */ + responseHeader?: 'raw' | null; + } + export interface RequestOptions extends DispatchOptions { + /** Default: `null` */ + opaque?: unknown; + /** Default: `null` */ + signal?: AbortSignal | EventEmitter | null; + /** Default: 0 */ + maxRedirections?: number; + /** Default: `null` */ + onInfo?: (info: { statusCode: number, headers: Record }) => void; + /** Default: `null` */ + responseHeader?: 'raw' | null; + /** Default: `64 KiB` */ + highWaterMark?: number; + } + export interface PipelineOptions extends RequestOptions { + /** `true` if the `handler` will return an object stream. Default: `false` */ + objectMode?: boolean; + } + export interface UpgradeOptions { + path: string; + /** Default: `'GET'` */ + method?: string; + /** Default: `null` */ + headers?: IncomingHttpHeaders | string[] | null; + /** A string of comma separated protocols, in descending preference order. Default: `'Websocket'` */ + protocol?: string; + /** Default: `null` */ + signal?: AbortSignal | EventEmitter | null; + /** Default: 0 */ + maxRedirections?: number; + /** Default: `null` */ + responseHeader?: 'raw' | null; + } + export interface ConnectData { + statusCode: number; + headers: IncomingHttpHeaders; + socket: Duplex; + opaque: unknown; + } + export interface ResponseData { + statusCode: number; + headers: IncomingHttpHeaders; + body: BodyReadable & BodyMixin; + trailers: Record; + opaque: unknown; + context: object; + } + export interface PipelineHandlerData { + statusCode: number; + headers: IncomingHttpHeaders; + opaque: unknown; + body: BodyReadable; + context: object; + } + export interface StreamData { + opaque: unknown; + trailers: Record; + } + export interface UpgradeData { + headers: IncomingHttpHeaders; + socket: Duplex; + opaque: unknown; + } + export interface StreamFactoryData { + statusCode: number; + headers: IncomingHttpHeaders; + opaque: unknown; + context: object; + } + export type StreamFactory = (data: StreamFactoryData) => Writable; + export interface DispatchHandlers { + /** Invoked before request is dispatched on socket. May be invoked multiple times when a request is retried when the request at the head of the pipeline fails. */ + onConnect?(abort: () => void): void; + /** Invoked when an error has occurred. */ + onError?(err: Error): void; + /** Invoked when request is upgraded either due to a `Upgrade` header or `CONNECT` method. */ + onUpgrade?(statusCode: number, headers: Buffer[] | string[] | null, socket: Duplex): void; + /** Invoked when statusCode and headers have been received. May be invoked multiple times due to 1xx informational headers. */ + onHeaders?(statusCode: number, headers: Buffer[] | string[] | null, resume: () => void): boolean; + /** Invoked when response payload data is received. */ + onData?(chunk: Buffer): boolean; + /** Invoked when response payload and trailers have been received and the request has completed. */ + onComplete?(trailers: string[] | null): void; + /** Invoked when a body chunk is sent to the server. May be invoked multiple times for chunked requests */ + onBodySent?(chunkSize: number, totalBytesSent: number): void; + } + export type PipelineHandler = (data: PipelineHandlerData) => Readable; + export type HttpMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH'; + + /** + * @link https://fetch.spec.whatwg.org/#body-mixin + */ + interface BodyMixin { + readonly body?: never; // throws on node v16.6.0 + readonly bodyUsed: boolean; + arrayBuffer(): Promise; + blob(): Promise; + formData(): Promise; + json(): Promise; + text(): Promise; + } + + export interface DispatchInterceptor { + (dispatch: Dispatcher['dispatch']): Dispatcher['dispatch'] + } +} diff --git a/node_modules/undici-types/errors.d.ts b/node_modules/undici-types/errors.d.ts new file mode 100644 index 0000000..7923ddd --- /dev/null +++ b/node_modules/undici-types/errors.d.ts @@ -0,0 +1,128 @@ +import { IncomingHttpHeaders } from "./header"; +import Client from './client' + +export default Errors + +declare namespace Errors { + export class UndiciError extends Error { + name: string; + code: string; + } + + /** Connect timeout error. */ + export class ConnectTimeoutError extends UndiciError { + name: 'ConnectTimeoutError'; + code: 'UND_ERR_CONNECT_TIMEOUT'; + } + + /** A header exceeds the `headersTimeout` option. */ + export class HeadersTimeoutError extends UndiciError { + name: 'HeadersTimeoutError'; + code: 'UND_ERR_HEADERS_TIMEOUT'; + } + + /** Headers overflow error. */ + export class HeadersOverflowError extends UndiciError { + name: 'HeadersOverflowError' + code: 'UND_ERR_HEADERS_OVERFLOW' + } + + /** A body exceeds the `bodyTimeout` option. */ + export class BodyTimeoutError extends UndiciError { + name: 'BodyTimeoutError'; + code: 'UND_ERR_BODY_TIMEOUT'; + } + + export class ResponseStatusCodeError extends UndiciError { + constructor ( + message?: string, + statusCode?: number, + headers?: IncomingHttpHeaders | string[] | null, + body?: null | Record | string + ); + name: 'ResponseStatusCodeError'; + code: 'UND_ERR_RESPONSE_STATUS_CODE'; + body: null | Record | string + status: number + statusCode: number + headers: IncomingHttpHeaders | string[] | null; + } + + /** Passed an invalid argument. */ + export class InvalidArgumentError extends UndiciError { + name: 'InvalidArgumentError'; + code: 'UND_ERR_INVALID_ARG'; + } + + /** Returned an invalid value. */ + export class InvalidReturnValueError extends UndiciError { + name: 'InvalidReturnValueError'; + code: 'UND_ERR_INVALID_RETURN_VALUE'; + } + + /** The request has been aborted by the user. */ + export class RequestAbortedError extends UndiciError { + name: 'AbortError'; + code: 'UND_ERR_ABORTED'; + } + + /** Expected error with reason. */ + export class InformationalError extends UndiciError { + name: 'InformationalError'; + code: 'UND_ERR_INFO'; + } + + /** Request body length does not match content-length header. */ + export class RequestContentLengthMismatchError extends UndiciError { + name: 'RequestContentLengthMismatchError'; + code: 'UND_ERR_REQ_CONTENT_LENGTH_MISMATCH'; + } + + /** Response body length does not match content-length header. */ + export class ResponseContentLengthMismatchError extends UndiciError { + name: 'ResponseContentLengthMismatchError'; + code: 'UND_ERR_RES_CONTENT_LENGTH_MISMATCH'; + } + + /** Trying to use a destroyed client. */ + export class ClientDestroyedError extends UndiciError { + name: 'ClientDestroyedError'; + code: 'UND_ERR_DESTROYED'; + } + + /** Trying to use a closed client. */ + export class ClientClosedError extends UndiciError { + name: 'ClientClosedError'; + code: 'UND_ERR_CLOSED'; + } + + /** There is an error with the socket. */ + export class SocketError extends UndiciError { + name: 'SocketError'; + code: 'UND_ERR_SOCKET'; + socket: Client.SocketInfo | null + } + + /** Encountered unsupported functionality. */ + export class NotSupportedError extends UndiciError { + name: 'NotSupportedError'; + code: 'UND_ERR_NOT_SUPPORTED'; + } + + /** No upstream has been added to the BalancedPool. */ + export class BalancedPoolMissingUpstreamError extends UndiciError { + name: 'MissingUpstreamError'; + code: 'UND_ERR_BPL_MISSING_UPSTREAM'; + } + + export class HTTPParserError extends UndiciError { + name: 'HTTPParserError'; + code: string; + } + + /** The response exceed the length allowed. */ + export class ResponseExceededMaxSizeError extends UndiciError { + name: 'ResponseExceededMaxSizeError'; + code: 'UND_ERR_RES_EXCEEDED_MAX_SIZE'; + } +} diff --git a/node_modules/undici-types/fetch.d.ts b/node_modules/undici-types/fetch.d.ts new file mode 100644 index 0000000..fa4619c --- /dev/null +++ b/node_modules/undici-types/fetch.d.ts @@ -0,0 +1,209 @@ +// based on https://github.com/Ethan-Arrowood/undici-fetch/blob/249269714db874351589d2d364a0645d5160ae71/index.d.ts (MIT license) +// and https://github.com/node-fetch/node-fetch/blob/914ce6be5ec67a8bab63d68510aabf07cb818b6d/index.d.ts (MIT license) +/// + +import { Blob } from 'buffer' +import { URL, URLSearchParams } from 'url' +import { ReadableStream } from 'stream/web' +import { FormData } from './formdata' + +import Dispatcher from './dispatcher' + +export type RequestInfo = string | URL | Request + +export declare function fetch ( + input: RequestInfo, + init?: RequestInit +): Promise + +export type BodyInit = + | ArrayBuffer + | AsyncIterable + | Blob + | FormData + | Iterable + | NodeJS.ArrayBufferView + | URLSearchParams + | null + | string + +export interface BodyMixin { + readonly body: ReadableStream | null + readonly bodyUsed: boolean + + readonly arrayBuffer: () => Promise + readonly blob: () => Promise + readonly formData: () => Promise + readonly json: () => Promise + readonly text: () => Promise +} + +export interface SpecIterator { + next(...args: [] | [TNext]): IteratorResult; +} + +export interface SpecIterableIterator extends SpecIterator { + [Symbol.iterator](): SpecIterableIterator; +} + +export interface SpecIterable { + [Symbol.iterator](): SpecIterator; +} + +export type HeadersInit = string[][] | Record> | Headers + +export declare class Headers implements SpecIterable<[string, string]> { + constructor (init?: HeadersInit) + readonly append: (name: string, value: string) => void + readonly delete: (name: string) => void + readonly get: (name: string) => string | null + readonly has: (name: string) => boolean + readonly set: (name: string, value: string) => void + readonly getSetCookie: () => string[] + readonly forEach: ( + callbackfn: (value: string, key: string, iterable: Headers) => void, + thisArg?: unknown + ) => void + + readonly keys: () => SpecIterableIterator + readonly values: () => SpecIterableIterator + readonly entries: () => SpecIterableIterator<[string, string]> + readonly [Symbol.iterator]: () => SpecIterator<[string, string]> +} + +export type RequestCache = + | 'default' + | 'force-cache' + | 'no-cache' + | 'no-store' + | 'only-if-cached' + | 'reload' + +export type RequestCredentials = 'omit' | 'include' | 'same-origin' + +type RequestDestination = + | '' + | 'audio' + | 'audioworklet' + | 'document' + | 'embed' + | 'font' + | 'image' + | 'manifest' + | 'object' + | 'paintworklet' + | 'report' + | 'script' + | 'sharedworker' + | 'style' + | 'track' + | 'video' + | 'worker' + | 'xslt' + +export interface RequestInit { + method?: string + keepalive?: boolean + headers?: HeadersInit + body?: BodyInit + redirect?: RequestRedirect + integrity?: string + signal?: AbortSignal + credentials?: RequestCredentials + mode?: RequestMode + referrer?: string + referrerPolicy?: ReferrerPolicy + window?: null + dispatcher?: Dispatcher + duplex?: RequestDuplex +} + +export type ReferrerPolicy = + | '' + | 'no-referrer' + | 'no-referrer-when-downgrade' + | 'origin' + | 'origin-when-cross-origin' + | 'same-origin' + | 'strict-origin' + | 'strict-origin-when-cross-origin' + | 'unsafe-url'; + +export type RequestMode = 'cors' | 'navigate' | 'no-cors' | 'same-origin' + +export type RequestRedirect = 'error' | 'follow' | 'manual' + +export type RequestDuplex = 'half' + +export declare class Request implements BodyMixin { + constructor (input: RequestInfo, init?: RequestInit) + + readonly cache: RequestCache + readonly credentials: RequestCredentials + readonly destination: RequestDestination + readonly headers: Headers + readonly integrity: string + readonly method: string + readonly mode: RequestMode + readonly redirect: RequestRedirect + readonly referrerPolicy: string + readonly url: string + + readonly keepalive: boolean + readonly signal: AbortSignal + readonly duplex: RequestDuplex + + readonly body: ReadableStream | null + readonly bodyUsed: boolean + + readonly arrayBuffer: () => Promise + readonly blob: () => Promise + readonly formData: () => Promise + readonly json: () => Promise + readonly text: () => Promise + + readonly clone: () => Request +} + +export interface ResponseInit { + readonly status?: number + readonly statusText?: string + readonly headers?: HeadersInit +} + +export type ResponseType = + | 'basic' + | 'cors' + | 'default' + | 'error' + | 'opaque' + | 'opaqueredirect' + +export type ResponseRedirectStatus = 301 | 302 | 303 | 307 | 308 + +export declare class Response implements BodyMixin { + constructor (body?: BodyInit, init?: ResponseInit) + + readonly headers: Headers + readonly ok: boolean + readonly status: number + readonly statusText: string + readonly type: ResponseType + readonly url: string + readonly redirected: boolean + + readonly body: ReadableStream | null + readonly bodyUsed: boolean + + readonly arrayBuffer: () => Promise + readonly blob: () => Promise + readonly formData: () => Promise + readonly json: () => Promise + readonly text: () => Promise + + readonly clone: () => Response + + static error (): Response + static json(data: any, init?: ResponseInit): Response + static redirect (url: string | URL, status: ResponseRedirectStatus): Response +} diff --git a/node_modules/undici-types/file.d.ts b/node_modules/undici-types/file.d.ts new file mode 100644 index 0000000..c695b7a --- /dev/null +++ b/node_modules/undici-types/file.d.ts @@ -0,0 +1,39 @@ +// Based on https://github.com/octet-stream/form-data/blob/2d0f0dc371517444ce1f22cdde13f51995d0953a/lib/File.ts (MIT) +/// + +import { Blob } from 'buffer' + +export interface BlobPropertyBag { + type?: string + endings?: 'native' | 'transparent' +} + +export interface FilePropertyBag extends BlobPropertyBag { + /** + * The last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). Files without a known last modified date return the current date. + */ + lastModified?: number +} + +export declare class File extends Blob { + /** + * Creates a new File instance. + * + * @param fileBits An `Array` strings, or [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), [`ArrayBufferView`](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView), [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) objects, or a mix of any of such objects, that will be put inside the [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File). + * @param fileName The name of the file. + * @param options An options object containing optional attributes for the file. + */ + constructor(fileBits: ReadonlyArray, fileName: string, options?: FilePropertyBag) + + /** + * Name of the file referenced by the File object. + */ + readonly name: string + + /** + * The last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). Files without a known last modified date return the current date. + */ + readonly lastModified: number + + readonly [Symbol.toStringTag]: string +} diff --git a/node_modules/undici-types/filereader.d.ts b/node_modules/undici-types/filereader.d.ts new file mode 100644 index 0000000..f05d231 --- /dev/null +++ b/node_modules/undici-types/filereader.d.ts @@ -0,0 +1,54 @@ +/// + +import { Blob } from 'buffer' +import { DOMException, Event, EventInit, EventTarget } from './patch' + +export declare class FileReader { + __proto__: EventTarget & FileReader + + constructor () + + readAsArrayBuffer (blob: Blob): void + readAsBinaryString (blob: Blob): void + readAsText (blob: Blob, encoding?: string): void + readAsDataURL (blob: Blob): void + + abort (): void + + static readonly EMPTY = 0 + static readonly LOADING = 1 + static readonly DONE = 2 + + readonly EMPTY = 0 + readonly LOADING = 1 + readonly DONE = 2 + + readonly readyState: number + + readonly result: string | ArrayBuffer | null + + readonly error: DOMException | null + + onloadstart: null | ((this: FileReader, event: ProgressEvent) => void) + onprogress: null | ((this: FileReader, event: ProgressEvent) => void) + onload: null | ((this: FileReader, event: ProgressEvent) => void) + onabort: null | ((this: FileReader, event: ProgressEvent) => void) + onerror: null | ((this: FileReader, event: ProgressEvent) => void) + onloadend: null | ((this: FileReader, event: ProgressEvent) => void) +} + +export interface ProgressEventInit extends EventInit { + lengthComputable?: boolean + loaded?: number + total?: number +} + +export declare class ProgressEvent { + __proto__: Event & ProgressEvent + + constructor (type: string, eventInitDict?: ProgressEventInit) + + readonly lengthComputable: boolean + readonly loaded: number + readonly total: number +} diff --git a/node_modules/undici-types/formdata.d.ts b/node_modules/undici-types/formdata.d.ts new file mode 100644 index 0000000..df29a57 --- /dev/null +++ b/node_modules/undici-types/formdata.d.ts @@ -0,0 +1,108 @@ +// Based on https://github.com/octet-stream/form-data/blob/2d0f0dc371517444ce1f22cdde13f51995d0953a/lib/FormData.ts (MIT) +/// + +import { File } from './file' +import { SpecIterator, SpecIterableIterator } from './fetch' + +/** + * A `string` or `File` that represents a single value from a set of `FormData` key-value pairs. + */ +declare type FormDataEntryValue = string | File + +/** + * Provides a way to easily construct a set of key/value pairs representing form fields and their values, which can then be easily sent using fetch(). + */ +export declare class FormData { + /** + * Appends a new value onto an existing key inside a FormData object, + * or adds the key if it does not already exist. + * + * The difference between `set()` and `append()` is that if the specified key already exists, `set()` will overwrite all existing values with the new one, whereas `append()` will append the new value onto the end of the existing set of values. + * + * @param name The name of the field whose data is contained in `value`. + * @param value The field's value. This can be [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) + or [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File). If none of these are specified the value is converted to a string. + * @param fileName The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename. + */ + append(name: string, value: unknown, fileName?: string): void + + /** + * Set a new value for an existing key inside FormData, + * or add the new field if it does not already exist. + * + * @param name The name of the field whose data is contained in `value`. + * @param value The field's value. This can be [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) + or [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File). If none of these are specified the value is converted to a string. + * @param fileName The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename. + * + */ + set(name: string, value: unknown, fileName?: string): void + + /** + * Returns the first value associated with a given key from within a `FormData` object. + * If you expect multiple values and want all of them, use the `getAll()` method instead. + * + * @param {string} name A name of the value you want to retrieve. + * + * @returns A `FormDataEntryValue` containing the value. If the key doesn't exist, the method returns null. + */ + get(name: string): FormDataEntryValue | null + + /** + * Returns all the values associated with a given key from within a `FormData` object. + * + * @param {string} name A name of the value you want to retrieve. + * + * @returns An array of `FormDataEntryValue` whose key matches the value passed in the `name` parameter. If the key doesn't exist, the method returns an empty list. + */ + getAll(name: string): FormDataEntryValue[] + + /** + * Returns a boolean stating whether a `FormData` object contains a certain key. + * + * @param name A string representing the name of the key you want to test for. + * + * @return A boolean value. + */ + has(name: string): boolean + + /** + * Deletes a key and its value(s) from a `FormData` object. + * + * @param name The name of the key you want to delete. + */ + delete(name: string): void + + /** + * Executes given callback function for each field of the FormData instance + */ + forEach: ( + callbackfn: (value: FormDataEntryValue, key: string, iterable: FormData) => void, + thisArg?: unknown + ) => void + + /** + * Returns an [`iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) allowing to go through all keys contained in this `FormData` object. + * Each key is a `string`. + */ + keys: () => SpecIterableIterator + + /** + * Returns an [`iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) allowing to go through all values contained in this object `FormData` object. + * Each value is a [`FormDataValue`](https://developer.mozilla.org/en-US/docs/Web/API/FormDataEntryValue). + */ + values: () => SpecIterableIterator + + /** + * Returns an [`iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) allowing to go through the `FormData` key/value pairs. + * The key of each pair is a string; the value is a [`FormDataValue`](https://developer.mozilla.org/en-US/docs/Web/API/FormDataEntryValue). + */ + entries: () => SpecIterableIterator<[string, FormDataEntryValue]> + + /** + * An alias for FormData#entries() + */ + [Symbol.iterator]: () => SpecIterableIterator<[string, FormDataEntryValue]> + + readonly [Symbol.toStringTag]: string +} diff --git a/node_modules/undici-types/global-dispatcher.d.ts b/node_modules/undici-types/global-dispatcher.d.ts new file mode 100644 index 0000000..728f95c --- /dev/null +++ b/node_modules/undici-types/global-dispatcher.d.ts @@ -0,0 +1,9 @@ +import Dispatcher from "./dispatcher"; + +export { + getGlobalDispatcher, + setGlobalDispatcher +} + +declare function setGlobalDispatcher(dispatcher: DispatcherImplementation): void; +declare function getGlobalDispatcher(): Dispatcher; diff --git a/node_modules/undici-types/global-origin.d.ts b/node_modules/undici-types/global-origin.d.ts new file mode 100644 index 0000000..322542d --- /dev/null +++ b/node_modules/undici-types/global-origin.d.ts @@ -0,0 +1,7 @@ +export { + setGlobalOrigin, + getGlobalOrigin +} + +declare function setGlobalOrigin(origin: string | URL | undefined): void; +declare function getGlobalOrigin(): URL | undefined; \ No newline at end of file diff --git a/node_modules/undici-types/handlers.d.ts b/node_modules/undici-types/handlers.d.ts new file mode 100644 index 0000000..eb4f5a9 --- /dev/null +++ b/node_modules/undici-types/handlers.d.ts @@ -0,0 +1,9 @@ +import Dispatcher from "./dispatcher"; + +export declare class RedirectHandler implements Dispatcher.DispatchHandlers{ + constructor (dispatch: Dispatcher, maxRedirections: number, opts: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandlers) +} + +export declare class DecoratorHandler implements Dispatcher.DispatchHandlers{ + constructor (handler: Dispatcher.DispatchHandlers) +} diff --git a/node_modules/undici-types/header.d.ts b/node_modules/undici-types/header.d.ts new file mode 100644 index 0000000..bfdb329 --- /dev/null +++ b/node_modules/undici-types/header.d.ts @@ -0,0 +1,4 @@ +/** + * The header type declaration of `undici`. + */ +export type IncomingHttpHeaders = Record; diff --git a/node_modules/undici-types/index.d.ts b/node_modules/undici-types/index.d.ts new file mode 100644 index 0000000..4589845 --- /dev/null +++ b/node_modules/undici-types/index.d.ts @@ -0,0 +1,63 @@ +import Dispatcher from'./dispatcher' +import { setGlobalDispatcher, getGlobalDispatcher } from './global-dispatcher' +import { setGlobalOrigin, getGlobalOrigin } from './global-origin' +import Pool from'./pool' +import { RedirectHandler, DecoratorHandler } from './handlers' + +import BalancedPool from './balanced-pool' +import Client from'./client' +import buildConnector from'./connector' +import errors from'./errors' +import Agent from'./agent' +import MockClient from'./mock-client' +import MockPool from'./mock-pool' +import MockAgent from'./mock-agent' +import mockErrors from'./mock-errors' +import ProxyAgent from'./proxy-agent' +import { request, pipeline, stream, connect, upgrade } from './api' + +export * from './cookies' +export * from './fetch' +export * from './file' +export * from './filereader' +export * from './formdata' +export * from './diagnostics-channel' +export * from './websocket' +export * from './content-type' +export * from './cache' +export { Interceptable } from './mock-interceptor' + +export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent, RedirectHandler, DecoratorHandler } +export default Undici + +declare namespace Undici { + var Dispatcher: typeof import('./dispatcher').default + var Pool: typeof import('./pool').default; + var RedirectHandler: typeof import ('./handlers').RedirectHandler + var DecoratorHandler: typeof import ('./handlers').DecoratorHandler + var createRedirectInterceptor: typeof import ('./interceptors').createRedirectInterceptor + var BalancedPool: typeof import('./balanced-pool').default; + var Client: typeof import('./client').default; + var buildConnector: typeof import('./connector').default; + var errors: typeof import('./errors').default; + var Agent: typeof import('./agent').default; + var setGlobalDispatcher: typeof import('./global-dispatcher').setGlobalDispatcher; + var getGlobalDispatcher: typeof import('./global-dispatcher').getGlobalDispatcher; + var request: typeof import('./api').request; + var stream: typeof import('./api').stream; + var pipeline: typeof import('./api').pipeline; + var connect: typeof import('./api').connect; + var upgrade: typeof import('./api').upgrade; + var MockClient: typeof import('./mock-client').default; + var MockPool: typeof import('./mock-pool').default; + var MockAgent: typeof import('./mock-agent').default; + var mockErrors: typeof import('./mock-errors').default; + var fetch: typeof import('./fetch').fetch; + var Headers: typeof import('./fetch').Headers; + var Response: typeof import('./fetch').Response; + var Request: typeof import('./fetch').Request; + var FormData: typeof import('./formdata').FormData; + var File: typeof import('./file').File; + var FileReader: typeof import('./filereader').FileReader; + var caches: typeof import('./cache').caches; +} diff --git a/node_modules/undici-types/interceptors.d.ts b/node_modules/undici-types/interceptors.d.ts new file mode 100644 index 0000000..047ac17 --- /dev/null +++ b/node_modules/undici-types/interceptors.d.ts @@ -0,0 +1,5 @@ +import Dispatcher from "./dispatcher"; + +type RedirectInterceptorOpts = { maxRedirections?: number } + +export declare function createRedirectInterceptor (opts: RedirectInterceptorOpts): Dispatcher.DispatchInterceptor diff --git a/node_modules/undici-types/mock-agent.d.ts b/node_modules/undici-types/mock-agent.d.ts new file mode 100644 index 0000000..98cd645 --- /dev/null +++ b/node_modules/undici-types/mock-agent.d.ts @@ -0,0 +1,50 @@ +import Agent from './agent' +import Dispatcher from './dispatcher' +import { Interceptable, MockInterceptor } from './mock-interceptor' +import MockDispatch = MockInterceptor.MockDispatch; + +export default MockAgent + +interface PendingInterceptor extends MockDispatch { + origin: string; +} + +/** A mocked Agent class that implements the Agent API. It allows one to intercept HTTP requests made through undici and return mocked responses instead. */ +declare class MockAgent extends Dispatcher { + constructor(options?: MockAgent.Options) + /** Creates and retrieves mock Dispatcher instances which can then be used to intercept HTTP requests. If the number of connections on the mock agent is set to 1, a MockClient instance is returned. Otherwise a MockPool instance is returned. */ + get(origin: string): TInterceptable; + get(origin: RegExp): TInterceptable; + get(origin: ((origin: string) => boolean)): TInterceptable; + /** Dispatches a mocked request. */ + dispatch(options: Agent.DispatchOptions, handler: Dispatcher.DispatchHandlers): boolean; + /** Closes the mock agent and waits for registered mock pools and clients to also close before resolving. */ + close(): Promise; + /** Disables mocking in MockAgent. */ + deactivate(): void; + /** Enables mocking in a MockAgent instance. When instantiated, a MockAgent is automatically activated. Therefore, this method is only effective after `MockAgent.deactivate` has been called. */ + activate(): void; + /** Define host matchers so only matching requests that aren't intercepted by the mock dispatchers will be attempted. */ + enableNetConnect(): void; + enableNetConnect(host: string): void; + enableNetConnect(host: RegExp): void; + enableNetConnect(host: ((host: string) => boolean)): void; + /** Causes all requests to throw when requests are not matched in a MockAgent intercept. */ + disableNetConnect(): void; + pendingInterceptors(): PendingInterceptor[]; + assertNoPendingInterceptors(options?: { + pendingInterceptorsFormatter?: PendingInterceptorsFormatter; + }): void; +} + +interface PendingInterceptorsFormatter { + format(pendingInterceptors: readonly PendingInterceptor[]): string; +} + +declare namespace MockAgent { + /** MockAgent options. */ + export interface Options extends Agent.Options { + /** A custom agent to be encapsulated by the MockAgent. */ + agent?: Agent; + } +} diff --git a/node_modules/undici-types/mock-client.d.ts b/node_modules/undici-types/mock-client.d.ts new file mode 100644 index 0000000..51d008c --- /dev/null +++ b/node_modules/undici-types/mock-client.d.ts @@ -0,0 +1,25 @@ +import Client from './client' +import Dispatcher from './dispatcher' +import MockAgent from './mock-agent' +import { MockInterceptor, Interceptable } from './mock-interceptor' + +export default MockClient + +/** MockClient extends the Client API and allows one to mock requests. */ +declare class MockClient extends Client implements Interceptable { + constructor(origin: string, options: MockClient.Options); + /** Intercepts any matching requests that use the same origin as this mock client. */ + intercept(options: MockInterceptor.Options): MockInterceptor; + /** Dispatches a mocked request. */ + dispatch(options: Dispatcher.DispatchOptions, handlers: Dispatcher.DispatchHandlers): boolean; + /** Closes the mock client and gracefully waits for enqueued requests to complete. */ + close(): Promise; +} + +declare namespace MockClient { + /** MockClient options. */ + export interface Options extends Client.Options { + /** The agent to associate this MockClient with. */ + agent: MockAgent; + } +} diff --git a/node_modules/undici-types/mock-errors.d.ts b/node_modules/undici-types/mock-errors.d.ts new file mode 100644 index 0000000..3d9e727 --- /dev/null +++ b/node_modules/undici-types/mock-errors.d.ts @@ -0,0 +1,12 @@ +import Errors from './errors' + +export default MockErrors + +declare namespace MockErrors { + /** The request does not match any registered mock dispatches. */ + export class MockNotMatchedError extends Errors.UndiciError { + constructor(message?: string); + name: 'MockNotMatchedError'; + code: 'UND_MOCK_ERR_MOCK_NOT_MATCHED'; + } +} diff --git a/node_modules/undici-types/mock-interceptor.d.ts b/node_modules/undici-types/mock-interceptor.d.ts new file mode 100644 index 0000000..6b3961c --- /dev/null +++ b/node_modules/undici-types/mock-interceptor.d.ts @@ -0,0 +1,93 @@ +import { IncomingHttpHeaders } from './header' +import Dispatcher from './dispatcher'; +import { BodyInit, Headers } from './fetch' + +export { + Interceptable, + MockInterceptor, + MockScope +} + +/** The scope associated with a mock dispatch. */ +declare class MockScope { + constructor(mockDispatch: MockInterceptor.MockDispatch); + /** Delay a reply by a set amount of time in ms. */ + delay(waitInMs: number): MockScope; + /** Persist the defined mock data for the associated reply. It will return the defined mock data indefinitely. */ + persist(): MockScope; + /** Define a reply for a set amount of matching requests. */ + times(repeatTimes: number): MockScope; +} + +/** The interceptor for a Mock. */ +declare class MockInterceptor { + constructor(options: MockInterceptor.Options, mockDispatches: MockInterceptor.MockDispatch[]); + /** Mock an undici request with the defined reply. */ + reply(replyOptionsCallback: MockInterceptor.MockReplyOptionsCallback): MockScope; + reply( + statusCode: number, + data?: TData | Buffer | string | MockInterceptor.MockResponseDataHandler, + responseOptions?: MockInterceptor.MockResponseOptions + ): MockScope; + /** Mock an undici request by throwing the defined reply error. */ + replyWithError(error: TError): MockScope; + /** Set default reply headers on the interceptor for subsequent mocked replies. */ + defaultReplyHeaders(headers: IncomingHttpHeaders): MockInterceptor; + /** Set default reply trailers on the interceptor for subsequent mocked replies. */ + defaultReplyTrailers(trailers: Record): MockInterceptor; + /** Set automatically calculated content-length header on subsequent mocked replies. */ + replyContentLength(): MockInterceptor; +} + +declare namespace MockInterceptor { + /** MockInterceptor options. */ + export interface Options { + /** Path to intercept on. */ + path: string | RegExp | ((path: string) => boolean); + /** Method to intercept on. Defaults to GET. */ + method?: string | RegExp | ((method: string) => boolean); + /** Body to intercept on. */ + body?: string | RegExp | ((body: string) => boolean); + /** Headers to intercept on. */ + headers?: Record boolean)> | ((headers: Record) => boolean); + /** Query params to intercept on */ + query?: Record; + } + export interface MockDispatch extends Options { + times: number | null; + persist: boolean; + consumed: boolean; + data: MockDispatchData; + } + export interface MockDispatchData extends MockResponseOptions { + error: TError | null; + statusCode?: number; + data?: TData | string; + } + export interface MockResponseOptions { + headers?: IncomingHttpHeaders; + trailers?: Record; + } + + export interface MockResponseCallbackOptions { + path: string; + origin: string; + method: string; + body?: BodyInit | Dispatcher.DispatchOptions['body']; + headers: Headers | Record; + maxRedirections: number; + } + + export type MockResponseDataHandler = ( + opts: MockResponseCallbackOptions + ) => TData | Buffer | string; + + export type MockReplyOptionsCallback = ( + opts: MockResponseCallbackOptions + ) => { statusCode: number, data?: TData | Buffer | string, responseOptions?: MockResponseOptions } +} + +interface Interceptable extends Dispatcher { + /** Intercepts any matching requests that use the same origin as this mock client. */ + intercept(options: MockInterceptor.Options): MockInterceptor; +} diff --git a/node_modules/undici-types/mock-pool.d.ts b/node_modules/undici-types/mock-pool.d.ts new file mode 100644 index 0000000..39e709a --- /dev/null +++ b/node_modules/undici-types/mock-pool.d.ts @@ -0,0 +1,25 @@ +import Pool from './pool' +import MockAgent from './mock-agent' +import { Interceptable, MockInterceptor } from './mock-interceptor' +import Dispatcher from './dispatcher' + +export default MockPool + +/** MockPool extends the Pool API and allows one to mock requests. */ +declare class MockPool extends Pool implements Interceptable { + constructor(origin: string, options: MockPool.Options); + /** Intercepts any matching requests that use the same origin as this mock pool. */ + intercept(options: MockInterceptor.Options): MockInterceptor; + /** Dispatches a mocked request. */ + dispatch(options: Dispatcher.DispatchOptions, handlers: Dispatcher.DispatchHandlers): boolean; + /** Closes the mock pool and gracefully waits for enqueued requests to complete. */ + close(): Promise; +} + +declare namespace MockPool { + /** MockPool options. */ + export interface Options extends Pool.Options { + /** The agent to associate this MockPool with. */ + agent: MockAgent; + } +} diff --git a/node_modules/undici-types/package.json b/node_modules/undici-types/package.json new file mode 100644 index 0000000..be7aa4c --- /dev/null +++ b/node_modules/undici-types/package.json @@ -0,0 +1,55 @@ +{ + "name": "undici-types", + "version": "5.26.5", + "description": "A stand-alone types package for Undici", + "homepage": "https://undici.nodejs.org", + "bugs": { + "url": "https://github.com/nodejs/undici/issues" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/nodejs/undici.git" + }, + "license": "MIT", + "types": "index.d.ts", + "files": [ + "*.d.ts" + ], + "contributors": [ + { + "name": "Daniele Belardi", + "url": "https://github.com/dnlup", + "author": true + }, + { + "name": "Ethan Arrowood", + "url": "https://github.com/ethan-arrowood", + "author": true + }, + { + "name": "Matteo Collina", + "url": "https://github.com/mcollina", + "author": true + }, + { + "name": "Matthew Aitken", + "url": "https://github.com/KhafraDev", + "author": true + }, + { + "name": "Robert Nagy", + "url": "https://github.com/ronag", + "author": true + }, + { + "name": "Szymon Marczak", + "url": "https://github.com/szmarczak", + "author": true + }, + { + "name": "Tomas Della Vedova", + "url": "https://github.com/delvedor", + "author": true + } + ] +} \ No newline at end of file diff --git a/node_modules/undici-types/patch.d.ts b/node_modules/undici-types/patch.d.ts new file mode 100644 index 0000000..3871acf --- /dev/null +++ b/node_modules/undici-types/patch.d.ts @@ -0,0 +1,71 @@ +/// + +// See https://github.com/nodejs/undici/issues/1740 + +export type DOMException = typeof globalThis extends { DOMException: infer T } + ? T + : any + +export type EventTarget = typeof globalThis extends { EventTarget: infer T } + ? T + : { + addEventListener( + type: string, + listener: any, + options?: any, + ): void + dispatchEvent(event: Event): boolean + removeEventListener( + type: string, + listener: any, + options?: any | boolean, + ): void + } + +export type Event = typeof globalThis extends { Event: infer T } + ? T + : { + readonly bubbles: boolean + cancelBubble: () => void + readonly cancelable: boolean + readonly composed: boolean + composedPath(): [EventTarget?] + readonly currentTarget: EventTarget | null + readonly defaultPrevented: boolean + readonly eventPhase: 0 | 2 + readonly isTrusted: boolean + preventDefault(): void + returnValue: boolean + readonly srcElement: EventTarget | null + stopImmediatePropagation(): void + stopPropagation(): void + readonly target: EventTarget | null + readonly timeStamp: number + readonly type: string + } + +export interface EventInit { + bubbles?: boolean + cancelable?: boolean + composed?: boolean +} + +export interface EventListenerOptions { + capture?: boolean +} + +export interface AddEventListenerOptions extends EventListenerOptions { + once?: boolean + passive?: boolean + signal?: AbortSignal +} + +export type EventListenerOrEventListenerObject = EventListener | EventListenerObject + +export interface EventListenerObject { + handleEvent (object: Event): void +} + +export interface EventListener { + (evt: Event): void +} diff --git a/node_modules/undici-types/pool-stats.d.ts b/node_modules/undici-types/pool-stats.d.ts new file mode 100644 index 0000000..8b6d2bf --- /dev/null +++ b/node_modules/undici-types/pool-stats.d.ts @@ -0,0 +1,19 @@ +import Pool from "./pool" + +export default PoolStats + +declare class PoolStats { + constructor(pool: Pool); + /** Number of open socket connections in this pool. */ + connected: number; + /** Number of open socket connections in this pool that do not have an active request. */ + free: number; + /** Number of pending requests across all clients in this pool. */ + pending: number; + /** Number of queued requests across all clients in this pool. */ + queued: number; + /** Number of currently active requests across all clients in this pool. */ + running: number; + /** Number of active, pending, or queued requests across all clients in this pool. */ + size: number; +} diff --git a/node_modules/undici-types/pool.d.ts b/node_modules/undici-types/pool.d.ts new file mode 100644 index 0000000..7747d48 --- /dev/null +++ b/node_modules/undici-types/pool.d.ts @@ -0,0 +1,28 @@ +import Client from './client' +import TPoolStats from './pool-stats' +import { URL } from 'url' +import Dispatcher from "./dispatcher"; + +export default Pool + +declare class Pool extends Dispatcher { + constructor(url: string | URL, options?: Pool.Options) + /** `true` after `pool.close()` has been called. */ + closed: boolean; + /** `true` after `pool.destroyed()` has been called or `pool.close()` has been called and the pool shutdown has completed. */ + destroyed: boolean; + /** Aggregate stats for a Pool. */ + readonly stats: TPoolStats; +} + +declare namespace Pool { + export type PoolStats = TPoolStats; + export interface Options extends Client.Options { + /** Default: `(origin, opts) => new Client(origin, opts)`. */ + factory?(origin: URL, opts: object): Dispatcher; + /** The max number of clients to create. `null` if no limit. Default `null`. */ + connections?: number | null; + + interceptors?: { Pool?: readonly Dispatcher.DispatchInterceptor[] } & Client.Options["interceptors"] + } +} diff --git a/node_modules/undici-types/proxy-agent.d.ts b/node_modules/undici-types/proxy-agent.d.ts new file mode 100644 index 0000000..96b2638 --- /dev/null +++ b/node_modules/undici-types/proxy-agent.d.ts @@ -0,0 +1,30 @@ +import Agent from './agent' +import buildConnector from './connector'; +import Client from './client' +import Dispatcher from './dispatcher' +import { IncomingHttpHeaders } from './header' +import Pool from './pool' + +export default ProxyAgent + +declare class ProxyAgent extends Dispatcher { + constructor(options: ProxyAgent.Options | string) + + dispatch(options: Agent.DispatchOptions, handler: Dispatcher.DispatchHandlers): boolean; + close(): Promise; +} + +declare namespace ProxyAgent { + export interface Options extends Agent.Options { + uri: string; + /** + * @deprecated use opts.token + */ + auth?: string; + token?: string; + headers?: IncomingHttpHeaders; + requestTls?: buildConnector.BuildOptions; + proxyTls?: buildConnector.BuildOptions; + clientFactory?(origin: URL, opts: object): Dispatcher; + } +} diff --git a/node_modules/undici-types/readable.d.ts b/node_modules/undici-types/readable.d.ts new file mode 100644 index 0000000..4549a8c --- /dev/null +++ b/node_modules/undici-types/readable.d.ts @@ -0,0 +1,61 @@ +import { Readable } from "stream"; +import { Blob } from 'buffer' + +export default BodyReadable + +declare class BodyReadable extends Readable { + constructor( + resume?: (this: Readable, size: number) => void | null, + abort?: () => void | null, + contentType?: string + ) + + /** Consumes and returns the body as a string + * https://fetch.spec.whatwg.org/#dom-body-text + */ + text(): Promise + + /** Consumes and returns the body as a JavaScript Object + * https://fetch.spec.whatwg.org/#dom-body-json + */ + json(): Promise + + /** Consumes and returns the body as a Blob + * https://fetch.spec.whatwg.org/#dom-body-blob + */ + blob(): Promise + + /** Consumes and returns the body as an ArrayBuffer + * https://fetch.spec.whatwg.org/#dom-body-arraybuffer + */ + arrayBuffer(): Promise + + /** Not implemented + * + * https://fetch.spec.whatwg.org/#dom-body-formdata + */ + formData(): Promise + + /** Returns true if the body is not null and the body has been consumed + * + * Otherwise, returns false + * + * https://fetch.spec.whatwg.org/#dom-body-bodyused + */ + readonly bodyUsed: boolean + + /** Throws on node 16.6.0 + * + * If body is null, it should return null as the body + * + * If body is not null, should return the body as a ReadableStream + * + * https://fetch.spec.whatwg.org/#dom-body-body + */ + readonly body: never | undefined + + /** Dumps the response body by reading `limit` number of bytes. + * @param opts.limit Number of bytes to read (optional) - Default: 262144 + */ + dump(opts?: { limit: number }): Promise +} diff --git a/node_modules/undici-types/webidl.d.ts b/node_modules/undici-types/webidl.d.ts new file mode 100644 index 0000000..40cfe06 --- /dev/null +++ b/node_modules/undici-types/webidl.d.ts @@ -0,0 +1,220 @@ +// These types are not exported, and are only used internally + +/** + * Take in an unknown value and return one that is of type T + */ +type Converter = (object: unknown) => T + +type SequenceConverter = (object: unknown) => T[] + +type RecordConverter = (object: unknown) => Record + +interface ConvertToIntOpts { + clamp?: boolean + enforceRange?: boolean +} + +interface WebidlErrors { + exception (opts: { header: string, message: string }): TypeError + /** + * @description Throw an error when conversion from one type to another has failed + */ + conversionFailed (opts: { + prefix: string + argument: string + types: string[] + }): TypeError + /** + * @description Throw an error when an invalid argument is provided + */ + invalidArgument (opts: { + prefix: string + value: string + type: string + }): TypeError +} + +interface WebidlUtil { + /** + * @see https://tc39.es/ecma262/#sec-ecmascript-data-types-and-values + */ + Type (object: unknown): + | 'Undefined' + | 'Boolean' + | 'String' + | 'Symbol' + | 'Number' + | 'BigInt' + | 'Null' + | 'Object' + + /** + * @see https://webidl.spec.whatwg.org/#abstract-opdef-converttoint + */ + ConvertToInt ( + V: unknown, + bitLength: number, + signedness: 'signed' | 'unsigned', + opts?: ConvertToIntOpts + ): number + + /** + * @see https://webidl.spec.whatwg.org/#abstract-opdef-converttoint + */ + IntegerPart (N: number): number +} + +interface WebidlConverters { + /** + * @see https://webidl.spec.whatwg.org/#es-DOMString + */ + DOMString (V: unknown, opts?: { + legacyNullToEmptyString: boolean + }): string + + /** + * @see https://webidl.spec.whatwg.org/#es-ByteString + */ + ByteString (V: unknown): string + + /** + * @see https://webidl.spec.whatwg.org/#es-USVString + */ + USVString (V: unknown): string + + /** + * @see https://webidl.spec.whatwg.org/#es-boolean + */ + boolean (V: unknown): boolean + + /** + * @see https://webidl.spec.whatwg.org/#es-any + */ + any (V: Value): Value + + /** + * @see https://webidl.spec.whatwg.org/#es-long-long + */ + ['long long'] (V: unknown): number + + /** + * @see https://webidl.spec.whatwg.org/#es-unsigned-long-long + */ + ['unsigned long long'] (V: unknown): number + + /** + * @see https://webidl.spec.whatwg.org/#es-unsigned-long + */ + ['unsigned long'] (V: unknown): number + + /** + * @see https://webidl.spec.whatwg.org/#es-unsigned-short + */ + ['unsigned short'] (V: unknown, opts?: ConvertToIntOpts): number + + /** + * @see https://webidl.spec.whatwg.org/#idl-ArrayBuffer + */ + ArrayBuffer (V: unknown): ArrayBufferLike + ArrayBuffer (V: unknown, opts: { allowShared: false }): ArrayBuffer + + /** + * @see https://webidl.spec.whatwg.org/#es-buffer-source-types + */ + TypedArray ( + V: unknown, + TypedArray: NodeJS.TypedArray | ArrayBufferLike + ): NodeJS.TypedArray | ArrayBufferLike + TypedArray ( + V: unknown, + TypedArray: NodeJS.TypedArray | ArrayBufferLike, + opts?: { allowShared: false } + ): NodeJS.TypedArray | ArrayBuffer + + /** + * @see https://webidl.spec.whatwg.org/#es-buffer-source-types + */ + DataView (V: unknown, opts?: { allowShared: boolean }): DataView + + /** + * @see https://webidl.spec.whatwg.org/#BufferSource + */ + BufferSource ( + V: unknown, + opts?: { allowShared: boolean } + ): NodeJS.TypedArray | ArrayBufferLike | DataView + + ['sequence']: SequenceConverter + + ['sequence>']: SequenceConverter + + ['record']: RecordConverter + + [Key: string]: (...args: any[]) => unknown +} + +export interface Webidl { + errors: WebidlErrors + util: WebidlUtil + converters: WebidlConverters + + /** + * @description Performs a brand-check on {@param V} to ensure it is a + * {@param cls} object. + */ + brandCheck (V: unknown, cls: Interface, opts?: { strict?: boolean }): asserts V is Interface + + /** + * @see https://webidl.spec.whatwg.org/#es-sequence + * @description Convert a value, V, to a WebIDL sequence type. + */ + sequenceConverter (C: Converter): SequenceConverter + + illegalConstructor (): never + + /** + * @see https://webidl.spec.whatwg.org/#es-to-record + * @description Convert a value, V, to a WebIDL record type. + */ + recordConverter ( + keyConverter: Converter, + valueConverter: Converter + ): RecordConverter + + /** + * Similar to {@link Webidl.brandCheck} but allows skipping the check if third party + * interfaces are allowed. + */ + interfaceConverter (cls: Interface): ( + V: unknown, + opts?: { strict: boolean } + ) => asserts V is typeof cls + + // TODO(@KhafraDev): a type could likely be implemented that can infer the return type + // from the converters given? + /** + * Converts a value, V, to a WebIDL dictionary types. Allows limiting which keys are + * allowed, values allowed, optional and required keys. Auto converts the value to + * a type given a converter. + */ + dictionaryConverter (converters: { + key: string, + defaultValue?: unknown, + required?: boolean, + converter: (...args: unknown[]) => unknown, + allowedValues?: unknown[] + }[]): (V: unknown) => Record + + /** + * @see https://webidl.spec.whatwg.org/#idl-nullable-type + * @description allows a type, V, to be null + */ + nullableConverter ( + converter: Converter + ): (V: unknown) => ReturnType | null + + argumentLengthCheck (args: { length: number }, min: number, context: { + header: string + message?: string + }): void +} diff --git a/node_modules/undici-types/websocket.d.ts b/node_modules/undici-types/websocket.d.ts new file mode 100644 index 0000000..15a357d --- /dev/null +++ b/node_modules/undici-types/websocket.d.ts @@ -0,0 +1,131 @@ +/// + +import type { Blob } from 'buffer' +import type { MessagePort } from 'worker_threads' +import { + EventTarget, + Event, + EventInit, + EventListenerOptions, + AddEventListenerOptions, + EventListenerOrEventListenerObject +} from './patch' +import Dispatcher from './dispatcher' +import { HeadersInit } from './fetch' + +export type BinaryType = 'blob' | 'arraybuffer' + +interface WebSocketEventMap { + close: CloseEvent + error: Event + message: MessageEvent + open: Event +} + +interface WebSocket extends EventTarget { + binaryType: BinaryType + + readonly bufferedAmount: number + readonly extensions: string + + onclose: ((this: WebSocket, ev: WebSocketEventMap['close']) => any) | null + onerror: ((this: WebSocket, ev: WebSocketEventMap['error']) => any) | null + onmessage: ((this: WebSocket, ev: WebSocketEventMap['message']) => any) | null + onopen: ((this: WebSocket, ev: WebSocketEventMap['open']) => any) | null + + readonly protocol: string + readonly readyState: number + readonly url: string + + close(code?: number, reason?: string): void + send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void + + readonly CLOSED: number + readonly CLOSING: number + readonly CONNECTING: number + readonly OPEN: number + + addEventListener( + type: K, + listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any, + options?: boolean | AddEventListenerOptions + ): void + addEventListener( + type: string, + listener: EventListenerOrEventListenerObject, + options?: boolean | AddEventListenerOptions + ): void + removeEventListener( + type: K, + listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any, + options?: boolean | EventListenerOptions + ): void + removeEventListener( + type: string, + listener: EventListenerOrEventListenerObject, + options?: boolean | EventListenerOptions + ): void +} + +export declare const WebSocket: { + prototype: WebSocket + new (url: string | URL, protocols?: string | string[] | WebSocketInit): WebSocket + readonly CLOSED: number + readonly CLOSING: number + readonly CONNECTING: number + readonly OPEN: number +} + +interface CloseEventInit extends EventInit { + code?: number + reason?: string + wasClean?: boolean +} + +interface CloseEvent extends Event { + readonly code: number + readonly reason: string + readonly wasClean: boolean +} + +export declare const CloseEvent: { + prototype: CloseEvent + new (type: string, eventInitDict?: CloseEventInit): CloseEvent +} + +interface MessageEventInit extends EventInit { + data?: T + lastEventId?: string + origin?: string + ports?: (typeof MessagePort)[] + source?: typeof MessagePort | null +} + +interface MessageEvent extends Event { + readonly data: T + readonly lastEventId: string + readonly origin: string + readonly ports: ReadonlyArray + readonly source: typeof MessagePort | null + initMessageEvent( + type: string, + bubbles?: boolean, + cancelable?: boolean, + data?: any, + origin?: string, + lastEventId?: string, + source?: typeof MessagePort | null, + ports?: (typeof MessagePort)[] + ): void; +} + +export declare const MessageEvent: { + prototype: MessageEvent + new(type: string, eventInitDict?: MessageEventInit): MessageEvent +} + +interface WebSocketInit { + protocols?: string | string[], + dispatcher?: Dispatcher, + headers?: HeadersInit +}