Add sort option to .parse() (#177)

ndtreviv · sindresorhus · sindresorhus · commit b75ca4a38614 · 2019-06-05T21:26:18.000+07:00
Co-authored-by: Sindre Sorhus &lt;sindresorhus@gmail.com&gt;
diff --git a/index.d.ts b/index.d.ts
@@ -34,6 +34,27 @@ export interface ParseOptions {
 	 *    //=> 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;
+
 }
 
 export interface ParsedQuery {
diff --git a/index.js b/index.js
@@ -174,6 +174,7 @@ function extract(input) {
 function parse(input, options) {
 	options = Object.assign({
 		decode: true,
+		sort: true,
 		arrayFormat: 'none'
 	}, options);
 
@@ -202,7 +203,11 @@ function parse(input, options) {
 		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
diff --git a/readme.md b/readme.md
@@ -96,6 +96,13 @@ queryString.parse('foo=1&foo=2&foo=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.
+
 ### .stringify(object, [options])
 
 Stringify an object into a query string and sorting the keys.
diff --git a/test/parse.js b/test/parse.js
@@ -24,6 +24,32 @@ test('parse multiple query string', t => {
 	});
 });
 
+test('parse multiple query string retain order when not sorted', t => {
+	const expectedKeys = ['b', 'a', 'c'];
+	const parsed = queryString.parse('b=foo&a=bar&c=yay', {sort: false});
+	Object.keys(parsed).forEach((key, index) => {
+		t.is(key, expectedKeys[index]);
+	});
+});
+
+test('parse multiple query string sorted keys', t => {
+	const fixture = ['a', 'b', 'c'];
+	const parsed = queryString.parse('a=foo&c=bar&b=yay');
+	Object.keys(parsed).forEach((key, index) => {
+		t.is(key, fixture[index]);
+	});
+});
+
+test('should sort parsed keys in given order', t => {
+	const fixture = ['c', 'a', 'b'];
+	const sort = (key1, key2) => fixture.indexOf(key1) - fixture.indexOf(key2);
+
+	const parsed = queryString.parse('a=foo&b=bar&c=yay', {sort});
+	Object.keys(parsed).forEach((key, index) => {
+		t.is(key, fixture[index]);
+	});
+});
+
 test('parse query string without a value', t => {
 	t.deepEqual(queryString.parse('foo'), {foo: null});
 	t.deepEqual(queryString.parse('foo&key'), {
