@types/node 16.4.2 → 16.4.6

node/punycode.d.ts

@@ -1,41 +1,81 @@
 /**
- * @deprecated since v7.0.0
- * The version of the punycode module bundled in Node.js is being deprecated.
- * In a future major version of Node.js this module will be removed.
- * Users currently depending on the punycode module should switch to using
- * the userland-provided Punycode.js module instead.
+ * **The version of the punycode module bundled in Node.js is being deprecated**.
+ * In a future major version of Node.js this module will be removed. Users
+ * currently depending on the `punycode` module should switch to using the
+ * userland-provided [Punycode.js](https://github.com/bestiejs/punycode.js) module instead. For punycode-based URL
+ * encoding, see `url.domainToASCII` or, more generally, the `WHATWG URL API`.
+ *
+ * The `punycode` module is a bundled version of the [Punycode.js](https://github.com/bestiejs/punycode.js) module. It
+ * can be accessed using:
+ *
+ * ```js
+ * const punycode = require('punycode');
+ * ```
+ *
+ * [Punycode](https://tools.ietf.org/html/rfc3492) is a character encoding scheme defined by RFC 3492 that is
+ * primarily intended for use in Internationalized Domain Names. Because host
+ * names in URLs are limited to ASCII characters only, Domain Names that contain
+ * non-ASCII characters must be converted into ASCII using the Punycode scheme.
+ * For instance, the Japanese character that translates into the English word,`'example'` is `'例'`. The Internationalized Domain Name, `'例.com'` (equivalent
+ * to `'example.com'`) is represented by Punycode as the ASCII string`'xn--fsq.com'`.
+ *
+ * The `punycode` module provides a simple implementation of the Punycode standard.
+ *
+ * The `punycode` module is a third-party dependency used by Node.js and
+ * 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.4.2/lib/punycode.js)
  */
 declare module 'punycode' {
     /**
-     * @deprecated since v7.0.0
-     * The version of the punycode module bundled in Node.js is being deprecated.
-     * In a future major version of Node.js this module will be removed.
-     * Users currently depending on the punycode module should switch to using
-     * the userland-provided Punycode.js module instead.
+     * 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.
+     *
+     * ```js
+     * punycode.decode('maana-pta'); // 'mañana'
+     * punycode.decode('--dqo34k'); // '☃-⌘'
+     * ```
+     * @since v0.5.1
      */
     function decode(string: string): string;
     /**
-     * @deprecated since v7.0.0
-     * The version of the punycode module bundled in Node.js is being deprecated.
-     * In a future major version of Node.js this module will be removed.
-     * Users currently depending on the punycode module should switch to using
-     * the userland-provided Punycode.js module instead.
+     * The `punycode.encode()` method converts a string of Unicode codepoints to a[Punycode](https://tools.ietf.org/html/rfc3492) string of ASCII-only characters.
+     *
+     * ```js
+     * punycode.encode('mañana'); // 'maana-pta'
+     * punycode.encode('☃-⌘'); // '--dqo34k'
+     * ```
+     * @since v0.5.1
      */
     function encode(string: string): string;
     /**
-     * @deprecated since v7.0.0
-     * The version of the punycode module bundled in Node.js is being deprecated.
-     * In a future major version of Node.js this module will be removed.
-     * Users currently depending on the punycode module should switch to using
-     * the userland-provided Punycode.js module instead.
+     * The `punycode.toUnicode()` method converts a string representing a domain name
+     * containing [Punycode](https://tools.ietf.org/html/rfc3492) encoded characters into Unicode. Only the [Punycode](https://tools.ietf.org/html/rfc3492)encoded parts of the domain name are be
+     * converted.
+     *
+     * ```js
+     * // decode domain names
+     * punycode.toUnicode('xn--maana-pta.com'); // 'mañana.com'
+     * punycode.toUnicode('xn----dqo34k.com');  // '☃-⌘.com'
+     * punycode.toUnicode('example.com');       // 'example.com'
+     * ```
+     * @since v0.6.1
      */
     function toUnicode(domain: string): string;
     /**
-     * @deprecated since v7.0.0
-     * The version of the punycode module bundled in Node.js is being deprecated.
-     * In a future major version of Node.js this module will be removed.
-     * Users currently depending on the punycode module should switch to using
-     * the userland-provided Punycode.js module instead.
+     * The `punycode.toASCII()` method converts a Unicode string representing an
+     * Internationalized Domain Name to [Punycode](https://tools.ietf.org/html/rfc3492). Only the non-ASCII parts of the
+     * domain name will be converted. Calling `punycode.toASCII()` on a string that
+     * already only contains ASCII characters will have no effect.
+     *
+     * ```js
+     * // encode domain names
+     * punycode.toASCII('mañana.com');  // 'xn--maana-pta.com'
+     * punycode.toASCII('☃-⌘.com');   // 'xn----dqo34k.com'
+     * punycode.toASCII('example.com'); // 'example.com'
+     * ```
+     * @since v0.6.1
      */
     function toASCII(domain: string): string;
     /**
@@ -73,7 +113,6 @@ declare module 'punycode' {
      */
     const version: string;
 }
-
 declare module 'node:punycode' {
     export * from 'punycode';
 }

node/querystring.d.ts

@@ -1,19 +1,95 @@
+/**
+ * The `querystring` module provides utilities for parsing and formatting URL
+ * query strings. It can be accessed using:
+ *
+ * ```js
+ * const querystring = require('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.4.2/lib/querystring.js)
+ */
 declare module 'querystring' {
     interface StringifyOptions {
         encodeURIComponent?: ((str: string) => string) | undefined;
     }
-
     interface ParseOptions {
         maxKeys?: number | undefined;
         decodeURIComponent?: ((str: string) => string) | undefined;
     }
-
-    interface ParsedUrlQuery extends NodeJS.Dict<string | string[]> { }
-
-    interface ParsedUrlQueryInput extends NodeJS.Dict<string | number | boolean | ReadonlyArray<string> | ReadonlyArray<number> | ReadonlyArray<boolean> | null> {
-    }
-
+    interface ParsedUrlQuery extends NodeJS.Dict<string | string[]> {}
+    interface ParsedUrlQueryInput extends NodeJS.Dict<string | number | boolean | ReadonlyArray<string> | ReadonlyArray<number> | ReadonlyArray<boolean> | null> {}
+    /**
+     * The `querystring.stringify()` method produces a URL query string from a
+     * given `obj` by iterating through the object's "own properties".
+     *
+     * It serializes the following types of values passed in `obj`:[&lt;string&gt;](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) |
+     * [&lt;number&gt;](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) |
+     * [&lt;bigint&gt;](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) |
+     * [&lt;boolean&gt;](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) |
+     * [&lt;string\[\]&gt;](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) |
+     * [&lt;number\[\]&gt;](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) |
+     * [&lt;bigint\[\]&gt;](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) |
+     * [&lt;boolean\[\]&gt;](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)The numeric values must be finite. Any other input values will be coerced to
+     * empty strings.
+     *
+     * ```js
+     * querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' });
+     * // Returns 'foo=bar&#x26;baz=qux&#x26;baz=quux&#x26;corge='
+     *
+     * querystring.stringify({ foo: 'bar', baz: 'qux' }, ';', ':');
+     * // Returns 'foo:bar;baz:qux'
+     * ```
+     *
+     * By default, characters requiring percent-encoding within the query string will
+     * be encoded as UTF-8\. If an alternative encoding is required, then an alternative`encodeURIComponent` option will need to be specified:
+     *
+     * ```js
+     * // Assuming gbkEncodeURIComponent function already exists,
+     *
+     * querystring.stringify({ w: '中文', foo: 'bar' }, null, null,
+     *                       { encodeURIComponent: gbkEncodeURIComponent });
+     * ```
+     * @since v0.1.25
+     * @param obj The object to serialize into a URL query string
+     * @param sep The substring used to delimit key and value pairs in the query string.
+     * @param eq . The substring used to delimit keys and values in the query string.
+     */
     function stringify(obj?: ParsedUrlQueryInput, sep?: string, eq?: string, options?: StringifyOptions): string;
+    /**
+     * The `querystring.parse()` method parses a URL query string (`str`) into a
+     * collection of key and value pairs.
+     *
+     * For example, the query string `'foo=bar&#x26;abc=xyz&#x26;abc=123'` is parsed into:
+     *
+     * ```js
+     * {
+     *   foo: 'bar',
+     *   abc: ['xyz', '123']
+     * }
+     * ```
+     *
+     * The object returned by the `querystring.parse()` method _does 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_.
+     *
+     * By default, percent-encoded characters within the query string will be assumed
+     * to use UTF-8 encoding. If an alternative character encoding is used, then an
+     * alternative `decodeURIComponent` option will need to be specified:
+     *
+     * ```js
+     * // Assuming gbkDecodeURIComponent function already exists...
+     *
+     * querystring.parse('w=%D6%D0%CE%C4&#x26;foo=bar', null, null,
+     *                   { decodeURIComponent: gbkDecodeURIComponent });
+     * ```
+     * @since v0.1.25
+     * @param str The URL query string to parse
+     * @param sep The substring used to delimit key and value pairs in the query string.
+     * @param eq . The substring used to delimit keys and values in the query string.
+     */
     function parse(str: string, sep?: string, eq?: string, options?: ParseOptions): ParsedUrlQuery;
     /**
      * The querystring.encode() function is an alias for querystring.stringify().
@@ -23,10 +99,33 @@ declare module 'querystring' {
      * The querystring.decode() function is an alias for querystring.parse().
      */
     const decode: typeof parse;
+    /**
+     * The `querystring.escape()` method performs URL percent-encoding on the given`str` in a manner that is optimized for the specific requirements of URL
+     * query strings.
+     *
+     * The `querystring.escape()` method is used by `querystring.stringify()` and is
+     * generally not expected to be used directly. It is exported primarily to allow
+     * application code to provide a replacement percent-encoding implementation if
+     * necessary by assigning `querystring.escape` to an alternative function.
+     * @since v0.1.25
+     */
     function escape(str: string): string;
+    /**
+     * The `querystring.unescape()` method performs decoding of URL percent-encoded
+     * characters on the given `str`.
+     *
+     * The `querystring.unescape()` method is used by `querystring.parse()` and is
+     * generally not expected to be used directly. It is exported primarily to allow
+     * application code to provide a replacement decoding implementation if
+     * necessary by assigning `querystring.unescape` to an alternative function.
+     *
+     * By default, the `querystring.unescape()` method will attempt to use the
+     * JavaScript built-in `decodeURIComponent()` method to decode. If that fails,
+     * a safer equivalent that does not throw on malformed URLs will be used.
+     * @since v0.1.25
+     */
     function unescape(str: string): string;
 }
-
 declare module 'node:querystring' {
     export * from 'querystring';
 }