query-string 6.9.0 → 6.11.1

package/index.d.ts

@@ -36,6 +36,15 @@ export interface ParseOptions {
 		//=> {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']}
+		```
+
 	- `none`: Parse arrays with elements using duplicate keys:
 
 		```
@@ -45,7 +54,14 @@ export interface ParseOptions {
 		//=> {foo: ['1', '2', '3']}
 		```
 	*/
-	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'none';
+	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | '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.
@@ -188,6 +204,15 @@ export interface StringifyOptions {
 		//=> 'foo=1,2,3'
 		```
 
+  - `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'
+		```
+
 	- `none`: Serialize arrays by using duplicate keys:
 
 		```
@@ -197,7 +222,14 @@ export interface StringifyOptions {
 		//=> 'foo=1&foo=2&foo=3'
 		```
 	*/
-	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'none';
+	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | '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.
@@ -267,3 +299,22 @@ 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;
+
+/**
+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.
+
+@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'
+```
+*/
+export function stringifyUrl(
+	object: ParsedUrl,
+	options?: StringifyOptions
+): string;

package/index.js

@@ -36,6 +36,7 @@ function encoderForArrayFormat(options) {
 			};
 
 		case 'comma':
+		case 'separator':
 			return key => (result, value) => {
 				if (value === null || value === undefined || value.length === 0) {
 					return result;
@@ -45,7 +46,7 @@ function encoderForArrayFormat(options) {
 					return [[encode(key, options), '=', encode(value, options)].join('')];
 				}
 
-				return [[result, encode(value, options)].join(',')];
+				return [[result, encode(value, options)].join(options.arrayFormatSeparator)];
 			};
 
 		default:
@@ -104,9 +105,10 @@ function parserForArrayFormat(options) {
 			};
 
 		case 'comma':
+		case 'separator':
 			return (key, value, accumulator) => {
-				const isArray = typeof value === 'string' && value.split('').indexOf(',') > -1;
-				const newValue = isArray ? value.split(',') : value;
+				const isArray = typeof value === 'string' && value.split('').indexOf(options.arrayFormatSeparator) > -1;
+				const newValue = isArray ? value.split(options.arrayFormatSeparator).map(item => decode(item, options)) : value === null ? value : decode(value, options);
 				accumulator[key] = newValue;
 			};
 
@@ -122,6 +124,12 @@ function parserForArrayFormat(options) {
 	}
 }
 
+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);
@@ -161,6 +169,16 @@ function removeHash(input) {
 	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('?');
@@ -186,10 +204,13 @@ function parse(input, 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
@@ -210,7 +231,7 @@ function parse(input, options) {
 
 		// Missing `=` should be `null`:
 		// http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters
-		value = value === undefined ? null : decode(value, options);
+		value = value === undefined ? null : options.arrayFormat === 'comma' ? value : decode(value, options);
 		formatter(decode(key, options), value, ret);
 	}
 
@@ -253,9 +274,12 @@ exports.stringify = (object, options) => {
 	options = Object.assign({
 		encode: true,
 		strict: true,
-		arrayFormat: 'none'
+		arrayFormat: 'none',
+		arrayFormatSeparator: ','
 	}, options);
 
+	validateArrayFormatSeparator(options.arrayFormatSeparator);
+
 	const formatter = encoderForArrayFormat(options);
 
 	const objectCopy = Object.assign({}, object);
@@ -300,3 +324,17 @@ exports.parseUrl = (input, options) => {
 		query: parse(extract(input), options)
 	};
 };
+
+exports.stringifyUrl = (input, options) => {
+	const url = removeHash(input.url).split('?')[0] || '';
+	const queryFromUrl = exports.extract(input.url);
+	const parsedQueryFromUrl = exports.parse(queryFromUrl);
+	const hash = getHash(input.url);
+	const query = Object.assign(parsedQueryFromUrl, input.query);
+	let queryString = exports.stringify(query, options);
+	if (queryString) {
+		queryString = `?${queryString}`;
+	}
+
+	return `${url}${queryString}${hash}`;
+};

package/package.json

@@ -1,9 +1,10 @@
 {
 	"name": "query-string",
-	"version": "6.9.0",
+	"version": "6.11.1",
 	"description": "Parse and stringify URL query strings",
 	"license": "MIT",
 	"repository": "sindresorhus/query-string",
+	"funding": "https://github.com/sponsors/sindresorhus",
 	"author": {
 		"name": "Sindre Sorhus",
 		"email": "sindresorhus@gmail.com",

package/readme.md

@@ -2,6 +2,34 @@
 
 > Parse and stringify URL [query strings](https://en.wikipedia.org/wiki/Query_string)
 
+<br>
+
+---
+
+<div align="center">
+	<p>
+		<p>
+			<sup>
+				<a href="https://github.com/sponsors/sindresorhus">My open source work is supported by the community</a>
+			</sup>
+		</p>
+		<sup>Special thanks to:</sup>
+		<br>
+		<br>
+		<a href="https://github.com/botpress/botpress">
+			<img src="https://sindresorhus.com/assets/thanks/botpress-logo.svg" width="260" alt="Botpress">
+		</a>
+		<br>
+		<sub><b>Botpress is an open-source conversational assistant creation platform.</b></sub>
+		<br>
+		<sub>They <a href="https://github.com/botpress/botpress/blob/master/.github/CONTRIBUTING.md">welcome contributions</a> from anyone, whether you're into machine learning,<br>want to get started in open-source, or just have an improvement idea.</sub>
+		<br>
+	</p>
+</div>
+
+---
+
+<br>
 
 ## Install
 
@@ -9,8 +37,7 @@
 $ 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](https://github.com/sindresorhus/query-string/pull/148#issuecomment-399656020), use version 5: `npm install query-string@5`.
-
+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`.
 
 ## Usage
 
@@ -43,7 +70,6 @@ console.log(location.search);
 //=> '?foo=unicorn&ilike=pizza'
 ```
 
-
 ## API
 
 ### .parse(string, options?)
@@ -95,6 +121,15 @@ queryString.parse('foo=1,2,3', {arrayFormat: 'comma'});
 //=> {foo: ['1', '2', '3']}
 ```
 
+- `'separator'`: Parse arrays with elements separated by a custom character:
+
+```js
+const queryString = require('query-string');
+
+queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: '|'});
+//=> {foo: ['1', '2', '3']}
+```
+
 - `'none'`: Parse arrays with elements using duplicate keys:
 
 ```js
@@ -104,6 +139,13 @@ queryString.parse('foo=1&foo=2&foo=3');
 //=> {foo: ['1', '2', '3']}
 ```
 
+##### arrayFormatSeparator
+
+Type: `string`\
+Default: `','`
+
+The character used to separate array elements when using `{arrayFormat: 'separator'}`.
+
 ##### sort
 
 Type: `Function | boolean`\
@@ -202,6 +244,13 @@ queryString.stringify({foo: [1, 2, 3]});
 //=> 'foo=1&foo=2&foo=3'
 ```
 
+##### arrayFormatSeparator
+
+Type: `string`\
+Default: `','`
+
+The character used to separate array elements when using `{arrayFormat: 'separator'}`.
+
 ##### sort
 
 Type: `Function | boolean`
@@ -276,6 +325,39 @@ queryString.parseUrl('https://foo.bar?foo=bar');
 //=> {url: 'https://foo.bar', query: {foo: 'bar'}}
 ```
 
+### .stringifyUrl(object, options?)
+
+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)
+
+The `options` are the same as for `.stringify()`.
+
+Returns a string with the URL and a query string.
+
+Query items in the `query` property overrides queries in the `url` property.
+
+```js
+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'
+```
+
+#### object
+
+Type: `object`
+
+##### url
+
+Type: `string`
+
+The URL to stringify.
+
+##### query
+
+Type: `object`
+
+Query items to add to the URL.
 
 ## Nesting
 
@@ -307,7 +389,6 @@ queryString.stringify({color: ['taupe', 'chartreuse'], id: '515'});
 //=> 'color=taupe&color=chartreuse&id=515'
 ```
 
-
 ## Falsy values
 
 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:
@@ -325,7 +406,6 @@ queryString.stringify({foo: undefined});
 //=> ''
 ```
 
-
 ## query-string for enterprise
 
 Available as part of the Tidelift Subscription.