From 39aef9164653dd7a35877e67ea731a1bbb7ae736 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Wed, 20 Jan 2021 14:44:06 +0700 Subject: [PATCH 01/50] Update a link --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 0914d74..85f72ce 100644 --- a/readme.md +++ b/readme.md @@ -16,7 +16,7 @@ Special thanks to:

- +

From 667c9e9d296a7f7197bcc8d6abe4a41c8cf4b912 Mon Sep 17 00:00:00 2001 From: Oleksii Teplenko Date: Tue, 9 Feb 2021 20:03:27 +0200 Subject: [PATCH 02/50] Ignore ending ampersand when parsing (#306) --- index.js | 4 ++++ test/parse.js | 5 +++++ 2 files changed, 9 insertions(+) diff --git a/index.js b/index.js index 559ecd4..39e86e3 100644 --- a/index.js +++ b/index.js @@ -244,6 +244,10 @@ function parse(query, options) { } for (const param of query.split('&')) { + if (param === '') { + continue; + } + let [key, value] = splitOnFirst(options.decode ? param.replace(/\+/g, ' ') : param, '='); // Missing `=` should be `null`: diff --git a/test/parse.js b/test/parse.js index 365eb2f..9bfc034 100644 --- a/test/parse.js +++ b/test/parse.js @@ -13,6 +13,11 @@ test('query strings starting with a `&`', t => { t.deepEqual(queryString.parse('&foo=bar&foo=baz'), {foo: ['bar', 'baz']}); }); +test('query strings ending with a `&`', t => { + t.deepEqual(queryString.parse('foo=bar&'), {foo: 'bar'}); + t.deepEqual(queryString.parse('foo=bar&&&'), {foo: 'bar'}); +}); + test('parse a query string', t => { t.deepEqual(queryString.parse('foo=bar'), {foo: 'bar'}); }); From 6ed5cb3d36f3e12eb024293c5d262e2d0efed9ec Mon Sep 17 00:00:00 2001 From: Richie Bendall Date: Wed, 10 Feb 2021 19:13:18 +1300 Subject: [PATCH 03/50] Add `.pick()` and `.exclude()` (#282) Co-authored-by: Sindre Sorhus --- index.d.ts | 78 +++++++++++++++++++++++++++++++++++++++++++++++++ index.js | 20 +++++++++++++ index.test-d.ts | 6 ++++ package.json | 4 ++- readme.md | 58 ++++++++++++++++++++++++++++++++++++ test/exclude.js | 17 +++++++++++ test/pick.js | 17 +++++++++++ 7 files changed, 199 insertions(+), 1 deletion(-) create mode 100644 test/exclude.js create mode 100644 test/pick.js diff --git a/index.d.ts b/index.d.ts index 026d287..b6d651b 100644 --- a/index.d.ts +++ b/index.d.ts @@ -409,3 +409,81 @@ export function stringifyUrl( object: UrlObject, options?: StringifyOptions ): string; + +/** +Pick query parameters from a URL. + +@param url - The URL containing the query parameters to pick. +@param keys - The names of the query parameters to keep. All other query parameters will be removed from the URL. +@param filter - A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`. + +@returns The URL with the picked query parameters. + +@example +``` +queryString.pick('https://foo.bar?foo=1&bar=2#hello', ['foo']); +//=> 'https://foo.bar?foo=1#hello' + +queryString.pick('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true}); +//=> 'https://foo.bar?bar=2#hello' +``` +*/ +export function pick( + url: string, + keys: readonly string[], + options?: ParseOptions & StringifyOptions +): string +export function pick( + url: string, + filter: (key: string, value: string | boolean | number) => boolean, + options?: {parseBooleans: true, parseNumbers: true} & ParseOptions & StringifyOptions +): string +export function pick( + url: string, + filter: (key: string, value: string | boolean) => boolean, + options?: {parseBooleans: true} & ParseOptions & StringifyOptions +): string +export function pick( + url: string, + filter: (key: string, value: string | number) => boolean, + options?: {parseNumbers: true} & ParseOptions & StringifyOptions +): string + +/** +Exclude query parameters from a URL. Like `.pick()` but reversed. + +@param url - The URL containing the query parameters to exclude. +@param keys - The names of the query parameters to remove. All other query parameters will remain in the URL. +@param filter - A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`. + +@returns The URL without the excluded the query parameters. + +@example +``` +queryString.exclude('https://foo.bar?foo=1&bar=2#hello', ['foo']); +//=> 'https://foo.bar?bar=2#hello' + +queryString.exclude('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true}); +//=> 'https://foo.bar?foo=1#hello' +``` +*/ +export function exclude( + url: string, + keys: readonly string[], + options?: ParseOptions & StringifyOptions +): string +export function exclude( + url: string, + filter: (key: string, value: string | boolean | number) => boolean, + options?: {parseBooleans: true, parseNumbers: true} & ParseOptions & StringifyOptions +): string +export function exclude( + url: string, + filter: (key: string, value: string | boolean) => boolean, + options?: {parseBooleans: true} & ParseOptions & StringifyOptions +): string +export function exclude( + url: string, + filter: (key: string, value: string | number) => boolean, + options?: {parseNumbers: true} & ParseOptions & StringifyOptions +): string diff --git a/index.js b/index.js index 39e86e3..423b9d6 100644 --- a/index.js +++ b/index.js @@ -2,6 +2,7 @@ const strictUriEncode = require('strict-uri-encode'); const decodeComponent = require('decode-uri-component'); const splitOnFirst = require('split-on-first'); +const filterObject = require('filter-obj'); const isNullOrUndefined = value => value === null || value === undefined; @@ -382,3 +383,22 @@ exports.stringifyUrl = (object, options) => { return `${url}${queryString}${hash}`; }; + +exports.pick = (input, filter, options) => { + options = Object.assign({ + parseFragmentIdentifier: true + }, options); + + const {url, query, fragmentIdentifier} = exports.parseUrl(input, options); + return exports.stringifyUrl({ + url, + query: filterObject(query, filter), + fragmentIdentifier + }, options); +}; + +exports.exclude = (input, filter, options) => { + const exclusionFilter = Array.isArray(filter) ? key => !filter.includes(key) : (key, value) => !filter(key, value); + + return exports.pick(input, exclusionFilter, options); +}; diff --git a/index.test-d.ts b/index.test-d.ts index 2aab3fe..2032584 100644 --- a/index.test-d.ts +++ b/index.test-d.ts @@ -124,3 +124,9 @@ expectType( }, }) ); + +// Pick +expectType(queryString.pick('http://foo.bar/?abc=def&hij=klm', ['abc'])) + +// Exclude +expectType(queryString.exclude('http://foo.bar/?abc=def&hij=klm', ['abc'])) diff --git a/package.json b/package.json index df8a1f2..6f5372b 100644 --- a/package.json +++ b/package.json @@ -34,10 +34,12 @@ "stringify", "encode", "decode", - "searchparams" + "searchparams", + "filter" ], "dependencies": { "decode-uri-component": "^0.2.0", + "filter-obj": "^1.1.0", "split-on-first": "^1.0.0", "strict-uri-encode": "^2.0.0" }, diff --git a/readme.md b/readme.md index 85f72ce..280972e 100644 --- a/readme.md +++ b/readme.md @@ -415,6 +415,64 @@ Type: `object` Query items to add to the URL. +### .pick(url, keys, options?) +### .pick(url, filter, options?) + +Pick query parameters from a URL. + +Returns a string with the new URL. + +```js +const queryString = require('query-string'); + +queryString.pick('https://foo.bar?foo=1&bar=2#hello', ['foo']); +//=> 'https://foo.bar?foo=1#hello' + +queryString.pick('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true}); +//=> 'https://foo.bar?bar=2#hello' +``` + +### .exclude(url, keys, options?) +### .exclude(url, filter, options?) + +Exclude query parameters from a URL. + +Returns a string with the new URL. + +```js +const queryString = require('query-string'); + +queryString.exclude('https://foo.bar?foo=1&bar=2#hello', ['foo']); +//=> 'https://foo.bar?bar=2#hello' + +queryString.exclude('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true}); +//=> 'https://foo.bar?foo=1#hello' +``` + +#### url + +Type: `string` + +The URL containing the query parameters to filter. + +#### keys + +Type: `string[]` + +The names of the query parameters to filter based on the function used. + +#### filter + +Type: `(key, value) => boolean` + +A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`. + +#### options + +Type: `object` + +[Parse options](#options) and [stringify options](#options-1). + ## Nesting This module intentionally doesn't support nesting as it's not spec'd and varies between implementations, which causes a lot of [edge cases](https://github.com/visionmedia/node-querystring/issues). diff --git a/test/exclude.js b/test/exclude.js new file mode 100644 index 0000000..91e0d4f --- /dev/null +++ b/test/exclude.js @@ -0,0 +1,17 @@ +import test from 'ava'; +import queryString from '..'; + +test('excludes elements in a URL with a filter array', t => { + t.is(queryString.exclude('http://example.com/?a=1&b=2&c=3#a', ['c']), 'http://example.com/?a=1&b=2#a'); +}); + +test('excludes elements in a URL with a filter predicate', t => { + t.is(queryString.exclude('http://example.com/?a=1&b=2&c=3#a', (name, value) => { + t.is(typeof name, 'string'); + t.is(typeof value, 'number'); + + return name === 'a'; + }, { + parseNumbers: true + }), 'http://example.com/?b=2&c=3#a'); +}); diff --git a/test/pick.js b/test/pick.js new file mode 100644 index 0000000..e5e4381 --- /dev/null +++ b/test/pick.js @@ -0,0 +1,17 @@ +import test from 'ava'; +import queryString from '..'; + +test('picks elements in a URL with a filter array', t => { + t.is(queryString.pick('http://example.com/?a=1&b=2&c=3#a', ['a', 'b']), 'http://example.com/?a=1&b=2#a'); +}); + +test('picks elements in a URL with a filter predicate', t => { + t.is(queryString.pick('http://example.com/?a=1&b=2&c=3#a', (name, value) => { + t.is(typeof name, 'string'); + t.is(typeof value, 'number'); + + return name === 'a'; + }, { + parseNumbers: true + }), 'http://example.com/?a=1#a'); +}); From 2a178815cf9b31ea4eef31efd48d9017a29d9519 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Wed, 10 Feb 2021 13:15:35 +0700 Subject: [PATCH 04/50] 6.14.0 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 6f5372b..3b90b26 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "6.13.8", + "version": "6.14.0", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From a6d4a3f480b2810a8cce3c0118a2aacc6c6c7add Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Fri, 26 Feb 2021 18:15:35 +0700 Subject: [PATCH 05/50] Fix TypeScript type for `stringifyUrl()` Fixes #308 --- index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.d.ts b/index.d.ts index b6d651b..4a115fb 100644 --- a/index.d.ts +++ b/index.d.ts @@ -372,7 +372,7 @@ export interface UrlObject { /** Overrides queries in the `url` property. */ - readonly query: StringifiableRecord; + readonly query?: StringifiableRecord; /** Overrides the fragment identifier in the `url` property. From 0090a3418253eea4b2c437ba034dd445361325b2 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Fri, 26 Feb 2021 18:16:40 +0700 Subject: [PATCH 06/50] 6.14.1 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 3b90b26..c75f01a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "6.14.0", + "version": "6.14.1", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 44abc66628199bd3766ac471e265e64206f146c9 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Sat, 13 Mar 2021 00:54:58 +0700 Subject: [PATCH 07/50] Meta tweaks --- readme.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 280972e..884b0fd 100644 --- a/readme.md +++ b/readme.md @@ -17,7 +17,20 @@

- + + +
+
+ +
+ Doppler +
+ All your environment variables, in one place +
+ Stop struggling with scattered API keys, hacking together home-brewed tools, +
+ and avoiding access controls. Keep your team and servers in sync with Doppler. +

From 828f032306216f09a17d900fb765b002e1fd7691 Mon Sep 17 00:00:00 2001 From: Miguel Valenzuela Date: Tue, 16 Mar 2021 22:56:31 -0700 Subject: [PATCH 08/50] Implement skips for stringify array format comma (#304) Co-authored-by: Sindre Sorhus --- index.d.ts | 5 +++++ index.js | 12 ++++++++++-- readme.md | 5 +++++ test/parse.js | 31 +++++++++++++++++++++++++++++-- test/stringify.js | 23 ++++++++++++++++++----- 5 files changed, 67 insertions(+), 9 deletions(-) diff --git a/index.d.ts b/index.d.ts index 4a115fb..035ded8 100644 --- a/index.d.ts +++ b/index.d.ts @@ -229,6 +229,11 @@ export interface StringifyOptions { queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'}); //=> 'foo=1,2,3' + + queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'}); + //=> 'foo=1,,' + // Note that typing information for null values is lost + // and `.parse('foo=1,,')` would return `{foo: [1, '', '']}`. ``` - `separator`: Serialize arrays by separating elements with character: diff --git a/index.js b/index.js index 423b9d6..07764d5 100644 --- a/index.js +++ b/index.js @@ -50,12 +50,20 @@ function encoderForArrayFormat(options) { case 'comma': case 'separator': return key => (result, value) => { - if (value === null || value === undefined || value.length === 0) { + if ( + value === undefined || + (options.skipNull && value === null) || + (options.skipEmptyString && value === '') + ) { return result; } if (result.length === 0) { - return [[encode(key, options), '=', encode(value, options)].join('')]; + return [[encode(key, options), '=', encode(value === null ? '' : value, options)].join('')]; + } + + if (value === null || value === '') { + return [[result, ''].join(options.arrayFormatSeparator)]; } return [[result, encode(value, options)].join(options.arrayFormatSeparator)]; diff --git a/readme.md b/readme.md index 884b0fd..f90aba6 100644 --- a/readme.md +++ b/readme.md @@ -241,6 +241,11 @@ const queryString = require('query-string'); queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'}); //=> 'foo=1,2,3' + +queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'}); +//=> 'foo=1,,' +// Note that typing information for null values is lost +// and `.parse('foo=1,,')` would return `{foo: [1, '', '']}`. ``` - `'none'`: Serialize arrays by using duplicate keys: diff --git a/test/parse.js b/test/parse.js index 9bfc034..70759f1 100644 --- a/test/parse.js +++ b/test/parse.js @@ -218,7 +218,7 @@ test('query strings having ordered index arrays and format option as `index`', t }), {bat: 'buz', foo: ['zero', 'two', 'one', 'three']}); }); -test('circuit parse -> stringify', t => { +test('circuit parse → stringify', t => { const original = 'foo[3]=foo&foo[2]&foo[1]=one&foo[0]=&bat=buz'; const sortedOriginal = 'bat=buz&foo[0]=&foo[1]=one&foo[2]&foo[3]=foo'; const expected = {bat: 'buz', foo: ['', 'one', null, 'foo']}; @@ -231,7 +231,7 @@ test('circuit parse -> stringify', t => { t.is(queryString.stringify(expected, options), sortedOriginal); }); -test('circuit original -> parse - > stringify -> sorted original', t => { +test('circuit original → parse → stringify → sorted original', t => { const original = 'foo[21474836471]=foo&foo[21474836470]&foo[1]=one&foo[0]=&bat=buz'; const sortedOriginal = 'bat=buz&foo[0]=&foo[1]=one&foo[2]&foo[3]=foo'; const options = { @@ -241,6 +241,33 @@ test('circuit original -> parse - > stringify -> sorted original', t => { t.deepEqual(queryString.stringify(queryString.parse(original, options), options), sortedOriginal); }); +test('circuit parse → stringify with array commas', t => { + const original = 'c=,a,,&b=&a='; + const sortedOriginal = 'a=&b=&c=,a,,'; + const expected = { + c: ['', 'a', '', ''], + b: '', + a: '' + }; + const options = { + arrayFormat: 'comma' + }; + + t.deepEqual(queryString.parse(original, options), expected); + + t.is(queryString.stringify(expected, options), sortedOriginal); +}); + +test('circuit original → parse → stringify with array commas → sorted original', t => { + const original = 'c=,a,,&b=&a='; + const sortedOriginal = 'a=&b=&c=,a,,'; + const options = { + arrayFormat: 'comma' + }; + + t.deepEqual(queryString.stringify(queryString.parse(original, options), options), sortedOriginal); +}); + test('decode keys and values', t => { t.deepEqual(queryString.parse('st%C3%A5le=foo'), {ståle: 'foo'}); t.deepEqual(queryString.parse('foo=%7B%ab%%7C%de%%7D+%%7Bst%C3%A5le%7D%'), {foo: '{%ab%|%de%} %{ståle}%'}); diff --git a/test/stringify.js b/test/stringify.js index 5c3487b..4b8bda5 100644 --- a/test/stringify.js +++ b/test/stringify.js @@ -126,13 +126,26 @@ test('array stringify representation with array commas', t => { }), 'bar=one,two&foo'); }); -test('array stringify representation with array commas and null value', t => { +test('array stringify representation with array commas, null & empty string', t => { t.is(queryString.stringify({ - foo: [null, 'a', null, ''], - bar: [null] + c: [null, 'a', '', null], + b: [null], + a: [''] + }, { + arrayFormat: 'comma' + }), 'a=&b=&c=,a,,'); +}); + +test('array stringify representation with array commas, null & empty string (skip both)', t => { + t.is(queryString.stringify({ + c: [null, 'a', '', null], + b: [null], + a: [''] }, { + skipNull: true, + skipEmptyString: true, arrayFormat: 'comma' - }), 'foo=a'); + }), 'c=a'); }); test('array stringify representation with array commas and 0 value', t => { @@ -141,7 +154,7 @@ test('array stringify representation with array commas and 0 value', t => { bar: [null] }, { arrayFormat: 'comma' - }), 'foo=a,0'); + }), 'bar=&foo=a,,0'); }); test('array stringify representation with a bad array format', t => { From b10bc19699a09580c055a381541e726dfd01a001 Mon Sep 17 00:00:00 2001 From: Austin Keener Date: Thu, 18 Mar 2021 07:52:12 -0400 Subject: [PATCH 09/50] Add support for `arrayFormat: 'bracket-separator'` (#276) Co-authored-by: Sindre Sorhus --- benchmark.js | 5 +++- index.d.ts | 57 ++++++++++++++++++++++++++++++++++++++--- index.js | 43 ++++++++++++++++++++++++++----- readme.md | 60 +++++++++++++++++++++++++++++++++++++++++++ test/parse.js | 30 ++++++++++++++++++++++ test/stringify.js | 65 +++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 250 insertions(+), 10 deletions(-) diff --git a/benchmark.js b/benchmark.js index af120ea..b152460 100644 --- a/benchmark.js +++ b/benchmark.js @@ -20,6 +20,7 @@ const TEST_STRING = stringify(TEST_OBJECT); const TEST_BRACKETS_STRING = stringify(TEST_OBJECT, {arrayFormat: 'bracket'}); const TEST_INDEX_STRING = stringify(TEST_OBJECT, {arrayFormat: 'index'}); const TEST_COMMA_STRING = stringify(TEST_OBJECT, {arrayFormat: 'comma'}); +const TEST_BRACKET_SEPARATOR_STRING = stringify(TEST_OBJECT, {arrayFormat: 'bracket-separator'}); const TEST_URL = stringifyUrl({url: TEST_HOST, query: TEST_OBJECT}); // Creates a test case and adds it to the suite @@ -41,6 +42,7 @@ defineTestCase('parse', TEST_STRING, {decode: false}); defineTestCase('parse', TEST_BRACKETS_STRING, {arrayFormat: 'bracket'}); defineTestCase('parse', TEST_INDEX_STRING, {arrayFormat: 'index'}); defineTestCase('parse', TEST_COMMA_STRING, {arrayFormat: 'comma'}); +defineTestCase('parse', TEST_BRACKET_SEPARATOR_STRING, {arrayFormat: 'bracket-separator'}); // Stringify defineTestCase('stringify', TEST_OBJECT); @@ -51,6 +53,7 @@ defineTestCase('stringify', TEST_OBJECT, {skipEmptyString: true}); defineTestCase('stringify', TEST_OBJECT, {arrayFormat: 'bracket'}); defineTestCase('stringify', TEST_OBJECT, {arrayFormat: 'index'}); defineTestCase('stringify', TEST_OBJECT, {arrayFormat: 'comma'}); +defineTestCase('stringify', TEST_OBJECT, {arrayFormat: 'bracket-separator'}); // Extract defineTestCase('extract', TEST_URL); @@ -66,7 +69,7 @@ suite.on('cycle', event => { const {name, hz} = event.target; const opsPerSec = Math.round(hz).toLocaleString(); - console.log(name.padEnd(36, '_') + opsPerSec.padStart(12, '_') + ' ops/s'); + console.log(name.padEnd(46, '_') + opsPerSec.padStart(3, '_') + ' ops/s'); }); suite.run(); diff --git a/index.d.ts b/index.d.ts index 035ded8..847336d 100644 --- a/index.d.ts +++ b/index.d.ts @@ -45,6 +45,30 @@ export interface ParseOptions { //=> {foo: ['1', '2', '3']} ``` + - `bracket-separator`: Parse arrays (that are explicitly marked with brackets) with elements separated by a custom character: + + ``` + import queryString = require('query-string'); + + queryString.parse('foo[]', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: []} + + queryString.parse('foo[]=', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: ['']} + + queryString.parse('foo[]=1', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: ['1']} + + queryString.parse('foo[]=1|2|3', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: ['1', '2', '3']} + + queryString.parse('foo[]=1||3|||6', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: ['1', '', 3, '', '', '6']} + + queryString.parse('foo[]=1|2|3&bar=fluffy&baz[]=4', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: ['1', '2', '3'], bar: 'fluffy', baz:['4']} + ``` + - `none`: Parse arrays with elements using duplicate keys: ``` @@ -54,7 +78,7 @@ export interface ParseOptions { //=> {foo: ['1', '2', '3']} ``` */ - readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'none'; + readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'none'; /** The character used to separate array elements when using `{arrayFormat: 'separator'}`. @@ -236,7 +260,7 @@ export interface StringifyOptions { // and `.parse('foo=1,,')` would return `{foo: [1, '', '']}`. ``` - - `separator`: Serialize arrays by separating elements with character: + - `separator`: Serialize arrays by separating elements with character: ``` import queryString = require('query-string'); @@ -245,6 +269,33 @@ export interface StringifyOptions { //=> 'foo=1|2|3' ``` + - `bracket-separator`: Serialize arrays by explicitly post-fixing array names with brackets and separating elements with a custom character: + + ``` + import queryString = require('query-string'); + + queryString.stringify({foo: []}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]' + + queryString.stringify({foo: ['']}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]=' + + queryString.stringify({foo: [1]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]=1' + + queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]=1|2|3' + + queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]=1||3|||6' + + queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|', skipNull: true}); + //=> 'foo[]=1||3|6' + + queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]=1|2|3&bar=fluffy&baz[]=4' + ``` + - `none`: Serialize arrays by using duplicate keys: ``` @@ -254,7 +305,7 @@ export interface StringifyOptions { //=> 'foo=1&foo=2&foo=3' ``` */ - readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'none'; + readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'none'; /** The character used to separate array elements when using `{arrayFormat: 'separator'}`. diff --git a/index.js b/index.js index 07764d5..7ab5d92 100644 --- a/index.js +++ b/index.js @@ -49,6 +49,11 @@ function encoderForArrayFormat(options) { case 'comma': case 'separator': + case 'bracket-separator': { + const keyValueSep = options.arrayFormat === 'bracket-separator' ? + '[]=' : + '='; + return key => (result, value) => { if ( value === undefined || @@ -58,16 +63,16 @@ function encoderForArrayFormat(options) { return result; } - if (result.length === 0) { - return [[encode(key, options), '=', encode(value === null ? '' : value, options)].join('')]; - } + // Translate null to an empty string so that it doesn't serialize as 'null' + value = value === null ? '' : value; - if (value === null || value === '') { - return [[result, ''].join(options.arrayFormatSeparator)]; + if (result.length === 0) { + return [[encode(key, options), keyValueSep, encode(value, options)].join('')]; } return [[result, encode(value, options)].join(options.arrayFormatSeparator)]; }; + } default: return key => (result, value) => { @@ -138,6 +143,28 @@ function parserForArrayFormat(options) { accumulator[key] = newValue; }; + case 'bracket-separator': + return (key, value, accumulator) => { + const isArray = /(\[\])$/.test(key); + key = key.replace(/\[\]$/, ''); + + if (!isArray) { + accumulator[key] = value ? decode(value, options) : value; + return; + } + + const arrayValue = value === null ? + [] : + value.split(options.arrayFormatSeparator).map(item => decode(item, options)); + + if (accumulator[key] === undefined) { + accumulator[key] = arrayValue; + return; + } + + accumulator[key] = [].concat(accumulator[key], arrayValue); + }; + default: return (key, value, accumulator) => { if (accumulator[key] === undefined) { @@ -261,7 +288,7 @@ function parse(query, options) { // Missing `=` should be `null`: // http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters - value = value === undefined ? null : ['comma', 'separator'].includes(options.arrayFormat) ? value : decode(value, options); + value = value === undefined ? null : ['comma', 'separator', 'bracket-separator'].includes(options.arrayFormat) ? value : decode(value, options); formatter(decode(key, options), value, ret); } @@ -343,6 +370,10 @@ exports.stringify = (object, options) => { } if (Array.isArray(value)) { + if (value.length === 0 && options.arrayFormat === 'bracket-separator') { + return encode(key, options) + '[]'; + } + return value .reduce(formatter(key), []) .join('&'); diff --git a/readme.md b/readme.md index f90aba6..600a971 100644 --- a/readme.md +++ b/readme.md @@ -138,6 +138,30 @@ queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: //=> {foo: ['1', '2', '3']} ``` +- `'bracket-separator'`: Parse arrays (that are explicitly marked with brackets) with elements separated by a custom character: + +```js +const queryString = require('query-string'); + +queryString.parse('foo[]', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> {foo: []} + +queryString.parse('foo[]=', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> {foo: ['']} + +queryString.parse('foo[]=1', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> {foo: ['1']} + +queryString.parse('foo[]=1|2|3', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> {foo: ['1', '2', '3']} + +queryString.parse('foo[]=1||3|||6', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> {foo: ['1', '', 3, '', '', '6']} + +queryString.parse('foo[]=1|2|3&bar=fluffy&baz[]=4', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> {foo: ['1', '2', '3'], bar: 'fluffy', baz:['4']} +``` + - `'none'`: Parse arrays with elements using duplicate keys: ```js @@ -248,6 +272,42 @@ queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'}); // and `.parse('foo=1,,')` would return `{foo: [1, '', '']}`. ``` +- `'separator'`: Serialize arrays by separating elements with a custom character: + +```js +const queryString = require('query-string'); + +queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSeparator: '|'}); +//=> 'foo=1|2|3' +``` + +- `'bracket-separator'`: Serialize arrays by explicitly post-fixing array names with brackets and separating elements with a custom character: + +```js +const queryString = require('query-string'); + +queryString.stringify({foo: []}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> 'foo[]' + +queryString.stringify({foo: ['']}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> 'foo[]=' + +queryString.stringify({foo: [1]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> 'foo[]=1' + +queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> 'foo[]=1|2|3' + +queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> 'foo[]=1||3|||6' + +queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|', skipNull: true}); +//=> 'foo[]=1||3|6' + +queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); +//=> 'foo[]=1|2|3&bar=fluffy&baz[]=4' +``` + - `'none'`: Serialize arrays by using duplicate keys: ```js diff --git a/test/parse.js b/test/parse.js index 70759f1..731a848 100644 --- a/test/parse.js +++ b/test/parse.js @@ -184,6 +184,36 @@ test('query strings having indexed arrays and format option as `index`', t => { }), {foo: ['bar', 'baz']}); }); +test('query strings having brackets+separator arrays and format option as `bracket-separator` with 1 value', t => { + t.deepEqual(queryString.parse('foo[]=bar', { + arrayFormat: 'bracket-separator' + }), {foo: ['bar']}); +}); + +test('query strings having brackets+separator arrays and format option as `bracket-separator` with multiple values', t => { + t.deepEqual(queryString.parse('foo[]=bar,baz,,,biz', { + arrayFormat: 'bracket-separator' + }), {foo: ['bar', 'baz', '', '', 'biz']}); +}); + +test('query strings with multiple brackets+separator arrays and format option as `bracket-separator` using same key name', t => { + t.deepEqual(queryString.parse('foo[]=bar,baz&foo[]=biz,boz', { + arrayFormat: 'bracket-separator' + }), {foo: ['bar', 'baz', 'biz', 'boz']}); +}); + +test('query strings having an empty brackets+separator array and format option as `bracket-separator`', t => { + t.deepEqual(queryString.parse('foo[]', { + arrayFormat: 'bracket-separator' + }), {foo: []}); +}); + +test('query strings having a brackets+separator array and format option as `bracket-separator` with a single empty string', t => { + t.deepEqual(queryString.parse('foo[]=', { + arrayFormat: 'bracket-separator' + }), {foo: ['']}); +}); + test('query strings having = within parameters (i.e. GraphQL IDs)', t => { t.deepEqual(queryString.parse('foo=bar=&foo=ba=z='), {foo: ['bar=', 'ba=z=']}); }); diff --git a/test/stringify.js b/test/stringify.js index 4b8bda5..c8751eb 100644 --- a/test/stringify.js +++ b/test/stringify.js @@ -172,6 +172,71 @@ test('array stringify representation with array indexes and sparse array', t => t.is(queryString.stringify({bar: fixture}, {arrayFormat: 'index'}), 'bar[0]=one&bar[1]=two&bar[2]=three'); }); +test('array stringify representation with brackets and separators with empty array', t => { + t.is(queryString.stringify({ + foo: null, + bar: [] + }, { + arrayFormat: 'bracket-separator' + }), 'bar[]&foo'); +}); + +test('array stringify representation with brackets and separators with single value', t => { + t.is(queryString.stringify({ + foo: null, + bar: ['one'] + }, { + arrayFormat: 'bracket-separator' + }), 'bar[]=one&foo'); +}); + +test('array stringify representation with brackets and separators with multiple values', t => { + t.is(queryString.stringify({ + foo: null, + bar: ['one', 'two', 'three'] + }, { + arrayFormat: 'bracket-separator' + }), 'bar[]=one,two,three&foo'); +}); + +test('array stringify representation with brackets and separators with a single empty string', t => { + t.is(queryString.stringify({ + foo: null, + bar: [''] + }, { + arrayFormat: 'bracket-separator' + }), 'bar[]=&foo'); +}); + +test('array stringify representation with brackets and separators with a multiple empty string', t => { + t.is(queryString.stringify({ + foo: null, + bar: ['', 'two', ''] + }, { + arrayFormat: 'bracket-separator' + }), 'bar[]=,two,&foo'); +}); + +test('array stringify representation with brackets and separators with dropped empty strings', t => { + t.is(queryString.stringify({ + foo: null, + bar: ['', 'two', ''] + }, { + arrayFormat: 'bracket-separator', + skipEmptyString: true + }), 'bar[]=two&foo'); +}); + +test('array stringify representation with brackets and separators with dropped null values', t => { + t.is(queryString.stringify({ + foo: null, + bar: ['one', null, 'three', null, '', 'six'] + }, { + arrayFormat: 'bracket-separator', + skipNull: true + }), 'bar[]=one,three,,six'); +}); + test('should sort keys in given order', t => { const fixture = ['c', 'a', 'b']; const sort = (key1, key2) => fixture.indexOf(key1) - fixture.indexOf(key2); From 20992772758fc74188db64e789535469adaf241f Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Thu, 18 Mar 2021 18:53:55 +0700 Subject: [PATCH 10/50] 7.0.0 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index c75f01a..2680bc1 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "6.14.1", + "version": "7.0.0", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From bc6b4785b123aa97d5bb44876356b9a1069798f6 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Fri, 21 May 2021 19:05:11 +0700 Subject: [PATCH 11/50] Meta tweaks --- readme.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/readme.md b/readme.md index 600a971..68a8b6a 100644 --- a/readme.md +++ b/readme.md @@ -21,6 +21,7 @@

+
Doppler @@ -32,6 +33,16 @@ and avoiding access controls. Keep your team and servers in sync with Doppler.
+
+ +
+ Strapi +
+ Strapi is the leading open-source headless CMS. +
+ It’s 100% JavaScript, fully customizable, and developer-first. +
+

From 9e2482d458a5fc4a997fa9f1558d8a0daeeaa512 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Wed, 26 May 2021 00:04:51 +0700 Subject: [PATCH 12/50] Update readme.md --- readme.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 68a8b6a..67bd4bc 100644 --- a/readme.md +++ b/readme.md @@ -56,7 +56,9 @@ $ npm install query-string ``` -This module targets Node.js 6 or later and the latest version of Chrome, Firefox, and Safari. If you want support for older browsers, or, if your project is using create-react-app v1, use version 5: `npm install query-string@5`. +**Not `npm install querystring`!!!!!** + +This module targets Node.js 6 or later and the latest version of Chrome, Firefox, and Safari. ## Usage From 4279ef880c0d4fbbed60c3149bed73298800daa2 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Wed, 9 Jun 2021 01:11:53 +0700 Subject: [PATCH 13/50] Meta tweaks --- readme.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/readme.md b/readme.md index 67bd4bc..24310d7 100644 --- a/readme.md +++ b/readme.md @@ -43,6 +43,15 @@ It’s 100% JavaScript, fully customizable, and developer-first. +
+ +
+ OSS Capital +
+
+ Founded in 2018, OSS Capital is the first and only venture capital platform focused
exclusively on supporting early-stage COSS (commercial open source) startup founders.
+
+

From 8887f78ddc5a5755916ff53b7c4f9a2c845fa3df Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Sun, 20 Jun 2021 20:55:12 +0700 Subject: [PATCH 14/50] Add FAQ to the readme Closes #305 --- readme.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/readme.md b/readme.md index 24310d7..3af49af 100644 --- a/readme.md +++ b/readme.md @@ -620,6 +620,12 @@ queryString.stringify({foo: undefined}); //=> '' ``` +## FAQ + +### Why is it parsing `+` as a space? + +See [this answer](https://github.com/sindresorhus/query-string/issues/305). + ## query-string for enterprise Available as part of the Tidelift Subscription. From fd3e7792e0ec0fb72925627869a4d583ed832e54 Mon Sep 17 00:00:00 2001 From: Richie Bendall Date: Tue, 22 Jun 2021 05:30:44 +1200 Subject: [PATCH 15/50] Don't encode the fragment identifier in `.pick` and `.exclude` (#320) --- index.js | 10 +++++++--- test/exclude.js | 4 ++++ test/pick.js | 4 ++++ 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/index.js b/index.js index 7ab5d92..cc57637 100644 --- a/index.js +++ b/index.js @@ -6,6 +6,8 @@ const filterObject = require('filter-obj'); const isNullOrUndefined = value => value === null || value === undefined; +const encodeFragmentIdentifier = Symbol('encodeFragmentIdentifier'); + function encoderForArrayFormat(options) { switch (options.arrayFormat) { case 'index': @@ -402,7 +404,8 @@ exports.parseUrl = (url, options) => { exports.stringifyUrl = (object, options) => { options = Object.assign({ encode: true, - strict: true + strict: true, + [encodeFragmentIdentifier]: true }, options); const url = removeHash(object.url).split('?')[0] || ''; @@ -417,7 +420,7 @@ exports.stringifyUrl = (object, options) => { let hash = getHash(object.url); if (object.fragmentIdentifier) { - hash = `#${encode(object.fragmentIdentifier, options)}`; + hash = `#${options[encodeFragmentIdentifier] ? encode(object.fragmentIdentifier, options) : object.fragmentIdentifier}`; } return `${url}${queryString}${hash}`; @@ -425,7 +428,8 @@ exports.stringifyUrl = (object, options) => { exports.pick = (input, filter, options) => { options = Object.assign({ - parseFragmentIdentifier: true + parseFragmentIdentifier: true, + [encodeFragmentIdentifier]: false }, options); const {url, query, fragmentIdentifier} = exports.parseUrl(input, options); diff --git a/test/exclude.js b/test/exclude.js index 91e0d4f..646db88 100644 --- a/test/exclude.js +++ b/test/exclude.js @@ -15,3 +15,7 @@ test('excludes elements in a URL with a filter predicate', t => { parseNumbers: true }), 'http://example.com/?b=2&c=3#a'); }); + +test('excludes elements in a URL without encoding fragment identifiers', t => { + t.is(queryString.exclude('https://example.com?a=b#/home', ['a']), 'https://example.com#/home'); +}); diff --git a/test/pick.js b/test/pick.js index e5e4381..0bfaf72 100644 --- a/test/pick.js +++ b/test/pick.js @@ -15,3 +15,7 @@ test('picks elements in a URL with a filter predicate', t => { parseNumbers: true }), 'http://example.com/?a=1#a'); }); + +test('picks elements in a URL without encoding fragment identifiers', t => { + t.is(queryString.pick('https://example.com?a=b#/home', []), 'https://example.com#/home'); +}); From b03e2e709664834e6cdcf50cd84b0056cdb5b7ff Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Tue, 22 Jun 2021 00:33:16 +0700 Subject: [PATCH 16/50] 7.0.1 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 2680bc1..c1a4a75 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "7.0.0", + "version": "7.0.1", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 6d220e665c5e776dc9853ad5f0578b270d521d08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Fern=C3=A1ndez=20de=20Alba?= Date: Thu, 6 Jan 2022 13:19:14 +0100 Subject: [PATCH 17/50] Add support for parameters with an explicit `:list` marker (#335) --- index.d.ts | 22 ++++++++++++++++++++-- index.js | 35 +++++++++++++++++++++++++++++++++++ readme.md | 18 ++++++++++++++++++ test/parse.js | 8 ++++++++ test/stringify.js | 24 ++++++++++++++++++++++++ 5 files changed, 105 insertions(+), 2 deletions(-) diff --git a/index.d.ts b/index.d.ts index 847336d..5633c5e 100644 --- a/index.d.ts +++ b/index.d.ts @@ -69,6 +69,15 @@ export interface ParseOptions { //=> {foo: ['1', '2', '3'], bar: 'fluffy', baz:['4']} ``` + - `colon-list-separator`: Parse arrays with parameter names that are explicitly marked with `:list`: + + ``` + import queryString = require('query-string'); + + queryString.parse('foo:list=one&foo:list=two', {arrayFormat: 'colon-list-separator'}); + //=> {foo: ['one', 'two']} + ``` + - `none`: Parse arrays with elements using duplicate keys: ``` @@ -78,7 +87,7 @@ export interface ParseOptions { //=> {foo: ['1', '2', '3']} ``` */ - readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'none'; + readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'colon-list-separator' | 'none'; /** The character used to separate array elements when using `{arrayFormat: 'separator'}`. @@ -296,6 +305,15 @@ export interface StringifyOptions { //=> 'foo[]=1|2|3&bar=fluffy&baz[]=4' ``` + - `colon-list-separator`: Serialize arrays with parameter names that are explicitly marked with `:list`: + + ```js + import queryString = require('query-string'); + + queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator'}); + //=> 'foo:list=one&foo:list=two' + ``` + - `none`: Serialize arrays by using duplicate keys: ``` @@ -305,7 +323,7 @@ export interface StringifyOptions { //=> 'foo=1&foo=2&foo=3' ``` */ - readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'none'; + readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'colon-list-separator' | 'none'; /** The character used to separate array elements when using `{arrayFormat: 'separator'}`. diff --git a/index.js b/index.js index cc57637..d45e67d 100644 --- a/index.js +++ b/index.js @@ -49,6 +49,23 @@ function encoderForArrayFormat(options) { return [...result, [encode(key, options), '[]=', encode(value, options)].join('')]; }; + case 'colon-list-separator': + return key => (result, value) => { + if ( + value === undefined || + (options.skipNull && value === null) || + (options.skipEmptyString && value === '') + ) { + return result; + } + + if (value === null) { + return [...result, [encode(key, options), ':list='].join('')]; + } + + return [...result, [encode(key, options), ':list=', encode(value, options)].join('')]; + }; + case 'comma': case 'separator': case 'bracket-separator': { @@ -135,6 +152,24 @@ function parserForArrayFormat(options) { accumulator[key] = [].concat(accumulator[key], value); }; + case 'colon-list-separator': + return (key, value, accumulator) => { + result = /(:list)$/.exec(key); + key = key.replace(/:list$/, ''); + + if (!result) { + accumulator[key] = value; + return; + } + + if (accumulator[key] === undefined) { + accumulator[key] = [value]; + return; + } + + accumulator[key] = [].concat(accumulator[key], value); + }; + case 'comma': case 'separator': return (key, value, accumulator) => { diff --git a/readme.md b/readme.md index 3af49af..f696aae 100644 --- a/readme.md +++ b/readme.md @@ -184,6 +184,15 @@ queryString.parse('foo[]=1|2|3&bar=fluffy&baz[]=4', {arrayFormat: 'bracket-separ //=> {foo: ['1', '2', '3'], bar: 'fluffy', baz:['4']} ``` +- `'colon-list-separator'`: Parse arrays with parameter names that are explicitly marked with `:list`: + +```js +const queryString = require('query-string'); + +queryString.parse('foo:list=one&foo:list=two', {arrayFormat: 'colon-list-separator'}); +//=> {foo: ['one', 'two']} +``` + - `'none'`: Parse arrays with elements using duplicate keys: ```js @@ -330,6 +339,15 @@ queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: ' //=> 'foo[]=1|2|3&bar=fluffy&baz[]=4' ``` +- `'colon-list-separator'`: Serialize arrays with parameter names that are explicitly marked with `:list`: + +```js +const queryString = require('query-string'); + +queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator'}); +//=> 'foo:list=one&foo:list=two' +``` + - `'none'`: Serialize arrays by using duplicate keys: ```js diff --git a/test/parse.js b/test/parse.js index 731a848..9986efd 100644 --- a/test/parse.js +++ b/test/parse.js @@ -390,3 +390,11 @@ test('value separated by encoded comma will not be parsed as array with `arrayFo id: [1, 2, 3] }); }); + +test('query strings having (:list) colon-list-separator arrays', t => { + t.deepEqual(queryString.parse('bar:list=one&bar:list=two', {arrayFormat: 'colon-list-separator'}), {bar: ['one', 'two']}); +}); + +test('query strings having (:list) colon-list-separator arrays including null values', t => { + t.deepEqual(queryString.parse('bar:list=one&bar:list=two&foo', {arrayFormat: 'colon-list-separator'}), {bar: ['one', 'two'], foo: null}); +}); diff --git a/test/stringify.js b/test/stringify.js index c8751eb..e3f2a61 100644 --- a/test/stringify.js +++ b/test/stringify.js @@ -400,3 +400,27 @@ test('stringify throws TypeError for invalid arrayFormatSeparator', t => { instanceOf: TypeError }); }); + +test('array stringify representation with (:list) colon-list-separator', t => { + t.is(queryString.stringify({ + foo: null, + bar: ['one', 'two'] + }, { + arrayFormat: 'colon-list-separator' + }), 'bar:list=one&bar:list=two&foo'); +}); + +test('array stringify representation with (:list) colon-list-separator with null values', t => { + t.is(queryString.stringify({ + foo: null, + bar: ['one', ''] + }, { + arrayFormat: 'colon-list-separator' + }), 'bar:list=one&bar:list=&foo'); + t.is(queryString.stringify({ + foo: null, + bar: ['one', null] + }, { + arrayFormat: 'colon-list-separator' + }), 'bar:list=one&bar:list=&foo'); +}); From a5f3ccc6cba000f8b94895e66f31c1e88e35a0bb Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Thu, 6 Jan 2022 13:20:23 +0100 Subject: [PATCH 18/50] 7.1.0 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index c1a4a75..bf72a09 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "7.0.1", + "version": "7.1.0", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 53315790fa01e0843c924cb07457fc0aecd4a745 Mon Sep 17 00:00:00 2001 From: bug-brain <40305896+bug-brain@users.noreply.github.com> Date: Sat, 5 Feb 2022 19:50:32 +0100 Subject: [PATCH 19/50] Fix `ParsedQuery` type to allow null in array (#338) --- index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.d.ts b/index.d.ts index 5633c5e..59de603 100644 --- a/index.d.ts +++ b/index.d.ts @@ -172,7 +172,7 @@ export interface ParseOptions { } export interface ParsedQuery { - [key: string]: T | T[] | null; + [key: string]: T | null | Array; } /** From a5ed7eaf496b47e0cd7f6071a56ac297c8e280e4 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Sun, 6 Feb 2022 01:52:05 +0700 Subject: [PATCH 20/50] 7.1.1 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index bf72a09..fd0b303 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "7.1.0", + "version": "7.1.1", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 114da9a3041b96280cb18c9f8032c621f370d5d0 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Mon, 28 Nov 2022 13:21:39 +0700 Subject: [PATCH 21/50] Meta tweaks --- readme.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/readme.md b/readme.md index f696aae..5721ca0 100644 --- a/readme.md +++ b/readme.md @@ -22,18 +22,6 @@


- -
- Doppler -
- All your environment variables, in one place -
- Stop struggling with scattered API keys, hacking together home-brewed tools, -
- and avoiding access controls. Keep your team and servers in sync with Doppler. -
-
-
Strapi From d2c3596a24ff1b4a82bf9351a7e0ab236f614ce8 Mon Sep 17 00:00:00 2001 From: Victor Zhuravlev <11217819+viczhuravlev@users.noreply.github.com> Date: Thu, 1 Dec 2022 20:13:03 +0300 Subject: [PATCH 22/50] Update dependency (#353) --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index fd0b303..d529167 100644 --- a/package.json +++ b/package.json @@ -38,7 +38,7 @@ "filter" ], "dependencies": { - "decode-uri-component": "^0.2.0", + "decode-uri-component": "^0.2.1", "filter-obj": "^1.1.0", "split-on-first": "^1.0.0", "strict-uri-encode": "^2.0.0" From 88129068bc733bcb16ba0422468e7fff74dc712e Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Fri, 2 Dec 2022 00:14:40 +0700 Subject: [PATCH 23/50] 7.1.2 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index d529167..c04181d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "7.1.1", + "version": "7.1.2", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 7537410e80d04c9a4c46958575ea4a834fb2cf33 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Fri, 2 Dec 2022 00:17:58 +0700 Subject: [PATCH 24/50] Fix CI --- .github/workflows/main.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index b85fc2a..ca8ed6f 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -14,10 +14,9 @@ jobs: - 12 - 10 - 8 - - 6 steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v1 + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 with: node-version: ${{ matrix.node-version }} - run: npm install From e60e797f884f8c08389c68c9cff3efc09e2f59e2 Mon Sep 17 00:00:00 2001 From: krudos Date: Fri, 2 Dec 2022 18:42:14 +0100 Subject: [PATCH 25/50] Update dependencies (#354) --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index c04181d..4393feb 100644 --- a/package.json +++ b/package.json @@ -38,7 +38,7 @@ "filter" ], "dependencies": { - "decode-uri-component": "^0.2.1", + "decode-uri-component": "^0.2.2", "filter-obj": "^1.1.0", "split-on-first": "^1.0.0", "strict-uri-encode": "^2.0.0" From 5beef41d37f18916dc15bded8fac803a33153aa2 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Sat, 3 Dec 2022 00:43:23 +0700 Subject: [PATCH 26/50] 7.1.3 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 4393feb..d87d6df 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "7.1.2", + "version": "7.1.3", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 16a7b8f37f8b88f1785b68efca57e55ae96904e2 Mon Sep 17 00:00:00 2001 From: HanBinKim <37659866+hanbin9775@users.noreply.github.com> Date: Mon, 12 Dec 2022 23:18:54 +0900 Subject: [PATCH 27/50] Fix encoding of `fragmentIdentifier` (#355) --- index.js | 4 +++- test/stringify-url.js | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/index.js b/index.js index d45e67d..129ea26 100644 --- a/index.js +++ b/index.js @@ -455,7 +455,9 @@ exports.stringifyUrl = (object, options) => { let hash = getHash(object.url); if (object.fragmentIdentifier) { - hash = `#${options[encodeFragmentIdentifier] ? encode(object.fragmentIdentifier, options) : object.fragmentIdentifier}`; + const urlObjectForFragmentEncode = new URL(url); + urlObjectForFragmentEncode.hash = object.fragmentIdentifier; + hash = options[encodeFragmentIdentifier] ? urlObjectForFragmentEncode.hash : `#${object.fragmentIdentifier}`; } return `${url}${queryString}${hash}`; diff --git a/test/stringify-url.js b/test/stringify-url.js index 2b3c372..9b6ff43 100644 --- a/test/stringify-url.js +++ b/test/stringify-url.js @@ -26,6 +26,7 @@ test('stringify URL with fragment identifier', t => { t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar/#abc', query: {}, fragmentIdentifier: 'top'}), 'https://foo.bar/#top'); t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar', query: {}}), 'https://foo.bar'); t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar', query: {}, fragmentIdentifier: 'foo bar'}), 'https://foo.bar#foo%20bar'); + t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar/', query: {}, fragmentIdentifier: '/foo/bar'}), 'https://foo.bar/#/foo/bar'); }); test('skipEmptyString:: stringify URL with a query string', t => { From c2ab7cd102fbc96d374c6a55deea20f1bf2929c4 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Mon, 12 Dec 2022 15:25:00 +0100 Subject: [PATCH 28/50] Require Node.js 14 and move to ESM --- .github/workflows/main.yml | 5 +- base.d.ts | 561 ++++++++++++++++++++++++++++++++++++ base.js | 517 +++++++++++++++++++++++++++++++++ benchmark.js | 7 +- index.d.ts | 574 +------------------------------------ index.js | 485 +------------------------------ index.test-d.ts | 62 ++-- license | 2 +- package.json | 31 +- readme.md | 81 +++--- test/exclude.js | 4 +- test/extract.js | 10 +- test/parse-url.js | 11 +- test/parse.js | 91 +++--- test/pick.js | 4 +- test/properties.js | 23 +- test/stringify-url.js | 46 +-- test/stringify.js | 154 +++++----- 18 files changed, 1361 insertions(+), 1307 deletions(-) create mode 100644 base.d.ts create mode 100644 base.js diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ca8ed6f..d50ada6 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -10,10 +10,9 @@ jobs: fail-fast: false matrix: node-version: + - 18 + - 16 - 14 - - 12 - - 10 - - 8 steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 diff --git a/base.d.ts b/base.d.ts new file mode 100644 index 0000000..cf3b592 --- /dev/null +++ b/base.d.ts @@ -0,0 +1,561 @@ +export type ParseOptions = { + /** + Decode the keys and values. URI components are decoded with [`decode-uri-component`](https://github.com/SamVerschueren/decode-uri-component). + + @default true + */ + readonly decode?: boolean; + + /** + @default 'none' + + - `bracket`: Parse arrays with bracket representation: + + ``` + import queryString from 'query-string'; + + queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'}); + //=> {foo: ['1', '2', '3']} + ``` + + - `index`: Parse arrays with index representation: + + ``` + import queryString from 'query-string'; + + queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'}); + //=> {foo: ['1', '2', '3']} + ``` + + - `comma`: Parse arrays with elements separated by comma: + + ``` + import queryString from 'query-string'; + + queryString.parse('foo=1,2,3', {arrayFormat: 'comma'}); + //=> {foo: ['1', '2', '3']} + ``` + + - `separator`: Parse arrays with elements separated by a custom character: + + ``` + import queryString from 'query-string'; + + queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: '|'}); + //=> {foo: ['1', '2', '3']} + ``` + + - `bracket-separator`: Parse arrays (that are explicitly marked with brackets) with elements separated by a custom character: + + ``` + import queryString from 'query-string'; + + queryString.parse('foo[]', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: []} + + queryString.parse('foo[]=', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: ['']} + + queryString.parse('foo[]=1', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: ['1']} + + queryString.parse('foo[]=1|2|3', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: ['1', '2', '3']} + + queryString.parse('foo[]=1||3|||6', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: ['1', '', 3, '', '', '6']} + + queryString.parse('foo[]=1|2|3&bar=fluffy&baz[]=4', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> {foo: ['1', '2', '3'], bar: 'fluffy', baz:['4']} + ``` + + - `colon-list-separator`: Parse arrays with parameter names that are explicitly marked with `:list`: + + ``` + import queryString from 'query-string'; + + queryString.parse('foo:list=one&foo:list=two', {arrayFormat: 'colon-list-separator'}); + //=> {foo: ['one', 'two']} + ``` + + - `none`: Parse arrays with elements using duplicate keys: + + ``` + import queryString from 'query-string'; + + queryString.parse('foo=1&foo=2&foo=3'); + //=> {foo: ['1', '2', '3']} + ``` + */ + readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'colon-list-separator' | 'none'; + + /** + The character used to separate array elements when using `{arrayFormat: 'separator'}`. + + @default , + */ + readonly arrayFormatSeparator?: string; + + /** + Supports both `Function` as a custom sorting function or `false` to disable sorting. + + If omitted, keys are sorted using `Array#sort`, which means, converting them to strings and comparing strings in Unicode code point order. + + @default true + + @example + ``` + import queryString from 'query-string'; + + const order = ['c', 'a', 'b']; + + queryString.parse('?a=one&b=two&c=three', { + sort: (itemLeft, itemRight) => order.indexOf(itemLeft) - order.indexOf(itemRight) + }); + //=> {c: 'three', a: 'one', b: 'two'} + ``` + + @example + ``` + import queryString from 'query-string'; + + queryString.parse('?a=one&c=three&b=two', {sort: false}); + //=> {a: 'one', c: 'three', b: 'two'} + ``` + */ + readonly sort?: ((itemLeft: string, itemRight: string) => number) | false; + + /** + Parse the value as a number type instead of string type if it's a number. + + @default false + + @example + ``` + import queryString from 'query-string'; + + queryString.parse('foo=1', {parseNumbers: true}); + //=> {foo: 1} + ``` + */ + readonly parseNumbers?: boolean; + + /** + Parse the value as a boolean type instead of string type if it's a boolean. + + @default false + + @example + ``` + import queryString from 'query-string'; + + queryString.parse('foo=true', {parseBooleans: true}); + //=> {foo: true} + ``` + */ + readonly parseBooleans?: boolean; + + /** + Parse the fragment identifier from the URL and add it to result object. + + @default false + + @example + ``` + import queryString from 'query-string'; + + queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true}); + //=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'} + ``` + */ + readonly parseFragmentIdentifier?: boolean; +}; + +export type ParsedQuery = Record>; + +/** +Parse a query string into an object. Leading `?` or `#` are ignored, so you can pass `location.search` or `location.hash` directly. + +The returned object is created with [`Object.create(null)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create) and thus does not have a `prototype`. + +@param query - The query string to parse. +*/ +export function parse(query: string, options: {parseBooleans: true; parseNumbers: true} & ParseOptions): ParsedQuery; +export function parse(query: string, options: {parseBooleans: true} & ParseOptions): ParsedQuery; +export function parse(query: string, options: {parseNumbers: true} & ParseOptions): ParsedQuery; +export function parse(query: string, options?: ParseOptions): ParsedQuery; + +export type ParsedUrl = { + readonly url: string; + readonly query: ParsedQuery; + + /** + The fragment identifier of the URL. + + Present when the `parseFragmentIdentifier` option is `true`. + */ + readonly fragmentIdentifier?: string; +}; + +/** +Extract the URL and the query string as an object. + +If the `parseFragmentIdentifier` option is `true`, the object will also contain a `fragmentIdentifier` property. + +@param url - The URL to parse. + +@example +``` +import queryString from 'query-string'; + +queryString.parseUrl('https://foo.bar?foo=bar'); +//=> {url: 'https://foo.bar', query: {foo: 'bar'}} + +queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true}); +//=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'} +``` +*/ +export function parseUrl(url: string, options?: ParseOptions): ParsedUrl; + +export type StringifyOptions = { + /** + Strictly encode URI components with [`strict-uri-encode`](https://github.com/kevva/strict-uri-encode). It uses [`encodeURIComponent`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) if set to `false`. You probably [don't care](https://github.com/sindresorhus/query-string/issues/42) about this option. + + @default true + */ + readonly strict?: boolean; + + /** + [URL encode](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) the keys and values. + + @default true + */ + readonly encode?: boolean; + + /** + @default 'none' + + - `bracket`: Serialize arrays using bracket representation: + + ``` + import queryString from 'query-string'; + + queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'}); + //=> 'foo[]=1&foo[]=2&foo[]=3' + ``` + + - `index`: Serialize arrays using index representation: + + ``` + import queryString from 'query-string'; + + queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'}); + //=> 'foo[0]=1&foo[1]=2&foo[2]=3' + ``` + + - `comma`: Serialize arrays by separating elements with comma: + + ``` + import queryString from 'query-string'; + + queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'}); + //=> 'foo=1,2,3' + + queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'}); + //=> 'foo=1,,' + // Note that typing information for null values is lost + // and `.parse('foo=1,,')` would return `{foo: [1, '', '']}`. + ``` + + - `separator`: Serialize arrays by separating elements with character: + + ``` + import queryString from 'query-string'; + + queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSeparator: '|'}); + //=> 'foo=1|2|3' + ``` + + - `bracket-separator`: Serialize arrays by explicitly post-fixing array names with brackets and separating elements with a custom character: + + ``` + import queryString from 'query-string'; + + queryString.stringify({foo: []}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]' + + queryString.stringify({foo: ['']}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]=' + + queryString.stringify({foo: [1]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]=1' + + queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]=1|2|3' + + queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]=1||3|||6' + + queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|', skipNull: true}); + //=> 'foo[]=1||3|6' + + queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); + //=> 'foo[]=1|2|3&bar=fluffy&baz[]=4' + ``` + + - `colon-list-separator`: Serialize arrays with parameter names that are explicitly marked with `:list`: + + ```js + import queryString from 'query-string'; + + queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator'}); + //=> 'foo:list=one&foo:list=two' + ``` + + - `none`: Serialize arrays by using duplicate keys: + + ``` + import queryString from 'query-string'; + + queryString.stringify({foo: [1, 2, 3]}); + //=> 'foo=1&foo=2&foo=3' + ``` + */ + readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'colon-list-separator' | 'none'; + + /** + The character used to separate array elements when using `{arrayFormat: 'separator'}`. + + @default , + */ + readonly arrayFormatSeparator?: string; + + /** + Supports both `Function` as a custom sorting function or `false` to disable sorting. + + If omitted, keys are sorted using `Array#sort`, which means, converting them to strings and comparing strings in Unicode code point order. + + @default true + + @example + ``` + import queryString from 'query-string'; + + const order = ['c', 'a', 'b']; + + queryString.stringify({a: 1, b: 2, c: 3}, { + sort: (itemLeft, itemRight) => order.indexOf(itemLeft) - order.indexOf(itemRight) + }); + //=> 'c=3&a=1&b=2' + ``` + + @example + ``` + import queryString from 'query-string'; + + queryString.stringify({b: 1, c: 2, a: 3}, {sort: false}); + //=> 'b=1&c=2&a=3' + ``` + */ + readonly sort?: ((itemLeft: string, itemRight: string) => number) | false; + + /** + Skip keys with `null` as the value. + + Note that keys with `undefined` as the value are always skipped. + + @default false + + @example + ``` + import queryString from 'query-string'; + + queryString.stringify({a: 1, b: undefined, c: null, d: 4}, { + skipNull: true + }); + //=> 'a=1&d=4' + + queryString.stringify({a: undefined, b: null}, { + skipNull: true + }); + //=> '' + ``` + */ + readonly skipNull?: boolean; + + /** + Skip keys with an empty string as the value. + + @default false + + @example + ``` + import queryString from 'query-string'; + + queryString.stringify({a: 1, b: '', c: '', d: 4}, { + skipEmptyString: true + }); + //=> 'a=1&d=4' + ``` + + @example + ``` + import queryString from 'query-string'; + + queryString.stringify({a: '', b: ''}, { + skipEmptyString: true + }); + //=> '' + ``` + */ + readonly skipEmptyString?: boolean; +}; + +export type Stringifiable = string | boolean | number | null | undefined; // eslint-disable-line @typescript-eslint/ban-types + +export type StringifiableRecord = Record< +string, +Stringifiable | readonly Stringifiable[] +>; + +/** +Stringify an object into a query string and sort the keys. +*/ +export function stringify( + // TODO: Use the below instead when the following TS issues are fixed: + // - https://github.com/microsoft/TypeScript/issues/15300 + // - https://github.com/microsoft/TypeScript/issues/42021 + // Context: https://github.com/sindresorhus/query-string/issues/298 + // object: StringifiableRecord, + object: Record, + options?: StringifyOptions +): string; + +/** +Extract a query string from a URL that can be passed into `.parse()`. + +Note: This behaviour can be changed with the `skipNull` option. +*/ +export function extract(url: string): string; + +export type UrlObject = { + readonly url: string; + + /** + Overrides queries in the `url` property. + */ + readonly query?: StringifiableRecord; + + /** + Overrides the fragment identifier in the `url` property. + */ + readonly fragmentIdentifier?: string; +}; + +/** +Stringify an object into a URL with a query string and sorting the keys. The inverse of [`.parseUrl()`](https://github.com/sindresorhus/query-string#parseurlstring-options) + +Query items in the `query` property overrides queries in the `url` property. + +The `fragmentIdentifier` property overrides the fragment identifier in the `url` property. + +@example +``` +queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar'}}); +//=> 'https://foo.bar?foo=bar' + +queryString.stringifyUrl({url: 'https://foo.bar?foo=baz', query: {foo: 'bar'}}); +//=> 'https://foo.bar?foo=bar' + +queryString.stringifyUrl({ + url: 'https://foo.bar', + query: { + top: 'foo' + }, + fragmentIdentifier: 'bar' +}); +//=> 'https://foo.bar?top=foo#bar' +``` +*/ +export function stringifyUrl( + object: UrlObject, + options?: StringifyOptions +): string; + +/** +Pick query parameters from a URL. + +@param url - The URL containing the query parameters to pick. +@param keys - The names of the query parameters to keep. All other query parameters will be removed from the URL. +@param filter - A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`. + +@returns The URL with the picked query parameters. + +@example +``` +queryString.pick('https://foo.bar?foo=1&bar=2#hello', ['foo']); +//=> 'https://foo.bar?foo=1#hello' + +queryString.pick('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true}); +//=> 'https://foo.bar?bar=2#hello' +``` +*/ +export function pick( + url: string, + keys: readonly string[], + options?: ParseOptions & StringifyOptions +): string; +export function pick( + url: string, + filter: (key: string, value: string | boolean | number) => boolean, + options?: {parseBooleans: true; parseNumbers: true} & ParseOptions & StringifyOptions +): string; +export function pick( + url: string, + filter: (key: string, value: string | boolean) => boolean, + options?: {parseBooleans: true} & ParseOptions & StringifyOptions +): string; +export function pick( + url: string, + filter: (key: string, value: string | number) => boolean, + options?: {parseNumbers: true} & ParseOptions & StringifyOptions +): string; + +/** +Exclude query parameters from a URL. Like `.pick()` but reversed. + +@param url - The URL containing the query parameters to exclude. +@param keys - The names of the query parameters to remove. All other query parameters will remain in the URL. +@param filter - A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`. + +@returns The URL without the excluded the query parameters. + +@example +``` +queryString.exclude('https://foo.bar?foo=1&bar=2#hello', ['foo']); +//=> 'https://foo.bar?bar=2#hello' + +queryString.exclude('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true}); +//=> 'https://foo.bar?foo=1#hello' +``` +*/ +export function exclude( + url: string, + keys: readonly string[], + options?: ParseOptions & StringifyOptions +): string; +export function exclude( + url: string, + filter: (key: string, value: string | boolean | number) => boolean, + options?: {parseBooleans: true; parseNumbers: true} & ParseOptions & StringifyOptions +): string; +export function exclude( + url: string, + filter: (key: string, value: string | boolean) => boolean, + options?: {parseBooleans: true} & ParseOptions & StringifyOptions +): string; +export function exclude( + url: string, + filter: (key: string, value: string | number) => boolean, + options?: {parseNumbers: true} & ParseOptions & StringifyOptions +): string; diff --git a/base.js b/base.js new file mode 100644 index 0000000..ba41935 --- /dev/null +++ b/base.js @@ -0,0 +1,517 @@ +import decodeComponent from 'decode-uri-component'; +import splitOnFirst from 'split-on-first'; +import {includeKeys} from 'filter-obj'; + +const isNullOrUndefined = value => value === null || value === undefined; + +// eslint-disable-next-line unicorn/prefer-code-point +const strictUriEncode = string => encodeURIComponent(string).replace(/[!'()*]/g, x => `%${x.charCodeAt(0).toString(16).toUpperCase()}`); + +const encodeFragmentIdentifier = Symbol('encodeFragmentIdentifier'); + +function encoderForArrayFormat(options) { + switch (options.arrayFormat) { + case 'index': { + return key => (result, value) => { + const index = result.length; + + if ( + value === undefined + || (options.skipNull && value === null) + || (options.skipEmptyString && value === '') + ) { + return result; + } + + if (value === null) { + return [ + ...result, [encode(key, options), '[', index, ']'].join(''), + ]; + } + + return [ + ...result, + [encode(key, options), '[', encode(index, options), ']=', encode(value, options)].join(''), + ]; + }; + } + + case 'bracket': { + return key => (result, value) => { + if ( + value === undefined + || (options.skipNull && value === null) + || (options.skipEmptyString && value === '') + ) { + return result; + } + + if (value === null) { + return [ + ...result, + [encode(key, options), '[]'].join(''), + ]; + } + + return [ + ...result, + [encode(key, options), '[]=', encode(value, options)].join(''), + ]; + }; + } + + case 'colon-list-separator': { + return key => (result, value) => { + if ( + value === undefined + || (options.skipNull && value === null) + || (options.skipEmptyString && value === '') + ) { + return result; + } + + if (value === null) { + return [ + ...result, + [encode(key, options), ':list='].join(''), + ]; + } + + return [ + ...result, + [encode(key, options), ':list=', encode(value, options)].join(''), + ]; + }; + } + + case 'comma': + case 'separator': + case 'bracket-separator': { + const keyValueSep = options.arrayFormat === 'bracket-separator' + ? '[]=' + : '='; + + return key => (result, value) => { + if ( + value === undefined + || (options.skipNull && value === null) + || (options.skipEmptyString && value === '') + ) { + return result; + } + + // Translate null to an empty string so that it doesn't serialize as 'null' + value = value === null ? '' : value; + + if (result.length === 0) { + return [[encode(key, options), keyValueSep, encode(value, options)].join('')]; + } + + return [[result, encode(value, options)].join(options.arrayFormatSeparator)]; + }; + } + + default: { + return key => (result, value) => { + if ( + value === undefined + || (options.skipNull && value === null) + || (options.skipEmptyString && value === '') + ) { + return result; + } + + if (value === null) { + return [ + ...result, + encode(key, options), + ]; + } + + return [ + ...result, + [encode(key, options), '=', encode(value, options)].join(''), + ]; + }; + } + } +} + +function parserForArrayFormat(options) { + let result; + + switch (options.arrayFormat) { + case 'index': { + return (key, value, accumulator) => { + result = /\[(\d*)]$/.exec(key); + + key = key.replace(/\[\d*]$/, ''); + + if (!result) { + accumulator[key] = value; + return; + } + + if (accumulator[key] === undefined) { + accumulator[key] = {}; + } + + accumulator[key][result[1]] = value; + }; + } + + case 'bracket': { + return (key, value, accumulator) => { + result = /(\[])$/.exec(key); + key = key.replace(/\[]$/, ''); + + if (!result) { + accumulator[key] = value; + return; + } + + if (accumulator[key] === undefined) { + accumulator[key] = [value]; + return; + } + + accumulator[key] = [...accumulator[key], value]; + }; + } + + case 'colon-list-separator': { + return (key, value, accumulator) => { + result = /(:list)$/.exec(key); + key = key.replace(/:list$/, ''); + + if (!result) { + accumulator[key] = value; + return; + } + + if (accumulator[key] === undefined) { + accumulator[key] = [value]; + return; + } + + accumulator[key] = [...accumulator[key], value]; + }; + } + + case 'comma': + case 'separator': { + return (key, value, accumulator) => { + const isArray = typeof value === 'string' && value.includes(options.arrayFormatSeparator); + const isEncodedArray = (typeof value === 'string' && !isArray && decode(value, options).includes(options.arrayFormatSeparator)); + value = isEncodedArray ? decode(value, options) : value; + const newValue = isArray || isEncodedArray ? value.split(options.arrayFormatSeparator).map(item => decode(item, options)) : (value === null ? value : decode(value, options)); + accumulator[key] = newValue; + }; + } + + case 'bracket-separator': { + return (key, value, accumulator) => { + const isArray = /(\[])$/.test(key); + key = key.replace(/\[]$/, ''); + + if (!isArray) { + accumulator[key] = value ? decode(value, options) : value; + return; + } + + const arrayValue = value === null + ? [] + : value.split(options.arrayFormatSeparator).map(item => decode(item, options)); + + if (accumulator[key] === undefined) { + accumulator[key] = arrayValue; + return; + } + + accumulator[key] = [...accumulator[key], ...arrayValue]; + }; + } + + default: { + return (key, value, accumulator) => { + if (accumulator[key] === undefined) { + accumulator[key] = value; + return; + } + + accumulator[key] = [...[accumulator[key]].flat(), value]; + }; + } + } +} + +function validateArrayFormatSeparator(value) { + if (typeof value !== 'string' || value.length !== 1) { + throw new TypeError('arrayFormatSeparator must be single character string'); + } +} + +function encode(value, options) { + if (options.encode) { + return options.strict ? strictUriEncode(value) : encodeURIComponent(value); + } + + return value; +} + +function decode(value, options) { + if (options.decode) { + return decodeComponent(value); + } + + return value; +} + +function keysSorter(input) { + if (Array.isArray(input)) { + return input.sort(); + } + + if (typeof input === 'object') { + return keysSorter(Object.keys(input)) + .sort((a, b) => Number(a) - Number(b)) + .map(key => input[key]); + } + + return input; +} + +function removeHash(input) { + const hashStart = input.indexOf('#'); + if (hashStart !== -1) { + input = input.slice(0, hashStart); + } + + return input; +} + +function getHash(url) { + let hash = ''; + const hashStart = url.indexOf('#'); + if (hashStart !== -1) { + hash = url.slice(hashStart); + } + + return hash; +} + +function parseValue(value, options) { + if (options.parseNumbers && !Number.isNaN(Number(value)) && (typeof value === 'string' && value.trim() !== '')) { + value = Number(value); + } else if (options.parseBooleans && value !== null && (value.toLowerCase() === 'true' || value.toLowerCase() === 'false')) { + value = value.toLowerCase() === 'true'; + } + + return value; +} + +export function extract(input) { + input = removeHash(input); + const queryStart = input.indexOf('?'); + if (queryStart === -1) { + return ''; + } + + return input.slice(queryStart + 1); +} + +export function parse(query, options) { + options = { + decode: true, + sort: true, + arrayFormat: 'none', + arrayFormatSeparator: ',', + parseNumbers: false, + parseBooleans: false, + ...options, + }; + + validateArrayFormatSeparator(options.arrayFormatSeparator); + + const formatter = parserForArrayFormat(options); + + // Create an object with no prototype + const returnValue = Object.create(null); + + if (typeof query !== 'string') { + return returnValue; + } + + query = query.trim().replace(/^[?#&]/, ''); + + if (!query) { + return returnValue; + } + + for (const parameter of query.split('&')) { + if (parameter === '') { + continue; + } + + let [key, value] = splitOnFirst(options.decode ? parameter.replace(/\+/g, ' ') : parameter, '='); + + // Missing `=` should be `null`: + // http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters + value = value === undefined ? null : (['comma', 'separator', 'bracket-separator'].includes(options.arrayFormat) ? value : decode(value, options)); + formatter(decode(key, options), value, returnValue); + } + + for (const [key, value] of Object.entries(returnValue)) { + if (typeof value === 'object' && value !== null) { + for (const [key2, value2] of Object.entries(value)) { + value[key2] = parseValue(value2, options); + } + } else { + returnValue[key] = parseValue(value, options); + } + } + + if (options.sort === false) { + return returnValue; + } + + // TODO: Remove the use of `reduce`. + // eslint-disable-next-line unicorn/no-array-reduce + return (options.sort === true ? Object.keys(returnValue).sort() : Object.keys(returnValue).sort(options.sort)).reduce((result, key) => { + const value = returnValue[key]; + if (Boolean(value) && typeof value === 'object' && !Array.isArray(value)) { + // Sort object keys, not values + result[key] = keysSorter(value); + } else { + result[key] = value; + } + + return result; + }, Object.create(null)); +} + +export function stringify(object, options) { + if (!object) { + return ''; + } + + options = {encode: true, + strict: true, + arrayFormat: 'none', + arrayFormatSeparator: ',', ...options}; + + validateArrayFormatSeparator(options.arrayFormatSeparator); + + const shouldFilter = key => ( + (options.skipNull && isNullOrUndefined(object[key])) + || (options.skipEmptyString && object[key] === '') + ); + + const formatter = encoderForArrayFormat(options); + + const objectCopy = {}; + + for (const [key, value] of Object.entries(object)) { + if (!shouldFilter(key)) { + objectCopy[key] = value; + } + } + + const keys = Object.keys(objectCopy); + + if (options.sort !== false) { + keys.sort(options.sort); + } + + return keys.map(key => { + const value = object[key]; + + if (value === undefined) { + return ''; + } + + if (value === null) { + return encode(key, options); + } + + if (Array.isArray(value)) { + if (value.length === 0 && options.arrayFormat === 'bracket-separator') { + return encode(key, options) + '[]'; + } + + return value + .reduce(formatter(key), []) + .join('&'); + } + + return encode(key, options) + '=' + encode(value, options); + }).filter(x => x.length > 0).join('&'); +} + +export function parseUrl(url, options) { + options = { + decode: true, + ...options, + }; + + const [url_, hash] = splitOnFirst(url, '#'); + + return { + url: url_?.split('?')?.[0] ?? '', + query: parse(extract(url), options), + ...(options && options.parseFragmentIdentifier && hash ? {fragmentIdentifier: decode(hash, options)} : {}), + }; +} + +export function stringifyUrl(object, options) { + options = { + encode: true, + strict: true, + [encodeFragmentIdentifier]: true, + ...options, + }; + + const url = removeHash(object.url).split('?')[0] || ''; + const queryFromUrl = extract(object.url); + + const query = { + ...parse(queryFromUrl, {sort: false}), + ...object.query, + }; + + let queryString = stringify(query, options); + if (queryString) { + queryString = `?${queryString}`; + } + + let hash = getHash(object.url); + if (object.fragmentIdentifier) { + const urlObjectForFragmentEncode = new URL(url); + urlObjectForFragmentEncode.hash = object.fragmentIdentifier; + hash = options[encodeFragmentIdentifier] ? urlObjectForFragmentEncode.hash : `#${object.fragmentIdentifier}`; + } + + return `${url}${queryString}${hash}`; +} + +export function pick(input, filter, options) { + options = { + parseFragmentIdentifier: true, + [encodeFragmentIdentifier]: false, + ...options, + }; + + const {url, query, fragmentIdentifier} = parseUrl(input, options); + + return stringifyUrl({ + url, + query: includeKeys(query, filter), + fragmentIdentifier, + }, options); +} + +export function exclude(input, filter, options) { + const exclusionFilter = Array.isArray(filter) ? key => !filter.includes(key) : (key, value) => !filter(key, value); + + return pick(input, exclusionFilter, options); +} diff --git a/benchmark.js b/benchmark.js index b152460..0822c68 100644 --- a/benchmark.js +++ b/benchmark.js @@ -1,6 +1,5 @@ -'use strict'; -const Benchmark = require('benchmark'); -const queryString = require('.'); +import Benchmark from 'benchmark'; +import queryString from './index.js'; const {stringify, stringifyUrl} = queryString; const suite = new Benchmark.Suite(); @@ -13,7 +12,7 @@ const TEST_OBJECT = { published: true, symbols: 'πµ', chapters: [1, 2, 3], - none: null + none: null, }; const TEST_HOST = 'https://foo.bar/'; const TEST_STRING = stringify(TEST_OBJECT); diff --git a/index.d.ts b/index.d.ts index 59de603..a99eacb 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,563 +1,11 @@ -export interface ParseOptions { - /** - Decode the keys and values. URI components are decoded with [`decode-uri-component`](https://github.com/SamVerschueren/decode-uri-component). - - @default true - */ - readonly decode?: boolean; - - /** - @default 'none' - - - `bracket`: Parse arrays with bracket representation: - - ``` - import queryString = require('query-string'); - - queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'}); - //=> {foo: ['1', '2', '3']} - ``` - - - `index`: Parse arrays with index representation: - - ``` - import queryString = require('query-string'); - - queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'}); - //=> {foo: ['1', '2', '3']} - ``` - - - `comma`: Parse arrays with elements separated by comma: - - ``` - import queryString = require('query-string'); - - queryString.parse('foo=1,2,3', {arrayFormat: 'comma'}); - //=> {foo: ['1', '2', '3']} - ``` - - - `separator`: Parse arrays with elements separated by a custom character: - - ``` - import queryString = require('query-string'); - - queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: '|'}); - //=> {foo: ['1', '2', '3']} - ``` - - - `bracket-separator`: Parse arrays (that are explicitly marked with brackets) with elements separated by a custom character: - - ``` - import queryString = require('query-string'); - - queryString.parse('foo[]', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> {foo: []} - - queryString.parse('foo[]=', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> {foo: ['']} - - queryString.parse('foo[]=1', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> {foo: ['1']} - - queryString.parse('foo[]=1|2|3', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> {foo: ['1', '2', '3']} - - queryString.parse('foo[]=1||3|||6', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> {foo: ['1', '', 3, '', '', '6']} - - queryString.parse('foo[]=1|2|3&bar=fluffy&baz[]=4', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> {foo: ['1', '2', '3'], bar: 'fluffy', baz:['4']} - ``` - - - `colon-list-separator`: Parse arrays with parameter names that are explicitly marked with `:list`: - - ``` - import queryString = require('query-string'); - - queryString.parse('foo:list=one&foo:list=two', {arrayFormat: 'colon-list-separator'}); - //=> {foo: ['one', 'two']} - ``` - - - `none`: Parse arrays with elements using duplicate keys: - - ``` - import queryString = require('query-string'); - - queryString.parse('foo=1&foo=2&foo=3'); - //=> {foo: ['1', '2', '3']} - ``` - */ - readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'colon-list-separator' | 'none'; - - /** - The character used to separate array elements when using `{arrayFormat: 'separator'}`. - - @default , - */ - readonly arrayFormatSeparator?: string; - - /** - Supports both `Function` as a custom sorting function or `false` to disable sorting. - - If omitted, keys are sorted using `Array#sort`, which means, converting them to strings and comparing strings in Unicode code point order. - - @default true - - @example - ``` - import queryString = require('query-string'); - - const order = ['c', 'a', 'b']; - - queryString.parse('?a=one&b=two&c=three', { - sort: (itemLeft, itemRight) => order.indexOf(itemLeft) - order.indexOf(itemRight) - }); - //=> {c: 'three', a: 'one', b: 'two'} - ``` - - @example - ``` - import queryString = require('query-string'); - - queryString.parse('?a=one&c=three&b=two', {sort: false}); - //=> {a: 'one', c: 'three', b: 'two'} - ``` - */ - readonly sort?: ((itemLeft: string, itemRight: string) => number) | false; - - /** - Parse the value as a number type instead of string type if it's a number. - - @default false - - @example - ``` - import queryString = require('query-string'); - - queryString.parse('foo=1', {parseNumbers: true}); - //=> {foo: 1} - ``` - */ - readonly parseNumbers?: boolean; - - /** - Parse the value as a boolean type instead of string type if it's a boolean. - - @default false - - @example - ``` - import queryString = require('query-string'); - - queryString.parse('foo=true', {parseBooleans: true}); - //=> {foo: true} - ``` - */ - readonly parseBooleans?: boolean; - - /** - Parse the fragment identifier from the URL and add it to result object. - - @default false - - @example - ``` - import queryString = require('query-string'); - - queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true}); - //=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'} - ``` - */ - readonly parseFragmentIdentifier?: boolean; -} - -export interface ParsedQuery { - [key: string]: T | null | Array; -} - -/** -Parse a query string into an object. Leading `?` or `#` are ignored, so you can pass `location.search` or `location.hash` directly. - -The returned object is created with [`Object.create(null)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create) and thus does not have a `prototype`. - -@param query - The query string to parse. -*/ -export function parse(query: string, options: {parseBooleans: true, parseNumbers: true} & ParseOptions): ParsedQuery; -export function parse(query: string, options: {parseBooleans: true} & ParseOptions): ParsedQuery; -export function parse(query: string, options: {parseNumbers: true} & ParseOptions): ParsedQuery; -export function parse(query: string, options?: ParseOptions): ParsedQuery; - -export interface ParsedUrl { - readonly url: string; - readonly query: ParsedQuery; - - /** - The fragment identifier of the URL. - - Present when the `parseFragmentIdentifier` option is `true`. - */ - readonly fragmentIdentifier?: string; -} - -/** -Extract the URL and the query string as an object. - -If the `parseFragmentIdentifier` option is `true`, the object will also contain a `fragmentIdentifier` property. - -@param url - The URL to parse. - -@example -``` -import queryString = require('query-string'); - -queryString.parseUrl('https://foo.bar?foo=bar'); -//=> {url: 'https://foo.bar', query: {foo: 'bar'}} - -queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true}); -//=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'} -``` -*/ -export function parseUrl(url: string, options?: ParseOptions): ParsedUrl; - -export interface StringifyOptions { - /** - Strictly encode URI components with [`strict-uri-encode`](https://github.com/kevva/strict-uri-encode). It uses [`encodeURIComponent`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) if set to `false`. You probably [don't care](https://github.com/sindresorhus/query-string/issues/42) about this option. - - @default true - */ - readonly strict?: boolean; - - /** - [URL encode](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) the keys and values. - - @default true - */ - readonly encode?: boolean; - - /** - @default 'none' - - - `bracket`: Serialize arrays using bracket representation: - - ``` - import queryString = require('query-string'); - - queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'}); - //=> 'foo[]=1&foo[]=2&foo[]=3' - ``` - - - `index`: Serialize arrays using index representation: - - ``` - import queryString = require('query-string'); - - queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'}); - //=> 'foo[0]=1&foo[1]=2&foo[2]=3' - ``` - - - `comma`: Serialize arrays by separating elements with comma: - - ``` - import queryString = require('query-string'); - - queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'}); - //=> 'foo=1,2,3' - - queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'}); - //=> 'foo=1,,' - // Note that typing information for null values is lost - // and `.parse('foo=1,,')` would return `{foo: [1, '', '']}`. - ``` - - - `separator`: Serialize arrays by separating elements with character: - - ``` - import queryString = require('query-string'); - - queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSeparator: '|'}); - //=> 'foo=1|2|3' - ``` - - - `bracket-separator`: Serialize arrays by explicitly post-fixing array names with brackets and separating elements with a custom character: - - ``` - import queryString = require('query-string'); - - queryString.stringify({foo: []}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> 'foo[]' - - queryString.stringify({foo: ['']}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> 'foo[]=' - - queryString.stringify({foo: [1]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> 'foo[]=1' - - queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> 'foo[]=1|2|3' - - queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> 'foo[]=1||3|||6' - - queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|', skipNull: true}); - //=> 'foo[]=1||3|6' - - queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); - //=> 'foo[]=1|2|3&bar=fluffy&baz[]=4' - ``` - - - `colon-list-separator`: Serialize arrays with parameter names that are explicitly marked with `:list`: - - ```js - import queryString = require('query-string'); - - queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator'}); - //=> 'foo:list=one&foo:list=two' - ``` - - - `none`: Serialize arrays by using duplicate keys: - - ``` - import queryString = require('query-string'); - - queryString.stringify({foo: [1, 2, 3]}); - //=> 'foo=1&foo=2&foo=3' - ``` - */ - readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'colon-list-separator' | 'none'; - - /** - The character used to separate array elements when using `{arrayFormat: 'separator'}`. - - @default , - */ - readonly arrayFormatSeparator?: string; - - /** - Supports both `Function` as a custom sorting function or `false` to disable sorting. - - If omitted, keys are sorted using `Array#sort`, which means, converting them to strings and comparing strings in Unicode code point order. - - @default true - - @example - ``` - import queryString = require('query-string'); - - const order = ['c', 'a', 'b']; - - queryString.stringify({a: 1, b: 2, c: 3}, { - sort: (itemLeft, itemRight) => order.indexOf(itemLeft) - order.indexOf(itemRight) - }); - //=> 'c=3&a=1&b=2' - ``` - - @example - ``` - import queryString = require('query-string'); - - queryString.stringify({b: 1, c: 2, a: 3}, {sort: false}); - //=> 'b=1&c=2&a=3' - ``` - */ - readonly sort?: ((itemLeft: string, itemRight: string) => number) | false; - - /** - Skip keys with `null` as the value. - - Note that keys with `undefined` as the value are always skipped. - - @default false - - @example - ``` - import queryString = require('query-string'); - - queryString.stringify({a: 1, b: undefined, c: null, d: 4}, { - skipNull: true - }); - //=> 'a=1&d=4' - - queryString.stringify({a: undefined, b: null}, { - skipNull: true - }); - //=> '' - ``` - */ - readonly skipNull?: boolean; - - /** - Skip keys with an empty string as the value. - - @default false - - @example - ``` - import queryString = require('query-string'); - - queryString.stringify({a: 1, b: '', c: '', d: 4}, { - skipEmptyString: true - }); - //=> 'a=1&d=4' - ``` - - @example - ``` - import queryString = require('query-string'); - - queryString.stringify({a: '', b: ''}, { - skipEmptyString: true - }); - //=> '' - ``` - */ - readonly skipEmptyString?: boolean; -} - -export type Stringifiable = string | boolean | number | null | undefined; - -export type StringifiableRecord = Record< - string, - Stringifiable | readonly Stringifiable[] ->; - -/** -Stringify an object into a query string and sort the keys. -*/ -export function stringify( - // TODO: Use the below instead when the following TS issues are fixed: - // - https://github.com/microsoft/TypeScript/issues/15300 - // - https://github.com/microsoft/TypeScript/issues/42021 - // Context: https://github.com/sindresorhus/query-string/issues/298 - // object: StringifiableRecord, - object: Record, - options?: StringifyOptions -): string; - -/** -Extract a query string from a URL that can be passed into `.parse()`. - -Note: This behaviour can be changed with the `skipNull` option. -*/ -export function extract(url: string): string; - -export interface UrlObject { - readonly url: string; - - /** - Overrides queries in the `url` property. - */ - readonly query?: StringifiableRecord; - - /** - Overrides the fragment identifier in the `url` property. - */ - readonly fragmentIdentifier?: string; -} - -/** -Stringify an object into a URL with a query string and sorting the keys. The inverse of [`.parseUrl()`](https://github.com/sindresorhus/query-string#parseurlstring-options) - -Query items in the `query` property overrides queries in the `url` property. - -The `fragmentIdentifier` property overrides the fragment identifier in the `url` property. - -@example -``` -queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar'}}); -//=> 'https://foo.bar?foo=bar' - -queryString.stringifyUrl({url: 'https://foo.bar?foo=baz', query: {foo: 'bar'}}); -//=> 'https://foo.bar?foo=bar' - -queryString.stringifyUrl({ - url: 'https://foo.bar', - query: { - top: 'foo' - }, - fragmentIdentifier: 'bar' -}); -//=> 'https://foo.bar?top=foo#bar' -``` -*/ -export function stringifyUrl( - object: UrlObject, - options?: StringifyOptions -): string; - -/** -Pick query parameters from a URL. - -@param url - The URL containing the query parameters to pick. -@param keys - The names of the query parameters to keep. All other query parameters will be removed from the URL. -@param filter - A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`. - -@returns The URL with the picked query parameters. - -@example -``` -queryString.pick('https://foo.bar?foo=1&bar=2#hello', ['foo']); -//=> 'https://foo.bar?foo=1#hello' - -queryString.pick('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true}); -//=> 'https://foo.bar?bar=2#hello' -``` -*/ -export function pick( - url: string, - keys: readonly string[], - options?: ParseOptions & StringifyOptions -): string -export function pick( - url: string, - filter: (key: string, value: string | boolean | number) => boolean, - options?: {parseBooleans: true, parseNumbers: true} & ParseOptions & StringifyOptions -): string -export function pick( - url: string, - filter: (key: string, value: string | boolean) => boolean, - options?: {parseBooleans: true} & ParseOptions & StringifyOptions -): string -export function pick( - url: string, - filter: (key: string, value: string | number) => boolean, - options?: {parseNumbers: true} & ParseOptions & StringifyOptions -): string - -/** -Exclude query parameters from a URL. Like `.pick()` but reversed. - -@param url - The URL containing the query parameters to exclude. -@param keys - The names of the query parameters to remove. All other query parameters will remain in the URL. -@param filter - A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`. - -@returns The URL without the excluded the query parameters. - -@example -``` -queryString.exclude('https://foo.bar?foo=1&bar=2#hello', ['foo']); -//=> 'https://foo.bar?bar=2#hello' - -queryString.exclude('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true}); -//=> 'https://foo.bar?foo=1#hello' -``` -*/ -export function exclude( - url: string, - keys: readonly string[], - options?: ParseOptions & StringifyOptions -): string -export function exclude( - url: string, - filter: (key: string, value: string | boolean | number) => boolean, - options?: {parseBooleans: true, parseNumbers: true} & ParseOptions & StringifyOptions -): string -export function exclude( - url: string, - filter: (key: string, value: string | boolean) => boolean, - options?: {parseBooleans: true} & ParseOptions & StringifyOptions -): string -export function exclude( - url: string, - filter: (key: string, value: string | number) => boolean, - options?: {parseNumbers: true} & ParseOptions & StringifyOptions -): string +export * as default from './base.js'; + +export { + type ParseOptions, + type ParsedQuery, + type ParsedUrl, + type StringifyOptions, + type Stringifiable, + type StringifiableRecord, + type UrlObject, +} from './base.js'; diff --git a/index.js b/index.js index 129ea26..36a7b1f 100644 --- a/index.js +++ b/index.js @@ -1,484 +1 @@ -'use strict'; -const strictUriEncode = require('strict-uri-encode'); -const decodeComponent = require('decode-uri-component'); -const splitOnFirst = require('split-on-first'); -const filterObject = require('filter-obj'); - -const isNullOrUndefined = value => value === null || value === undefined; - -const encodeFragmentIdentifier = Symbol('encodeFragmentIdentifier'); - -function encoderForArrayFormat(options) { - switch (options.arrayFormat) { - case 'index': - return key => (result, value) => { - const index = result.length; - - if ( - value === undefined || - (options.skipNull && value === null) || - (options.skipEmptyString && value === '') - ) { - return result; - } - - if (value === null) { - return [...result, [encode(key, options), '[', index, ']'].join('')]; - } - - return [ - ...result, - [encode(key, options), '[', encode(index, options), ']=', encode(value, options)].join('') - ]; - }; - - case 'bracket': - return key => (result, value) => { - if ( - value === undefined || - (options.skipNull && value === null) || - (options.skipEmptyString && value === '') - ) { - return result; - } - - if (value === null) { - return [...result, [encode(key, options), '[]'].join('')]; - } - - return [...result, [encode(key, options), '[]=', encode(value, options)].join('')]; - }; - - case 'colon-list-separator': - return key => (result, value) => { - if ( - value === undefined || - (options.skipNull && value === null) || - (options.skipEmptyString && value === '') - ) { - return result; - } - - if (value === null) { - return [...result, [encode(key, options), ':list='].join('')]; - } - - return [...result, [encode(key, options), ':list=', encode(value, options)].join('')]; - }; - - case 'comma': - case 'separator': - case 'bracket-separator': { - const keyValueSep = options.arrayFormat === 'bracket-separator' ? - '[]=' : - '='; - - return key => (result, value) => { - if ( - value === undefined || - (options.skipNull && value === null) || - (options.skipEmptyString && value === '') - ) { - return result; - } - - // Translate null to an empty string so that it doesn't serialize as 'null' - value = value === null ? '' : value; - - if (result.length === 0) { - return [[encode(key, options), keyValueSep, encode(value, options)].join('')]; - } - - return [[result, encode(value, options)].join(options.arrayFormatSeparator)]; - }; - } - - default: - return key => (result, value) => { - if ( - value === undefined || - (options.skipNull && value === null) || - (options.skipEmptyString && value === '') - ) { - return result; - } - - if (value === null) { - return [...result, encode(key, options)]; - } - - return [...result, [encode(key, options), '=', encode(value, options)].join('')]; - }; - } -} - -function parserForArrayFormat(options) { - let result; - - switch (options.arrayFormat) { - case 'index': - return (key, value, accumulator) => { - result = /\[(\d*)\]$/.exec(key); - - key = key.replace(/\[\d*\]$/, ''); - - if (!result) { - accumulator[key] = value; - return; - } - - if (accumulator[key] === undefined) { - accumulator[key] = {}; - } - - accumulator[key][result[1]] = value; - }; - - case 'bracket': - return (key, value, accumulator) => { - result = /(\[\])$/.exec(key); - key = key.replace(/\[\]$/, ''); - - if (!result) { - accumulator[key] = value; - return; - } - - if (accumulator[key] === undefined) { - accumulator[key] = [value]; - return; - } - - accumulator[key] = [].concat(accumulator[key], value); - }; - - case 'colon-list-separator': - return (key, value, accumulator) => { - result = /(:list)$/.exec(key); - key = key.replace(/:list$/, ''); - - if (!result) { - accumulator[key] = value; - return; - } - - if (accumulator[key] === undefined) { - accumulator[key] = [value]; - return; - } - - accumulator[key] = [].concat(accumulator[key], value); - }; - - case 'comma': - case 'separator': - return (key, value, accumulator) => { - const isArray = typeof value === 'string' && value.includes(options.arrayFormatSeparator); - const isEncodedArray = (typeof value === 'string' && !isArray && decode(value, options).includes(options.arrayFormatSeparator)); - value = isEncodedArray ? decode(value, options) : value; - const newValue = isArray || isEncodedArray ? value.split(options.arrayFormatSeparator).map(item => decode(item, options)) : value === null ? value : decode(value, options); - accumulator[key] = newValue; - }; - - case 'bracket-separator': - return (key, value, accumulator) => { - const isArray = /(\[\])$/.test(key); - key = key.replace(/\[\]$/, ''); - - if (!isArray) { - accumulator[key] = value ? decode(value, options) : value; - return; - } - - const arrayValue = value === null ? - [] : - value.split(options.arrayFormatSeparator).map(item => decode(item, options)); - - if (accumulator[key] === undefined) { - accumulator[key] = arrayValue; - return; - } - - accumulator[key] = [].concat(accumulator[key], arrayValue); - }; - - default: - return (key, value, accumulator) => { - if (accumulator[key] === undefined) { - accumulator[key] = value; - return; - } - - accumulator[key] = [].concat(accumulator[key], value); - }; - } -} - -function validateArrayFormatSeparator(value) { - if (typeof value !== 'string' || value.length !== 1) { - throw new TypeError('arrayFormatSeparator must be single character string'); - } -} - -function encode(value, options) { - if (options.encode) { - return options.strict ? strictUriEncode(value) : encodeURIComponent(value); - } - - return value; -} - -function decode(value, options) { - if (options.decode) { - return decodeComponent(value); - } - - return value; -} - -function keysSorter(input) { - if (Array.isArray(input)) { - return input.sort(); - } - - if (typeof input === 'object') { - return keysSorter(Object.keys(input)) - .sort((a, b) => Number(a) - Number(b)) - .map(key => input[key]); - } - - return input; -} - -function removeHash(input) { - const hashStart = input.indexOf('#'); - if (hashStart !== -1) { - input = input.slice(0, hashStart); - } - - return input; -} - -function getHash(url) { - let hash = ''; - const hashStart = url.indexOf('#'); - if (hashStart !== -1) { - hash = url.slice(hashStart); - } - - return hash; -} - -function extract(input) { - input = removeHash(input); - const queryStart = input.indexOf('?'); - if (queryStart === -1) { - return ''; - } - - return input.slice(queryStart + 1); -} - -function parseValue(value, options) { - if (options.parseNumbers && !Number.isNaN(Number(value)) && (typeof value === 'string' && value.trim() !== '')) { - value = Number(value); - } else if (options.parseBooleans && value !== null && (value.toLowerCase() === 'true' || value.toLowerCase() === 'false')) { - value = value.toLowerCase() === 'true'; - } - - return value; -} - -function parse(query, options) { - options = Object.assign({ - decode: true, - sort: true, - arrayFormat: 'none', - arrayFormatSeparator: ',', - parseNumbers: false, - parseBooleans: false - }, options); - - validateArrayFormatSeparator(options.arrayFormatSeparator); - - const formatter = parserForArrayFormat(options); - - // Create an object with no prototype - const ret = Object.create(null); - - if (typeof query !== 'string') { - return ret; - } - - query = query.trim().replace(/^[?#&]/, ''); - - if (!query) { - return ret; - } - - for (const param of query.split('&')) { - if (param === '') { - continue; - } - - let [key, value] = splitOnFirst(options.decode ? param.replace(/\+/g, ' ') : param, '='); - - // Missing `=` should be `null`: - // http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters - value = value === undefined ? null : ['comma', 'separator', 'bracket-separator'].includes(options.arrayFormat) ? value : decode(value, options); - formatter(decode(key, options), value, ret); - } - - for (const key of Object.keys(ret)) { - const value = ret[key]; - if (typeof value === 'object' && value !== null) { - for (const k of Object.keys(value)) { - value[k] = parseValue(value[k], options); - } - } else { - ret[key] = parseValue(value, options); - } - } - - if (options.sort === false) { - return ret; - } - - return (options.sort === true ? Object.keys(ret).sort() : Object.keys(ret).sort(options.sort)).reduce((result, key) => { - const value = ret[key]; - if (Boolean(value) && typeof value === 'object' && !Array.isArray(value)) { - // Sort object keys, not values - result[key] = keysSorter(value); - } else { - result[key] = value; - } - - return result; - }, Object.create(null)); -} - -exports.extract = extract; -exports.parse = parse; - -exports.stringify = (object, options) => { - if (!object) { - return ''; - } - - options = Object.assign({ - encode: true, - strict: true, - arrayFormat: 'none', - arrayFormatSeparator: ',' - }, options); - - validateArrayFormatSeparator(options.arrayFormatSeparator); - - const shouldFilter = key => ( - (options.skipNull && isNullOrUndefined(object[key])) || - (options.skipEmptyString && object[key] === '') - ); - - const formatter = encoderForArrayFormat(options); - - const objectCopy = {}; - - for (const key of Object.keys(object)) { - if (!shouldFilter(key)) { - objectCopy[key] = object[key]; - } - } - - const keys = Object.keys(objectCopy); - - if (options.sort !== false) { - keys.sort(options.sort); - } - - return keys.map(key => { - const value = object[key]; - - if (value === undefined) { - return ''; - } - - if (value === null) { - return encode(key, options); - } - - if (Array.isArray(value)) { - if (value.length === 0 && options.arrayFormat === 'bracket-separator') { - return encode(key, options) + '[]'; - } - - return value - .reduce(formatter(key), []) - .join('&'); - } - - return encode(key, options) + '=' + encode(value, options); - }).filter(x => x.length > 0).join('&'); -}; - -exports.parseUrl = (url, options) => { - options = Object.assign({ - decode: true - }, options); - - const [url_, hash] = splitOnFirst(url, '#'); - - return Object.assign( - { - url: url_.split('?')[0] || '', - query: parse(extract(url), options) - }, - options && options.parseFragmentIdentifier && hash ? {fragmentIdentifier: decode(hash, options)} : {} - ); -}; - -exports.stringifyUrl = (object, options) => { - options = Object.assign({ - encode: true, - strict: true, - [encodeFragmentIdentifier]: true - }, options); - - const url = removeHash(object.url).split('?')[0] || ''; - const queryFromUrl = exports.extract(object.url); - const parsedQueryFromUrl = exports.parse(queryFromUrl, {sort: false}); - - const query = Object.assign(parsedQueryFromUrl, object.query); - let queryString = exports.stringify(query, options); - if (queryString) { - queryString = `?${queryString}`; - } - - let hash = getHash(object.url); - if (object.fragmentIdentifier) { - const urlObjectForFragmentEncode = new URL(url); - urlObjectForFragmentEncode.hash = object.fragmentIdentifier; - hash = options[encodeFragmentIdentifier] ? urlObjectForFragmentEncode.hash : `#${object.fragmentIdentifier}`; - } - - return `${url}${queryString}${hash}`; -}; - -exports.pick = (input, filter, options) => { - options = Object.assign({ - parseFragmentIdentifier: true, - [encodeFragmentIdentifier]: false - }, options); - - const {url, query, fragmentIdentifier} = exports.parseUrl(input, options); - return exports.stringifyUrl({ - url, - query: filterObject(query, filter), - fragmentIdentifier - }, options); -}; - -exports.exclude = (input, filter, options) => { - const exclusionFilter = Array.isArray(filter) ? key => !filter.includes(key) : (key, value) => !filter(key, value); - - return exports.pick(input, exclusionFilter, options); -}; +export * as default from './base.js'; diff --git a/index.test-d.ts b/index.test-d.ts index 2032584..bcb9702 100644 --- a/index.test-d.ts +++ b/index.test-d.ts @@ -1,5 +1,5 @@ import {expectType} from 'tsd'; -import * as queryString from '.'; +import queryString from './index.js'; // Stringify expectType( @@ -9,14 +9,14 @@ expectType( num: 123, numArray: [456], bool: true, - boolArray: [false] - }) + boolArray: [false], + }), ); expectType(queryString.stringify({foo: 'bar'}, {strict: false})); expectType(queryString.stringify({foo: 'bar'}, {encode: false})); expectType( - queryString.stringify({foo: 'bar'}, {arrayFormat: 'bracket'}) + queryString.stringify({foo: 'bar'}, {arrayFormat: 'bracket'}), ); expectType(queryString.stringify({foo: 'bar'}, {arrayFormat: 'index'})); expectType(queryString.stringify({foo: 'bar'}, {arrayFormat: 'none'})); @@ -30,18 +30,18 @@ expectType( {foo: 'bar'}, { sort: (itemLeft, itemRight) => - order.indexOf(itemLeft) - order.indexOf(itemRight) - } - ) + order.indexOf(itemLeft) - order.indexOf(itemRight), + }, + ), ); // Ensure it accepts an `interface`. -interface Query { +type Query = { foo: string; -} +}; const query: Query = { - foo: 'bar' + foo: 'bar', }; queryString.stringify(query); @@ -50,56 +50,56 @@ queryString.stringify(query); expectType(queryString.parse('?foo=bar')); expectType( - queryString.parse('?foo=bar', {decode: false}) + queryString.parse('?foo=bar', {decode: false}), ); expectType( - queryString.parse('?foo=bar', {arrayFormat: 'bracket'}) + queryString.parse('?foo=bar', {arrayFormat: 'bracket'}), ); expectType( - queryString.parse('?foo=bar', {arrayFormat: 'index'}) + queryString.parse('?foo=bar', {arrayFormat: 'index'}), ); expectType( - queryString.parse('?foo=bar', {arrayFormat: 'none'}) + queryString.parse('?foo=bar', {arrayFormat: 'none'}), ); expectType( - queryString.parse('?foo=bar', {arrayFormat: 'comma'}) + queryString.parse('?foo=bar', {arrayFormat: 'comma'}), ); expectType>( - queryString.parse('?foo=1', {parseNumbers: true}) + queryString.parse('?foo=1', {parseNumbers: true}), ); expectType>( - queryString.parse('?foo=true', {parseBooleans: true}) + queryString.parse('?foo=true', {parseBooleans: true}), ); expectType>( - queryString.parse('?foo=true', {parseBooleans: true, parseNumbers: true}) + queryString.parse('?foo=true', {parseBooleans: true, parseNumbers: true}), ); // Parse URL expectType(queryString.parseUrl('?foo=bar')); expectType( - queryString.parseUrl('?foo=bar', {decode: false}) + queryString.parseUrl('?foo=bar', {decode: false}), ); expectType( - queryString.parseUrl('?foo=bar', {arrayFormat: 'bracket'}) + queryString.parseUrl('?foo=bar', {arrayFormat: 'bracket'}), ); expectType( - queryString.parseUrl('?foo=bar', {arrayFormat: 'index'}) + queryString.parseUrl('?foo=bar', {arrayFormat: 'index'}), ); expectType( - queryString.parseUrl('?foo=bar', {arrayFormat: 'none'}) + queryString.parseUrl('?foo=bar', {arrayFormat: 'none'}), ); expectType( - queryString.parseUrl('?foo=bar', {arrayFormat: 'comma'}) + queryString.parseUrl('?foo=bar', {arrayFormat: 'comma'}), ); expectType( - queryString.parseUrl('?foo=1', {parseNumbers: true}) + queryString.parseUrl('?foo=1', {parseNumbers: true}), ); expectType( - queryString.parseUrl('?foo=true', {parseBooleans: true}) + queryString.parseUrl('?foo=true', {parseBooleans: true}), ); expectType( - queryString.parseUrl('?foo=true#bar', {parseFragmentIdentifier: true}) + queryString.parseUrl('?foo=true#bar', {parseFragmentIdentifier: true}), ); // Extract @@ -114,19 +114,19 @@ expectType( 1, true, null, - undefined + undefined, ], fooNumber: 1, fooBoolean: true, fooNull: null, fooUndefined: undefined, - fooString: 'hi' + fooString: 'hi', }, - }) + }), ); // Pick -expectType(queryString.pick('http://foo.bar/?abc=def&hij=klm', ['abc'])) +expectType(queryString.pick('http://foo.bar/?abc=def&hij=klm', ['abc'])); // Exclude -expectType(queryString.exclude('http://foo.bar/?abc=def&hij=klm', ['abc'])) +expectType(queryString.exclude('http://foo.bar/?abc=def&hij=klm', ['abc'])); diff --git a/license b/license index e464bf7..fa7ceba 100644 --- a/license +++ b/license @@ -1,6 +1,6 @@ MIT License -Copyright (c) Sindre Sorhus (http://sindresorhus.com) +Copyright (c) Sindre Sorhus (https://sindresorhus.com) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: diff --git a/package.json b/package.json index d87d6df..009aa61 100644 --- a/package.json +++ b/package.json @@ -10,8 +10,13 @@ "email": "sindresorhus@gmail.com", "url": "https://sindresorhus.com" }, + "type": "module", + "exports": { + "types": "./index.d.ts", + "default": "./index.js" + }, "engines": { - "node": ">=6" + "node": ">=14.16" }, "scripts": { "benchmark": "node benchmark.js", @@ -19,7 +24,9 @@ }, "files": [ "index.js", - "index.d.ts" + "index.d.ts", + "base.js", + "base.d.ts" ], "keywords": [ "browser", @@ -39,16 +46,20 @@ ], "dependencies": { "decode-uri-component": "^0.2.2", - "filter-obj": "^1.1.0", - "split-on-first": "^1.0.0", - "strict-uri-encode": "^2.0.0" + "filter-obj": "^5.1.0", + "split-on-first": "^1.0.0" }, "devDependencies": { - "ava": "^1.4.1", + "ava": "^5.1.0", "benchmark": "^2.1.4", - "deep-equal": "^1.0.1", - "fast-check": "^1.5.0", - "tsd": "^0.7.3", - "xo": "^0.24.0" + "deep-equal": "^2.1.0", + "fast-check": "^3.4.0", + "tsd": "^0.25.0", + "xo": "^0.53.1" + }, + "tsd": { + "compilerOptions": { + "module": "node16" + } } } diff --git a/readme.md b/readme.md index 5721ca0..85d9a71 100644 --- a/readme.md +++ b/readme.md @@ -31,15 +31,6 @@ It’s 100% JavaScript, fully customizable, and developer-first.
-
- -
- OSS Capital -
-
- Founded in 2018, OSS Capital is the first and only venture capital platform focused
exclusively on supporting early-stage COSS (commercial open source) startup founders.
-
-

@@ -49,18 +40,18 @@ ## Install -``` -$ npm install query-string +```sh +npm install query-string ``` **Not `npm install querystring`!!!!!** -This module targets Node.js 6 or later and the latest version of Chrome, Firefox, and Safari. +For browser usage, this package targets the latest version of Chrome, Firefox, and Safari. ## Usage ```js -const queryString = require('query-string'); +import queryString from 'query-string'; console.log(location.search); //=> '?foo=bar' @@ -115,7 +106,7 @@ Default: `'none'` - `'bracket'`: Parse arrays with bracket representation: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'}); //=> {foo: ['1', '2', '3']} @@ -124,7 +115,7 @@ queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'}); - `'index'`: Parse arrays with index representation: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'}); //=> {foo: ['1', '2', '3']} @@ -133,7 +124,7 @@ queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'}); - `'comma'`: Parse arrays with elements separated by comma: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parse('foo=1,2,3', {arrayFormat: 'comma'}); //=> {foo: ['1', '2', '3']} @@ -142,7 +133,7 @@ queryString.parse('foo=1,2,3', {arrayFormat: 'comma'}); - `'separator'`: Parse arrays with elements separated by a custom character: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: '|'}); //=> {foo: ['1', '2', '3']} @@ -151,7 +142,7 @@ queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: - `'bracket-separator'`: Parse arrays (that are explicitly marked with brackets) with elements separated by a custom character: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parse('foo[]', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> {foo: []} @@ -175,7 +166,7 @@ queryString.parse('foo[]=1|2|3&bar=fluffy&baz[]=4', {arrayFormat: 'bracket-separ - `'colon-list-separator'`: Parse arrays with parameter names that are explicitly marked with `:list`: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parse('foo:list=one&foo:list=two', {arrayFormat: 'colon-list-separator'}); //=> {foo: ['one', 'two']} @@ -184,7 +175,7 @@ queryString.parse('foo:list=one&foo:list=two', {arrayFormat: 'colon-list-separat - `'none'`: Parse arrays with elements using duplicate keys: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parse('foo=1&foo=2&foo=3'); //=> {foo: ['1', '2', '3']} @@ -210,7 +201,7 @@ Type: `boolean`\ Default: `false` ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parse('foo=1', {parseNumbers: true}); //=> {foo: 1} @@ -224,7 +215,7 @@ Type: `boolean`\ Default: `false` ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parse('foo=true', {parseBooleans: true}); //=> {foo: true} @@ -262,7 +253,7 @@ Default: `'none'` - `'bracket'`: Serialize arrays using bracket representation: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'}); //=> 'foo[]=1&foo[]=2&foo[]=3' @@ -271,7 +262,7 @@ queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'}); - `'index'`: Serialize arrays using index representation: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'}); //=> 'foo[0]=1&foo[1]=2&foo[2]=3' @@ -280,7 +271,7 @@ queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'}); - `'comma'`: Serialize arrays by separating elements with comma: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'}); //=> 'foo=1,2,3' @@ -294,7 +285,7 @@ queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'}); - `'separator'`: Serialize arrays by separating elements with a custom character: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSeparator: '|'}); //=> 'foo=1|2|3' @@ -303,7 +294,7 @@ queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSe - `'bracket-separator'`: Serialize arrays by explicitly post-fixing array names with brackets and separating elements with a custom character: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({foo: []}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'}); //=> 'foo[]' @@ -330,7 +321,7 @@ queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: ' - `'colon-list-separator'`: Serialize arrays with parameter names that are explicitly marked with `:list`: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator'}); //=> 'foo:list=one&foo:list=two' @@ -339,7 +330,7 @@ queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator - `'none'`: Serialize arrays by using duplicate keys: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({foo: [1, 2, 3]}); //=> 'foo=1&foo=2&foo=3' @@ -359,7 +350,7 @@ Type: `Function | boolean` Supports both `Function` as a custom sorting function or `false` to disable sorting. ```js -const queryString = require('query-string'); +import queryString from 'query-string'; const order = ['c', 'a', 'b']; @@ -370,7 +361,7 @@ queryString.stringify({a: 1, b: 2, c: 3}, { ``` ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({b: 1, c: 2, a: 3}, {sort: false}); //=> 'b=1&c=2&a=3' @@ -388,7 +379,7 @@ Type: `boolean`\ Default: `false` ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({a: 1, b: undefined, c: null, d: 4}, { skipNull: true @@ -397,7 +388,7 @@ queryString.stringify({a: 1, b: undefined, c: null, d: 4}, { ``` ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({a: undefined, b: null}, { skipNull: true @@ -413,7 +404,7 @@ Type: `boolean`\ Default: `false` ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({a: 1, b: '', c: '', d: 4}, { skipEmptyString: true @@ -422,7 +413,7 @@ queryString.stringify({a: 1, b: '', c: '', d: 4}, { ``` ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({a: '', b: ''}, { skipEmptyString: true @@ -445,7 +436,7 @@ Returns an object with a `url` and `query` property. If the `parseFragmentIdentifier` option is `true`, the object will also contain a `fragmentIdentifier` property. ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parseUrl('https://foo.bar?foo=bar'); //=> {url: 'https://foo.bar', query: {foo: 'bar'}} @@ -470,7 +461,7 @@ Type: `boolean`\ Default: `false` ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true}); //=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'} @@ -529,7 +520,7 @@ Pick query parameters from a URL. Returns a string with the new URL. ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.pick('https://foo.bar?foo=1&bar=2#hello', ['foo']); //=> 'https://foo.bar?foo=1#hello' @@ -546,7 +537,7 @@ Exclude query parameters from a URL. Returns a string with the new URL. ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.exclude('https://foo.bar?foo=1&bar=2#hello', ['foo']); //=> 'https://foo.bar?bar=2#hello' @@ -586,7 +577,7 @@ This module intentionally doesn't support nesting as it's not spec'd and varies You're much better off just converting the object to a JSON string: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({ foo: 'bar', @@ -600,7 +591,7 @@ queryString.stringify({ However, there is support for multiple instances of the same key: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.parse('likes=cake&name=bob&likes=icecream'); //=> {likes: ['cake', 'icecream'], name: 'bob'} @@ -614,7 +605,7 @@ queryString.stringify({color: ['taupe', 'chartreuse'], id: '515'}); Sometimes you want to unset a key, or maybe just make it present without assigning a value to it. Here is how falsy values are stringified: ```js -const queryString = require('query-string'); +import queryString from 'query-string'; queryString.stringify({foo: false}); //=> 'foo=false' @@ -631,9 +622,3 @@ queryString.stringify({foo: undefined}); ### Why is it parsing `+` as a space? See [this answer](https://github.com/sindresorhus/query-string/issues/305). - -## query-string for enterprise - -Available as part of the Tidelift Subscription. - -The maintainers of query-string 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.](https://tidelift.com/subscription/pkg/npm-query-string?utm_source=npm-query-string&utm_medium=referral&utm_campaign=enterprise&utm_term=repo) diff --git a/test/exclude.js b/test/exclude.js index 646db88..d38d8e4 100644 --- a/test/exclude.js +++ b/test/exclude.js @@ -1,5 +1,5 @@ import test from 'ava'; -import queryString from '..'; +import queryString from '../index.js'; test('excludes elements in a URL with a filter array', t => { t.is(queryString.exclude('http://example.com/?a=1&b=2&c=3#a', ['c']), 'http://example.com/?a=1&b=2#a'); @@ -12,7 +12,7 @@ test('excludes elements in a URL with a filter predicate', t => { return name === 'a'; }, { - parseNumbers: true + parseNumbers: true, }), 'http://example.com/?b=2&c=3#a'); }); diff --git a/test/extract.js b/test/extract.js index b7cde18..eaf5e0b 100644 --- a/test/extract.js +++ b/test/extract.js @@ -1,5 +1,5 @@ import test from 'ava'; -import queryString from '..'; +import queryString from '../index.js'; test('extracts query string from url', t => { t.is(queryString.extract('https://foo.bar/?abc=def&hij=klm'), 'abc=def&hij=klm'); @@ -18,9 +18,13 @@ test('handles strings not containing query string', t => { test('throws for invalid values', t => { t.throws(() => { queryString.extract(null); - }, TypeError); + }, { + instanceOf: TypeError, + }); t.throws(() => { queryString.extract(undefined); - }, TypeError); + }, { + instanceOf: TypeError, + }); }); diff --git a/test/parse-url.js b/test/parse-url.js index 720333c..69399b9 100644 --- a/test/parse-url.js +++ b/test/parse-url.js @@ -1,7 +1,8 @@ import test from 'ava'; -import queryString from '..'; +import queryString from '../index.js'; test('handles strings with query string', t => { + console.log('f', queryString.parseUrl('https://foo.bar#top?foo=bar')); t.deepEqual(queryString.parseUrl('https://foo.bar#top?foo=bar'), {url: 'https://foo.bar', query: {}}); t.deepEqual(queryString.parseUrl('https://foo.bar?foo=bar&foo=baz#top'), {url: 'https://foo.bar', query: {foo: ['bar', 'baz']}}); t.deepEqual(queryString.parseUrl('https://foo.bar?foo=bar&foo=baz'), {url: 'https://foo.bar', query: {foo: ['bar', 'baz']}}); @@ -28,9 +29,13 @@ test('handles strings with fragment identifier', t => { test('throws for invalid values', t => { t.throws(() => { queryString.parseUrl(null); - }, TypeError); + }, { + instanceOf: TypeError, + }); t.throws(() => { queryString.parseUrl(undefined); - }, TypeError); + }, { + instanceOf: TypeError, + }); }); diff --git a/test/parse.js b/test/parse.js index 9986efd..e4904e9 100644 --- a/test/parse.js +++ b/test/parse.js @@ -1,5 +1,5 @@ import test from 'ava'; -import queryString from '..'; +import queryString from '../index.js'; test('query strings starting with a `?`', t => { t.deepEqual(queryString.parse('?foo=bar'), {foo: 'bar'}); @@ -25,24 +25,24 @@ test('parse a query string', t => { test('parse multiple query string', t => { t.deepEqual(queryString.parse('foo=bar&key=val'), { foo: 'bar', - key: 'val' + key: 'val', }); }); test('parse multiple query string retain order when not sorted', t => { const expectedKeys = ['b', 'a', 'c']; const parsed = queryString.parse('b=foo&a=bar&c=yay', {sort: false}); - Object.keys(parsed).forEach((key, index) => { + for (const [index, key] of Object.keys(parsed).entries()) { t.is(key, expectedKeys[index]); - }); + } }); test('parse multiple query string sorted keys', t => { const fixture = ['a', 'b', 'c']; const parsed = queryString.parse('a=foo&c=bar&b=yay'); - Object.keys(parsed).forEach((key, index) => { + for (const [index, key] of Object.keys(parsed).entries()) { t.is(key, fixture[index]); - }); + } }); test('should sort parsed keys in given order', t => { @@ -50,20 +50,20 @@ test('should sort parsed keys in given order', t => { const sort = (key1, key2) => fixture.indexOf(key1) - fixture.indexOf(key2); const parsed = queryString.parse('a=foo&b=bar&c=yay', {sort}); - Object.keys(parsed).forEach((key, index) => { + for (const [index, key] of Object.keys(parsed).entries()) { t.is(key, fixture[index]); - }); + } }); test('parse query string without a value', t => { t.deepEqual(queryString.parse('foo'), {foo: null}); t.deepEqual(queryString.parse('foo&key'), { foo: null, - key: null + key: null, }); t.deepEqual(queryString.parse('foo=bar&key'), { foo: 'bar', - key: null + key: null, }); t.deepEqual(queryString.parse('a&a'), {a: [null, null]}); t.deepEqual(queryString.parse('a=&a'), {a: ['', null]}); @@ -143,74 +143,74 @@ test('query string having a bracketed value and a single value and format option test('query strings having brackets arrays and format option as `bracket`', t => { t.deepEqual(queryString.parse('foo[]=bar&foo[]=baz', { - arrayFormat: 'bracket' + arrayFormat: 'bracket', }), {foo: ['bar', 'baz']}); }); test('query strings having comma separated arrays and format option as `comma`', t => { t.deepEqual(queryString.parse('foo=bar,baz', { - arrayFormat: 'comma' + arrayFormat: 'comma', }), {foo: ['bar', 'baz']}); }); test('query strings having pipe separated arrays and format option as `separator`', t => { t.deepEqual(queryString.parse('foo=bar|baz', { arrayFormat: 'separator', - arrayFormatSeparator: '|' + arrayFormatSeparator: '|', }), {foo: ['bar', 'baz']}); }); test('query strings having brackets arrays with null and format option as `bracket`', t => { t.deepEqual(queryString.parse('bar[]&foo[]=a&foo[]&foo[]=', { - arrayFormat: 'bracket' + arrayFormat: 'bracket', }), { foo: ['a', null, ''], - bar: [null] + bar: [null], }); }); test('query strings having comma separated arrays with null and format option as `comma`', t => { t.deepEqual(queryString.parse('bar&foo=a,', { - arrayFormat: 'comma' + arrayFormat: 'comma', }), { foo: ['a', ''], - bar: null + bar: null, }); }); test('query strings having indexed arrays and format option as `index`', t => { t.deepEqual(queryString.parse('foo[0]=bar&foo[1]=baz', { - arrayFormat: 'index' + arrayFormat: 'index', }), {foo: ['bar', 'baz']}); }); test('query strings having brackets+separator arrays and format option as `bracket-separator` with 1 value', t => { t.deepEqual(queryString.parse('foo[]=bar', { - arrayFormat: 'bracket-separator' + arrayFormat: 'bracket-separator', }), {foo: ['bar']}); }); test('query strings having brackets+separator arrays and format option as `bracket-separator` with multiple values', t => { t.deepEqual(queryString.parse('foo[]=bar,baz,,,biz', { - arrayFormat: 'bracket-separator' + arrayFormat: 'bracket-separator', }), {foo: ['bar', 'baz', '', '', 'biz']}); }); test('query strings with multiple brackets+separator arrays and format option as `bracket-separator` using same key name', t => { t.deepEqual(queryString.parse('foo[]=bar,baz&foo[]=biz,boz', { - arrayFormat: 'bracket-separator' + arrayFormat: 'bracket-separator', }), {foo: ['bar', 'baz', 'biz', 'boz']}); }); test('query strings having an empty brackets+separator array and format option as `bracket-separator`', t => { t.deepEqual(queryString.parse('foo[]', { - arrayFormat: 'bracket-separator' + arrayFormat: 'bracket-separator', }), {foo: []}); }); test('query strings having a brackets+separator array and format option as `bracket-separator` with a single empty string', t => { t.deepEqual(queryString.parse('foo[]=', { - arrayFormat: 'bracket-separator' + arrayFormat: 'bracket-separator', }), {foo: ['']}); }); @@ -220,31 +220,31 @@ test('query strings having = within parameters (i.e. GraphQL IDs)', t => { test('query strings having ordered index arrays and format option as `index`', t => { t.deepEqual(queryString.parse('foo[1]=bar&foo[0]=baz&foo[3]=one&foo[2]=two', { - arrayFormat: 'index' + arrayFormat: 'index', }), {foo: ['baz', 'bar', 'two', 'one']}); t.deepEqual(queryString.parse('foo[0]=bar&foo[1]=baz&foo[2]=one&foo[3]=two', { - arrayFormat: 'index' + arrayFormat: 'index', }), {foo: ['bar', 'baz', 'one', 'two']}); t.deepEqual(queryString.parse('foo[3]=three&foo[2]=two&foo[1]=one&foo[0]=zero', { - arrayFormat: 'index' + arrayFormat: 'index', }), {foo: ['zero', 'one', 'two', 'three']}); t.deepEqual(queryString.parse('foo[3]=three&foo[2]=two&foo[1]=one&foo[0]=zero&bat=buz', { - arrayFormat: 'index' + arrayFormat: 'index', }), {foo: ['zero', 'one', 'two', 'three'], bat: 'buz'}); t.deepEqual(queryString.parse('foo[1]=bar&foo[0]=baz', { - arrayFormat: 'index' + arrayFormat: 'index', }), {foo: ['baz', 'bar']}); t.deepEqual(queryString.parse('foo[102]=three&foo[2]=two&foo[1]=one&foo[0]=zero&bat=buz', { - arrayFormat: 'index' + arrayFormat: 'index', }), {bat: 'buz', foo: ['zero', 'one', 'two', 'three']}); t.deepEqual(queryString.parse('foo[102]=three&foo[2]=two&foo[100]=one&foo[0]=zero&bat=buz', { - arrayFormat: 'index' + arrayFormat: 'index', }), {bat: 'buz', foo: ['zero', 'two', 'one', 'three']}); }); @@ -253,7 +253,7 @@ test('circuit parse → stringify', t => { const sortedOriginal = 'bat=buz&foo[0]=&foo[1]=one&foo[2]&foo[3]=foo'; const expected = {bat: 'buz', foo: ['', 'one', null, 'foo']}; const options = { - arrayFormat: 'index' + arrayFormat: 'index', }; t.deepEqual(queryString.parse(original, options), expected); @@ -265,7 +265,7 @@ test('circuit original → parse → stringify → sorted original', t => { const original = 'foo[21474836471]=foo&foo[21474836470]&foo[1]=one&foo[0]=&bat=buz'; const sortedOriginal = 'bat=buz&foo[0]=&foo[1]=one&foo[2]&foo[3]=foo'; const options = { - arrayFormat: 'index' + arrayFormat: 'index', }; t.deepEqual(queryString.stringify(queryString.parse(original, options), options), sortedOriginal); @@ -277,10 +277,10 @@ test('circuit parse → stringify with array commas', t => { const expected = { c: ['', 'a', '', ''], b: '', - a: '' + a: '', }; const options = { - arrayFormat: 'comma' + arrayFormat: 'comma', }; t.deepEqual(queryString.parse(original, options), expected); @@ -292,7 +292,7 @@ test('circuit original → parse → stringify with array commas → sorted orig const original = 'c=,a,,&b=&a='; const sortedOriginal = 'a=&b=&c=,a,,'; const options = { - arrayFormat: 'comma' + arrayFormat: 'comma', }; t.deepEqual(queryString.stringify(queryString.parse(original, options), options), sortedOriginal); @@ -361,11 +361,16 @@ test('parseNumbers and parseBooleans can work with arrayFormat at the same time' }); test('parse throws TypeError for invalid arrayFormatSeparator', t => { - t.throws(_ => queryString.parse('', {arrayFormatSeparator: ',,'}), { - instanceOf: TypeError + t.throws(() => { + queryString.parse('', {arrayFormatSeparator: ',,'}); + }, { + instanceOf: TypeError, }); - t.throws(_ => queryString.parse('', {arrayFormatSeparator: []}), { - instanceOf: TypeError + + t.throws(() => { + queryString.parse('', {arrayFormatSeparator: []}); + }, { + instanceOf: TypeError, }); }); @@ -373,21 +378,21 @@ test('query strings having comma encoded and format option as `comma`', t => { t.deepEqual(queryString.parse('foo=zero%2Cone,two%2Cthree', {arrayFormat: 'comma'}), { foo: [ 'zero,one', - 'two,three' - ] + 'two,three', + ], }); }); test('value should not be decoded twice with `arrayFormat` option set as `separator`', t => { t.deepEqual(queryString.parse('foo=2020-01-01T00:00:00%2B03:00', {arrayFormat: 'separator'}), { - foo: '2020-01-01T00:00:00+03:00' + foo: '2020-01-01T00:00:00+03:00', }); }); // See https://github.com/sindresorhus/query-string/issues/242 test('value separated by encoded comma will not be parsed as array with `arrayFormat` option set to `comma`', t => { t.deepEqual(queryString.parse('id=1%2C2%2C3', {arrayFormat: 'comma', parseNumbers: true}), { - id: [1, 2, 3] + id: [1, 2, 3], }); }); diff --git a/test/pick.js b/test/pick.js index 0bfaf72..41dffa0 100644 --- a/test/pick.js +++ b/test/pick.js @@ -1,5 +1,5 @@ import test from 'ava'; -import queryString from '..'; +import queryString from '../index.js'; test('picks elements in a URL with a filter array', t => { t.is(queryString.pick('http://example.com/?a=1&b=2&c=3#a', ['a', 'b']), 'http://example.com/?a=1&b=2#a'); @@ -12,7 +12,7 @@ test('picks elements in a URL with a filter predicate', t => { return name === 'a'; }, { - parseNumbers: true + parseNumbers: true, }), 'http://example.com/?a=1#a'); }); diff --git a/test/properties.js b/test/properties.js index 6d4ace4..af2b435 100644 --- a/test/properties.js +++ b/test/properties.js @@ -1,7 +1,7 @@ import deepEqual from 'deep-equal'; -import * as fastCheck from 'fast-check'; +import fastCheck from 'fast-check'; import test from 'ava'; -import queryString from '..'; +import queryString from '../index.js'; // Valid query parameters must follow: // - key can be any unicode string (not empty) @@ -9,30 +9,33 @@ import queryString from '..'; // --> any unicode string // --> null // --> array containing values defined above (at least two items) -const queryParamsArbitrary = fastCheck.dictionary( +const queryParametersArbitrary = fastCheck.dictionary( fastCheck.fullUnicodeString(1, 10), fastCheck.oneof( fastCheck.fullUnicodeString(), fastCheck.constant(null), - fastCheck.array(fastCheck.oneof(fastCheck.fullUnicodeString(), fastCheck.constant(null)), 2, 10) - ) + fastCheck.array(fastCheck.oneof(fastCheck.fullUnicodeString(), fastCheck.constant(null)), 2, 10), + ), ); const optionsArbitrary = fastCheck.record({ arrayFormat: fastCheck.constantFrom('bracket', 'index', 'none'), strict: fastCheck.boolean(), encode: fastCheck.constant(true), - sort: fastCheck.constant(false) + sort: fastCheck.constant(false), }, {withDeletedKeys: true}); -test('should read correctly from stringified query params', t => { +test.failing('should read correctly from stringified query parameters', t => { t.notThrows(() => { fastCheck.assert( fastCheck.property( - queryParamsArbitrary, + queryParametersArbitrary, optionsArbitrary, - (object, options) => deepEqual(queryString.parse(queryString.stringify(object, options), options), object) - ) + (object, options) => deepEqual(queryString.parse(queryString.stringify(object, options), options), object), + ), + { + verbose: true, + }, ); }); }); diff --git a/test/stringify-url.js b/test/stringify-url.js index 9b6ff43..5359f3a 100644 --- a/test/stringify-url.js +++ b/test/stringify-url.js @@ -1,39 +1,39 @@ import test from 'ava'; -import queryString from '..'; +import queryString from '../index.js'; test('stringify URL without a query string', t => { - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar/'}), 'https://foo.bar/'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar/', query: {}}), 'https://foo.bar/'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar/#top', query: {}}), 'https://foo.bar/#top'); - t.deepEqual(queryString.stringifyUrl({url: '', query: {}}), ''); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar?', query: {}}), 'https://foo.bar'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar?foo=bar', query: {}}), 'https://foo.bar?foo=bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar/'}), 'https://foo.bar/'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar/', query: {}}), 'https://foo.bar/'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar/#top', query: {}}), 'https://foo.bar/#top'); + t.is(queryString.stringifyUrl({url: '', query: {}}), ''); + t.is(queryString.stringifyUrl({url: 'https://foo.bar?', query: {}}), 'https://foo.bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar?foo=bar', query: {}}), 'https://foo.bar?foo=bar'); }); test('stringify URL with a query string', t => { - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar'}}), 'https://foo.bar?foo=bar'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar?', query: {foo: 'bar'}}), 'https://foo.bar?foo=bar'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar/#top', query: {foo: 'bar'}}), 'https://foo.bar/?foo=bar#top'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar', a: 'b'}}), 'https://foo.bar?a=b&foo=bar'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar?a=b', query: {foo: ['bar', 'baz']}}), 'https://foo.bar?a=b&foo=bar&foo=baz'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar?foo=baz', query: {foo: 'bar'}}), 'https://foo.bar?foo=bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar'}}), 'https://foo.bar?foo=bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar?', query: {foo: 'bar'}}), 'https://foo.bar?foo=bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar/#top', query: {foo: 'bar'}}), 'https://foo.bar/?foo=bar#top'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar', a: 'b'}}), 'https://foo.bar?a=b&foo=bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar?a=b', query: {foo: ['bar', 'baz']}}), 'https://foo.bar?a=b&foo=bar&foo=baz'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar?foo=baz', query: {foo: 'bar'}}), 'https://foo.bar?foo=bar'); }); test('stringify URL with fragment identifier', t => { - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar', query: {top: 'foo'}, fragmentIdentifier: 'bar'}), 'https://foo.bar?top=foo#bar'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: ['bar', 'baz']}, fragmentIdentifier: 'top'}), 'https://foo.bar?foo=bar&foo=baz#top'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar/', query: {}, fragmentIdentifier: 'top'}), 'https://foo.bar/#top'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar/#abc', query: {}, fragmentIdentifier: 'top'}), 'https://foo.bar/#top'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar', query: {}}), 'https://foo.bar'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar', query: {}, fragmentIdentifier: 'foo bar'}), 'https://foo.bar#foo%20bar'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar/', query: {}, fragmentIdentifier: '/foo/bar'}), 'https://foo.bar/#/foo/bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar', query: {top: 'foo'}, fragmentIdentifier: 'bar'}), 'https://foo.bar?top=foo#bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: ['bar', 'baz']}, fragmentIdentifier: 'top'}), 'https://foo.bar?foo=bar&foo=baz#top'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar/', query: {}, fragmentIdentifier: 'top'}), 'https://foo.bar/#top'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar/#abc', query: {}, fragmentIdentifier: 'top'}), 'https://foo.bar/#top'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar', query: {}}), 'https://foo.bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar', query: {}, fragmentIdentifier: 'foo bar'}), 'https://foo.bar#foo%20bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar/', query: {}, fragmentIdentifier: '/foo/bar'}), 'https://foo.bar/#/foo/bar'); }); test('skipEmptyString:: stringify URL with a query string', t => { const config = {skipEmptyString: true}; - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar', baz: ''}}, config), 'https://foo.bar?foo=bar'); - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar', baz: ['', 'qux']}}, config), 'https://foo.bar?baz=qux&foo=bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar', baz: ''}}, config), 'https://foo.bar?foo=bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar', baz: ['', 'qux']}}, config), 'https://foo.bar?baz=qux&foo=bar'); }); test('stringify URL from the result of `parseUrl` without query string', t => { @@ -55,5 +55,5 @@ test('stringify URL from the result of `parseUrl` with query string that contain }); test('stringify URL without sorting existing query params', t => { - t.deepEqual(queryString.stringifyUrl({url: 'https://foo.bar?C=3&A=1', query: {D: 4, B: 2}}, {sort: false}), 'https://foo.bar?C=3&A=1&D=4&B=2'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar?C=3&A=1', query: {D: 4, B: 2}}, {sort: false}), 'https://foo.bar?C=3&A=1&D=4&B=2'); }); diff --git a/test/stringify.js b/test/stringify.js index e3f2a61..d68f097 100644 --- a/test/stringify.js +++ b/test/stringify.js @@ -1,11 +1,11 @@ import test from 'ava'; -import queryString from '..'; +import queryString from '../index.js'; test('stringify', t => { t.is(queryString.stringify({foo: 'bar'}), 'foo=bar'); t.is(queryString.stringify({ foo: 'bar', - bar: 'baz' + bar: 'baz', }), 'bar=baz&foo=bar'); }); @@ -26,28 +26,28 @@ test('no encoding', t => { test('handle array value', t => { t.is(queryString.stringify({ abc: 'abc', - foo: ['bar', 'baz'] + foo: ['bar', 'baz'], }), 'abc=abc&foo=bar&foo=baz'); }); test('array order', t => { t.is(queryString.stringify({ abc: 'abc', - foo: ['baz', 'bar'] + foo: ['baz', 'bar'], }), 'abc=abc&foo=baz&foo=bar'); }); test('handle empty array value', t => { t.is(queryString.stringify({ abc: 'abc', - foo: [] + foo: [], }), 'abc=abc'); }); test('should not encode undefined values', t => { t.is(queryString.stringify({ abc: undefined, - foo: 'baz' + foo: 'baz', }), 'foo=baz'); }); @@ -55,28 +55,28 @@ test('should encode null values as just a key', t => { t.is(queryString.stringify({ 'x y z': null, abc: null, - foo: 'baz' + foo: 'baz', }), 'abc&foo=baz&x%20y%20z'); }); test('handle null values in array', t => { t.is(queryString.stringify({ foo: null, - bar: [null, 'baz'] + bar: [null, 'baz'], }), 'bar&bar=baz&foo'); }); test('handle undefined values in array', t => { t.is(queryString.stringify({ foo: null, - bar: [undefined, 'baz'] + bar: [undefined, 'baz'], }), 'bar=baz&foo'); }); test('handle undefined and null values in array', t => { t.is(queryString.stringify({ foo: null, - bar: [undefined, null, 'baz'] + bar: [undefined, null, 'baz'], }), 'bar&bar=baz&foo'); }); @@ -93,36 +93,36 @@ test('loose encoding', t => { test('array stringify representation with array indexes', t => { t.is(queryString.stringify({ foo: null, - bar: ['one', 'two'] + bar: ['one', 'two'], }, { - arrayFormat: 'index' + arrayFormat: 'index', }), 'bar[0]=one&bar[1]=two&foo'); }); test('array stringify representation with array brackets', t => { t.is(queryString.stringify({ foo: null, - bar: ['one', 'two'] + bar: ['one', 'two'], }, { - arrayFormat: 'bracket' + arrayFormat: 'bracket', }), 'bar[]=one&bar[]=two&foo'); }); test('array stringify representation with array brackets and null value', t => { t.is(queryString.stringify({ foo: ['a', null, ''], - bar: [null] + bar: [null], }, { - arrayFormat: 'bracket' + arrayFormat: 'bracket', }), 'bar[]&foo[]=a&foo[]&foo[]='); }); test('array stringify representation with array commas', t => { t.is(queryString.stringify({ foo: null, - bar: ['one', 'two'] + bar: ['one', 'two'], }, { - arrayFormat: 'comma' + arrayFormat: 'comma', }), 'bar=one,two&foo'); }); @@ -130,9 +130,9 @@ test('array stringify representation with array commas, null & empty string', t t.is(queryString.stringify({ c: [null, 'a', '', null], b: [null], - a: [''] + a: [''], }, { - arrayFormat: 'comma' + arrayFormat: 'comma', }), 'a=&b=&c=,a,,'); }); @@ -140,29 +140,29 @@ test('array stringify representation with array commas, null & empty string (ski t.is(queryString.stringify({ c: [null, 'a', '', null], b: [null], - a: [''] + a: [''], }, { skipNull: true, skipEmptyString: true, - arrayFormat: 'comma' + arrayFormat: 'comma', }), 'c=a'); }); test('array stringify representation with array commas and 0 value', t => { t.is(queryString.stringify({ foo: ['a', null, 0], - bar: [null] + bar: [null], }, { - arrayFormat: 'comma' + arrayFormat: 'comma', }), 'bar=&foo=a,,0'); }); test('array stringify representation with a bad array format', t => { t.is(queryString.stringify({ foo: null, - bar: ['one', 'two'] + bar: ['one', 'two'], }, { - arrayFormat: 'badinput' + arrayFormat: 'badinput', }), 'bar=one&bar=two&foo'); }); @@ -175,65 +175,65 @@ test('array stringify representation with array indexes and sparse array', t => test('array stringify representation with brackets and separators with empty array', t => { t.is(queryString.stringify({ foo: null, - bar: [] + bar: [], }, { - arrayFormat: 'bracket-separator' + arrayFormat: 'bracket-separator', }), 'bar[]&foo'); }); test('array stringify representation with brackets and separators with single value', t => { t.is(queryString.stringify({ foo: null, - bar: ['one'] + bar: ['one'], }, { - arrayFormat: 'bracket-separator' + arrayFormat: 'bracket-separator', }), 'bar[]=one&foo'); }); test('array stringify representation with brackets and separators with multiple values', t => { t.is(queryString.stringify({ foo: null, - bar: ['one', 'two', 'three'] + bar: ['one', 'two', 'three'], }, { - arrayFormat: 'bracket-separator' + arrayFormat: 'bracket-separator', }), 'bar[]=one,two,three&foo'); }); test('array stringify representation with brackets and separators with a single empty string', t => { t.is(queryString.stringify({ foo: null, - bar: [''] + bar: [''], }, { - arrayFormat: 'bracket-separator' + arrayFormat: 'bracket-separator', }), 'bar[]=&foo'); }); test('array stringify representation with brackets and separators with a multiple empty string', t => { t.is(queryString.stringify({ foo: null, - bar: ['', 'two', ''] + bar: ['', 'two', ''], }, { - arrayFormat: 'bracket-separator' + arrayFormat: 'bracket-separator', }), 'bar[]=,two,&foo'); }); test('array stringify representation with brackets and separators with dropped empty strings', t => { t.is(queryString.stringify({ foo: null, - bar: ['', 'two', ''] + bar: ['', 'two', ''], }, { arrayFormat: 'bracket-separator', - skipEmptyString: true + skipEmptyString: true, }), 'bar[]=two&foo'); }); test('array stringify representation with brackets and separators with dropped null values', t => { t.is(queryString.stringify({ foo: null, - bar: ['one', null, 'three', null, '', 'six'] + bar: ['one', null, 'three', null, '', 'six'], }, { arrayFormat: 'bracket-separator', - skipNull: true + skipNull: true, }), 'bar[]=one,three,,six'); }); @@ -257,7 +257,7 @@ test('should not sort when sort is false', t => { ln: 'g', nf: 'h', srs: 'i', - destination: 'g' + destination: 'g', }; t.is(queryString.stringify(fixture, {sort: false}), 'story=a&patch=b&deployment=c&lat=10&lng=20&sb=d&sc=e&mn=f&ln=g&nf=h&srs=i&destination=g'); }); @@ -266,9 +266,9 @@ test('should disable sorting', t => { t.is(queryString.stringify({ c: 'foo', b: 'bar', - a: 'baz' + a: 'baz', }, { - sort: false + sort: false, }), 'c=foo&b=bar&a=baz'); }); @@ -276,9 +276,9 @@ test('should ignore null when skipNull is set', t => { t.is(queryString.stringify({ a: 1, b: null, - c: 3 + c: 3, }, { - skipNull: true + skipNull: true, }), 'a=1&c=3'); }); @@ -286,9 +286,9 @@ test('should ignore emptyString when skipEmptyString is set', t => { t.is(queryString.stringify({ a: 1, b: '', - c: 3 + c: 3, }, { - skipEmptyString: true + skipEmptyString: true, }), 'a=1&c=3'); }); @@ -296,18 +296,18 @@ test('should ignore undefined when skipNull is set', t => { t.is(queryString.stringify({ a: 1, b: undefined, - c: 3 + c: 3, }, { - skipNull: true + skipNull: true, }), 'a=1&c=3'); }); test('should ignore both null and undefined when skipNull is set', t => { t.is(queryString.stringify({ a: undefined, - b: null + b: null, }, { - skipNull: true + skipNull: true, }), ''); }); @@ -315,36 +315,36 @@ test('should ignore both null and undefined when skipNull is set for arrayFormat t.is(queryString.stringify({ a: [undefined, null, 1, undefined, 2, null], b: null, - c: 1 + c: 1, }, { - skipNull: true + skipNull: true, }), 'a=1&a=2&c=1'); t.is(queryString.stringify({ a: [undefined, null, 1, undefined, 2, null], b: null, - c: 1 + c: 1, }, { skipNull: true, - arrayFormat: 'bracket' + arrayFormat: 'bracket', }), 'a[]=1&a[]=2&c=1'); t.is(queryString.stringify({ a: [undefined, null, 1, undefined, 2, null], b: null, - c: 1 + c: 1, }, { skipNull: true, - arrayFormat: 'comma' + arrayFormat: 'comma', }), 'a=1,2&c=1'); t.is(queryString.stringify({ a: [undefined, null, 1, undefined, 2, null], b: null, - c: 1 + c: 1, }, { skipNull: true, - arrayFormat: 'index' + arrayFormat: 'index', }), 'a[0]=1&a[1]=2&c=1'); }); @@ -352,75 +352,75 @@ test('should ignore empty string when skipEmptyString is set for arrayFormat', t t.is(queryString.stringify({ a: ['', 1, '', 2], b: '', - c: 1 + c: 1, }, { - skipEmptyString: true + skipEmptyString: true, }), 'a=1&a=2&c=1'); t.is(queryString.stringify({ a: ['', 1, '', 2], b: '', - c: 1 + c: 1, }, { skipEmptyString: true, - arrayFormat: 'bracket' + arrayFormat: 'bracket', }), 'a[]=1&a[]=2&c=1'); t.is(queryString.stringify({ a: ['', 1, '', 2], b: '', - c: 1 + c: 1, }, { skipEmptyString: true, - arrayFormat: 'comma' + arrayFormat: 'comma', }), 'a=1,2&c=1'); t.is(queryString.stringify({ a: ['', 1, '', 2], b: '', - c: 1 + c: 1, }, { skipEmptyString: true, - arrayFormat: 'index' + arrayFormat: 'index', }), 'a[0]=1&a[1]=2&c=1'); t.is(queryString.stringify({ a: ['', '', '', ''], - c: 1 + c: 1, }, { - skipEmptyString: true + skipEmptyString: true, }), 'c=1'); }); test('stringify throws TypeError for invalid arrayFormatSeparator', t => { t.throws(_ => queryString.stringify({}, {arrayFormatSeparator: ',,'}), { - instanceOf: TypeError + instanceOf: TypeError, }); t.throws(_ => queryString.stringify({}, {arrayFormatSeparator: []}), { - instanceOf: TypeError + instanceOf: TypeError, }); }); test('array stringify representation with (:list) colon-list-separator', t => { t.is(queryString.stringify({ foo: null, - bar: ['one', 'two'] + bar: ['one', 'two'], }, { - arrayFormat: 'colon-list-separator' + arrayFormat: 'colon-list-separator', }), 'bar:list=one&bar:list=two&foo'); }); test('array stringify representation with (:list) colon-list-separator with null values', t => { t.is(queryString.stringify({ foo: null, - bar: ['one', ''] + bar: ['one', ''], }, { - arrayFormat: 'colon-list-separator' + arrayFormat: 'colon-list-separator', }), 'bar:list=one&bar:list=&foo'); t.is(queryString.stringify({ foo: null, - bar: ['one', null] + bar: ['one', null], }, { - arrayFormat: 'colon-list-separator' + arrayFormat: 'colon-list-separator', }), 'bar:list=one&bar:list=&foo'); }); From 5f418d4177da32e4f9e5ca046df98b5338dd5f96 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Mon, 12 Dec 2022 17:48:54 +0100 Subject: [PATCH 29/50] 8.0.0 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 009aa61..87dbb46 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "7.1.3", + "version": "8.0.0", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 76f8fc5990932fe55beab5d27340731081c3c8b4 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Tue, 13 Dec 2022 10:57:58 +0100 Subject: [PATCH 30/50] Fix TypeScript compatibility Fixes #358 --- index.d.ts | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/index.d.ts b/index.d.ts index a99eacb..5385c47 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,4 +1,9 @@ -export * as default from './base.js'; +/// export * as default from './base.js'; + +// Workaround for TS missing feature. +import * as queryString from './base.js'; + +export default queryString; export { type ParseOptions, From 2213ab762541dab35829d929dd2e7dcee3cf3d85 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Tue, 13 Dec 2022 10:58:47 +0100 Subject: [PATCH 31/50] 8.0.1 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 87dbb46..924f816 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "8.0.0", + "version": "8.0.1", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 81f78e62d8e5440e01b82ea9df6fb1a2bebe962a Mon Sep 17 00:00:00 2001 From: Paul Melero Date: Tue, 13 Dec 2022 19:03:23 +0100 Subject: [PATCH 32/50] Use more compatible syntax (#361) --- index.js | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/index.js b/index.js index 36a7b1f..0480a96 100644 --- a/index.js +++ b/index.js @@ -1 +1,3 @@ -export * as default from './base.js'; +import * as queryString from './base.js'; + +export default queryString; From c97b6b2b9883fed28ab9d07416738a63e6e56529 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Tue, 13 Dec 2022 19:04:48 +0100 Subject: [PATCH 33/50] 8.0.2 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 924f816..819d319 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "8.0.1", + "version": "8.0.2", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 7bba5bbc96f8051d19dd3a212337c4ae21eb1c47 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Wed, 14 Dec 2022 12:50:18 +0100 Subject: [PATCH 34/50] Fix typo in a TypeScript type Fixes #362 --- base.d.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/base.d.ts b/base.d.ts index cf3b592..0803e2a 100644 --- a/base.d.ts +++ b/base.d.ts @@ -171,7 +171,8 @@ export type ParseOptions = { readonly parseFragmentIdentifier?: boolean; }; -export type ParsedQuery = Record>; +// eslint-disable-next-line @typescript-eslint/ban-types +export type ParsedQuery = Record>; /** Parse a query string into an object. Leading `?` or `#` are ignored, so you can pass `location.search` or `location.hash` directly. From 2e2fb6eea6606c380be1dc551aeb3500be2aea5f Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Wed, 14 Dec 2022 12:53:16 +0100 Subject: [PATCH 35/50] 8.0.3 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 819d319..fe13a13 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "8.0.2", + "version": "8.0.3", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 20cc109793f799ed576a66e6bf5526e4b37fc450 Mon Sep 17 00:00:00 2001 From: Sam Verschueren Date: Tue, 20 Dec 2022 20:08:12 +0100 Subject: [PATCH 36/50] Upgrade dependencies (#365) --- base.js | 14 ++++++++++++-- package.json | 4 ++-- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/base.js b/base.js index ba41935..0ca95bb 100644 --- a/base.js +++ b/base.js @@ -353,7 +353,13 @@ export function parse(query, options) { continue; } - let [key, value] = splitOnFirst(options.decode ? parameter.replace(/\+/g, ' ') : parameter, '='); + const parameter_ = options.decode ? parameter.replace(/\+/g, ' ') : parameter; + + let [key, value] = splitOnFirst(parameter_, '='); + + if (key === undefined) { + key = parameter_; + } // Missing `=` should be `null`: // http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters @@ -454,7 +460,11 @@ export function parseUrl(url, options) { ...options, }; - const [url_, hash] = splitOnFirst(url, '#'); + let [url_, hash] = splitOnFirst(url, '#'); + + if (url_ === undefined) { + url_ = url; + } return { url: url_?.split('?')?.[0] ?? '', diff --git a/package.json b/package.json index fe13a13..75f21fc 100644 --- a/package.json +++ b/package.json @@ -45,9 +45,9 @@ "filter" ], "dependencies": { - "decode-uri-component": "^0.2.2", + "decode-uri-component": "^0.4.1", "filter-obj": "^5.1.0", - "split-on-first": "^1.0.0" + "split-on-first": "^3.0.0" }, "devDependencies": { "ava": "^5.1.0", From c5c2efc5addf0d05a6269da4ef2cb365dd1b9e2c Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Tue, 20 Dec 2022 20:16:35 +0100 Subject: [PATCH 37/50] 8.1.0 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 75f21fc..910e36c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "8.0.3", + "version": "8.1.0", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 7f844903c8d711a9b8fe0f08b4b7fd9e3cc6761f Mon Sep 17 00:00:00 2001 From: bug-brain <40305896+bug-brain@users.noreply.github.com> Date: Sat, 3 Feb 2024 11:09:45 +0100 Subject: [PATCH 38/50] Allow BigInt as stringifiable value in the types (#377) --- base.d.ts | 2 +- base.js | 8 +------- package.json | 2 +- test/stringify.js | 7 +++++++ 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/base.d.ts b/base.d.ts index 0803e2a..f6bbd9a 100644 --- a/base.d.ts +++ b/base.d.ts @@ -412,7 +412,7 @@ export type StringifyOptions = { readonly skipEmptyString?: boolean; }; -export type Stringifiable = string | boolean | number | null | undefined; // eslint-disable-line @typescript-eslint/ban-types +export type Stringifiable = string | boolean | number | bigint | null | undefined; // eslint-disable-line @typescript-eslint/ban-types export type StringifiableRecord = Record< string, diff --git a/base.js b/base.js index 0ca95bb..d20872c 100644 --- a/base.js +++ b/base.js @@ -385,13 +385,7 @@ export function parse(query, options) { // eslint-disable-next-line unicorn/no-array-reduce return (options.sort === true ? Object.keys(returnValue).sort() : Object.keys(returnValue).sort(options.sort)).reduce((result, key) => { const value = returnValue[key]; - if (Boolean(value) && typeof value === 'object' && !Array.isArray(value)) { - // Sort object keys, not values - result[key] = keysSorter(value); - } else { - result[key] = value; - } - + result[key] = Boolean(value) && typeof value === 'object' && !Array.isArray(value) ? keysSorter(value) : value; return result; }, Object.create(null)); } diff --git a/package.json b/package.json index 910e36c..41dc0e4 100644 --- a/package.json +++ b/package.json @@ -55,7 +55,7 @@ "deep-equal": "^2.1.0", "fast-check": "^3.4.0", "tsd": "^0.25.0", - "xo": "^0.53.1" + "xo": "^0.54.2" }, "tsd": { "compilerOptions": { diff --git a/test/stringify.js b/test/stringify.js index d68f097..0cbdb49 100644 --- a/test/stringify.js +++ b/test/stringify.js @@ -14,6 +14,13 @@ test('different types', t => { t.is(queryString.stringify(0), ''); }); +test('primitive types', t => { + t.is(queryString.stringify({a: 'string'}), 'a=string'); + t.is(queryString.stringify({a: true, b: false}), 'a=true&b=false'); + t.is(queryString.stringify({a: 0, b: 1n}), 'a=0&b=1'); + t.is(queryString.stringify({a: null, b: undefined}), 'a'); +}); + test('URI encode', t => { t.is(queryString.stringify({'foo bar': 'baz faz'}), 'foo%20bar=baz%20faz'); t.is(queryString.stringify({'foo bar': 'baz\'faz'}), 'foo%20bar=baz%27faz'); From 3478c0aa0eb7d0f09efcd82853ff9322919966bd Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Sat, 3 Feb 2024 17:11:13 +0700 Subject: [PATCH 39/50] Meta tweaks --- .github/funding.yml | 4 ---- .github/workflows/main.yml | 4 ++-- base.d.ts | 2 +- package.json | 1 + readme.md | 2 +- 5 files changed, 5 insertions(+), 8 deletions(-) delete mode 100644 .github/funding.yml diff --git a/.github/funding.yml b/.github/funding.yml deleted file mode 100644 index 07c8db1..0000000 --- a/.github/funding.yml +++ /dev/null @@ -1,4 +0,0 @@ -github: sindresorhus -open_collective: sindresorhus -tidelift: npm/query-string -custom: https://sindresorhus.com/donate diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index d50ada6..31f93e9 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -14,8 +14,8 @@ jobs: - 16 - 14 steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} - run: npm install diff --git a/base.d.ts b/base.d.ts index f6bbd9a..4a2a3b0 100644 --- a/base.d.ts +++ b/base.d.ts @@ -220,7 +220,7 @@ export function parseUrl(url: string, options?: ParseOptions): ParsedUrl; export type StringifyOptions = { /** - Strictly encode URI components with [`strict-uri-encode`](https://github.com/kevva/strict-uri-encode). It uses [`encodeURIComponent`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) if set to `false`. You probably [don't care](https://github.com/sindresorhus/query-string/issues/42) about this option. + Strictly encode URI components. It uses [`encodeURIComponent`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) if set to `false`. You probably [don't care](https://github.com/sindresorhus/query-string/issues/42) about this option. @default true */ diff --git a/package.json b/package.json index 41dc0e4..023fe2a 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,7 @@ "types": "./index.d.ts", "default": "./index.js" }, + "sideEffects": false, "engines": { "node": ">=14.16" }, diff --git a/readme.md b/readme.md index 85d9a71..537a7c4 100644 --- a/readme.md +++ b/readme.md @@ -236,7 +236,7 @@ Type: `object` Type: `boolean`\ Default: `true` -Strictly encode URI components with [strict-uri-encode](https://github.com/kevva/strict-uri-encode). It uses [encodeURIComponent](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) if set to false. You probably [don't care](https://github.com/sindresorhus/query-string/issues/42) about this option. +Strictly encode URI components. It uses [encodeURIComponent](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) if set to false. You probably [don't care](https://github.com/sindresorhus/query-string/issues/42) about this option. ##### encode From c918df0147a43766d80a8484d5ef00ef111e8485 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Sat, 3 Feb 2024 17:12:39 +0700 Subject: [PATCH 40/50] 8.2.0 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 023fe2a..69d674e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "8.1.0", + "version": "8.2.0", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 50271f2d471286237701088045e034626b3e44a3 Mon Sep 17 00:00:00 2001 From: rix1 Date: Mon, 12 Feb 2024 16:22:47 +0100 Subject: [PATCH 41/50] Improve readme warning (#379) Co-authored-by: Sindre Sorhus --- readme.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 537a7c4..2bf52a1 100644 --- a/readme.md +++ b/readme.md @@ -44,7 +44,8 @@ npm install query-string ``` -**Not `npm install querystring`!!!!!** +> [!WARNING] +> Remember the hyphen! Do not install the deprecated [`querystring`](https://github.com/Gozala/querystring) package! For browser usage, this package targets the latest version of Chrome, Firefox, and Safari. From cc232cb8cbeb7bebcd8873c832bd7f0f1eeea4df Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Mon, 26 Feb 2024 14:30:05 +0700 Subject: [PATCH 42/50] Fix passing empty `fragmentIdentifier` to `stringifyUrl()` Fixes #380 --- base.js | 2 +- test/stringify-url.js | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/base.js b/base.js index d20872c..493eaa5 100644 --- a/base.js +++ b/base.js @@ -489,7 +489,7 @@ export function stringifyUrl(object, options) { } let hash = getHash(object.url); - if (object.fragmentIdentifier) { + if (typeof object.fragmentIdentifier === 'string') { const urlObjectForFragmentEncode = new URL(url); urlObjectForFragmentEncode.hash = object.fragmentIdentifier; hash = options[encodeFragmentIdentifier] ? urlObjectForFragmentEncode.hash : `#${object.fragmentIdentifier}`; diff --git a/test/stringify-url.js b/test/stringify-url.js index 5359f3a..706a272 100644 --- a/test/stringify-url.js +++ b/test/stringify-url.js @@ -27,6 +27,7 @@ test('stringify URL with fragment identifier', t => { t.is(queryString.stringifyUrl({url: 'https://foo.bar', query: {}}), 'https://foo.bar'); t.is(queryString.stringifyUrl({url: 'https://foo.bar', query: {}, fragmentIdentifier: 'foo bar'}), 'https://foo.bar#foo%20bar'); t.is(queryString.stringifyUrl({url: 'https://foo.bar/', query: {}, fragmentIdentifier: '/foo/bar'}), 'https://foo.bar/#/foo/bar'); + t.is(queryString.stringifyUrl({url: 'https://foo.bar/#foo', query: {}, fragmentIdentifier: ''}), 'https://foo.bar/'); }); test('skipEmptyString:: stringify URL with a query string', t => { From fd5a1c91b1bd33a9c13804f973cc37965cf5ecbd Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Mon, 26 Feb 2024 14:32:31 +0700 Subject: [PATCH 43/50] Require Node.js 18 --- .github/workflows/main.yml | 3 +-- base.js | 19 ++++++++++--------- benchmark.js | 4 ++-- package.json | 12 ++++++------ test/parse-url.js | 1 - 5 files changed, 19 insertions(+), 20 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 31f93e9..346585c 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -10,9 +10,8 @@ jobs: fail-fast: false matrix: node-version: + - 20 - 18 - - 16 - - 14 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 diff --git a/base.js b/base.js index 493eaa5..dc3f742 100644 --- a/base.js +++ b/base.js @@ -5,7 +5,7 @@ import {includeKeys} from 'filter-obj'; const isNullOrUndefined = value => value === null || value === undefined; // eslint-disable-next-line unicorn/prefer-code-point -const strictUriEncode = string => encodeURIComponent(string).replace(/[!'()*]/g, x => `%${x.charCodeAt(0).toString(16).toUpperCase()}`); +const strictUriEncode = string => encodeURIComponent(string).replaceAll(/[!'()*]/g, x => `%${x.charCodeAt(0).toString(16).toUpperCase()}`); const encodeFragmentIdentifier = Symbol('encodeFragmentIdentifier'); @@ -87,7 +87,7 @@ function encoderForArrayFormat(options) { case 'comma': case 'separator': case 'bracket-separator': { - const keyValueSep = options.arrayFormat === 'bracket-separator' + const keyValueSeparator = options.arrayFormat === 'bracket-separator' ? '[]=' : '='; @@ -104,7 +104,7 @@ function encoderForArrayFormat(options) { value = value === null ? '' : value; if (result.length === 0) { - return [[encode(key, options), keyValueSep, encode(value, options)].join('')]; + return [[encode(key, options), keyValueSeparator, encode(value, options)].join('')]; } return [[result, encode(value, options)].join(options.arrayFormatSeparator)]; @@ -353,7 +353,7 @@ export function parse(query, options) { continue; } - const parameter_ = options.decode ? parameter.replace(/\+/g, ' ') : parameter; + const parameter_ = options.decode ? parameter.replaceAll('+', ' ') : parameter; let [key, value] = splitOnFirst(parameter_, '='); @@ -395,10 +395,13 @@ export function stringify(object, options) { return ''; } - options = {encode: true, + options = { + encode: true, strict: true, arrayFormat: 'none', - arrayFormatSeparator: ',', ...options}; + arrayFormatSeparator: ',', + ...options, + }; validateArrayFormatSeparator(options.arrayFormatSeparator); @@ -484,9 +487,7 @@ export function stringifyUrl(object, options) { }; let queryString = stringify(query, options); - if (queryString) { - queryString = `?${queryString}`; - } + queryString &&= `?${queryString}`; let hash = getHash(object.url); if (typeof object.fragmentIdentifier === 'string') { diff --git a/benchmark.js b/benchmark.js index 0822c68..674e6ef 100644 --- a/benchmark.js +++ b/benchmark.js @@ -24,10 +24,10 @@ const TEST_URL = stringifyUrl({url: TEST_HOST, query: TEST_OBJECT}); // Creates a test case and adds it to the suite const defineTestCase = (methodName, input, options) => { - const fn = queryString[methodName]; + const function_ = queryString[methodName]; const label = options ? ` (${stringify(options)})` : ''; - suite.add(methodName + label, () => fn(input, options || {})); + suite.add(methodName + label, () => function_(input, options || {})); }; // Define all test cases diff --git a/package.json b/package.json index 69d674e..fa849ae 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,7 @@ }, "sideEffects": false, "engines": { - "node": ">=14.16" + "node": ">=18" }, "scripts": { "benchmark": "node benchmark.js", @@ -51,12 +51,12 @@ "split-on-first": "^3.0.0" }, "devDependencies": { - "ava": "^5.1.0", + "ava": "^6.1.1", "benchmark": "^2.1.4", - "deep-equal": "^2.1.0", - "fast-check": "^3.4.0", - "tsd": "^0.25.0", - "xo": "^0.54.2" + "deep-equal": "^2.2.3", + "fast-check": "^3.15.1", + "tsd": "^0.30.7", + "xo": "^0.57.0" }, "tsd": { "compilerOptions": { diff --git a/test/parse-url.js b/test/parse-url.js index 69399b9..a6c0848 100644 --- a/test/parse-url.js +++ b/test/parse-url.js @@ -2,7 +2,6 @@ import test from 'ava'; import queryString from '../index.js'; test('handles strings with query string', t => { - console.log('f', queryString.parseUrl('https://foo.bar#top?foo=bar')); t.deepEqual(queryString.parseUrl('https://foo.bar#top?foo=bar'), {url: 'https://foo.bar', query: {}}); t.deepEqual(queryString.parseUrl('https://foo.bar?foo=bar&foo=baz#top'), {url: 'https://foo.bar', query: {foo: ['bar', 'baz']}}); t.deepEqual(queryString.parseUrl('https://foo.bar?foo=bar&foo=baz'), {url: 'https://foo.bar', query: {foo: ['bar', 'baz']}}); From f4b59832c678cfabcd8b356709d96b616c1e19eb Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Mon, 26 Feb 2024 14:38:55 +0700 Subject: [PATCH 44/50] 9.0.0 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index fa849ae..287fd10 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "8.2.0", + "version": "9.0.0", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 3d8fbf2328220c06e45f166cdf58e70617c7ee68 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Thu, 29 Feb 2024 00:52:20 +0700 Subject: [PATCH 45/50] Add tests for #381 Closes #381 --- test/parse-url.js | 1 + test/parse.js | 1 + 2 files changed, 2 insertions(+) diff --git a/test/parse-url.js b/test/parse-url.js index a6c0848..35f8ae4 100644 --- a/test/parse-url.js +++ b/test/parse-url.js @@ -5,6 +5,7 @@ test('handles strings with query string', t => { t.deepEqual(queryString.parseUrl('https://foo.bar#top?foo=bar'), {url: 'https://foo.bar', query: {}}); t.deepEqual(queryString.parseUrl('https://foo.bar?foo=bar&foo=baz#top'), {url: 'https://foo.bar', query: {foo: ['bar', 'baz']}}); t.deepEqual(queryString.parseUrl('https://foo.bar?foo=bar&foo=baz'), {url: 'https://foo.bar', query: {foo: ['bar', 'baz']}}); + t.deepEqual(queryString.parseUrl('https://foo.bar?foo=null'), {url: 'https://foo.bar', query: {foo: 'null'}}); }); test('handles strings not containing query string', t => { diff --git a/test/parse.js b/test/parse.js index e4904e9..17de629 100644 --- a/test/parse.js +++ b/test/parse.js @@ -20,6 +20,7 @@ test('query strings ending with a `&`', t => { test('parse a query string', t => { t.deepEqual(queryString.parse('foo=bar'), {foo: 'bar'}); + t.deepEqual(queryString.parse('foo=null'), {foo: 'null'}); }); test('parse multiple query string', t => { From 672eb8263294ee9eea5a3f7305e15c036e5495b8 Mon Sep 17 00:00:00 2001 From: ScottEnock Date: Mon, 22 Jul 2024 13:24:31 +0100 Subject: [PATCH 46/50] Add `types` option to the `.parse()` method (#385) Co-authored-by: Sindre Sorhus --- base.d.ts | 111 ++++++++++++++++++++++++++++++++++++++++++- base.js | 34 ++++++++++---- readme.md | 108 ++++++++++++++++++++++++++++++++++++++++++ test/parse.js | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 371 insertions(+), 9 deletions(-) diff --git a/base.d.ts b/base.d.ts index 4a2a3b0..6bedc6d 100644 --- a/base.d.ts +++ b/base.d.ts @@ -87,7 +87,14 @@ export type ParseOptions = { //=> {foo: ['1', '2', '3']} ``` */ - readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'colon-list-separator' | 'none'; + readonly arrayFormat?: + | 'bracket' + | 'index' + | 'comma' + | 'separator' + | 'bracket-separator' + | 'colon-list-separator' + | 'none'; /** The character used to separate array elements when using `{arrayFormat: 'separator'}`. @@ -169,6 +176,108 @@ export type ParseOptions = { ``` */ readonly parseFragmentIdentifier?: boolean; + + /** + Specify a pre-defined schema to be used when parsing values. The types specified will take precedence over options such as: `parseNumber`, `parseBooleans`, and `arrayFormat`. + + Use this feature to override the type of a value. This can be useful when the type is ambiguous such as a phone number (see example 1 and 2). + + It is possible to provide a custom function as the parameter type. The parameter's value will equal the function's return value (see example 4). + + NOTE: Array types (`string[]` and `number[]`) will have no effect if `arrayFormat` is set to `none` (see example 5). + + @default {} + + @example + Parse `phoneNumber` as a string, overriding the `parseNumber` option: + ``` + import queryString from 'query-string'; + + queryString.parse('?phoneNumber=%2B380951234567&id=1', { + parseNumbers: true, + types: { + phoneNumber: 'string', + } + }); + //=> {phoneNumber: '+380951234567', id: 1} + ``` + + @example + Parse `items` as an array of strings, overriding the `parseNumber` option: + ``` + import queryString from 'query-string'; + + queryString.parse('?age=20&items=1%2C2%2C3', { + parseNumber: true, + types: { + items: 'string[]', + } + }); + //=> {age: 20, items: ['1', '2', '3']} + ``` + + @example + Parse `age` as a number, even when `parseNumber` is false: + ``` + import queryString from 'query-string'; + + queryString.parse('?age=20&id=01234&zipcode=90210', { + types: { + age: 'number', + } + }); + //=> {age: 20, id: '01234', zipcode: '90210 } + ``` + + @example + Parse `age` using a custom value parser: + ``` + import queryString from 'query-string'; + + queryString.parse('?age=20&id=01234&zipcode=90210', { + types: { + age: (value) => value * 2, + } + }); + //=> {age: 40, id: '01234', zipcode: '90210 } + ``` + + @example + Array types will have no effect when `arrayFormat` is set to `none` + ``` + queryString.parse('ids=001%2C002%2C003&foods=apple%2Corange%2Cmango', { + arrayFormat: 'none', + types: { + ids: 'number[]', + foods: 'string[]', + }, + } + //=> {ids:'001,002,003', foods:'apple,orange,mango'} + ``` + + @example + Parse a query utilizing all types: + ``` + import queryString from 'query-string'; + + queryString.parse('?ids=001%2C002%2C003&items=1%2C2%2C3&price=22%2E00&numbers=1%2C2%2C3&double=5&number=20', { + arrayFormat: 'comma', + types: { + ids: 'string', + items: 'string[]', + price: 'string', + numbers: 'number[]', + double: (value) => value * 2, + number: 'number', + }, + }); + //=> {ids: '001,002,003', items: ['1', '2', '3'], price: '22.00', numbers: [1, 2, 3], double: 10, number: 20} + ``` + */ + readonly types?: Record< + string, + 'number' | 'string' | 'string[]' | 'number[]' | ((value: string) => unknown) + >; }; // eslint-disable-next-line @typescript-eslint/ban-types diff --git a/base.js b/base.js index dc3f742..ccbdb6e 100644 --- a/base.js +++ b/base.js @@ -1,6 +1,6 @@ import decodeComponent from 'decode-uri-component'; -import splitOnFirst from 'split-on-first'; import {includeKeys} from 'filter-obj'; +import splitOnFirst from 'split-on-first'; const isNullOrUndefined = value => value === null || value === undefined; @@ -300,11 +300,25 @@ function getHash(url) { return hash; } -function parseValue(value, options) { +function parseValue(value, options, type) { + if (type === 'string' && typeof value === 'string') { + return value; + } + + if (typeof type === 'function' && typeof value === 'string') { + return type(value); + } + + if (options.parseBooleans && value !== null && (value.toLowerCase() === 'true' || value.toLowerCase() === 'false')) { + return value.toLowerCase() === 'true'; + } + + if (type === 'number' && !Number.isNaN(Number(value)) && (typeof value === 'string' && value.trim() !== '')) { + return Number(value); + } + if (options.parseNumbers && !Number.isNaN(Number(value)) && (typeof value === 'string' && value.trim() !== '')) { - value = Number(value); - } else if (options.parseBooleans && value !== null && (value.toLowerCase() === 'true' || value.toLowerCase() === 'false')) { - value = value.toLowerCase() === 'true'; + return Number(value); } return value; @@ -328,6 +342,7 @@ export function parse(query, options) { arrayFormatSeparator: ',', parseNumbers: false, parseBooleans: false, + types: Object.create(null), ...options, }; @@ -368,12 +383,15 @@ export function parse(query, options) { } for (const [key, value] of Object.entries(returnValue)) { - if (typeof value === 'object' && value !== null) { + if (typeof value === 'object' && value !== null && options.types[key] !== 'string') { for (const [key2, value2] of Object.entries(value)) { - value[key2] = parseValue(value2, options); + const type = options.types[key] ? options.types[key].replace('[]', '') : undefined; + value[key2] = parseValue(value2, options, type); } + } else if (typeof value === 'object' && value !== null && options.types[key] === 'string') { + returnValue[key] = Object.values(value).join(options.arrayFormatSeparator); } else { - returnValue[key] = parseValue(value, options); + returnValue[key] = parseValue(value, options, options.types[key]); } } diff --git a/readme.md b/readme.md index 2bf52a1..111f980 100644 --- a/readme.md +++ b/readme.md @@ -224,6 +224,114 @@ queryString.parse('foo=true', {parseBooleans: true}); Parse the value as a boolean type instead of string type if it's a boolean. +##### types + +Type: `object`\ +Default: `{}` + +Specify a pre-defined schema to be used when parsing values. The types specified will take precedence over options such as: `parseNumber`, `parseBooleans`, and `arrayFormat`. + +Use this feature to override the type of a value. This can be useful when the type is ambiguous such as a phone number. + +It is possible to provide a custom function as the parameter type. The parameter's value will equal the function's return value. + +Supported Types: + +- `'string'`: Parse `phoneNumber` as a string (overriding the `parseNumber` option): + +```js +import queryString from 'query-string'; + +queryString.parse('?phoneNumber=%2B380951234567&id=1', { + parseNumbers: true, + types: { + phoneNumber: 'string', + } +}); +//=> {phoneNumber: '+380951234567', id: 1} +``` + +- `'number'`: Parse `age` as a number (even when `parseNumber` is false): + +```js +import queryString from 'query-string'; + +queryString.parse('?age=20&id=01234&zipcode=90210', { + types: { + age: 'number', + } +}); +//=> {age: 20, id: '01234', zipcode: '90210 } +``` + +- `'string[]'`: Parse `items` as an array of strings (overriding the `parseNumber` option): + +```js +import queryString from 'query-string'; + +queryString.parse('?age=20&items=1%2C2%2C3', { + parseNumber: true, + types: { + items: 'string[]', + } +}); +//=> {age: 20, items: ['1', '2', '3']} +``` + +- `'number[]'`: Parse `items` as an array of numbers (even when `parseNumber` is false): + +```js +import queryString from 'query-string'; + +queryString.parse('?age=20&items=1%2C2%2C3', { + types: { + items: 'number[]', + } +}); +//=> {age: '20', items: [1, 2, 3]} +``` + +- `'Function'`: Provide a custom function as the parameter type. The parameter's value will equal the function's return value. + +```js +import queryString from 'query-string'; + +queryString.parse('?age=20&id=01234&zipcode=90210', { + types: { + age: (value) => value * 2, + } +}); +//=> {age: 40, id: '01234', zipcode: '90210 } +``` + +NOTE: Array types (`string[]` and `number[]`) will have no effect if `arrayFormat` is set to `none`. + +```js +queryString.parse('ids=001%2C002%2C003&foods=apple%2Corange%2Cmango', { + arrayFormat: 'none', + types: { + ids: 'number[]', + foods: 'string[]', + }, +} +//=> {ids:'001,002,003', foods:'apple,orange,mango'} +``` + +###### Function + +```js +import queryString from 'query-string'; + +queryString.parse('?age=20&id=01234&zipcode=90210', { + types: { + age: (value) => value * 2, + } +}); +//=> {age: 40, id: '01234', zipcode: '90210 } +``` + +Parse the value as a boolean type instead of string type if it's a boolean. + ### .stringify(object, options?) Stringify an object into a query string and sorting the keys. diff --git a/test/parse.js b/test/parse.js index 17de629..3409255 100644 --- a/test/parse.js +++ b/test/parse.js @@ -404,3 +404,130 @@ test('query strings having (:list) colon-list-separator arrays', t => { test('query strings having (:list) colon-list-separator arrays including null values', t => { t.deepEqual(queryString.parse('bar:list=one&bar:list=two&foo', {arrayFormat: 'colon-list-separator'}), {bar: ['one', 'two'], foo: null}); }); + +test('types option: can override a parsed number to be a string ', t => { + t.deepEqual(queryString.parse('phoneNumber=%2B380951234567', { + parseNumbers: true, + types: { + phoneNumber: 'string', + }, + }), {phoneNumber: '+380951234567'}); +}); + +test('types option: can override a parsed boolean value to be a string', t => { + t.deepEqual(queryString.parse('question=true', { + parseBooleans: true, + types: { + question: 'string', + }, + }), { + question: 'true', + }); +}); + +test('types option: can override parsed numbers arrays to be string[]', t => { + t.deepEqual(queryString.parse('ids=999%2C998%2C997&items=1%2C2%2C3', { + arrayFormat: 'comma', + parseNumbers: true, + types: { + ids: 'string[]', + }, + }), { + ids: ['999', '998', '997'], + items: [1, 2, 3], + }); +}); + +test('types option: can override string arrays to be number[]', t => { + t.deepEqual(queryString.parse('ids=001%2C002%2C003&items=1%2C2%2C3', { + arrayFormat: 'comma', + types: { + ids: 'number[]', + }, + }), { + ids: [1, 2, 3], + items: ['1', '2', '3'], + }); +}); + +test('types option: can override an array to be string', t => { + t.deepEqual(queryString.parse('ids=001%2C002%2C003&items=1%2C2%2C3', { + arrayFormat: 'comma', + parseNumbers: true, + types: { + ids: 'string', + }, + }), { + ids: '001,002,003', + items: [1, 2, 3], + }); +}); + +test('types option: can override a separator array to be string ', t => { + t.deepEqual(queryString.parse('ids=001|002|003&items=1|2|3', { + arrayFormat: 'separator', + arrayFormatSeparator: '|', + parseNumbers: true, + types: { + ids: 'string', + }, + }), { + ids: '001|002|003', + items: [1, 2, 3], + }); +}); + +test('types option: when value is not of specified type, it will safely parse the value as string', t => { + t.deepEqual(queryString.parse('id=example', { + types: { + id: 'number', + }, + }), { + id: 'example', + }); +}); + +test('types option: array types will have no effect if arrayFormat is set to "none"', t => { + t.deepEqual(queryString.parse('ids=001%2C002%2C003&foods=apple%2Corange%2Cmango', { + arrayFormat: 'none', + types: { + ids: 'number[]', + foods: 'string[]', + }, + }), { + ids: '001,002,003', + foods: 'apple,orange,mango', + }); +}); + +test('types option: will parse the value as number if specified in type but parseNumbers is false', t => { + t.deepEqual(queryString.parse('id=123', { + arrayFormat: 'comma', + types: { + id: 'number', + }, + }), { + id: 123, + }); +}); + +test('types option: all supported types work in conjunction with one another', t => { + t.deepEqual(queryString.parse('ids=001%2C002%2C003&items=1%2C2%2C3&price=22%2E00&numbers=1%2C2%2C3&double=5&number=20', { + arrayFormat: 'comma', + types: { + ids: 'string', + items: 'string[]', + price: 'string', + numbers: 'number[]', + double: value => value * 2, + number: 'number', + }, + }), { + ids: '001,002,003', + items: ['1', '2', '3'], + price: '22.00', + numbers: [1, 2, 3], + double: 10, + number: 20, + }); +}); From f38e98288e41e40ab72719123f751e7b345f0024 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Mon, 22 Jul 2024 14:26:05 +0200 Subject: [PATCH 47/50] 9.1.0 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 287fd10..c172a09 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "9.0.0", + "version": "9.1.0", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string", From 4287e770ed3e6133217a86ac4ed3cee24cde0622 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Wed, 7 Aug 2024 23:47:11 +0200 Subject: [PATCH 48/50] Meta tweaks --- readme.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/readme.md b/readme.md index 111f980..a53dfde 100644 --- a/readme.md +++ b/readme.md @@ -19,18 +19,6 @@ -
-
-
- -
- Strapi -
- Strapi is the leading open-source headless CMS. -
- It’s 100% JavaScript, fully customizable, and developer-first. -
-

From 19c43d4e19ed5f362ee22644b0cced6cabb4dda8 Mon Sep 17 00:00:00 2001 From: scottenock Date: Wed, 9 Oct 2024 07:19:14 +0100 Subject: [PATCH 49/50] Fix `arrayFormat` `bracket-separator` with a URL encoded value (#392) --- base.js | 2 +- test/parse.js | 35 +++++++++++++++++++++++++---------- 2 files changed, 26 insertions(+), 11 deletions(-) diff --git a/base.js b/base.js index ccbdb6e..ad9e7b1 100644 --- a/base.js +++ b/base.js @@ -221,7 +221,7 @@ function parserForArrayFormat(options) { const arrayValue = value === null ? [] - : value.split(options.arrayFormatSeparator).map(item => decode(item, options)); + : decode(value, options).split(options.arrayFormatSeparator); if (accumulator[key] === undefined) { accumulator[key] = arrayValue; diff --git a/test/parse.js b/test/parse.js index 3409255..6e2261a 100644 --- a/test/parse.js +++ b/test/parse.js @@ -110,7 +110,8 @@ test('handle multiple values and preserve appearance order with indexes', t => { }); test('query strings params including embedded `=`', t => { - t.deepEqual(queryString.parse('?param=https%3A%2F%2Fsomeurl%3Fid%3D2837'), {param: 'https://someurl?id=2837'}); + const value = 'https://someurl?id=2837'; + t.deepEqual(queryString.parse(`param=${encodeURIComponent(value)}`), {param: 'https://someurl?id=2837'}); }); test('object properties', t => { @@ -215,6 +216,16 @@ test('query strings having a brackets+separator array and format option as `brac }), {foo: ['']}); }); +test('query strings having a brackets+separator array and format option as `bracket-separator` with a URL encoded value', t => { + const key = 'foo[]'; + const value = 'a,b,c,d,e,f'; + t.deepEqual(queryString.parse(`?${encodeURIComponent(key)}=${encodeURIComponent(value)}`, { + arrayFormat: 'bracket-separator', + }), { + foo: ['a', 'b', 'c', 'd', 'e', 'f'], + }); +}); + test('query strings having = within parameters (i.e. GraphQL IDs)', t => { t.deepEqual(queryString.parse('foo=bar=&foo=ba=z='), {foo: ['bar=', 'ba=z=']}); }); @@ -305,7 +316,8 @@ test('decode keys and values', t => { }); test('disable decoding of keys and values', t => { - t.deepEqual(queryString.parse('tags=postal%20office,burger%2C%20fries%20and%20coke', {decode: false}), {tags: 'postal%20office,burger%2C%20fries%20and%20coke'}); + const value = 'postal office,burger, fries and coke'; + t.deepEqual(queryString.parse(`tags=${encodeURIComponent(value)}`, {decode: false}), {tags: 'postal%20office%2Cburger%2C%20fries%20and%20coke'}); }); test('number value returns as string by default', t => { @@ -376,7 +388,8 @@ test('parse throws TypeError for invalid arrayFormatSeparator', t => { }); test('query strings having comma encoded and format option as `comma`', t => { - t.deepEqual(queryString.parse('foo=zero%2Cone,two%2Cthree', {arrayFormat: 'comma'}), { + const values = ['zero,one', 'two,three']; + t.deepEqual(queryString.parse(`foo=${encodeURIComponent(values[0])},${encodeURIComponent(values[1])}`, {arrayFormat: 'comma'}), { foo: [ 'zero,one', 'two,three', @@ -392,7 +405,8 @@ test('value should not be decoded twice with `arrayFormat` option set as `separa // See https://github.com/sindresorhus/query-string/issues/242 test('value separated by encoded comma will not be parsed as array with `arrayFormat` option set to `comma`', t => { - t.deepEqual(queryString.parse('id=1%2C2%2C3', {arrayFormat: 'comma', parseNumbers: true}), { + const value = '1,2,3'; + t.deepEqual(queryString.parse(`id=${encodeURIComponent(value)}`, {arrayFormat: 'comma', parseNumbers: true}), { id: [1, 2, 3], }); }); @@ -406,7 +420,8 @@ test('query strings having (:list) colon-list-separator arrays including null va }); test('types option: can override a parsed number to be a string ', t => { - t.deepEqual(queryString.parse('phoneNumber=%2B380951234567', { + const phoneNumber = '+380951234567'; + t.deepEqual(queryString.parse(`phoneNumber=${encodeURIComponent(phoneNumber)}`, { parseNumbers: true, types: { phoneNumber: 'string', @@ -426,7 +441,7 @@ test('types option: can override a parsed boolean value to be a string', t => { }); test('types option: can override parsed numbers arrays to be string[]', t => { - t.deepEqual(queryString.parse('ids=999%2C998%2C997&items=1%2C2%2C3', { + t.deepEqual(queryString.parse('ids=999,998,997&items=1,2,3', { arrayFormat: 'comma', parseNumbers: true, types: { @@ -439,7 +454,7 @@ test('types option: can override parsed numbers arrays to be string[]', t => { }); test('types option: can override string arrays to be number[]', t => { - t.deepEqual(queryString.parse('ids=001%2C002%2C003&items=1%2C2%2C3', { + t.deepEqual(queryString.parse('ids=1,2,3&items=1,2,3', { arrayFormat: 'comma', types: { ids: 'number[]', @@ -451,7 +466,7 @@ test('types option: can override string arrays to be number[]', t => { }); test('types option: can override an array to be string', t => { - t.deepEqual(queryString.parse('ids=001%2C002%2C003&items=1%2C2%2C3', { + t.deepEqual(queryString.parse('ids=001,002,003&items=1,2,3', { arrayFormat: 'comma', parseNumbers: true, types: { @@ -488,7 +503,7 @@ test('types option: when value is not of specified type, it will safely parse th }); test('types option: array types will have no effect if arrayFormat is set to "none"', t => { - t.deepEqual(queryString.parse('ids=001%2C002%2C003&foods=apple%2Corange%2Cmango', { + t.deepEqual(queryString.parse('ids=001,002,003&foods=apple,orange,mango', { arrayFormat: 'none', types: { ids: 'number[]', @@ -512,7 +527,7 @@ test('types option: will parse the value as number if specified in type but pars }); test('types option: all supported types work in conjunction with one another', t => { - t.deepEqual(queryString.parse('ids=001%2C002%2C003&items=1%2C2%2C3&price=22%2E00&numbers=1%2C2%2C3&double=5&number=20', { + t.deepEqual(queryString.parse('ids=001,002,003&items=1,2,3&price=22.00&numbers=1,2,3&double=5&number=20', { arrayFormat: 'comma', types: { ids: 'string', From 9fce3f9245d3fa1915c4a824738cd1edb76a6c85 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Wed, 9 Oct 2024 13:20:32 +0700 Subject: [PATCH 50/50] 9.1.1 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index c172a09..4023082 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "query-string", - "version": "9.1.0", + "version": "9.1.1", "description": "Parse and stringify URL query strings", "license": "MIT", "repository": "sindresorhus/query-string",