query-string 6.5.0 → 6.8.1

package/index.d.ts

@@ -1,52 +1,108 @@
 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
-	 */
+	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:
-	 *
-	 *
-	 *    queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'});
-	 *    //=> foo: [1, 2, 3]
-	 *
-	 * - `index`: Parse arrays with index representation:
-	 *
-	 *
-	 *    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:
-	 *
-	 *
-	 *    queryString.parse('foo=1,2,3', {arrayFormat: 'comma'});
-	 *    //=> foo: [1, 2, 3]
-	 *
-	 * - `none`: Parse arrays with elements using duplicate keys:
-	 *
-	 *
-	 *    queryString.parse('foo=1&foo=2&foo=3');
-	 *    //=> foo: [1, 2, 3]
-	 */
+	@default 'none'
+
+	- `bracket`: Parse arrays with bracket representation:
+
+		```
+		queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'});
+		//=> {foo: ['1', '2', '3']}
+		```
+
+	- `index`: Parse arrays with index representation:
+
+		```
+		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:
+
+		```
+		queryString.parse('foo=1,2,3', {arrayFormat: 'comma'});
+		//=> {foo: ['1', '2', '3']}
+		```
+
+	- `none`: Parse arrays with elements using duplicate keys:
+
+		```
+		queryString.parse('foo=1&foo=2&foo=3');
+		//=> {foo: ['1', '2', '3']}
+		```
+	*/
 	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | '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.
+
+	@default true
+
+	@example
+	```
+	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'}
+	```
+
+	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
+	```js
+	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
+	```
+	queryString.parse('foo=true', {parseBooleans: true});
+	//=> {foo: true}
+	```
+	*/
+	readonly parseBooleans?: boolean;
 }
 
-export interface ParsedQuery {
-	readonly [key: string]: string | string[] | null | undefined;
+export interface ParsedQuery<T = string> {
+	[key: string]: T | T[] | null | 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.
- */
+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<string | boolean | number>;
+export function parse(query: string, options: {parseBooleans: true} & ParseOptions): ParsedQuery<string | boolean>;
+export function parse(query: string, options: {parseNumbers: true} & ParseOptions): ParsedQuery<string | number>;
 export function parse(query: string, options?: ParseOptions): ParsedQuery;
 
 export interface ParsedUrl {
@@ -55,89 +111,98 @@ export interface ParsedUrl {
 }
 
 /**
- * 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'}}
- */
+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
-	 */
+	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
-	 */
+	[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:
-	 *
-	 *
-	 *    queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
-	 *    //=> 'foo[]=1&foo[]=2&foo[]=3'
-	 *
-	 * - `index`: Serialize arrays using index representation:
-	 *
-	 *
-	 *    queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'});
-	 *    //=> 'foo[0]=1&foo[1]=2&foo[3]=3'
-	 *
-	 * - `comma`: Serialize arrays by separating elements with comma:
-	 *
-	 *
-	 *    queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'});
-	 *    //=> 'foo=1,2,3'
-	 *
-	 * - `none`: Serialize arrays by using duplicate keys:
-	 *
-	 *
-	 *    queryString.stringify({foo: [1, 2, 3]});
-	 *    //=> 'foo=1&foo=2&foo=3'
-	 */
+	@default 'none'
+
+	- `bracket`: Serialize arrays using bracket representation:
+
+		```
+		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
+		//=> 'foo[]=1&foo[]=2&foo[]=3'
+		```
+
+	- `index`: Serialize arrays using index representation:
+
+		```
+		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:
+
+		```
+		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'});
+		//=> 'foo=1,2,3'
+		```
+
+	- `none`: Serialize arrays by using duplicate keys:
+
+		```
+		queryString.stringify({foo: [1, 2, 3]});
+		//=> 'foo=1&foo=2&foo=3'
+		```
+	*/
 	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | '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'
-	 */
+	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
+	```
+	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 and sorting the keys.
- */
+Stringify an object into a query string and sort the keys.
+*/
 export function stringify(
-	object: {[key: string]: unknown},
+	object: {[key: string]: any},
 	options?: StringifyOptions
 ): string;
 
 /**
- * Extract a query string from a URL that can be passed into `.parse()`.
- */
+Extract a query string from a URL that can be passed into `.parse()`.
+*/
 export function extract(url: string): string;

package/index.js

@@ -174,7 +174,10 @@ function extract(input) {
 function parse(input, options) {
 	options = Object.assign({
 		decode: true,
-		arrayFormat: 'none'
+		sort: true,
+		arrayFormat: 'none',
+		parseNumbers: false,
+		parseBooleans: false
 	}, options);
 
 	const formatter = parserForArrayFormat(options);
@@ -199,10 +202,20 @@ function parse(input, options) {
 		// http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters
 		value = value === undefined ? null : decode(value, options);
 
+		if (options.parseNumbers && !Number.isNaN(Number(value))) {
+			value = Number(value);
+		} else if (options.parseBooleans && value !== null && (value.toLowerCase() === 'true' || value.toLowerCase() === 'false')) {
+			value = value.toLowerCase() === 'true';
+		}
+
 		formatter(decode(key, options), value, ret);
 	}
 
-	return Object.keys(ret).sort().reduce((result, key) => {
+	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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "query-string",
-	"version": "6.5.0",
+	"version": "6.8.1",
 	"description": "Parse and stringify URL query strings",
 	"license": "MIT",
 	"repository": "sindresorhus/query-string",
@@ -40,10 +40,10 @@
 		"strict-uri-encode": "^2.0.0"
 	},
 	"devDependencies": {
-		"ava": "^1.3.1",
+		"ava": "^1.4.1",
 		"deep-equal": "^1.0.1",
 		"fast-check": "^1.5.0",
-		"tsd": "^0.7.0",
+		"tsd": "^0.7.3",
 		"xo": "^0.24.0"
 	}
 }

package/readme.md

@@ -11,10 +11,6 @@ $ 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>
-
 
 ## Usage
 
@@ -50,7 +46,7 @@ console.log(location.search);
 
 ## API
 
-### .parse(string, [options])
+### .parse(string, options?)
 
 Parse a query string into an object. Leading `?` or `#` are ignored, so you can pass `location.search` or `location.hash` directly.
 
@@ -58,7 +54,7 @@ The returned object is created with [`Object.create(null)`](https://developer.mo
 
 #### options
 
-Type: `Object`
+Type: `object`
 
 ##### decode
 
@@ -70,43 +66,74 @@ Decode the keys and values. URL components are decoded with [`decode-uri-compone
 ##### arrayFormat
 
 Type: `string`<br>
-Default: `none`
+Default: `'none'`
 
-- `bracket`: Parse arrays with bracket representation:
+- `'bracket'`: Parse arrays with bracket representation:
 
 ```js
 queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'});
-//=> foo: [1, 2, 3]
+//=> {foo: ['1', '2', '3']}
 ```
 
-- `index`: Parse arrays with index representation:
+- `'index'`: Parse arrays with index representation:
 
 ```js
 queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'});
-//=> foo: [1, 2, 3]
+//=> {foo: ['1', '2', '3']}
 ```
 
-- `comma`: Parse arrays with elements separated by comma:
+- `'comma'`: Parse arrays with elements separated by comma:
 
 ```js
 queryString.parse('foo=1,2,3', {arrayFormat: 'comma'});
-//=> foo: [1, 2, 3]
+//=> {foo: ['1', '2', '3']}
 ```
 
-- `none`: Parse arrays with elements using duplicate keys:
+- `'none'`: Parse arrays with elements using duplicate keys:
 
 ```js
 queryString.parse('foo=1&foo=2&foo=3');
-//=> foo: [1, 2, 3]
+//=> {foo: ['1', '2', '3']}
 ```
 
+##### sort
+
+Type: `Function | boolean`<br>
+Default: `true`
+
+Supports both `Function` as a custom sorting function or `false` to disable sorting.
+
+##### parseNumbers
+
+Type: `boolean`<br>
+Default: `false`
+
+```js
+queryString.parse('foo=1', {parseNumbers: true});
+//=> {foo: 1}
+```
+
+Parse the value as a number type instead of string type if it's a number.
+
+##### parseBooleans
+
+Type: `boolean`<br>
+Default: `false`
+
+```js
+queryString.parse('foo=true', {parseBooleans: true});
+//=> {foo: true}
+```
+
+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.
 
 #### options
 
-Type: `Object`
+Type: `object`
 
 ##### strict
 
@@ -125,30 +152,30 @@ Default: `true`
 ##### arrayFormat
 
 Type: `string`<br>
-Default: `none`
+Default: `'none'`
 
-- `bracket`: Serialize arrays using bracket representation:
+- `'bracket'`: Serialize arrays using bracket representation:
 
 ```js
 queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
 //=> 'foo[]=1&foo[]=2&foo[]=3'
 ```
 
-- `index`: Serialize arrays using index representation:
+- `'index'`: Serialize arrays using index representation:
 
 ```js
 queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'});
-//=> 'foo[0]=1&foo[1]=2&foo[3]=3'
+//=> 'foo[0]=1&foo[1]=2&foo[2]=3'
 ```
 
-- `comma`: Serialize arrays by separating elements with comma:
+- `'comma'`: Serialize arrays by separating elements with comma:
 
 ```js
 queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'});
 //=> 'foo=1,2,3'
 ```
 
-- `none`: Serialize arrays by using duplicate keys:
+- `'none'`: Serialize arrays by using duplicate keys:
 
 ```js
 queryString.stringify({foo: [1, 2, 3]});
@@ -181,7 +208,7 @@ If omitted, keys are sorted using `Array#sort()`, which means, converting them t
 
 Extract a query string from a URL that can be passed into `.parse()`.
 
-### .parseUrl(string, [options])
+### .parseUrl(string, options?)
 
 Extract the URL and the query string as an object.
 
@@ -218,7 +245,7 @@ queryString.parse('likes=cake&name=bob&likes=icecream');
 //=> {likes: ['cake', 'icecream'], name: 'bob'}
 
 queryString.stringify({color: ['taupe', 'chartreuse'], id: '515'});
-//=> 'color=chartreuse&color=taupe&id=515'
+//=> 'color=taupe&color=chartreuse&id=515'
 ```
 
 
@@ -238,6 +265,14 @@ queryString.stringify({foo: undefined});
 ```
 
 
-## License
+---
 
-MIT © [Sindre Sorhus](https://sindresorhus.com)
+<div align="center">
+	<b>
+		<a href="https://tidelift.com/subscription/pkg/npm-query-string?utm_source=npm-query-string&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
+	</b>
+	<br>
+	<sub>
+		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
+	</sub>
+</div>