Vika a1fdb9607d hw react2 | 3 年之前 | |
---|---|---|
.. | ||
dist | 3 年之前 | |
lib | 3 年之前 | |
test | 3 年之前 | |
.editorconfig | 3 年之前 | |
.eslintignore | 3 年之前 | |
.eslintrc | 3 年之前 | |
CHANGELOG.md | 3 年之前 | |
LICENSE | 3 年之前 | |
README.md | 3 年之前 | |
package.json | 3 年之前 |
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.
|> click here to run codevar 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');
[](#preventEval)
|> click here to run codeqs.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:
|> click here to run codeassert.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 Object.create(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:
|> click here to run codevar 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.
|> click here to run codevar protoObject = qs.parse('a[hasOwnProperty]=b', { allowPrototypes: true });
assert.deepEqual(protoObject, { a: { hasOwnProperty: 'b' } });
URI encoded strings work too:
|> click here to run codeassert.deepEqual(qs.parse('a%5Bb%5D=c'), {
a: { b: 'c' }
});
You can also nest your objects, like 'foo[bar][baz]=foobarbaz'
:
|> click here to run codeassert.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:
|> click here to run codevar 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])
:
|> click here to run codevar 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' } } });
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.
For similar reasons, by default qs will only parse up to 1000 parameters. This can be overridden by passing a parameterLimit
option:
|> click here to run codevar limited = qs.parse('a=b&c=d', { parameterLimit: 1 });
assert.deepEqual(limited, { a: 'b' });
To bypass the leading question mark, use ignoreQueryPrefix
:
|> click here to run codevar prefixed = qs.parse('?a=b&c=d', { ignoreQueryPrefix: true });
assert.deepEqual(prefixed, { a: 'b', c: 'd' });
An optional delimiter can also be passed:
|> click here to run codevar delimited = qs.parse('a=b;c=d', { delimiter: ';' });
assert.deepEqual(delimited, { a: 'b', c: 'd' });
Delimiters can be a regular expression too:
|> click here to run codevar 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:
|> click here to run codevar withDots = qs.parse('a.b=c', { allowDots: true });
assert.deepEqual(withDots, { a: { b: 'c' } });
qs can also parse arrays using a similar []
notation:
|> click here to run codevar withArray = qs.parse('a[]=b&a[]=c');
assert.deepEqual(withArray, { a: ['b', 'c'] });
You may specify an index as well:
|> click here to run codevar 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:
|> click here to run codevar noSparse = qs.parse('a[1]=b&a[15]=c');
assert.deepEqual(noSparse, { a: ['b', 'c'] });
Note that an empty string is also a value, and will be preserved:
|> click here to run codevar 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 specifying indices in an array to a maximum index of 20
. Any array members with an index of greater than 20
will
instead be converted to an object with the index as the key:
|> click here to run codevar withMaxIndex = qs.parse('a[100]=b');
assert.deepEqual(withMaxIndex, { a: { '100': 'b' } });
This limit can be overridden by passing an arrayLimit
option:
|> click here to run codevar withArrayLimit = qs.parse('a[1]=b', { arrayLimit: 0 });
assert.deepEqual(withArrayLimit, { a: { '1': 'b' } });
To disable array parsing entirely, set parseArrays
to false
.
|> click here to run codevar 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:
|> click here to run codevar mixedNotation = qs.parse('a[0]=b&a[b]=c');
assert.deepEqual(mixedNotation, { a: { '0': 'b', b: 'c' } });
You can also create arrays of objects:
|> click here to run codevar arraysOfObjects = qs.parse('a[][b]=c');
assert.deepEqual(arraysOfObjects, { a: [{ b: 'c' }] });
[](#preventEval)
|> click here to run codeqs.stringify(object, [options]);
When stringifying, qs by default URI encodes output. Objects are stringified as you would expect:
|> click here to run codeassert.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
:
|> click here to run codevar 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
:
|> click here to run codevar 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:
|> click here to run codevar 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
)
Analogue to the encoder
there is a decoder
option for parse
to override decoding of properties and values:
|> click here to run codevar decoded = qs.parse('x=z', { decoder: function (str) {
// Passed in values `x`, `z`
return // Return decoded string
}})
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, by default they are given explicit indices:
|> click here to run codeqs.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
:
|> click here to run codeqs.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:
|> click here to run codeqs.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'
When objects are stringified, by default they use bracket notation:
|> click here to run codeqs.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
:
|> click here to run codeqs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { allowDots: true });
// 'a.b.c=d&a.b.e=f'
Empty strings and null values will omit the value, but the equals sign (=) remains in place:
|> click here to run codeassert.equal(qs.stringify({ a: '' }), 'a=');
Key with no values (such as an empty object or array) will return nothing:
|> click here to run codeassert.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:
|> click here to run codeassert.equal(qs.stringify({ a: null, b: undefined }), 'a=');
The query string may optionally be prepended with a question mark:
|> click here to run codeassert.equal(qs.stringify({ a: 'b', c: 'd' }, { addQueryPrefix: true }), '?a=b&c=d');
The delimiter may be overridden with stringify as well:
|> click here to run codeassert.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:
|> click here to run codevar 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:
|> click here to run codefunction 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:
|> click here to run codefunction 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'
By default, null
values are treated like empty strings:
|> click here to run codevar 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.
|> click here to run codevar 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:
|> click here to run codevar strictNull = qs.stringify({ a: null, b: '' }, { strictNullHandling: true });
assert.equal(strictNull, 'a&b=');
To parse values without =
back to null
use the strictNullHandling
flag:
|> click here to run codevar 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:
|> click here to run codevar nullsSkipped = qs.stringify({ a: 'b', c: null}, { skipNulls: true });
assert.equal(nullsSkipped, 'a=b');
By default the encoding and decoding of characters is done in utf-8
. If you
wish to encode querystrings to a different character set (i.e.
Shift JIS) you can use the
qs-iconv
library:
|> click here to run codevar 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:
|> click here to run codevar 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: 'こんにちは!' });
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');