query-string 6.2.0 → 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

@@ -19,6 +19,7 @@ function encoderForArrayFormat(options) {
 					encode(value, options)
 				].join('');
 			};
+
 		case 'bracket':
 			return (key, value) => {
 				return value === null ? [encode(key, options), '[]'].join('') : [
@@ -27,6 +28,7 @@ function encoderForArrayFormat(options) {
 					encode(value, options)
 				].join('');
 			};
+
 		default:
 			return (key, value) => {
 				return value === null ? encode(key, options) : [
@@ -59,6 +61,7 @@ function parserForArrayFormat(options) {
 
 				accumulator[key][result[1]] = value;
 			};
+
 		case 'bracket':
 			return (key, value, accumulator) => {
 				result = /(\[\])$/.exec(key);
@@ -76,6 +79,7 @@ function parserForArrayFormat(options) {
 
 				accumulator[key] = [].concat(accumulator[key], value);
 			};
+
 		default:
 			return (key, value, accumulator) => {
 				if (accumulator[key] === undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "query-string",
-	"version": "6.2.0",
+	"version": "6.3.0",
 	"description": "Parse and stringify URL query strings",
 	"license": "MIT",
 	"repository": "sindresorhus/query-string",
@@ -13,10 +13,11 @@
 		"node": ">=6"
 	},
 	"scripts": {
-		"test": "xo && ava"
+		"test": "xo && ava && tsd-check"
 	},
 	"files": [
-		"index.js"
+		"index.js",
+		"index.d.ts"
 	],
 	"keywords": [
 		"browser",
@@ -38,9 +39,10 @@
 		"strict-uri-encode": "^2.0.0"
 	},
 	"devDependencies": {
-		"ava": "^0.25.0",
+		"ava": "^1.2.1",
 		"deep-equal": "^1.0.1",
 		"fast-check": "^1.5.0",
-		"xo": "^0.23.0"
+		"tsd-check": "^0.3.0",
+		"xo": "^0.24.0"
 	}
 }

package/readme.md

@@ -15,7 +15,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](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](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">
@@ -153,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.