4ae6bd7c4a7c6b41e6ef100f0b3296171636e59cfd0444cf7964038d7c3501a96e20fcab10245507fcfbcfc2aaae37d6cf41c7bdd1c3b55bc0c99f6ba88550 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152
  1. /**
  2. * The `node:querystring` module provides utilities for parsing and formatting URL
  3. * query strings. It can be accessed using:
  4. *
  5. * ```js
  6. * import querystring from 'node:querystring';
  7. * ```
  8. *
  9. * `querystring` is more performant than `URLSearchParams` but is not a
  10. * standardized API. Use `URLSearchParams` when performance is not critical or
  11. * when compatibility with browser code is desirable.
  12. * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/querystring.js)
  13. */
  14. declare module "querystring" {
  15. interface StringifyOptions {
  16. /**
  17. * The function to use when converting URL-unsafe characters to percent-encoding in the query string.
  18. * @default `querystring.escape()`
  19. */
  20. encodeURIComponent?: ((str: string) => string) | undefined;
  21. }
  22. interface ParseOptions {
  23. /**
  24. * Specifies the maximum number of keys to parse. Specify `0` to remove key counting limitations.
  25. * @default 1000
  26. */
  27. maxKeys?: number | undefined;
  28. /**
  29. * The function to use when decoding percent-encoded characters in the query string.
  30. * @default `querystring.unescape()`
  31. */
  32. decodeURIComponent?: ((str: string) => string) | undefined;
  33. }
  34. interface ParsedUrlQuery extends NodeJS.Dict<string | string[]> {}
  35. interface ParsedUrlQueryInput extends
  36. NodeJS.Dict<
  37. | string
  38. | number
  39. | boolean
  40. | bigint
  41. | ReadonlyArray<string | number | boolean | bigint>
  42. | null
  43. >
  44. {}
  45. /**
  46. * The `querystring.stringify()` method produces a URL query string from a
  47. * given `obj` by iterating through the object's "own properties".
  48. *
  49. * It serializes the following types of values passed in `obj`: [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) |
  50. * [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) |
  51. * [bigint](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) |
  52. * [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) |
  53. * [string\[\]](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) |
  54. * [number\[\]](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) |
  55. * [bigint\[\]](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) |
  56. * [boolean\[\]](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
  57. * empty strings.
  58. *
  59. * ```js
  60. * querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' });
  61. * // Returns 'foo=bar&#x26;baz=qux&#x26;baz=quux&#x26;corge='
  62. *
  63. * querystring.stringify({ foo: 'bar', baz: 'qux' }, ';', ':');
  64. * // Returns 'foo:bar;baz:qux'
  65. * ```
  66. *
  67. * By default, characters requiring percent-encoding within the query string will
  68. * be encoded as UTF-8\. If an alternative encoding is required, then an alternative `encodeURIComponent` option will need to be specified:
  69. *
  70. * ```js
  71. * // Assuming gbkEncodeURIComponent function already exists,
  72. *
  73. * querystring.stringify({ w: '中文', foo: 'bar' }, null, null,
  74. * { encodeURIComponent: gbkEncodeURIComponent });
  75. * ```
  76. * @since v0.1.25
  77. * @param obj The object to serialize into a URL query string
  78. * @param [sep='&'] The substring used to delimit key and value pairs in the query string.
  79. * @param [eq='='] . The substring used to delimit keys and values in the query string.
  80. */
  81. function stringify(obj?: ParsedUrlQueryInput, sep?: string, eq?: string, options?: StringifyOptions): string;
  82. /**
  83. * The `querystring.parse()` method parses a URL query string (`str`) into a
  84. * collection of key and value pairs.
  85. *
  86. * For example, the query string `'foo=bar&#x26;abc=xyz&#x26;abc=123'` is parsed into:
  87. *
  88. * ```json
  89. * {
  90. * "foo": "bar",
  91. * "abc": ["xyz", "123"]
  92. * }
  93. * ```
  94. *
  95. * 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()`,
  96. * `obj.hasOwnProperty()`, and others
  97. * are not defined and _will not work_.
  98. *
  99. * By default, percent-encoded characters within the query string will be assumed
  100. * to use UTF-8 encoding. If an alternative character encoding is used, then an
  101. * alternative `decodeURIComponent` option will need to be specified:
  102. *
  103. * ```js
  104. * // Assuming gbkDecodeURIComponent function already exists...
  105. *
  106. * querystring.parse('w=%D6%D0%CE%C4&#x26;foo=bar', null, null,
  107. * { decodeURIComponent: gbkDecodeURIComponent });
  108. * ```
  109. * @since v0.1.25
  110. * @param str The URL query string to parse
  111. * @param [sep='&'] The substring used to delimit key and value pairs in the query string.
  112. * @param [eq='='] The substring used to delimit keys and values in the query string.
  113. */
  114. function parse(str: string, sep?: string, eq?: string, options?: ParseOptions): ParsedUrlQuery;
  115. /**
  116. * The querystring.encode() function is an alias for querystring.stringify().
  117. */
  118. const encode: typeof stringify;
  119. /**
  120. * The querystring.decode() function is an alias for querystring.parse().
  121. */
  122. const decode: typeof parse;
  123. /**
  124. * The `querystring.escape()` method performs URL percent-encoding on the given `str` in a manner that is optimized for the specific requirements of URL
  125. * query strings.
  126. *
  127. * The `querystring.escape()` method is used by `querystring.stringify()` and is
  128. * generally not expected to be used directly. It is exported primarily to allow
  129. * application code to provide a replacement percent-encoding implementation if
  130. * necessary by assigning `querystring.escape` to an alternative function.
  131. * @since v0.1.25
  132. */
  133. function escape(str: string): string;
  134. /**
  135. * The `querystring.unescape()` method performs decoding of URL percent-encoded
  136. * characters on the given `str`.
  137. *
  138. * The `querystring.unescape()` method is used by `querystring.parse()` and is
  139. * generally not expected to be used directly. It is exported primarily to allow
  140. * application code to provide a replacement decoding implementation if
  141. * necessary by assigning `querystring.unescape` to an alternative function.
  142. *
  143. * By default, the `querystring.unescape()` method will attempt to use the
  144. * JavaScript built-in `decodeURIComponent()` method to decode. If that fails,
  145. * a safer equivalent that does not throw on malformed URLs will be used.
  146. * @since v0.1.25
  147. */
  148. function unescape(str: string): string;
  149. }
  150. declare module "node:querystring" {
  151. export * from "querystring";
  152. }