query-string 6.14.0 → 7.1.0

package/index.d.ts

@@ -45,6 +45,39 @@ 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']}
+		```
+
+	- `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:
 
 		```
@@ -54,7 +87,7 @@ export interface ParseOptions {
 		//=> {foo: ['1', '2', '3']}
 		```
 	*/
-	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | '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'}`.
@@ -229,9 +262,14 @@ 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:
+	- `separator`: Serialize arrays by separating elements with character:
 
 		```
 		import queryString = require('query-string');
@@ -240,6 +278,42 @@ 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'
+		```
+
+	- `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:
 
 		```
@@ -249,7 +323,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' | 'colon-list-separator' | 'none';
 
 	/**
 	The character used to separate array elements when using `{arrayFormat: 'separator'}`.
@@ -372,7 +446,7 @@ export interface UrlObject {
 	/**
 	Overrides queries in the `url` property.
 	*/
-	readonly query: StringifiableRecord;
+	readonly query?: StringifiableRecord;
 
 	/**
 	Overrides the fragment identifier in the `url` property.

package/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':
@@ -47,19 +49,49 @@ 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': {
+			const keyValueSep = options.arrayFormat === 'bracket-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;
 				}
 
+				// 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), '=', encode(value, options)].join('')];
+					return [[encode(key, options), keyValueSep, encode(value, options)].join('')];
 				}
 
 				return [[result, encode(value, options)].join(options.arrayFormatSeparator)];
 			};
+		}
 
 		default:
 			return key => (result, value) => {
@@ -120,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) => {
@@ -130,6 +180,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) {
@@ -253,7 +325,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);
 	}
 
@@ -335,6 +407,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('&');
@@ -363,7 +439,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] || '';
@@ -378,7 +455,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}`;
@@ -386,7 +463,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);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "query-string",
-	"version": "6.14.0",
+	"version": "7.1.0",
 	"description": "Parse and stringify URL query strings",
 	"license": "MIT",
 	"repository": "sindresorhus/query-string",

package/readme.md

@@ -17,7 +17,40 @@
 		<br>
 		<br>
 		<a href="https://standardresume.co/tech">
-			<img src="https://sindresorhus.com/assets/thanks/standard-resume-logo.svg" width="200"/>
+			<img src="https://sindresorhus.com/assets/thanks/standard-resume-logo.svg" width="180"/>
+		</a>
+		<br>
+		<br>
+		<br>
+		<a href="https://doppler.com/?utm_campaign=github_repo&utm_medium=referral&utm_content=query-string&utm_source=github">
+			<div>
+				<img src="https://dashboard.doppler.com/imgs/logo-long.svg" width="240" alt="Doppler">
+			</div>
+			<b>All your environment variables, in one place</b>
+			<div>
+				<span>Stop struggling with scattered API keys, hacking together home-brewed tools,</span>
+				<br>
+				<span>and avoiding access controls. Keep your team and servers in sync with Doppler.</span>
+			</div>
+		</a>
+		<br>
+		<a href="https://strapi.io/?ref=sindresorhus">
+			<div>
+				<img src="https://sindresorhus.com/assets/thanks/strapi-logo-white-bg.png" width="200" alt="Strapi">
+			</div>
+			<b>Strapi is the leading open-source headless CMS.</b>
+			<div>
+				<sup>It’s 100% JavaScript, fully customizable, and developer-first.</sup>
+			</div>
+		</a>
+		<br>
+		<a href="https://oss.capital">
+			<div>
+				<img src="https://sindresorhus.com/assets/thanks/oss-capital-logo-white-bg.svg" width="300" alt="OSS Capital">
+			</div>
+			<div>
+				<sup><b>Founded in 2018, OSS Capital is the first and only venture capital platform focused<br>exclusively on supporting early-stage COSS (commercial open source) startup founders.</b></sup>
+			</div>
 		</a>
 	</p>
 </div>
@@ -32,7 +65,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
 
@@ -125,6 +160,39 @@ 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']}
+```
+
+- `'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
@@ -228,6 +296,56 @@ 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, '', '']}`.
+```
+
+- `'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'
+```
+
+- `'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:
@@ -520,6 +638,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.