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