\n\n# qs [![Version Badge][npm-version-svg]][package-url]\n\n[![github actions][actions-image]][actions-url]\n[![coverage][codecov-image]][codecov-url]\n[![License][license-image]][license-url]\n[![Downloads][downloads-image]][downloads-url]\n[](https://bestpractices.coreinfrastructure.org/projects/9058)\n\n[![npm badge][npm-badge-png]][package-url]\n\nA querystring parsing and stringifying library with some added security.\n\nLead Maintainer: [Jordan Harband](https://github.com/ljharb)\n\nThe **qs** module was originally created and maintained by [TJ Holowaychuk](https://github.com/visionmedia/node-querystring).\n\n## Usage\n\n```javascript\nvar qs = require('qs');\nvar assert = require('assert');\n\nvar obj = qs.parse('a=c');\nassert.deepEqual(obj, { a: 'c' });\n\nvar str = qs.stringify(obj);\nassert.equal(str, 'a=c');\n```\n\n### Parsing Objects\n\n[](#preventEval)\n```javascript\nqs.parse(string, [options]);\n```\n\n**qs** allows you to create nested objects within your query strings, by surrounding the name of sub-keys with square brackets `[]`.\nFor example, the string `'foo[bar]=baz'` converts to:\n\n```javascript\nassert.deepEqual(qs.parse('foo[bar]=baz'), {\n foo: {\n bar: 'baz'\n }\n});\n```\n\nWhen using the `plainObjects` option the parsed value is returned as a null object, created via `{ __proto__: null }` and as such you should be aware that prototype methods will not exist on it and a user may set those names to whatever value they like:\n\n```javascript\nvar nullObject = qs.parse('a[hasOwnProperty]=b', { plainObjects: true });\nassert.deepEqual(nullObject, { a: { hasOwnProperty: 'b' } });\n```\n\nBy default parameters that would overwrite properties on the object prototype are ignored, if you wish to keep the data from those fields either use `plainObjects` as mentioned above, or set `allowPrototypes` to `true` which will allow user input to overwrite those properties.\n*WARNING* It is generally a bad idea to enable this option as it can cause problems when attempting to use the properties that have been overwritten.\nAlways be careful with this option.\n\n```javascript\nvar protoObject = qs.parse('a[hasOwnProperty]=b', { allowPrototypes: true });\nassert.deepEqual(protoObject, { a: { hasOwnProperty: 'b' } });\n```\n\nURI encoded strings work too:\n\n```javascript\nassert.deepEqual(qs.parse('a%5Bb%5D=c'), {\n a: { b: 'c' }\n});\n```\n\nYou can also nest your objects, like `'foo[bar][baz]=foobarbaz'`:\n\n```javascript\nassert.deepEqual(qs.parse('foo[bar][baz]=foobarbaz'), {\n foo: {\n bar: {\n baz: 'foobarbaz'\n }\n }\n});\n```\n\nBy default, when nesting objects **qs** will only parse up to 5 children deep.\nThis means if you attempt to parse a string like `'a[b][c][d][e][f][g][h][i]=j'` your resulting object will be:\n\n```javascript\nvar expected = {\n a: {\n b: {\n c: {\n d: {\n e: {\n f: {\n '[g][h][i]': 'j'\n }\n }\n }\n }\n }\n }\n};\nvar string = 'a[b][c][d][e][f][g][h][i]=j';\nassert.deepEqual(qs.parse(string), expected);\n```\n\nThis depth can be overridden by passing a `depth` option to `qs.parse(string, [options])`:\n\n```javascript\nvar deep = qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1 });\nassert.deepEqual(deep, { a: { b: { '[c][d][e][f][g][h][i]': 'j' } } });\n```\n\nYou can configure **qs** to throw an error when parsing nested input beyond this depth using the `strictDepth` option (defaulted to false):\n\n```javascript\ntry {\n qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1, strictDepth: true });\n} catch (err) {\n assert(err instanceof RangeError);\n assert.strictEqual(err.message, 'Input depth exceeded depth option of 1 and strictDepth is true');\n}\n```\n\nThe depth limit helps mitigate abuse when **qs** is used to parse user input, and it is recommended to keep it a reasonably small number. The strictDepth option adds a layer of protection by throwing an error when the limit is exceeded, allowing you to catch and handle such cases.\n\nFor similar reasons, by default **qs** will only parse up to 1000 parameters. This can be overridden by passing a `parameterLimit` option:\n\n```javascript\nvar limited = qs.parse('a=b&c=d', { parameterLimit: 1 });\nassert.deepEqual(limited, { a: 'b' });\n```\n\nIf you want an error to be thrown whenever the a limit is exceeded (eg, `parameterLimit`, `arrayLimit`), set the `throwOnLimitExceeded` option to `true`. This option will generate a descriptive error if the query string exceeds a configured limit.\n```javascript\ntry {\n qs.parse('a=1&b=2&c=3&d=4', { parameterLimit: 3, throwOnLimitExceeded: true });\n} catch (err) {\n assert(err instanceof Error);\n assert.strictEqual(err.message, 'Parameter limit exceeded. Only 3 parameters allowed.');\n}\n```\n\nWhen `throwOnLimitExceeded` is set to `false` (default), **qs** will parse up to the specified `parameterLimit` and ignore the rest without throwing an error.\n\nTo bypass the leading question mark, use `ignoreQueryPrefix`:\n\n```javascript\nvar prefixed = qs.parse('?a=b&c=d', { ignoreQueryPrefix: true });\nassert.deepEqual(prefixed, { a: 'b', c: 'd' });\n```\n\nAn optional delimiter can also be passed:\n\n```javascript\nvar delimited = qs.parse('a=b;c=d', { delimiter: ';' });\nassert.deepEqual(delimited, { a: 'b', c: 'd' });\n```\n\nDelimiters can be a regular expression too:\n\n```javascript\nvar regexed = qs.parse('a=b;c=d,e=f', { delimiter: /[;,]/ });\nassert.deepEqual(regexed, { a: 'b', c: 'd', e: 'f' });\n```\n\nOption `allowDots` can be used to enable dot notation:\n\n```javascript\nvar withDots = qs.parse('a.b=c', { allowDots: true });\nassert.deepEqual(withDots, { a: { b: 'c' } });\n```\n\nOption `decodeDotInKeys` can be used to decode dots in keys\nNote: it implies `allowDots`, so `parse` will error if you set `decodeDotInKeys` to `true`, and `allowDots` to `false`.\n\n```javascript\nvar withDots = qs.parse('name%252Eobj.first=John&name%252Eobj.last=Doe', { decodeDotInKeys: true });\nassert.deepEqual(withDots, { 'name.obj': { first: 'John', last: 'Doe' }});\n```\n\nOption `allowEmptyArrays` can be used to allowing empty array values in object\n```javascript\nvar withEmptyArrays = qs.parse('foo[]&bar=baz', { allowEmptyArrays: true });\nassert.deepEqual(withEmptyArrays, { foo: [], bar: 'baz' });\n```\n\nOption `duplicates` can be used to change the behavior when duplicate keys are encountered\n```javascript\nassert.deepEqual(qs.parse('foo=bar&foo=baz'), { foo: ['bar', 'baz'] });\nassert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'combine' }), { foo: ['bar', 'baz'] });\nassert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'first' }), { foo: 'bar' });\nassert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'last' }), { foo: 'baz' });\n```\n\nNote that keys with bracket notation (`[]`) always combine into arrays, regardless of the `duplicates` setting:\n```javascript\nassert.deepEqual(qs.parse('a=1&a=2&b[]=1&b[]=2', { duplicates: 'last' }), { a: '2', b: ['1', '2'] });\n```\n\nIf you have to deal with legacy browsers or services, there's also support for decoding percent-encoded octets as iso-8859-1:\n\n```javascript\nvar oldCharset = qs.parse('a=%A7', { charset: 'iso-8859-1' });\nassert.deepEqual(oldCharset, { a: '§' });\n```\n\nSome services add an initial `utf8=✓` value to forms so that old Internet Explorer versions are more likely to submit the form as utf-8.\nAdditionally, the server can check the value against wrong encodings of the checkmark character and detect that a query string or `application/x-www-form-urlencoded` body was *not* sent as utf-8, eg. if the form had an `accept-charset` parameter or the containing page had a different character set.\n\n**qs** supports this mechanism via the `charsetSentinel` option.\nIf specified, the `utf8` parameter will be omitted from the returned object.\nIt will be used to switch to `iso-8859-1`/`utf-8` mode depending on how the checkmark is encoded.\n\n**Important**: When you specify both the `charset` option and the `charsetSentinel` option, the `charset` will be overridden when the request contains a `utf8` parameter from which the actual charset can be deduced.\nIn that sense the `charset` will behave as the default charset rather than the authoritative charset.\n\n```javascript\nvar detectedAsUtf8 = qs.parse('utf8=%E2%9C%93&a=%C3%B8', {\n charset: 'iso-8859-1',\n charsetSentinel: true\n});\nassert.deepEqual(detectedAsUtf8, { a: 'ø' });\n\n// Browsers encode the checkmark as ✓ when submitting as iso-8859-1:\nvar detectedAsIso8859_1 = qs.parse('utf8=%26%2310003%3B&a=%F8', {\n charset: 'utf-8',\n charsetSentinel: true\n});\nassert.deepEqual(detectedAsIso8859_1, { a: 'ø' });\n```\n\nIf you want to decode the `&#...;` syntax to the actual character, you can specify the `interpretNumericEntities` option as well:\n\n```javascript\nvar detectedAsIso8859_1 = qs.parse('a=%26%239786%3B', {\n charset: 'iso-8859-1',\n interpretNumericEntities: true\n});\nassert.deepEqual(detectedAsIso8859_1, { a: '☺' });\n```\n\nIt also works when the charset has been detected in `charsetSentinel` mode.\n\n### Parsing Arrays\n\n**qs** can also parse arrays using a similar `[]` notation:\n\n```javascript\nvar withArray = qs.parse('a[]=b&a[]=c');\nassert.deepEqual(withArray, { a: ['b', 'c'] });\n```\n\nYou may specify an index as well:\n\n```javascript\nvar withIndexes = qs.parse('a[1]=c&a[0]=b');\nassert.deepEqual(withIndexes, { a: ['b', 'c'] });\n```\n\nNote that the only difference between an index in an array and a key in an object is that the value between the brackets must be a number to create an array.\nWhen creating arrays with specific indices, **qs** will compact a sparse array to only the existing values preserving their order:\n\n```javascript\nvar noSparse = qs.parse('a[1]=b&a[15]=c');\nassert.deepEqual(noSparse, { a: ['b', 'c'] });\n```\n\nYou may also use `allowSparse` option to parse sparse arrays:\n\n```javascript\nvar sparseArray = qs.parse('a[1]=2&a[3]=5', { allowSparse: true });\nassert.deepEqual(sparseArray, { a: [, '2', , '5'] });\n```\n\nNote that an empty string is also a value, and will be preserved:\n\n```javascript\nvar withEmptyString = qs.parse('a[]=&a[]=b');\nassert.deepEqual(withEmptyString, { a: ['', 'b'] });\n\nvar withIndexedEmptyString = qs.parse('a[0]=b&a[1]=&a[2]=c');\nassert.deepEqual(withIndexedEmptyString, { a: ['b', '', 'c'] });\n```\n\n**qs** will also limit arrays to a maximum of `20` elements.\nAny array members with an index of `20` or greater will instead be converted to an object with the index as the key.\nThis is needed to handle cases when someone sent, for example, `a[999999999]` and it will take significant time to iterate over this huge array.\n\n```javascript\nvar withMaxIndex = qs.parse('a[100]=b');\nassert.deepEqual(withMaxIndex, { a: { '100': 'b' } });\n```\n\nThis limit can be overridden by passing an `arrayLimit` option:\n\n```javascript\nvar withArrayLimit = qs.parse('a[1]=b', { arrayLimit: 0 });\nassert.deepEqual(withArrayLimit, { a: { '1': 'b' } });\n```\n\nIf you want to throw an error whenever the array limit is exceeded, set the `throwOnLimitExceeded` option to `true`. This option will generate a descriptive error if the query string exceeds a configured limit.\n```javascript\ntry {\n qs.parse('a[1]=b', { arrayLimit: 0, throwOnLimitExceeded: true });\n} catch (err) {\n assert(err instanceof Error);\n assert.strictEqual(err.message, 'Array limit exceeded. Only 0 elements allowed in an array.');\n}\n```\n\nWhen `throwOnLimitExceeded` is set to `false` (default), **qs** will parse up to the specified `arrayLimit` and if the limit is exceeded, the array will instead be converted to an object with the index as the key\n\nTo prevent array syntax (`a[]`, `a[0]`) from being parsed as arrays, set `parseArrays` to `false`.\nNote that duplicate keys (e.g. `a=b&a=c`) may still produce arrays when `duplicates` is `'combine'` (the default).\n\n```javascript\nvar noParsingArrays = qs.parse('a[]=b', { parseArrays: false });\nassert.deepEqual(noParsingArrays, { a: { '0': 'b' } });\n```\n\nIf you mix notations, **qs** will merge the two items into an object:\n\n```javascript\nvar mixedNotation = qs.parse('a[0]=b&a[b]=c');\nassert.deepEqual(mixedNotation, { a: { '0': 'b', b: 'c' } });\n```\n\nWhen a key appears as both a plain value and an object, **qs** will by default wrap the conflicting values in an array (`strictMerge` defaults to `true`):\n\n```javascript\nassert.deepEqual(qs.parse('a[b]=c&a=d'), { a: [{ b: 'c' }, 'd'] });\nassert.deepEqual(qs.parse('a=d&a[b]=c'), { a: ['d', { b: 'c' }] });\n```\n\nTo restore the legacy behavior (where the primitive is used as a key with value `true`), set `strictMerge` to `false`:\n\n```javascript\nassert.deepEqual(qs.parse('a[b]=c&a=d', { strictMerge: false }), { a: { b: 'c', d: true } });\n```\n\nYou can also create arrays of objects:\n\n```javascript\nvar arraysOfObjects = qs.parse('a[][b]=c');\nassert.deepEqual(arraysOfObjects, { a: [{ b: 'c' }] });\n```\n\nSome people use comma to join array, **qs** can parse it:\n```javascript\nvar arraysOfObjects = qs.parse('a=b,c', { comma: true })\nassert.deepEqual(arraysOfObjects, { a: ['b', 'c'] })\n```\n(_this cannot convert nested objects, such as `a={b:1},{c:d}`_)\n\n### Parsing primitive/scalar values (numbers, booleans, null, etc)\n\nBy default, all values are parsed as strings.\nThis behavior will not change and is explained in [issue #91](https://github.com/ljharb/qs/issues/91).\n\n```javascript\nvar primitiveValues = qs.parse('a=15&b=true&c=null');\nassert.deepEqual(primitiveValues, { a: '15', b: 'true', c: 'null' });\n```\n\nIf you wish to auto-convert values which look like numbers, booleans, and other values into their primitive counterparts, you can use the [query-types Express JS middleware](https://github.com/xpepermint/query-types) which will auto-convert all request query parameters.\n\n### Stringifying\n\n[](#preventEval)\n```javascript\nqs.stringify(object, [options]);\n```\n\nWhen stringifying, **qs** by default URI encodes output. Objects are stringified as you would expect:\n\n```javascript\nassert.equal(qs.stringify({ a: 'b' }), 'a=b');\nassert.equal(qs.stringify({ a: { b: 'c' } }), 'a%5Bb%5D=c');\n```\n\nThis encoding can be disabled by setting the `encode` option to `false`:\n\n```javascript\nvar unencoded = qs.stringify({ a: { b: 'c' } }, { encode: false });\nassert.equal(unencoded, 'a[b]=c');\n```\n\nEncoding can be disabled for keys by setting the `encodeValuesOnly` option to `true`:\n```javascript\nvar encodedValues = qs.stringify(\n { a: 'b', c: ['d', 'e=f'], f: [['g'], ['h']] },\n { encodeValuesOnly: true }\n);\nassert.equal(encodedValues,'a=b&c[0]=d&c[1]=e%3Df&f[0][0]=g&f[1][0]=h');\n```\n\nThis encoding can also be replaced by a custom encoding method set as `encoder` option:\n\n```javascript\nvar encoded = qs.stringify({ a: { b: 'c' } }, { encoder: function (str) {\n // Passed in values `a`, `b`, `c`\n return // Return encoded string\n}})\n```\n\n_(Note: the `encoder` option does not apply if `encode` is `false`)_\n\nAnalogue to the `encoder` there is a `decoder` option for `parse` to override decoding of properties and values:\n\n```javascript\nvar decoded = qs.parse('x=z', { decoder: function (str) {\n // Passed in values `x`, `z`\n return // Return decoded string\n}})\n```\n\nYou can encode keys and values using different logic by using the type argument provided to the encoder:\n\n```javascript\nvar encoded = qs.stringify({ a: { b: 'c' } }, { encoder: function (str, defaultEncoder, charset, type) {\n if (type === 'key') {\n return // Encoded key\n } else if (type === 'value') {\n return // Encoded value\n }\n}})\n```\n\nThe type argument is also provided to the decoder:\n\n```javascript\nvar decoded = qs.parse('x=z', { decoder: function (str, defaultDecoder, charset, type) {\n if (type === 'key') {\n return // Decoded key\n } else if (type === 'value') {\n return // Decoded value\n }\n}})\n```\n\nExamples beyond this point will be shown as though the output is not URI encoded for clarity.\nPlease note that the return values in these cases *will* be URI encoded during real usage.\n\nWhen arrays are stringified, they follow the `arrayFormat` option, which defaults to `indices`:\n\n```javascript\nqs.stringify({ a: ['b', 'c', 'd'] });\n// 'a[0]=b&a[1]=c&a[2]=d'\n```\n\nYou may override this by setting the `indices` option to `false`, or to be more explicit, the `arrayFormat` option to `repeat`:\n\n```javascript\nqs.stringify({ a: ['b', 'c', 'd'] }, { indices: false });\n// 'a=b&a=c&a=d'\n```\n\nYou may use the `arrayFormat` option to specify the format of the output array:\n\n```javascript\nqs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'indices' })\n// 'a[0]=b&a[1]=c'\nqs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'brackets' })\n// 'a[]=b&a[]=c'\nqs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'repeat' })\n// 'a=b&a=c'\nqs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'comma' })\n// 'a=b,c'\n```\n\nNote: when using `arrayFormat` set to `'comma'`, you can also pass the `commaRoundTrip` option set to `true` or `false`, to append `[]` on single-item arrays, so that they can round trip through a parse.\n\nWhen objects are stringified, by default they use bracket notation:\n\n```javascript\nqs.stringify({ a: { b: { c: 'd', e: 'f' } } });\n// 'a[b][c]=d&a[b][e]=f'\n```\n\nYou may override this to use dot notation by setting the `allowDots` option to `true`:\n\n```javascript\nqs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { allowDots: true });\n// 'a.b.c=d&a.b.e=f'\n```\n\nYou may encode the dot notation in the keys of object with option `encodeDotInKeys` by setting it to `true`:\nNote: it implies `allowDots`, so `stringify` will error if you set `decodeDotInKeys` to `true`, and `allowDots` to `false`.\nCaveat: when `encodeValuesOnly` is `true` as well as `encodeDotInKeys`, only dots in keys and nothing else will be encoded.\n```javascript\nqs.stringify({ \"name.obj\": { \"first\": \"John\", \"last\": \"Doe\" } }, { allowDots: true, encodeDotInKeys: true })\n// 'name%252Eobj.first=John&name%252Eobj.last=Doe'\n```\n\nYou may allow empty array values by setting the `allowEmptyArrays` option to `true`:\n```javascript\nqs.stringify({ foo: [], bar: 'baz' }, { allowEmptyArrays: true });\n// 'foo[]&bar=baz'\n```\n\nEmpty strings and null values will omit the value, but the equals sign (=) remains in place:\n\n```javascript\nassert.equal(qs.stringify({ a: '' }), 'a=');\n```\n\nKey with no values (such as an empty object or array) will return nothing:\n\n```javascript\nassert.equal(qs.stringify({ a: [] }), '');\nassert.equal(qs.stringify({ a: {} }), '');\nassert.equal(qs.stringify({ a: [{}] }), '');\nassert.equal(qs.stringify({ a: { b: []} }), '');\nassert.equal(qs.stringify({ a: { b: {}} }), '');\n```\n\nProperties that are set to `undefined` will be omitted entirely:\n\n```javascript\nassert.equal(qs.stringify({ a: null, b: undefined }), 'a=');\n```\n\nThe query string may optionally be prepended with a question mark:\n\n```javascript\nassert.equal(qs.stringify({ a: 'b', c: 'd' }, { addQueryPrefix: true }), '?a=b&c=d');\n```\n\nNote that when the output is an empty string, the prefix will not be added:\n\n```javascript\nassert.equal(qs.stringify({}, { addQueryPrefix: true }), '');\n```\n\nThe delimiter may be overridden with stringify as well:\n\n```javascript\nassert.equal(qs.stringify({ a: 'b', c: 'd' }, { delimiter: ';' }), 'a=b;c=d');\n```\n\nIf you only want to override the serialization of `Date` objects, you can provide a `serializeDate` option:\n\n```javascript\nvar date = new Date(7);\nassert.equal(qs.stringify({ a: date }), 'a=1970-01-01T00:00:00.007Z'.replace(/:/g, '%3A'));\nassert.equal(\n qs.stringify({ a: date }, { serializeDate: function (d) { return d.getTime(); } }),\n 'a=7'\n);\n```\n\nYou may use the `sort` option to affect the order of parameter keys:\n\n```javascript\nfunction alphabeticalSort(a, b) {\n return a.localeCompare(b);\n}\nassert.equal(qs.stringify({ a: 'c', z: 'y', b : 'f' }, { sort: alphabeticalSort }), 'a=c&b=f&z=y');\n```\n\nFinally, you can use the `filter` option to restrict which keys will be included in the stringified output.\nIf you pass a function, it will be called for each key to obtain the replacement value.\nOtherwise, if you pass an array, it will be used to select properties and array indices for stringification:\n\n```javascript\nfunction filterFunc(prefix, value) {\n if (prefix == 'b') {\n // Return an `undefined` value to omit a property.\n return;\n }\n if (prefix == 'e[f]') {\n return value.getTime();\n }\n if (prefix == 'e[g][0]') {\n return value * 2;\n }\n return value;\n}\nqs.stringify({ a: 'b', c: 'd', e: { f: new Date(123), g: [2] } }, { filter: filterFunc });\n// 'a=b&c=d&e[f]=123&e[g][0]=4'\nqs.stringify({ a: 'b', c: 'd', e: 'f' }, { filter: ['a', 'e'] });\n// 'a=b&e=f'\nqs.stringify({ a: ['b', 'c', 'd'], e: 'f' }, { filter: ['a', 0, 2] });\n// 'a[0]=b&a[2]=d'\n```\n\nYou could also use `filter` to inject custom serialization for user defined types.\nConsider you're working with some api that expects query strings of the format for ranges:\n\n```\nhttps://domain.com/endpoint?range=30...70\n```\n\nFor which you model as:\n\n```javascript\nclass Range {\n constructor(from, to) {\n this.from = from;\n this.to = to;\n }\n}\n```\n\nYou could _inject_ a custom serializer to handle values of this type:\n\n```javascript\nqs.stringify(\n {\n range: new Range(30, 70),\n },\n {\n filter: (prefix, value) => {\n if (value instanceof Range) {\n return `${value.from}...${value.to}`;\n }\n // serialize the usual way\n return value;\n },\n }\n);\n// range=30...70\n```\n\n### Handling of `null` values\n\nBy default, `null` values are treated like empty strings:\n\n```javascript\nvar withNull = qs.stringify({ a: null, b: '' });\nassert.equal(withNull, 'a=&b=');\n```\n\nParsing does not distinguish between parameters with and without equal signs.\nBoth are converted to empty strings.\n\n```javascript\nvar equalsInsensitive = qs.parse('a&b=');\nassert.deepEqual(equalsInsensitive, { a: '', b: '' });\n```\n\nTo distinguish between `null` values and empty strings use the `strictNullHandling` flag. In the result string the `null`\nvalues have no `=` sign:\n\n```javascript\nvar strictNull = qs.stringify({ a: null, b: '' }, { strictNullHandling: true });\nassert.equal(strictNull, 'a&b=');\n```\n\nTo parse values without `=` back to `null` use the `strictNullHandling` flag:\n\n```javascript\nvar parsedStrictNull = qs.parse('a&b=', { strictNullHandling: true });\nassert.deepEqual(parsedStrictNull, { a: null, b: '' });\n```\n\nTo completely skip rendering keys with `null` values, use the `skipNulls` flag:\n\n```javascript\nvar nullsSkipped = qs.stringify({ a: 'b', c: null}, { skipNulls: true });\nassert.equal(nullsSkipped, 'a=b');\n```\n\nIf you're communicating with legacy systems, you can switch to `iso-8859-1` using the `charset` option:\n\n```javascript\nvar iso = qs.stringify({ æ: 'æ' }, { charset: 'iso-8859-1' });\nassert.equal(iso, '%E6=%E6');\n```\n\nCharacters that don't exist in `iso-8859-1` will be converted to numeric entities, similar to what browsers do:\n\n```javascript\nvar numeric = qs.stringify({ a: '☺' }, { charset: 'iso-8859-1' });\nassert.equal(numeric, 'a=%26%239786%3B');\n```\n\nYou can use the `charsetSentinel` option to announce the character by including an `utf8=✓` parameter with the proper encoding if the checkmark, similar to what Ruby on Rails and others do when submitting forms.\n\n```javascript\nvar sentinel = qs.stringify({ a: '☺' }, { charsetSentinel: true });\nassert.equal(sentinel, 'utf8=%E2%9C%93&a=%E2%98%BA');\n\nvar isoSentinel = qs.stringify({ a: 'æ' }, { charsetSentinel: true, charset: 'iso-8859-1' });\nassert.equal(isoSentinel, 'utf8=%26%2310003%3B&a=%E6');\n```\n\n### Dealing with special character sets\n\nBy default the encoding and decoding of characters is done in `utf-8`, and `iso-8859-1` support is also built in via the `charset` parameter.\n\nIf you wish to encode querystrings to a different character set (i.e.\n[Shift JIS](https://en.wikipedia.org/wiki/Shift_JIS)) you can use the\n[`qs-iconv`](https://github.com/martinheidegger/qs-iconv) library:\n\n```javascript\nvar encoder = require('qs-iconv/encoder')('shift_jis');\nvar shiftJISEncoded = qs.stringify({ a: 'こんにちは！' }, { encoder: encoder });\nassert.equal(shiftJISEncoded, 'a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I');\n```\n\nThis also works for decoding of query strings:\n\n```javascript\nvar decoder = require('qs-iconv/decoder')('shift_jis');\nvar obj = qs.parse('a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I', { decoder: decoder });\nassert.deepEqual(obj, { a: 'こんにちは！' });\n```\n\n### RFC 3986 and RFC 1738 space encoding\n\nRFC3986 used as default option and encodes ' ' to *%20* which is backward compatible.\nIn the same time, output can be stringified as per RFC1738 with ' ' equal to '+'.\n\n```\nassert.equal(qs.stringify({ a: 'b c' }), 'a=b%20c');\nassert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC3986' }), 'a=b%20c');\nassert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC1738' }), 'a=b+c');\n```\n\n## Security\n\nPlease email [@ljharb](https://github.com/ljharb) or see https://tidelift.com/security if you have a potential security vulnerability to report.\n\n## qs for enterprise\n\nAvailable as part of the Tidelift Subscription\n\nThe maintainers of qs and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications.\nSave time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use.\n[Learn more.](https://tidelift.com/subscription/pkg/npm-qs?utm_source=npm-qs&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)\n\n[package-url]: https://npmjs.org/package/qs\n[npm-version-svg]: https://versionbadg.es/ljharb/qs.svg\n[deps-svg]: https://david-dm.org/ljharb/qs.svg\n[deps-url]: https://david-dm.org/ljharb/qs\n[dev-deps-svg]: https://david-dm.org/ljharb/qs/dev-status.svg\n[dev-deps-url]: https://david-dm.org/ljharb/qs#info=devDependencies\n[npm-badge-png]: https://nodei.co/npm/qs.png?downloads=true&stars=true\n[license-image]: https://img.shields.io/npm/l/qs.svg\n[license-url]: LICENSE\n[downloads-image]: https://img.shields.io/npm/dm/qs.svg\n[downloads-url]: https://npm-stat.com/charts.html?package=qs\n[codecov-image]: https://codecov.io/gh/ljharb/qs/branch/main/graphs/badge.svg\n[codecov-url]: https://app.codecov.io/gh/ljharb/qs/\n[actions-image]: https://img.shields.io/github/check-runs/ljharb/qs/main\n[actions-url]: https://github.com/ljharb/qs/actions\n\n## Acknowledgements\n\nqs logo by [NUMI](https://github.com/numi-hq/open-design):\n\n[](https://numi.tech/?ref=qs)",
"_attachments": {}
}
![\"qs\"](\"./logos/banner_default.png\")
\n![\"NUMI](\"https://raw.githubusercontent.com/numi-hq/open-design/main/assets/numi-lockup.png\")
](https://numi.tech/?ref=qs)",
"_attachments": {}
}