@types/node 16.11.39 → 18.11.2

node/ts4.8/trace_events.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The `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
+ * accepts a list of comma-separated category names.
+ *
+ * The available categories are:
+ *
+ * * `node`: An empty placeholder.
+ * * `node.async_hooks`: Enables capture of detailed `async_hooks` trace data.
+ * 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.dns.native`: Enables capture of trace data for DNS queries.
+ * * `node.environment`: Enables capture of Node.js Environment milestones.
+ * * `node.fs.sync`: Enables capture of trace data for file system sync methods.
+ * * `node.perf`: Enables capture of `Performance API` measurements.
+ *    * `node.perf.usertiming`: Enables capture of only Performance API User Timing
+ *    measures and marks.
+ *    * `node.perf.timerify`: Enables capture of only Performance API timerify
+ *    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.
+ * * `v8`: The `V8` events are GC, compiling, and execution related.
+ *
+ * By default the `node`, `node.async_hooks`, and `v8` categories are enabled.
+ *
+ * ```bash
+ * node --trace-event-categories v8,node,node.async_hooks server.js
+ * ```
+ *
+ * Prior versions of Node.js required the use of the `--trace-events-enabled`flag to enable trace events. This requirement has been removed. However, the`--trace-events-enabled` flag _may_ still be
+ * used and will enable the`node`, `node.async_hooks`, and `v8` trace event categories by default.
+ *
+ * ```bash
+ * node --trace-events-enabled
+ *
+ * # is equivalent to
+ *
+ * node --trace-event-categories v8,node,node.async_hooks
+ * ```
+ *
+ * Alternatively, trace events may be enabled using the `trace_events` module:
+ *
+ * ```js
+ * const trace_events = require('trace_events');
+ * const tracing = trace_events.createTracing({ categories: ['node.perf'] });
+ * tracing.enable();  // Enable trace event capture for the 'node.perf' category
+ *
+ * // do work
+ *
+ * tracing.disable();  // Disable trace event capture for the 'node.perf' category
+ * ```
+ *
+ * Running Node.js with tracing enabled will produce log files that can be opened
+ * in the [`chrome://tracing`](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool) tab of Chrome.
+ *
+ * The logging file is by default called `node_trace.${rotation}.log`, where`${rotation}` is an incrementing log-rotation id. The filepath pattern can
+ * be specified with `--trace-event-file-pattern` that accepts a template
+ * string that supports `${rotation}` and `${pid}`:
+ *
+ * ```bash
+ * 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,
+ * unlike `process.hrtime()` which returns nanoseconds.
+ *
+ * The features from this module are not available in `Worker` threads.
+ * @experimental
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/trace_events.js)
+ */
+declare module 'trace_events' {
+    /**
+     * The `Tracing` object is used to enable or disable tracing for sets of
+     * categories. Instances are created using the
+     * `trace_events.createTracing()` method.
+     *
+     * When created, the `Tracing` object is disabled. Calling the
+     * `tracing.enable()` method adds the categories to the set of enabled trace
+     * event categories. Calling `tracing.disable()` will remove the categories
+     * from the set of enabled trace event categories.
+     */
+    interface Tracing {
+        /**
+         * A comma-separated list of the trace event categories covered by this
+         * `Tracing` object.
+         */
+        readonly categories: string;
+        /**
+         * Disables this `Tracing` object.
+         *
+         * Only trace event categories _not_ covered by other enabled `Tracing`
+         * objects and _not_ specified by the `--trace-event-categories` flag
+         * will be disabled.
+         */
+        disable(): void;
+        /**
+         * Enables this `Tracing` object for the set of categories covered by
+         * the `Tracing` object.
+         */
+        enable(): void;
+        /**
+         * `true` only if the `Tracing` object has been enabled.
+         */
+        readonly enabled: boolean;
+    }
+    interface CreateTracingOptions {
+        /**
+         * An array of trace category names. Values included in the array are
+         * coerced to a string when possible. An error will be thrown if the
+         * value cannot be coerced.
+         */
+        categories: string[];
+    }
+    /**
+     * Creates and returns a `Tracing` object for the given set of `categories`.
+     *
+     * ```js
+     * const trace_events = require('trace_events');
+     * const categories = ['node.perf', 'node.async_hooks'];
+     * const tracing = trace_events.createTracing({ categories });
+     * tracing.enable();
+     * // do stuff
+     * tracing.disable();
+     * ```
+     * @since v10.0.0
+     * @return .
+     */
+    function createTracing(options: CreateTracingOptions): Tracing;
+    /**
+     * Returns a comma-separated list of all currently-enabled trace event
+     * categories. The current set of enabled trace event categories is determined
+     * by the _union_ of all currently-enabled `Tracing` objects and any categories
+     * enabled using the `--trace-event-categories` flag.
+     *
+     * 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 t1 = trace_events.createTracing({ categories: ['node.async_hooks'] });
+     * const t2 = trace_events.createTracing({ categories: ['node.perf'] });
+     * const t3 = trace_events.createTracing({ categories: ['v8'] });
+     *
+     * t1.enable();
+     * t2.enable();
+     *
+     * console.log(trace_events.getEnabledCategories());
+     * ```
+     * @since v10.0.0
+     */
+    function getEnabledCategories(): string | undefined;
+}
+declare module 'node:trace_events' {
+    export * from 'trace_events';
+}

node v16.11/tty.d.ts → node/ts4.8/tty.d.ts

@@ -22,7 +22,7 @@
  *
  * 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/v18.0.0/lib/tty.js)
  */
 declare module 'tty' {
     import * as net from 'node:net';
@@ -52,7 +52,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.

node v16.11/url.d.ts → node/ts4.8/url.d.ts

@@ -5,10 +5,10 @@
  * ```js
  * import url from 'url';
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/url.js)
+ * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/url.js)
  */
 declare module 'url' {
-    import { Blob } from 'node:buffer';
+    import { Blob as NodeBlob } from 'node:buffer';
     import { ClientRequestArgs } from 'node:http';
     import { ParsedUrlQuery, ParsedUrlQueryInput } from 'node:querystring';
     // Input to `url.format`
@@ -59,8 +59,12 @@ declare module 'url' {
      * 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.
+     *
      * @since v0.1.25
-     * @deprecated Legacy: 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,27 +76,67 @@ declare module 'url' {
     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('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
+     * // => 'https://example.com/some/path?page=1&format=json'
+     * ```
      *
-     * console.log(myURL.toString());
-     * // Prints https://a:b@xn--g6w251d/?abc#foo
+     * If `urlObject` is not an object or a string, `url.format()` will throw a `TypeError`.
      *
-     * console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
-     * // Prints 'https://測試/?abc'
-     * ```
-     * @since v7.6.0
-     * @param urlObject A `WHATWG URL` object
-     * @param options
+     * 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
+     * @deprecated 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;
     /**
@@ -161,7 +205,7 @@ declare module 'url' {
     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');
@@ -170,7 +214,7 @@ declare module 'url' {
      * 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) {
@@ -189,8 +233,8 @@ declare module 'url' {
      * ```
      * @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.
+     * @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;
     /**
@@ -288,7 +332,7 @@ declare module 'url' {
      * const myURL = new URL('https://a:b@測試?abc#foo');
      *
      * console.log(urlToHttpOptions(myURL));
-     *
+     * /*
      * {
      *   protocol: 'https:',
      *   hostname: 'xn--g6w251d',
@@ -301,7 +345,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
      */
@@ -351,9 +395,10 @@ 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()`.
@@ -815,7 +860,6 @@ declare module 'url' {
         values(): IterableIterator<string>;
         [Symbol.iterator](): IterableIterator<[string, string]>;
     }
-
     import { URL as _URL, URLSearchParams as _URLSearchParams } from 'url';
     global {
         interface URLSearchParams extends _URLSearchParams {}
@@ -829,21 +873,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' {