query-string 6.10.0 → 6.12.0

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.
@@ -251,6 +283,33 @@ export interface StringifyOptions {
 	```
 	*/
 	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;
 }
 
 /**

package/index.js

@@ -3,12 +3,19 @@ const strictUriEncode = require('strict-uri-encode');
 const decodeComponent = require('decode-uri-component');
 const splitOnFirst = require('split-on-first');
 
+const isNullOrUndefined = value => value === null || value === undefined;
+
 function encoderForArrayFormat(options) {
 	switch (options.arrayFormat) {
 		case 'index':
 			return key => (result, value) => {
 				const index = result.length;
-				if (value === undefined || (options.skipNull && value === null)) {
+
+				if (
+					value === undefined ||
+					(options.skipNull && value === null) ||
+					(options.skipEmptyString && value === '')
+				) {
 					return result;
 				}
 
@@ -24,7 +31,11 @@ function encoderForArrayFormat(options) {
 
 		case 'bracket':
 			return key => (result, value) => {
-				if (value === undefined || (options.skipNull && value === null)) {
+				if (
+					value === undefined ||
+					(options.skipNull && value === null) ||
+					(options.skipEmptyString && value === '')
+				) {
 					return result;
 				}
 
@@ -36,6 +47,7 @@ function encoderForArrayFormat(options) {
 			};
 
 		case 'comma':
+		case 'separator':
 			return key => (result, value) => {
 				if (value === null || value === undefined || value.length === 0) {
 					return result;
@@ -45,12 +57,16 @@ 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:
 			return key => (result, value) => {
-				if (value === undefined || (options.skipNull && value === null)) {
+				if (
+					value === undefined ||
+					(options.skipNull && value === null) ||
+					(options.skipEmptyString && value === '')
+				) {
 					return result;
 				}
 
@@ -104,9 +120,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 +139,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);
@@ -196,10 +219,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
@@ -220,7 +246,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);
 	}
 
@@ -263,17 +289,24 @@ exports.stringify = (object, options) => {
 	options = Object.assign({
 		encode: true,
 		strict: true,
-		arrayFormat: 'none'
+		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 = Object.assign({}, object);
-	if (options.skipNull) {
-		for (const key of Object.keys(objectCopy)) {
-			if (objectCopy[key] === undefined || objectCopy[key] === null) {
-				delete objectCopy[key];
-			}
+	const objectCopy = {};
+
+	for (const key of Object.keys(object)) {
+		if (!shouldFilter(key)) {
+			objectCopy[key] = object[key];
 		}
 	}
 
@@ -313,11 +346,11 @@ exports.parseUrl = (input, options) => {
 
 exports.stringifyUrl = (input, options) => {
 	const url = removeHash(input.url).split('?')[0] || '';
-	const queryFromUrl = this.extract(input.url);
-	const parsedQueryFromUrl = this.parse(queryFromUrl);
+	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 = this.stringify(query, options);
+	let queryString = exports.stringify(query, options);
 	if (queryString) {
 		queryString = `?${queryString}`;
 	}

package/package.json

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

package/readme.md

@@ -121,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
@@ -130,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`\
@@ -228,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`
@@ -281,6 +304,31 @@ queryString.stringify({a: undefined, b: null}, {
 //=> ''
 ```
 
+##### skipEmptyString
+
+Skip keys with an empty string as the value.
+
+Type: `boolean`\
+Default: `false`
+
+```js
+const queryString = require('query-string');
+
+queryString.stringify({a: 1, b: '', c: '', d: 4}, {
+	skipEmptyString: true
+});
+//=> 'a=1&d=4'
+```
+
+```js
+const queryString = require('query-string');
+
+queryString.stringify({a: '', b: ''}, {
+	skipEmptyString: true
+});
+//=> ''
+```
+
 ### .extract(string)
 
 Extract a query string from a URL that can be passed into `.parse()`.