query-string 5.1.1 → 6.3.0

package/index.d.ts

@@ -0,0 +1,135 @@
+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;
+
+	/**
+	 * Supports both `index` for an indexed array representation or `bracket` for a *bracketed* array representation.
+	 *
+	 * @default 'none'
+	 *
+	 * - `bracket`: stands for parsing correctly arrays with bracket representation on the query string, such as:
+	 *
+	 *
+	 *    queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'});
+	 *    //=> foo: [1,2,3]
+	 *
+	 * - `index`: stands for parsing taking the index into account, such as:
+	 *
+	 *
+	 *    queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'});
+	 *    //=> foo: [1,2,3]
+	 *
+	 * - `none`: is the **default** option and removes any bracket representation, such as:
+	 *
+	 *
+	 *    queryString.parse('foo=1&foo=2&foo=3');
+	 *    //=> foo: [1,2,3]
+	 */
+	readonly arrayFormat?: 'bracket' | 'index' | 'none';
+}
+
+export interface ParsedQuery {
+	readonly [key: string]: string | string[] | undefined;
+}
+
+/**
+ * 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?: ParseOptions): ParsedQuery;
+
+export interface ParsedUrl {
+	readonly url: string;
+	readonly query: ParsedQuery;
+}
+
+/**
+ * Extract the URL and the query string as an object.
+ *
+ * @param url - The URL to parse.
+ *
+ * @example
+ *
+ * queryString.parseUrl('https://foo.bar?foo=bar');
+ * //=> {url: 'https://foo.bar', query: {foo: 'bar'}}
+ */
+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;
+
+	/**
+	 * Supports both `index` for an indexed array representation or `bracket` for a *bracketed* array representation.
+	 *
+	 * @default 'none'
+	 *
+	 * - `bracket`: stands for parsing correctly arrays with bracket representation on the query string, such as:
+	 *
+	 *
+	 *    queryString.stringify({foo: [1,2,3]}, {arrayFormat: 'bracket'});
+	 *    // => foo[]=1&foo[]=2&foo[]=3
+	 *
+	 * - `index`: stands for parsing taking the index into account, such as:
+	 *
+	 *
+	 *    queryString.stringify({foo: [1,2,3]}, {arrayFormat: 'index'});
+	 *    // => foo[0]=1&foo[1]=2&foo[3]=3
+	 *
+	 * - `none`: is the **default** option and removes any bracket representation, such as:
+	 *
+	 *
+	 *    queryString.stringify({foo: [1,2,3]});
+	 *    // => foo=1&foo=2&foo=3
+	 */
+	readonly arrayFormat?: 'bracket' | 'index' | 'none';
+
+	/**
+	 * 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.
+	 *
+	 * @example
+	 *
+	 * 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'
+	 *
+	 * queryString.stringify({ b: 1, c: 2, a: 3}, {sort: false});
+	 * // => 'b=1&c=2&a=3'
+	 */
+	readonly sort?: ((itemLeft: string, itemRight: string) => number) | false;
+}
+
+/**
+ * Stringify an object into a query string, sorting the keys.
+ */
+export function stringify(
+	object: {[key: string]: unknown},
+	options?: StringifyOptions
+): string;
+
+/**
+ * Extract a query string from a URL that can be passed into `.parse()`.
+ */
+export function extract(url: string): string;

package/index.js

@@ -1,52 +1,51 @@
 'use strict';
-var strictUriEncode = require('strict-uri-encode');
-var objectAssign = require('object-assign');
-var decodeComponent = require('decode-uri-component');
+const strictUriEncode = require('strict-uri-encode');
+const decodeComponent = require('decode-uri-component');
 
-function encoderForArrayFormat(opts) {
-	switch (opts.arrayFormat) {
+function encoderForArrayFormat(options) {
+	switch (options.arrayFormat) {
 		case 'index':
-			return function (key, value, index) {
+			return (key, value, index) => {
 				return value === null ? [
-					encode(key, opts),
+					encode(key, options),
 					'[',
 					index,
 					']'
 				].join('') : [
-					encode(key, opts),
+					encode(key, options),
 					'[',
-					encode(index, opts),
+					encode(index, options),
 					']=',
-					encode(value, opts)
+					encode(value, options)
 				].join('');
 			};
 
 		case 'bracket':
-			return function (key, value) {
-				return value === null ? encode(key, opts) : [
-					encode(key, opts),
+			return (key, value) => {
+				return value === null ? [encode(key, options), '[]'].join('') : [
+					encode(key, options),
 					'[]=',
-					encode(value, opts)
+					encode(value, options)
 				].join('');
 			};
 
 		default:
-			return function (key, value) {
-				return value === null ? encode(key, opts) : [
-					encode(key, opts),
+			return (key, value) => {
+				return value === null ? encode(key, options) : [
+					encode(key, options),
 					'=',
-					encode(value, opts)
+					encode(value, options)
 				].join('');
 			};
 	}
 }
 
-function parserForArrayFormat(opts) {
-	var result;
+function parserForArrayFormat(options) {
+	let result;
 
-	switch (opts.arrayFormat) {
+	switch (options.arrayFormat) {
 		case 'index':
-			return function (key, value, accumulator) {
+			return (key, value, accumulator) => {
 				result = /\[(\d*)\]$/.exec(key);
 
 				key = key.replace(/\[\d*\]$/, '');
@@ -64,14 +63,16 @@ function parserForArrayFormat(opts) {
 			};
 
 		case 'bracket':
-			return function (key, value, accumulator) {
+			return (key, value, accumulator) => {
 				result = /(\[\])$/.exec(key);
 				key = key.replace(/\[\]$/, '');
 
 				if (!result) {
 					accumulator[key] = value;
 					return;
-				} else if (accumulator[key] === undefined) {
+				}
+
+				if (accumulator[key] === undefined) {
 					accumulator[key] = [value];
 					return;
 				}
@@ -80,7 +81,7 @@ function parserForArrayFormat(opts) {
 			};
 
 		default:
-			return function (key, value, accumulator) {
+			return (key, value, accumulator) => {
 				if (accumulator[key] === undefined) {
 					accumulator[key] = value;
 					return;
@@ -91,9 +92,17 @@ function parserForArrayFormat(opts) {
 	}
 }
 
-function encode(value, opts) {
-	if (opts.encode) {
-		return opts.strict ? strictUriEncode(value) : encodeURIComponent(value);
+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;
@@ -102,65 +111,61 @@ function encode(value, opts) {
 function keysSorter(input) {
 	if (Array.isArray(input)) {
 		return input.sort();
-	} else if (typeof input === 'object') {
-		return keysSorter(Object.keys(input)).sort(function (a, b) {
-			return Number(a) - Number(b);
-		}).map(function (key) {
-			return input[key];
-		});
+	}
+
+	if (typeof input === 'object') {
+		return keysSorter(Object.keys(input))
+			.sort((a, b) => Number(a) - Number(b))
+			.map(key => input[key]);
 	}
 
 	return input;
 }
 
-function extract(str) {
-	var queryStart = str.indexOf('?');
+function extract(input) {
+	const queryStart = input.indexOf('?');
 	if (queryStart === -1) {
 		return '';
 	}
-	return str.slice(queryStart + 1);
+
+	return input.slice(queryStart + 1);
 }
 
-function parse(str, opts) {
-	opts = objectAssign({arrayFormat: 'none'}, opts);
+function parse(input, options) {
+	options = Object.assign({decode: true, arrayFormat: 'none'}, options);
 
-	var formatter = parserForArrayFormat(opts);
+	const formatter = parserForArrayFormat(options);
 
 	// Create an object with no prototype
-	// https://github.com/sindresorhus/query-string/issues/47
-	var ret = Object.create(null);
+	const ret = Object.create(null);
 
-	if (typeof str !== 'string') {
+	if (typeof input !== 'string') {
 		return ret;
 	}
 
-	str = str.trim().replace(/^[?#&]/, '');
+	input = input.trim().replace(/^[?#&]/, '');
 
-	if (!str) {
+	if (!input) {
 		return ret;
 	}
 
-	str.split('&').forEach(function (param) {
-		var parts = param.replace(/\+/g, ' ').split('=');
-		// Firefox (pre 40) decodes `%3D` to `=`
-		// https://github.com/sindresorhus/query-string/pull/37
-		var key = parts.shift();
-		var val = parts.length > 0 ? parts.join('=') : undefined;
+	for (const param of input.split('&')) {
+		let [key, value] = param.replace(/\+/g, ' ').split('=');
 
-		// missing `=` should be `null`:
+		// Missing `=` should be `null`:
 		// http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters
-		val = val === undefined ? null : decodeComponent(val);
+		value = value === undefined ? null : decode(value, options);
 
-		formatter(decodeComponent(key), val, ret);
-	});
+		formatter(decode(key, options), value, ret);
+	}
 
-	return Object.keys(ret).sort().reduce(function (result, key) {
-		var val = ret[key];
-		if (Boolean(val) && typeof val === 'object' && !Array.isArray(val)) {
+	return Object.keys(ret).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(val);
+			result[key] = keysSorter(value);
 		} else {
-			result[key] = val;
+			result[key] = value;
 		}
 
 		return result;
@@ -170,55 +175,61 @@ function parse(str, opts) {
 exports.extract = extract;
 exports.parse = parse;
 
-exports.stringify = function (obj, opts) {
-	var defaults = {
+exports.stringify = (obj, options) => {
+	if (!obj) {
+		return '';
+	}
+
+	options = Object.assign({
 		encode: true,
 		strict: true,
 		arrayFormat: 'none'
-	};
+	}, options);
 
-	opts = objectAssign(defaults, opts);
+	const formatter = encoderForArrayFormat(options);
+	const keys = Object.keys(obj);
 
-	if (opts.sort === false) {
-		opts.sort = function () {};
+	if (options.sort !== false) {
+		keys.sort(options.sort);
 	}
 
-	var formatter = encoderForArrayFormat(opts);
-
-	return obj ? Object.keys(obj).sort(opts.sort).map(function (key) {
-		var val = obj[key];
+	return keys.map(key => {
+		const value = obj[key];
 
-		if (val === undefined) {
+		if (value === undefined) {
 			return '';
 		}
 
-		if (val === null) {
-			return encode(key, opts);
+		if (value === null) {
+			return encode(key, options);
 		}
 
-		if (Array.isArray(val)) {
-			var result = [];
+		if (Array.isArray(value)) {
+			const result = [];
 
-			val.slice().forEach(function (val2) {
-				if (val2 === undefined) {
-					return;
+			for (const value2 of value.slice()) {
+				if (value2 === undefined) {
+					continue;
 				}
 
-				result.push(formatter(key, val2, result.length));
-			});
+				result.push(formatter(key, value2, result.length));
+			}
 
 			return result.join('&');
 		}
 
-		return encode(key, opts) + '=' + encode(val, opts);
-	}).filter(function (x) {
-		return x.length > 0;
-	}).join('&') : '';
+		return encode(key, options) + '=' + encode(value, options);
+	}).filter(x => x.length > 0).join('&');
 };
 
-exports.parseUrl = function (str, opts) {
+exports.parseUrl = (input, options) => {
+	const hashStart = input.indexOf('#');
+	if (hashStart !== -1) {
+		input = input.slice(0, hashStart);
+	}
+
 	return {
-		url: str.split('?')[0] || '',
-		query: parse(extract(str), opts)
+		url: input.split('?')[0] || '',
+		query: parse(extract(input), options)
 	};
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "query-string",
-	"version": "5.1.1",
+	"version": "6.3.0",
 	"description": "Parse and stringify URL query strings",
 	"license": "MIT",
 	"repository": "sindresorhus/query-string",
@@ -10,13 +10,14 @@
 		"url": "sindresorhus.com"
 	},
 	"engines": {
-		"node": ">=0.10.0"
+		"node": ">=6"
 	},
 	"scripts": {
-		"test": "xo && ava"
+		"test": "xo && ava && tsd-check"
 	},
 	"files": [
-		"index.js"
+		"index.js",
+		"index.d.ts"
 	],
 	"keywords": [
 		"browser",
@@ -27,19 +28,21 @@
 		"param",
 		"parameter",
 		"url",
-		"uri",
 		"parse",
 		"stringify",
 		"encode",
-		"decode"
+		"decode",
+		"searchparams"
 	],
 	"dependencies": {
 		"decode-uri-component": "^0.2.0",
-		"object-assign": "^4.1.0",
-		"strict-uri-encode": "^1.0.0"
+		"strict-uri-encode": "^2.0.0"
 	},
 	"devDependencies": {
-		"ava": "^0.17.0",
-		"xo": "^0.16.0"
+		"ava": "^1.2.1",
+		"deep-equal": "^1.0.1",
+		"fast-check": "^1.5.0",
+		"tsd-check": "^0.3.0",
+		"xo": "^0.24.0"
 	}
 }

package/readme.md

@@ -15,6 +15,8 @@
 $ 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`.
+
 <a href="https://www.patreon.com/sindresorhus">
 	<img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
 </a>
@@ -60,7 +62,12 @@ Parse a query string into an object. Leading `?` or `#` are ignored, so you can
 
 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`.
 
-URI components are decoded with [`decode-uri-component`](https://github.com/SamVerschueren/decode-uri-component).
+#### decode
+
+Type: `boolean`<br>
+Default: `true`
+
+Decode the keys and values. URI components are decoded with [`decode-uri-component`](https://github.com/SamVerschueren/decode-uri-component).
 
 #### arrayFormat
 
@@ -146,14 +153,14 @@ Supports both `Function` as a custom sorting function or `false` to disable sort
 ```js
 const order = ['c', 'a', 'b'];
 queryString.stringify({ a: 1, b: 2, c: 3}, {
-	sort: (m, n) => order.indexOf(m) >= order.indexOf(n)
+	sort: (m, n) => order.indexOf(m) - order.indexOf(n)
 });
 // => 'c=3&a=1&b=2'
 ```
 
 ```js
 queryString.stringify({ b: 1, c: 2, a: 3}, {sort: false});
-// => 'c=3&a=1&b=2'
+// => 'b=1&c=2&a=3'
 ```
 
 If omitted, keys are sorted using `Array#sort`, which means, converting them to strings and comparing strings in Unicode code point order.