@common.js/query-string 9.0.0 → 9.1.0

package/README.md

@@ -2,4 +2,4 @@
 
 The [query-string](https://www.npmjs.com/package/query-string) package exported as CommonJS modules.
 
-Exported from [query-string@9.0.0](https://www.npmjs.com/package/query-string/v/9.0.0) using https://github.com/etienne-martin/common.js.
+Exported from [query-string@9.1.0](https://www.npmjs.com/package/query-string/v/9.1.0) using https://github.com/etienne-martin/common.js.

package/base.d.ts

@@ -87,7 +87,14 @@ export type ParseOptions = {
 		//=> {foo: ['1', '2', '3']}
 		```
 	*/
-	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'colon-list-separator' | 'none';
+	readonly arrayFormat?:
+	| 'bracket'
+	| 'index'
+	| 'comma'
+	| 'separator'
+	| 'bracket-separator'
+	| 'colon-list-separator'
+	| 'none';
 
 	/**
 	The character used to separate array elements when using `{arrayFormat: 'separator'}`.
@@ -169,6 +176,108 @@ export type ParseOptions = {
 	```
 	*/
 	readonly parseFragmentIdentifier?: boolean;
+
+	/**
+	Specify a pre-defined schema to be used when parsing values. The types specified will take precedence over options such as: `parseNumber`, `parseBooleans`, and `arrayFormat`.
+
+	Use this feature to override the type of a value. This can be useful when the type is ambiguous such as a phone number (see example 1 and 2).
+
+	It is possible to provide a custom function as the parameter type. The parameter's value will equal the function's return value (see example 4).
+
+	NOTE: Array types (`string[]` and `number[]`) will have no effect if `arrayFormat` is set to `none` (see example 5).
+
+	@default {}
+
+	@example
+	Parse `phoneNumber` as a string, overriding the `parseNumber` option:
+	```
+	import queryString from 'query-string';
+
+	queryString.parse('?phoneNumber=%2B380951234567&id=1', {
+		parseNumbers: true,
+		types: {
+			phoneNumber: 'string',
+		}
+	});
+	//=> {phoneNumber: '+380951234567', id: 1}
+	```
+
+	@example
+	Parse `items` as an array of strings, overriding the `parseNumber` option:
+	```
+	import queryString from 'query-string';
+
+	queryString.parse('?age=20&items=1%2C2%2C3', {
+		parseNumber: true,
+		types: {
+			items: 'string[]',
+		}
+	});
+	//=> {age: 20, items: ['1', '2', '3']}
+	```
+
+	@example
+	Parse `age` as a number, even when `parseNumber` is false:
+	```
+	import queryString from 'query-string';
+
+	queryString.parse('?age=20&id=01234&zipcode=90210', {
+		types: {
+			age: 'number',
+		}
+	});
+	//=> {age: 20, id: '01234', zipcode: '90210 }
+	```
+
+	@example
+	Parse `age` using a custom value parser:
+	```
+	import queryString from 'query-string';
+
+	queryString.parse('?age=20&id=01234&zipcode=90210', {
+		types: {
+			age: (value) => value * 2,
+		}
+	});
+	//=> {age: 40, id: '01234', zipcode: '90210 }
+	```
+
+	@example
+	Array types will have no effect when `arrayFormat` is set to `none`
+	```
+	queryString.parse('ids=001%2C002%2C003&foods=apple%2Corange%2Cmango', {
+		arrayFormat: 'none',
+		types: {
+			ids: 'number[]',
+			foods: 'string[]',
+		},
+	}
+	//=> {ids:'001,002,003', foods:'apple,orange,mango'}
+	```
+
+	@example
+	Parse a query utilizing all types:
+	```
+	import queryString from 'query-string';
+
+	queryString.parse('?ids=001%2C002%2C003&items=1%2C2%2C3&price=22%2E00&numbers=1%2C2%2C3&double=5&number=20', {
+		arrayFormat: 'comma',
+		types: {
+			ids: 'string',
+			items: 'string[]',
+			price: 'string',
+			numbers: 'number[]',
+			double: (value) => value * 2,
+			number: 'number',
+		},
+	});
+	//=> {ids: '001,002,003', items: ['1', '2', '3'], price: '22.00', numbers: [1, 2, 3], double: 10, number: 20}
+	```
+	*/
+	readonly types?: Record<
+	string,
+	'number' | 'string' | 'string[]' | 'number[]' | ((value: string) => unknown)
+	>;
 };
 
 // eslint-disable-next-line @typescript-eslint/ban-types

package/base.js

@@ -32,8 +32,8 @@ _export(exports, {
     }
 });
 var _decodeUriComponent = /*#__PURE__*/ _interopRequireDefault(require("decode-uri-component"));
-var _splitOnFirst = /*#__PURE__*/ _interopRequireDefault(require("split-on-first"));
 var _filterObj = require("filter-obj");
+var _splitOnFirst = /*#__PURE__*/ _interopRequireDefault(require("split-on-first"));
 function _arrayLikeToArray(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
@@ -422,11 +422,21 @@ function getHash(url) {
     }
     return hash;
 }
-function parseValue(value, options) {
+function parseValue(value, options, type) {
+    if (type === "string" && typeof value === "string") {
+        return value;
+    }
+    if (typeof type === "function" && typeof value === "string") {
+        return type(value);
+    }
+    if (options.parseBooleans && value !== null && (value.toLowerCase() === "true" || value.toLowerCase() === "false")) {
+        return value.toLowerCase() === "true";
+    }
+    if (type === "number" && !Number.isNaN(Number(value)) && typeof value === "string" && value.trim() !== "") {
+        return Number(value);
+    }
     if (options.parseNumbers && !Number.isNaN(Number(value)) && typeof value === "string" && value.trim() !== "") {
-        value = Number(value);
-    } else if (options.parseBooleans && value !== null && (value.toLowerCase() === "true" || value.toLowerCase() === "false")) {
-        value = value.toLowerCase() === "true";
+        return Number(value);
     }
     return value;
 }
@@ -445,7 +455,8 @@ function parse(query, options) {
         arrayFormat: "none",
         arrayFormatSeparator: ",",
         parseNumbers: false,
-        parseBooleans: false
+        parseBooleans: false,
+        types: Object.create(null)
     }, options);
     validateArrayFormatSeparator(options.arrayFormatSeparator);
     var formatter = parserForArrayFormat(options);
@@ -497,12 +508,13 @@ function parse(query, options) {
     try {
         for(var _iterator1 = Object.entries(returnValue)[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
             var _value = _slicedToArray(_step1.value, 2), key1 = _value[0], value1 = _value[1];
-            if (typeof value1 === "object" && value1 !== null) {
+            if (typeof value1 === "object" && value1 !== null && options.types[key1] !== "string") {
                 var _iteratorNormalCompletion2 = true, _didIteratorError2 = false, _iteratorError2 = undefined;
                 try {
                     for(var _iterator2 = Object.entries(value1)[Symbol.iterator](), _step2; !(_iteratorNormalCompletion2 = (_step2 = _iterator2.next()).done); _iteratorNormalCompletion2 = true){
                         var _value1 = _slicedToArray(_step2.value, 2), key2 = _value1[0], value2 = _value1[1];
-                        value1[key2] = parseValue(value2, options);
+                        var type = options.types[key1] ? options.types[key1].replace("[]", "") : undefined;
+                        value1[key2] = parseValue(value2, options, type);
                     }
                 } catch (err) {
                     _didIteratorError2 = true;
@@ -518,8 +530,10 @@ function parse(query, options) {
                         }
                     }
                 }
+            } else if (typeof value1 === "object" && value1 !== null && options.types[key1] === "string") {
+                returnValue[key1] = Object.values(value1).join(options.arrayFormatSeparator);
             } else {
-                returnValue[key1] = parseValue(value1, options);
+                returnValue[key1] = parseValue(value1, options, options.types[key1]);
             }
         }
     } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@common.js/query-string",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "description": "query-string package exported as CommonJS modules",
   "license": "MIT",
   "repository": "etienne-martin/common.js",