qs vs query-string vs url-parse vs url-search-params vs url-search-params-polyfill
URL 查询字符串解析与序列化的架构选型指南
qsquery-stringurl-parseurl-search-paramsurl-search-params-polyfill类似的npm包:

URL 查询字符串解析与序列化的架构选型指南

qs、query-string、url-parse、url-search-params 和 url-search-params-polyfill 都是用于处理 URL 中查询参数(Query Parameters)的 JavaScript 工具。它们的核心任务是将字符串(如 ?a=1&b=2)转换为对象,或将对象序列化为字符串,但在处理嵌套数据、数组格式、编码规则以及浏览器兼容性上存在显著差异。qs 以强大的嵌套对象支持著称;query-string 专注于轻量级和严格的 URL 标准;url-parse 提供完整的 URL 各部分解析能力;而 url-search-params 系列则分别代表现代浏览器原生 API 及其旧环境补丁方案。

npm下载趋势

3 年

GitHub Stars 排名

统计详情

npm包名称
下载量
Stars
大小
Issues
发布时间
License
qs08,944375 kB738 天前BSD-3-Clause
query-string06,90759.3 kB35 天前MIT
url-parse01,03463 kB16-MIT
url-search-params0762-08 年前MIT
url-search-params-polyfill059917.4 kB33 年前MIT

URL 查询参数处理库深度对比:qs vs query-string vs url-parse vs 原生 API

在前端架构中,处理 URL 查询字符串(Query String)看似简单,实则暗藏陷阱。不同的库对嵌套对象、数组格式、特殊字符编码以及布尔值的处理方式截然不同。选错工具可能导致前后端数据对接失败,或在旧浏览器中引发崩溃。本文将深入对比 qs、query-string、url-parse、url-search-params 及其 Polyfill,帮助你做出精准的架构决策。

🏗️ 核心能力:嵌套对象与数组的处理

这是区分这些库最关键的因素。后端框架(如 PHP、Ruby on Rails、Hapi)通常期望查询参数能表示嵌套结构,而原生标准则倾向于扁平化。

qs 是唯一真正支持深度嵌套解析的库。它能将 a[b]=c 自动转换为 { a: { b: 'c' } }。

import qs from 'qs';

// 解析嵌套字符串
const parsed = qs.parse('user[name]=tomy&user[roles][0]=admin&user[roles][1]=editor');
// 结果:{ user: { name: 'tomy', roles: ['admin', 'editor'] } }

// 序列化对象
const str = qs.stringify({ filter: { price: { min: 10, max: 50 } } });
// 结果:'filter[price][min]=10&filter[price][max]=50'

query-string 严格遵循 URL 标准,默认不支持嵌套。它会将方括号视为键名的一部分,或者在特定配置下忽略嵌套结构。

import queryString from 'query-string';

const parsed = queryString.parse('user[name]=tomy&user[roles][0]=admin');
// 结果:{ 'user[name]': 'tomy', 'user[roles][0]': 'admin' }
// 注意:键名保留了方括号,没有变成嵌套对象

// 即使使用数组,它也更倾向于重复键名
const arrStr = queryString.stringify({ tags: ['js', 'css'] });
// 结果:'tags=js&tags=css' (默认行为)

url-parse 的查询解析功能基于简单的分割逻辑,本质上与 query-string 的默认行为类似,不支持自动嵌套转换。

import UrlParse from 'url-parse';

const url = new UrlParse('?user[name]=tomy&role=admin');
const query = url.query;
// 结果:{ 'user[name]': 'tomy', role: 'admin' }
// 需要手动处理键名才能转换为嵌套对象

url-search-params (原生) 完全不支持嵌套。它只能处理扁平的键值对。

const params = new URLSearchParams('user[name]=tomy&role=admin');
const obj = Object.fromEntries(params.entries());
// 结果:{ 'user[name]': 'tomy', role: 'admin' }
// 无法直接生成 { user: { name: 'tomy' } }

url-search-params-polyfill 行为与原生 API 保持一致,旨在模仿标准,因此同样不支持嵌套结构。

// 行为与原生完全一致
const params = new URLSearchParams('user[name]=tomy');
// 无法解析为嵌套对象

🔐 编码与特殊字符:空格、布尔值与 Null

不同库对“空值”和“特殊字符”的哲学不同,这直接影响 SEO 和缓存键的生成。

qs 默认将空格编码为 +(符合 application/x-www-form-urlencoded 标准),并且默认会过滤掉 null 值,但保留 undefined(取决于配置)。

import qs from 'qs';

qs.stringify({ q: 'hello world', active: true, empty: null });
// 结果:'q=hello+world&active=true' (null 被默认忽略)

// 配置保留 null
qs.stringify({ empty: null }, { skipNulls: false });
// 结果:'empty='

query-string 更加严格和现代。它默认将空格编码为 %20(符合 RFC 3986),并且显式支持 null 和 boolean 的序列化。

import queryString from 'query-string';

queryString.stringify({ q: 'hello world', active: true, empty: null });
// 结果:'q=hello%20world&active=true&empty=null'
// 注意:空格是 %20,且 null 被显式序列化为字符串 'null'

url-parse 依赖浏览器或 Node 的原生 decodeURIComponent,通常行为较为保守,对布尔值的处理需要手动转换。

import UrlParse from 'url-parse';

// url-parse 主要关注解析,序列化能力较弱,通常建议配合其他库使用
// 其内部解析会将 %20 和 + 都视为空格,具体取决于底层实现

url-search-params (原生) 强制将空格编码为 +,且没有布尔值或 null 的概念,所有值必须转为字符串。

const params = new URLSearchParams();
params.append('q', 'hello world');
params.append('active', true); 
// 结果:'q=hello+world&active=true' (true 被转为字符串 "true")

params.append('empty', null);
// 结果:'...&empty=null' (null 被转为字符串 "null")

url-search-params-polyfill 尽力模拟原生行为,因此在空格编码和类型转换上与原生保持一致。

🧩 完整 URL 解析 vs 仅查询字符串

有些场景你需要解析整个 URL(包括协议、域名),而不仅仅是 ? 后面的部分。

url-parse 是此场景的王者。它不仅能解析 query,还能提取 protocol, hostname, port, pathname 等。

import UrlParse from 'url-parse';

const url = new UrlParse('https://api.example.com:8080/v1/users?id=123#section');

console.log(url.protocol); // 'https:'
console.log(url.hostname); // 'api.example.com'
console.log(url.port);     // '8080'
console.log(url.pathname); // '/v1/users'
console.log(url.query);    // { id: '123' }
console.log(url.hash);     // '#section'

qs, query-string, url-search-params 都只处理查询字符串部分。如果你传入完整 URL,它们通常会报错或返回意外结果,你需要先手动提取。

// 错误示范:直接传入完整 URL
// qs.parse('https://example.com?a=1') -> 会尝试解析整个字符串为参数,导致错误

// 正确做法:先提取
const query = window.location.search; // 获取 '?a=1'
const parsed = qs.parse(query);

📉 兼容性与维护状态

url-search-params-polyfill 的状态需要特别注意。随着 IE11 的正式退役,现代前端工程(如基于 Vite, Webpack 5, Next.js 13+ 的项目)通常不再需要此包。

  • 现状:该库主要用于填补旧浏览器缺口。
  • 建议:如果你的目标用户包含 IE11,可以使用它。否则,强烈建议直接使用原生 URLSearchParams。如果必须支持旧环境,推荐使用 core-js 进行全局填充,而不是引入这个独立的 Polyfill 包,以减少依赖碎片化。
// 现代项目推荐:直接使用原生
const params = new URLSearchParams(window.location.search);

// 仅在必须支持 IE11 且未使用全局 Polyfill 时考虑
// import 'url-search-params-polyfill'; 

qs 和 query-string 维护状况良好,广泛应用于生产环境。url-parse 同样稳定,但在纯前端项目中,原生的 new URL() API 正在逐渐取代它的部分功能。

// 现代替代方案:使用原生 URL 对象解析完整 URL
const url = new URL('https://example.com/path?a=1');
console.log url.hostname; // 'example.com'
console.log url.searchParams.get('a'); // '1'
// 这在现代浏览器中比 url-parse 更标准,但在 Node.js 旧版本中需注意支持情况

📊 选型总结表

特性qsquery-stringurl-parseURLSearchParams (原生)url-search-params-polyfill
嵌套对象支持✅ 完美支持❌ 不支持❌ 不支持❌ 不支持❌ 不支持
数组格式可配置 (索引/重复)重复键名 (a=1&a=2)简单分割重复键名重复键名
空格编码+ (默认)%20 (默认)依赖环境++
完整 URL 解析❌❌✅ 支持❌ (需配合 new URL)❌
Bundle 大小中等极小小0 (原生)小
主要场景Node.js, 复杂表单现代 SPA, 简单过滤工具库, 旧 Node 环境现代浏览器/NodeIE11 兼容

💡 架构师建议

  1. Node.js / SSR 项目:无脑选 qs。后端生态(Express, Hapi, NestJS)普遍依赖它的嵌套解析逻辑,能确保前后端数据模型一致。
  2. 现代前端 SPA (React/Vue):首选 query-string。它轻量、行为可预测,且对布尔值和 null 的处理更符合前端直觉。如果项目仅需简单参数且无需 Polyfill,直接使用原生 URLSearchParams 是更优解。
  3. 需要解析完整 URL:在现代环境中,优先使用原生 new URL() 构造函数。只有在需要兼容非常旧的 Node.js 版本或特殊解析需求时,才考虑 url-parse。
  4. 关于 Polyfill:除非你有明确的 IE11 流量指标,否则不要在新项目中引入 url-search-params-polyfill。利用构建工具的 Babel 配置来处理兼容性是更现代化的做法。

选择正确的工具不仅能减少代码量,更能避免那些难以调试的“编码不一致”或“参数丢失”问题。

如何选择: qs vs query-string vs url-parse vs url-search-params vs url-search-params-polyfill

  • qs:

    选择 qs 如果你的后端(如 Node.js/Hapi/Express)期望接收嵌套对象格式(如 user[name]=foo),或者你需要处理极其复杂的查询结构。它是处理深度嵌套数据和自定义数组格式(如索引数组)的行业标准,特别适合服务端渲染(SSR)或 Node.js 中间件场景。

  • query-string:

    选择 query-string 如果你需要一个轻量级、纯前端友好的库,且数据结构相对扁平。它在处理布尔值、null 值和数组时严格遵循 URL 标准,不会像 qs 那样自动猜测嵌套结构,非常适合现代单页应用(SPA)中管理简单的过滤和分页参数。

  • url-parse:

    选择 url-parse 如果你不仅需要解析查询参数,还需要同时提取协议、主机名、端口和路径等其他 URL 组成部分。它是一个完整的 URL 解析器,内置了查询字符串处理功能,适合需要一次性拆解完整 URL 且对性能有要求的工具类库开发。

  • url-search-params:

    选择原生 URLSearchParams 如果你的项目仅需支持现代浏览器(或 Node.js 10+)且数据结构简单。它是 Web 标准的一部分,无需额外依赖,性能最佳,但缺乏对嵌套对象的支持,且在不同浏览器间对空格编码等细节的处理可能存在微小差异。

  • url-search-params-polyfill:

    不要在新项目中主动选择 url-search-params-polyfill。该库仅应用于必须支持 IE11 或极旧安卓浏览器的遗留项目。对于任何现代架构,应直接使用原生 API 或通过构建工具(如 Babel/Core-js)进行按需填充,而非直接依赖此独立包。

qs的README

qs

qs Version Badge

github actions coverage License Downloads CII Best Practices

npm badge

A querystring parsing and stringifying library with some added security.

Lead Maintainer: Jordan Harband

The qs module was originally created and maintained by TJ Holowaychuk.

Usage

var qs = require('qs');
var assert = require('assert');

var obj = qs.parse('a=c');
assert.deepEqual(obj, { a: 'c' });

var str = qs.stringify(obj);
assert.equal(str, 'a=c');

Parsing Objects

qs.parse(string, [options]);

qs allows you to create nested objects within your query strings, by surrounding the name of sub-keys with square brackets []. For example, the string 'foo[bar]=baz' converts to:

assert.deepEqual(qs.parse('foo[bar]=baz'), {
    foo: {
        bar: 'baz'
    }
});

When 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:

var nullObject = qs.parse('a[hasOwnProperty]=b', { plainObjects: true });
assert.deepEqual(nullObject, { a: { hasOwnProperty: 'b' } });

By 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. 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. Always be careful with this option.

var protoObject = qs.parse('a[hasOwnProperty]=b', { allowPrototypes: true });
assert.deepEqual(protoObject, { a: { hasOwnProperty: 'b' } });

URI encoded strings work too:

assert.deepEqual(qs.parse('a%5Bb%5D=c'), {
    a: { b: 'c' }
});

You can also nest your objects, like 'foo[bar][baz]=foobarbaz':

assert.deepEqual(qs.parse('foo[bar][baz]=foobarbaz'), {
    foo: {
        bar: {
            baz: 'foobarbaz'
        }
    }
});

By default, when nesting objects qs will only parse up to 5 children deep. This means if you attempt to parse a string like 'a[b][c][d][e][f][g][h][i]=j' your resulting object will be:

var expected = {
    a: {
        b: {
            c: {
                d: {
                    e: {
                        f: {
                            '[g][h][i]': 'j'
                        }
                    }
                }
            }
        }
    }
};
var string = 'a[b][c][d][e][f][g][h][i]=j';
assert.deepEqual(qs.parse(string), expected);

This depth can be overridden by passing a depth option to qs.parse(string, [options]):

var deep = qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1 });
assert.deepEqual(deep, { a: { b: { '[c][d][e][f][g][h][i]': 'j' } } });

You can configure qs to throw an error when parsing nested input beyond this depth using the strictDepth option (defaulted to false):

try {
    qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1, strictDepth: true });
} catch (err) {
    assert(err instanceof RangeError);
    assert.strictEqual(err.message, 'Input depth exceeded depth option of 1 and strictDepth is true');
}

The 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.

For similar reasons, by default qs will only parse up to 1000 parameters. This can be overridden by passing a parameterLimit option:

var limited = qs.parse('a=b&c=d', { parameterLimit: 1 });
assert.deepEqual(limited, { a: 'b' });

If 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.

try {
    qs.parse('a=1&b=2&c=3&d=4', { parameterLimit: 3, throwOnLimitExceeded: true });
} catch (err) {
    assert(err instanceof Error);
    assert.strictEqual(err.message, 'Parameter limit exceeded. Only 3 parameters allowed.');
}

When throwOnLimitExceeded is set to false (default), qs will parse up to the specified parameterLimit and ignore the rest without throwing an error.

Note that parameterLimit only bounds the number of &-delimited parameters; it does not limit how many values a single parameter expands into. In particular, when comma: true is enabled, a single parameter's value is split on commas into arbitrarily many elements, which parameterLimit does not constrain. To bound the total element count from untrusted input, set throwOnLimitExceeded: true (see arrayLimit below), and always bound the input size at the transport layer (e.g. an HTTP body-size limit).

To bypass the leading question mark, use ignoreQueryPrefix:

var prefixed = qs.parse('?a=b&c=d', { ignoreQueryPrefix: true });
assert.deepEqual(prefixed, { a: 'b', c: 'd' });

An optional delimiter can also be passed:

var delimited = qs.parse('a=b;c=d', { delimiter: ';' });
assert.deepEqual(delimited, { a: 'b', c: 'd' });

Delimiters can be a regular expression too:

var regexed = qs.parse('a=b;c=d,e=f', { delimiter: /[;,]/ });
assert.deepEqual(regexed, { a: 'b', c: 'd', e: 'f' });

Option allowDots can be used to enable dot notation:

var withDots = qs.parse('a.b=c', { allowDots: true });
assert.deepEqual(withDots, { a: { b: 'c' } });

Option decodeDotInKeys can be used to decode dots in keys Note: it implies allowDots, so parse will error if you set decodeDotInKeys to true, and allowDots to false.

var withDots = qs.parse('name%252Eobj.first=John&name%252Eobj.last=Doe', { decodeDotInKeys: true });
assert.deepEqual(withDots, { 'name.obj': { first: 'John', last: 'Doe' }});

Option allowEmptyArrays can be used to allow empty array values in an object

var withEmptyArrays = qs.parse('foo[]&bar=baz', { allowEmptyArrays: true });
assert.deepEqual(withEmptyArrays, { foo: [], bar: 'baz' });

Option duplicates can be used to change the behavior when duplicate keys are encountered

assert.deepEqual(qs.parse('foo=bar&foo=baz'), { foo: ['bar', 'baz'] });
assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'combine' }), { foo: ['bar', 'baz'] });
assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'first' }), { foo: 'bar' });
assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'last' }), { foo: 'baz' });

Note that keys with bracket notation ([]) always combine into arrays, regardless of the duplicates setting:

assert.deepEqual(qs.parse('a=1&a=2&b[]=1&b[]=2', { duplicates: 'last' }), { a: '2', b: ['1', '2'] });

If you have to deal with legacy browsers or services, there's also support for decoding percent-encoded octets as iso-8859-1:

var oldCharset = qs.parse('a=%A7', { charset: 'iso-8859-1' });
assert.deepEqual(oldCharset, { a: '§' });

Some services add an initial utf8=✓ value to forms so that old Internet Explorer versions are more likely to submit the form as utf-8. Additionally, 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.

qs supports this mechanism via the charsetSentinel option. If specified, the utf8 parameter will be omitted from the returned object. It will be used to switch to iso-8859-1/utf-8 mode depending on how the checkmark is encoded.

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. In that sense the charset will behave as the default charset rather than the authoritative charset.

var detectedAsUtf8 = qs.parse('utf8=%E2%9C%93&a=%C3%B8', {
    charset: 'iso-8859-1',
    charsetSentinel: true
});
assert.deepEqual(detectedAsUtf8, { a: 'ø' });

// Browsers encode the checkmark as ✓ when submitting as iso-8859-1:
var detectedAsIso8859_1 = qs.parse('utf8=%26%2310003%3B&a=%F8', {
    charset: 'utf-8',
    charsetSentinel: true
});
assert.deepEqual(detectedAsIso8859_1, { a: 'ø' });

If you want to decode the &#...; syntax to the actual character, you can specify the interpretNumericEntities option as well:

var detectedAsIso8859_1 = qs.parse('a=%26%239786%3B', {
    charset: 'iso-8859-1',
    interpretNumericEntities: true
});
assert.deepEqual(detectedAsIso8859_1, { a: '☺' });

It also works when the charset has been detected in charsetSentinel mode.

Parsing Arrays

qs can also parse arrays using a similar [] notation:

var withArray = qs.parse('a[]=b&a[]=c');
assert.deepEqual(withArray, { a: ['b', 'c'] });

You may specify an index as well:

var withIndexes = qs.parse('a[1]=c&a[0]=b');
assert.deepEqual(withIndexes, { a: ['b', 'c'] });

Note 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. When creating arrays with specific indices, qs will compact a sparse array to only the existing values preserving their order:

var noSparse = qs.parse('a[1]=b&a[15]=c');
assert.deepEqual(noSparse, { a: ['b', 'c'] });

You may also use allowSparse option to parse sparse arrays:

var sparseArray = qs.parse('a[1]=2&a[3]=5', { allowSparse: true });
assert.deepEqual(sparseArray, { a: [, '2', , '5'] });

Note that an empty string is also a value, and will be preserved:

var withEmptyString = qs.parse('a[]=&a[]=b');
assert.deepEqual(withEmptyString, { a: ['', 'b'] });

var withIndexedEmptyString = qs.parse('a[0]=b&a[1]=&a[2]=c');
assert.deepEqual(withIndexedEmptyString, { a: ['b', '', 'c'] });

qs will also limit arrays to a maximum of 20 elements. Any array members with an index of 20 or greater will instead be converted to an object with the index as the key. This is needed to handle cases when someone sent, for example, a[999999999] and it will take significant time to iterate over this huge array.

var withMaxIndex = qs.parse('a[100]=b');
assert.deepEqual(withMaxIndex, { a: { '100': 'b' } });

This limit can be overridden by passing an arrayLimit option:

var withArrayLimit = qs.parse('a[1]=b', { arrayLimit: 0 });
assert.deepEqual(withArrayLimit, { a: { '1': 'b' } });

If 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.

try {
    qs.parse('a[1]=b', { arrayLimit: 0, throwOnLimitExceeded: true });
} catch (err) {
    assert(err instanceof Error);
    assert.strictEqual(err.message, 'Array limit exceeded. Only 0 elements allowed in an array.');
}

When 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.

Note that arrayLimit is a representation threshold that controls when a numerically-indexed collection switches from an array to an object — it is not a hard cap on the total number of elements parsed. With the default throwOnLimitExceeded: false, exceeding arrayLimit never rejects or truncates input; it only changes the container type, and the resulting object still holds every element (so its size stays proportional to the input). This conversion is itself a safeguard: it avoids allocating a huge sparse array for input like a[999999999]. If you need a hard limit that rejects oversized input from untrusted sources, set throwOnLimitExceeded: true.

To prevent array syntax (a[], a[0]) from being parsed as arrays, set parseArrays to false. Note that duplicate keys (e.g. a=b&a=c) may still produce arrays when duplicates is 'combine' (the default).

var noParsingArrays = qs.parse('a[]=b', { parseArrays: false });
assert.deepEqual(noParsingArrays, { a: { '0': 'b' } });

If you mix notations, qs will merge the two items into an object:

var mixedNotation = qs.parse('a[0]=b&a[b]=c');
assert.deepEqual(mixedNotation, { a: { '0': 'b', b: 'c' } });

When 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):

assert.deepEqual(qs.parse('a[b]=c&a=d'), { a: [{ b: 'c' }, 'd'] });
assert.deepEqual(qs.parse('a=d&a[b]=c'), { a: ['d', { b: 'c' }] });

To restore the legacy behavior (where the primitive is used as a key with value true), set strictMerge to false:

assert.deepEqual(qs.parse('a[b]=c&a=d', { strictMerge: false }), { a: { b: 'c', d: true } });

You can also create arrays of objects:

var arraysOfObjects = qs.parse('a[][b]=c');
assert.deepEqual(arraysOfObjects, { a: [{ b: 'c' }] });

Some people use comma to join array, qs can parse it:

var arraysOfObjects = qs.parse('a=b,c', { comma: true })
assert.deepEqual(arraysOfObjects, { a: ['b', 'c'] })

(this cannot convert nested objects, such as a={b:1},{c:d})

Parsing primitive/scalar values (numbers, booleans, null, etc)

By default, all values are parsed as strings. This behavior will not change and is explained in issue #91.

var primitiveValues = qs.parse('a=15&b=true&c=null');
assert.deepEqual(primitiveValues, { a: '15', b: 'true', c: 'null' });

If 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 which will auto-convert all request query parameters.

Stringifying

qs.stringify(object, [options]);

When stringifying, qs by default URI encodes output. Objects are stringified as you would expect:

assert.equal(qs.stringify({ a: 'b' }), 'a=b');
assert.equal(qs.stringify({ a: { b: 'c' } }), 'a%5Bb%5D=c');

This encoding can be disabled by setting the encode option to false:

var unencoded = qs.stringify({ a: { b: 'c' } }, { encode: false });
assert.equal(unencoded, 'a[b]=c');

Encoding can be disabled for keys by setting the encodeValuesOnly option to true:

var encodedValues = qs.stringify(
    { a: 'b', c: ['d', 'e=f'], f: [['g'], ['h']] },
    { encodeValuesOnly: true }
);
assert.equal(encodedValues,'a=b&c[0]=d&c[1]=e%3Df&f[0][0]=g&f[1][0]=h');

This encoding can also be replaced by a custom encoding method set as encoder option:

var encoded = qs.stringify({ a: { b: 'c' } }, { encoder: function (str) {
    // Passed in values `a`, `b`, `c`
    return // Return encoded string
}})

(Note: the encoder option does not apply if encode is false)

By default, qs.stringify serializes an object of any nesting depth. For backwards compatibility, and because its input is the caller's own object rather than a query string parsed by qs, this is unbounded. If you serialize objects whose nesting can be influenced by untrusted input, bound it with the numeric depth option (default Infinity); exceeding it throws a catchable RangeError instead of eventually overflowing the call stack:

try {
    qs.stringify({ a: { b: { c: { d: 'e' } } } }, { depth: 2 });
} catch (err) {
    assert(err instanceof RangeError);
    assert.strictEqual(err.message, 'Input depth exceeded depth option of 2');
}

Analogue to the encoder there is a decoder option for parse to override decoding of properties and values:

var decoded = qs.parse('x=z', { decoder: function (str) {
    // Passed in values `x`, `z`
    return // Return decoded string
}})

You can encode keys and values using different logic by using the type argument provided to the encoder:

var encoded = qs.stringify({ a: { b: 'c' } }, { encoder: function (str, defaultEncoder, charset, type) {
    if (type === 'key') {
        return // Encoded key
    } else if (type === 'value') {
        return // Encoded value
    }
}})

The type argument is also provided to the decoder:

var decoded = qs.parse('x=z', { decoder: function (str, defaultDecoder, charset, type) {
    if (type === 'key') {
        return // Decoded key
    } else if (type === 'value') {
        return // Decoded value
    }
}})

Examples beyond this point will be shown as though the output is not URI encoded for clarity. Please note that the return values in these cases will be URI encoded during real usage.

When arrays are stringified, they follow the arrayFormat option, which defaults to indices:

qs.stringify({ a: ['b', 'c', 'd'] });
// 'a[0]=b&a[1]=c&a[2]=d'

You may override this by setting the indices option to false, or to be more explicit, the arrayFormat option to repeat:

qs.stringify({ a: ['b', 'c', 'd'] }, { indices: false });
// 'a=b&a=c&a=d'

You may use the arrayFormat option to specify the format of the output array:

qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'indices' })
// 'a[0]=b&a[1]=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'brackets' })
// 'a[]=b&a[]=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'repeat' })
// 'a=b&a=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'comma' })
// 'a=b,c'

Note: 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.

When objects are stringified, by default they use bracket notation:

qs.stringify({ a: { b: { c: 'd', e: 'f' } } });
// 'a[b][c]=d&a[b][e]=f'

You may override this to use dot notation by setting the allowDots option to true:

qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { allowDots: true });
// 'a.b.c=d&a.b.e=f'

You may encode the dot notation in the keys of object with option encodeDotInKeys by setting it to true: Note: it implies allowDots, so stringify will error if you set decodeDotInKeys to true, and allowDots to false. Caveat: when encodeValuesOnly is true as well as encodeDotInKeys, only dots in keys and nothing else will be encoded.

qs.stringify({ "name.obj": { "first": "John", "last": "Doe" } }, { allowDots: true, encodeDotInKeys: true })
// 'name%252Eobj.first=John&name%252Eobj.last=Doe'

You may allow empty array values by setting the allowEmptyArrays option to true:

qs.stringify({ foo: [], bar: 'baz' }, { allowEmptyArrays: true });
// 'foo[]&bar=baz'

Empty strings and null values will omit the value, but the equals sign (=) remains in place:

assert.equal(qs.stringify({ a: '' }), 'a=');

Key with no values (such as an empty object or array) will return nothing:

assert.equal(qs.stringify({ a: [] }), '');
assert.equal(qs.stringify({ a: {} }), '');
assert.equal(qs.stringify({ a: [{}] }), '');
assert.equal(qs.stringify({ a: { b: []} }), '');
assert.equal(qs.stringify({ a: { b: {}} }), '');

Properties that are set to undefined will be omitted entirely:

assert.equal(qs.stringify({ a: null, b: undefined }), 'a=');

The query string may optionally be prepended with a question mark:

assert.equal(qs.stringify({ a: 'b', c: 'd' }, { addQueryPrefix: true }), '?a=b&c=d');

Note that when the output is an empty string, the prefix will not be added:

assert.equal(qs.stringify({}, { addQueryPrefix: true }), '');

The delimiter may be overridden with stringify as well:

assert.equal(qs.stringify({ a: 'b', c: 'd' }, { delimiter: ';' }), 'a=b;c=d');

If you only want to override the serialization of Date objects, you can provide a serializeDate option:

var date = new Date(7);
assert.equal(qs.stringify({ a: date }), 'a=1970-01-01T00:00:00.007Z'.replace(/:/g, '%3A'));
assert.equal(
    qs.stringify({ a: date }, { serializeDate: function (d) { return d.getTime(); } }),
    'a=7'
);

You may use the sort option to affect the order of parameter keys:

function alphabeticalSort(a, b) {
    return a.localeCompare(b);
}
assert.equal(qs.stringify({ a: 'c', z: 'y', b : 'f' }, { sort: alphabeticalSort }), 'a=c&b=f&z=y');

Finally, you can use the filter option to restrict which keys will be included in the stringified output. If you pass a function, it will be called for each key to obtain the replacement value. Otherwise, if you pass an array, it will be used to select properties and array indices for stringification:

function filterFunc(prefix, value) {
    if (prefix == 'b') {
        // Return an `undefined` value to omit a property.
        return;
    }
    if (prefix == 'e[f]') {
        return value.getTime();
    }
    if (prefix == 'e[g][0]') {
        return value * 2;
    }
    return value;
}
qs.stringify({ a: 'b', c: 'd', e: { f: new Date(123), g: [2] } }, { filter: filterFunc });
// 'a=b&c=d&e[f]=123&e[g][0]=4'
qs.stringify({ a: 'b', c: 'd', e: 'f' }, { filter: ['a', 'e'] });
// 'a=b&e=f'
qs.stringify({ a: ['b', 'c', 'd'], e: 'f' }, { filter: ['a', 0, 2] });
// 'a[0]=b&a[2]=d'

You could also use filter to inject custom serialization for user defined types. Consider you're working with some api that expects query strings of the format for ranges:

https://domain.com/endpoint?range=30...70

For which you model as:

class Range {
    constructor(from, to) {
        this.from = from;
        this.to = to;
    }
}

You could inject a custom serializer to handle values of this type:

qs.stringify(
    {
        range: new Range(30, 70),
    },
    {
        filter: (prefix, value) => {
            if (value instanceof Range) {
                return `${value.from}...${value.to}`;
            }
            // serialize the usual way
            return value;
        },
    }
);
// range=30...70

Handling of null values

By default, null values are treated like empty strings:

var withNull = qs.stringify({ a: null, b: '' });
assert.equal(withNull, 'a=&b=');

Parsing does not distinguish between parameters with and without equal signs. Both are converted to empty strings.

var equalsInsensitive = qs.parse('a&b=');
assert.deepEqual(equalsInsensitive, { a: '', b: '' });

To distinguish between null values and empty strings use the strictNullHandling flag. In the result string the null values have no = sign:

var strictNull = qs.stringify({ a: null, b: '' }, { strictNullHandling: true });
assert.equal(strictNull, 'a&b=');

To parse values without = back to null use the strictNullHandling flag:

var parsedStrictNull = qs.parse('a&b=', { strictNullHandling: true });
assert.deepEqual(parsedStrictNull, { a: null, b: '' });

To completely skip rendering keys with null values, use the skipNulls flag:

var nullsSkipped = qs.stringify({ a: 'b', c: null}, { skipNulls: true });
assert.equal(nullsSkipped, 'a=b');

If you're communicating with legacy systems, you can switch to iso-8859-1 using the charset option:

var iso = qs.stringify({ æ: 'æ' }, { charset: 'iso-8859-1' });
assert.equal(iso, '%E6=%E6');

Characters that don't exist in iso-8859-1 will be converted to numeric entities, similar to what browsers do:

var numeric = qs.stringify({ a: '☺' }, { charset: 'iso-8859-1' });
assert.equal(numeric, 'a=%26%239786%3B');

You 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.

var sentinel = qs.stringify({ a: '☺' }, { charsetSentinel: true });
assert.equal(sentinel, 'utf8=%E2%9C%93&a=%E2%98%BA');

var isoSentinel = qs.stringify({ a: 'æ' }, { charsetSentinel: true, charset: 'iso-8859-1' });
assert.equal(isoSentinel, 'utf8=%26%2310003%3B&a=%E6');

Dealing with special character sets

By 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.

If you wish to encode querystrings to a different character set (i.e. Shift JIS) you can use the qs-iconv library:

var encoder = require('qs-iconv/encoder')('shift_jis');
var shiftJISEncoded = qs.stringify({ a: 'こんにちは!' }, { encoder: encoder });
assert.equal(shiftJISEncoded, 'a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I');

This also works for decoding of query strings:

var decoder = require('qs-iconv/decoder')('shift_jis');
var obj = qs.parse('a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I', { decoder: decoder });
assert.deepEqual(obj, { a: 'こんにちは!' });

RFC 3986 and RFC 1738 space encoding

RFC3986 used as default option and encodes ' ' to %20 which is backward compatible. In the same time, output can be stringified as per RFC1738 with ' ' equal to '+'.

assert.equal(qs.stringify({ a: 'b c' }), 'a=b%20c');
assert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC3986' }), 'a=b%20c');
assert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC1738' }), 'a=b+c');

Security

Please email @ljharb or see https://tidelift.com/security if you have a potential security vulnerability to report.

qs for enterprise

Available as part of the Tidelift Subscription

The 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. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

Acknowledgements

qs logo by NUMI:

NUMI Logo