{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.0.json","id":"querystring","path":"/querystring","type":"module","module":"querystring","title":"Query string","introducedIn":"v0.1.25","sourceLink":{"path":"lib/querystring.js","url":"https://github.com/nodejs/node/blob/HEAD/lib/querystring.js"},"stability":{"index":"2","description":"Stable"},"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `node:querystring` module provides utilities for parsing and formatting URL\nquery strings. It can be accessed using:\n\n```js\nconst querystring = require('node:querystring');\n```\n\n`querystring` is more performant than {URLSearchParams} but is not a\nstandardized API. Use {URLSearchParams} when performance is not critical or\nwhen compatibility with browser code is desirable.","summary":"The `node:querystring` module provides utilities for parsing and formatting URL query strings. It can be accessed using:","examples":[{"language":"js","displayName":null,"code":"const querystring = require('node:querystring');"}],"children":[{"kind":"method","id":"querystringdecode","name":"decode","title":"`querystring.decode()`","scope":"module","overloadOf":null,"stability":null,"added":["v0.1.99"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":null},"description":"The `querystring.decode()` function is an alias for `querystring.parse()`.","summary":"The `querystring.decode()` function is an alias for `querystring.parse()`.","examples":[],"children":[]},{"kind":"method","id":"querystringencode","name":"encode","title":"`querystring.encode()`","scope":"module","overloadOf":null,"stability":null,"added":["v0.1.99"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[],"returns":null},"description":"The `querystring.encode()` function is an alias for `querystring.stringify()`.","summary":"The `querystring.encode()` function is an alias for `querystring.stringify()`.","examples":[],"children":[]},{"kind":"method","id":"querystringescapestr","name":"escape","title":"`querystring.escape(str)`","scope":"module","overloadOf":null,"stability":null,"added":["v0.1.25"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"str","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"The `querystring.escape()` method performs URL percent-encoding on the given\n`str` in a manner that is optimized for the specific requirements of URL\nquery strings.\n\nThe `querystring.escape()` method is used by `querystring.stringify()` and is\ngenerally not expected to be used directly. It is exported primarily to allow\napplication code to provide a replacement percent-encoding implementation if\nnecessary by assigning `querystring.escape` to an alternative function.","summary":"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.","examples":[],"children":[]},{"kind":"method","id":"querystringparsestr-sep-eq-options","name":"parse","title":"`querystring.parse(str[, sep[, eq[, options]]])`","scope":"module","overloadOf":null,"stability":null,"added":["v0.1.25"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[{"versions":["v8.0.0"],"prUrl":"https://github.com/nodejs/node/pull/10967","commit":null,"description":"Multiple empty entries are now parsed correctly (e.g. `&=&=`)."},{"versions":["v6.0.0"],"prUrl":"https://github.com/nodejs/node/pull/6055","commit":null,"description":"The returned object no longer inherits from `Object.prototype`."},{"versions":["v6.0.0","v4.2.4"],"prUrl":"https://github.com/nodejs/node/pull/3807","commit":null,"description":"The `eq` parameter may now have a length of more than `1`."}],"signature":{"parameters":[{"name":"str","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"The URL query string to parse","default":null,"optional":false,"rest":false,"properties":[]},{"name":"sep","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"The substring used to delimit key and value pairs in the\nquery string.","default":"'&'","optional":true,"rest":false,"properties":[]},{"name":"eq","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":". The substring used to delimit keys and values in the\nquery string.","default":"'='","optional":true,"rest":false,"properties":[]},{"name":"options","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"","default":null,"optional":true,"rest":false,"properties":[{"name":"decodeURIComponent","type":{"text":"Function","links":[{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":0,"end":8}]},"description":"The function to use when decoding\npercent-encoded characters in the query string.","default":"querystring.unescape()","optional":true,"rest":false,"properties":[]},{"name":"maxKeys","type":{"text":"number","links":[{"name":"number","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type","start":0,"end":6}]},"description":"Specifies the maximum number of keys to parse.\nSpecify `0` to remove key counting limitations.","default":"1000","optional":true,"rest":false,"properties":[]}]}],"returns":null},"description":"The `querystring.parse()` method parses a URL query string (`str`) into a\ncollection of key and value pairs.\n\nFor example, the query string `'foo=bar&abc=xyz&abc=123'` is parsed into:\n\n```json\n{\n  \"foo\": \"bar\",\n  \"abc\": [\"xyz\", \"123\"]\n}\n```\n\nThe object returned by the `querystring.parse()` method *does not*\nprototypically inherit from the JavaScript `Object`. This means that typical\n`Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others\nare not defined and *will not work*.\n\nBy default, percent-encoded characters within the query string will be assumed\nto use UTF-8 encoding. If an alternative character encoding is used, then an\nalternative `decodeURIComponent` option will need to be specified:\n\n```js\n// Assuming gbkDecodeURIComponent function already exists...\n\nquerystring.parse('w=%D6%D0%CE%C4&foo=bar', null, null,\n                  { decodeURIComponent: gbkDecodeURIComponent });\n```","summary":"The `querystring.parse()` method parses a URL query string (`str`) into a collection of key and value pairs.","examples":[{"language":"json","displayName":null,"code":"{\n  \"foo\": \"bar\",\n  \"abc\": [\"xyz\", \"123\"]\n}"},{"language":"js","displayName":null,"code":"// Assuming gbkDecodeURIComponent function already exists...\n\nquerystring.parse('w=%D6%D0%CE%C4&foo=bar', null, null,\n                  { decodeURIComponent: gbkDecodeURIComponent });"}],"children":[]},{"kind":"method","id":"querystringstringifyobj-sep-eq-options","name":"stringify","title":"`querystring.stringify(obj[, sep[, eq[, options]]])`","scope":"module","overloadOf":null,"stability":null,"added":["v0.1.25"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"obj","type":{"text":"Object","links":[{"name":"Object","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object","start":0,"end":6}]},"description":"The object to serialize into a URL query string","default":null,"optional":false,"rest":false,"properties":[]},{"name":"sep","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"The substring used to delimit key and value pairs in the\nquery string.","default":"'&'","optional":true,"rest":false,"properties":[]},{"name":"eq","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":". The substring used to delimit keys and values in the\nquery string.","default":"'='","optional":true,"rest":false,"properties":[]},{"name":"options","type":null,"description":"","default":null,"optional":true,"rest":false,"properties":[{"name":"encodeURIComponent","type":{"text":"Function","links":[{"name":"Function","href":"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function","start":0,"end":8}]},"description":"The function to use when converting\nURL-unsafe characters to percent-encoding in the query string.","default":"querystring.escape()","optional":true,"rest":false,"properties":[]}]}],"returns":null},"description":"The `querystring.stringify()` method produces a URL query string from a\ngiven `obj` by iterating through the object's \"own properties\".\n\nIt serializes the following types of values passed in `obj`:\n{string | number | bigint | boolean | string[] | number[] | bigint[] | boolean[]}\nThe numeric values must be finite. Any other input values will be coerced to\nempty strings.\n\n```js\nquerystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' });\n// Returns 'foo=bar&baz=qux&baz=quux&corge='\n\nquerystring.stringify({ foo: 'bar', baz: 'qux' }, ';', ':');\n// Returns 'foo:bar;baz:qux'\n```\n\nBy default, characters requiring percent-encoding within the query string will\nbe encoded as UTF-8. If an alternative encoding is required, then an alternative\n`encodeURIComponent` option will need to be specified:\n\n```js\n// Assuming gbkEncodeURIComponent function already exists,\n\nquerystring.stringify({ w: '中文', foo: 'bar' }, null, null,\n                      { encodeURIComponent: gbkEncodeURIComponent });\n```","summary":"The `querystring.stringify()` method produces a URL query string from a given `obj` by iterating through the object's \"own properties\".","examples":[{"language":"js","displayName":null,"code":"querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' });\n// Returns 'foo=bar&baz=qux&baz=quux&corge='\n\nquerystring.stringify({ foo: 'bar', baz: 'qux' }, ';', ':');\n// Returns 'foo:bar;baz:qux'"},{"language":"js","displayName":null,"code":"// Assuming gbkEncodeURIComponent function already exists,\n\nquerystring.stringify({ w: '中文', foo: 'bar' }, null, null,\n                      { encodeURIComponent: gbkEncodeURIComponent });"}],"children":[]},{"kind":"method","id":"querystringunescapestr","name":"unescape","title":"`querystring.unescape(str)`","scope":"module","overloadOf":null,"stability":null,"added":["v0.1.25"],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"signature":{"parameters":[{"name":"str","type":{"text":"string","links":[{"name":"string","href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type","start":0,"end":6}]},"description":"","default":null,"optional":false,"rest":false,"properties":[]}],"returns":null},"description":"The `querystring.unescape()` method performs decoding of URL percent-encoded\ncharacters on the given `str`.\n\nThe `querystring.unescape()` method is used by `querystring.parse()` and is\ngenerally not expected to be used directly. It is exported primarily to allow\napplication code to provide a replacement decoding implementation if\nnecessary by assigning `querystring.unescape` to an alternative function.\n\nBy default, the `querystring.unescape()` method will attempt to use the\nJavaScript built-in `decodeURIComponent()` method to decode. If that fails,\na safer equivalent that does not throw on malformed URLs will be used.","summary":"The `querystring.unescape()` method performs decoding of URL percent-encoded characters on the given `str`.","examples":[],"children":[]}]}