qs 6.11.2 → 6.12.0

package/.eslintrc

@@ -14,7 +14,7 @@
         "id-length": [2, { "min": 1, "max": 25, "properties": "never" }],
         "indent": [2, 4],
         "max-lines-per-function": [2, { "max": 150 }],
-        "max-params": [2, 16],
+        "max-params": [2, 18],
         "max-statements": [2, 100],
         "multiline-comment-style": 0,
         "no-continue": 1,

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## **6.12.0**
+
+- [New] `parse`/`stringify`: add `decodeDotInKeys`/`encodeDotKeys` options (#488)
+- [New] `parse`: add `duplicates` option
+- [New] `parse`/`stringify`: add `allowEmptyArrays` option to allow [] in object values (#487)
+- [Refactor] `parse`/`stringify`: move allowDots config logic to its own variable
+- [Refactor] `stringify`: move option-handling code into `normalizeStringifyOptions`
+- [readme] update readme, add logos (#484)
+- [readme] `stringify`: clarify default `arrayFormat` behavior
+- [readme] fix line wrapping
+- [readme] remove dead badges
+- [Deps] update `side-channel`
+- [meta] make the dist build 50% smaller
+- [meta] add `sideEffects` flag
+- [meta] run build in prepack, not prepublish
+- [Tests] `parse`: remove useless tests; add coverage
+- [Tests] `stringify`: increase coverage
+- [Tests] use `mock-property`
+- [Tests] `stringify`: improve coverage
+- [Dev Deps] update `@ljharb/eslint-config `, `aud`, `has-override-mistake`, `has-property-descriptors`, `mock-property`, `npmignore`, `object-inspect`, `tape`
+- [Dev Deps] pin `glob`, since v10.3.8+ requires a broken `jackspeak`
+- [Dev Deps] pin `jackspeak` since 2.1.2+ depends on npm aliases, which kill the install process in npm < 6
+
 ## **6.11.2**
 - [Fix] `parse`: Fix parsing when the global Object prototype is frozen (#473)
 - [Tests] add passing test cases with empty keys (#473)

package/README.md

@@ -1,9 +1,11 @@
+<p align="center">
+    <img alt="qs" src="./logos/banner_default.png" width="800" />
+</p>
+
 # qs <sup>[![Version Badge][npm-version-svg]][package-url]</sup>
 
 [![github actions][actions-image]][actions-url]
 [![coverage][codecov-image]][codecov-url]
-[![dependency status][deps-svg]][deps-url]
-[![dev dependency status][dev-deps-svg]][dev-deps-url]
 [![License][license-image]][license-url]
 [![Downloads][downloads-image]][downloads-url]
 
@@ -53,7 +55,9 @@ var nullObject = qs.parse('a[hasOwnProperty]=b', { plainObjects: true });
 assert.deepEqual(nullObject, { a: { hasOwnProperty: 'b' } });
 ```
 
-By default parameters that would overwrite properties on the object prototype are ignored, if you wish to keep the data from those fields either use `plainObjects` as mentioned above, or set `allowPrototypes` to `true` which will allow user input to overwrite those properties. *WARNING* It is generally a bad idea to enable this option as it can cause problems when attempting to use the properties that have been overwritten. Always be careful with this option.
+By default parameters that would overwrite properties on the object prototype are ignored, if you wish to keep the data from those fields either use `plainObjects` as mentioned above, or set `allowPrototypes` to `true` which will allow user input to overwrite those properties.
+*WARNING* It is generally a bad idea to enable this option as it can cause problems when attempting to use the properties that have been overwritten.
+Always be careful with this option.
 
 ```javascript
 var protoObject = qs.parse('a[hasOwnProperty]=b', { allowPrototypes: true });
@@ -80,8 +84,8 @@ assert.deepEqual(qs.parse('foo[bar][baz]=foobarbaz'), {
 });
 ```
 
-By default, when nesting objects **qs** will only parse up to 5 children deep. This means if you attempt to parse a string like
-`'a[b][c][d][e][f][g][h][i]=j'` your resulting object will be:
+By default, when nesting objects **qs** will only parse up to 5 children deep.
+This means if you attempt to parse a string like `'a[b][c][d][e][f][g][h][i]=j'` your resulting object will be:
 
 ```javascript
 var expected = {
@@ -147,32 +151,44 @@ var withDots = qs.parse('a.b=c', { allowDots: true });
 assert.deepEqual(withDots, { a: { b: 'c' } });
 ```
 
-If you have to deal with legacy browsers or services, there's
-also support for decoding percent-encoded octets as iso-8859-1:
+Option `decodeDotInKeys` can be used to decode dots in keys
+Note: it implies `allowDots`, so `parse` will error if you set `decodeDotInKeys` to `true`, and `allowDots` to `false`.
+
+```javascript
+var withDots = qs.parse('name%252Eobj.first=John&name%252Eobj.last=Doe', { decodeDotInKeys: true });
+assert.deepEqual(withDots, { 'name.obj': { first: 'John', last: 'Doe' }});
+```
+
+Option `allowEmptyArrays` can be used to allowing empty array values in object
+```javascript
+var withEmptyArrays = qs.parse('foo[]&bar=baz', { allowEmptyArrays: true });
+assert.deepEqual(withEmptyArrays, { foo: [], bar: 'baz' });
+```
+
+Option `duplicates` can be used to change the behavior when duplicate keys are encountered
+```javascript
+assert.deepEqual(qs.parse('foo=bar&foo=baz'), { foo: ['bar', 'baz'] });
+assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'combine' }), { foo: ['bar', 'baz'] });
+assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'first' }), { foo: 'bar' });
+assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'last' }), { foo: 'baz' });
+```
+
+If you have to deal with legacy browsers or services, there's also support for decoding percent-encoded octets as iso-8859-1:
 
 ```javascript
 var oldCharset = qs.parse('a=%A7', { charset: 'iso-8859-1' });
 assert.deepEqual(oldCharset, { a: '§' });
 ```
 
-Some services add an initial `utf8=✓` value to forms so that old
-Internet Explorer versions are more likely to submit the form as
-utf-8. Additionally, the server can check the value against wrong
-encodings of the checkmark character and detect that a query string
-or `application/x-www-form-urlencoded` body was *not* sent as
-utf-8, eg. if the form had an `accept-charset` parameter or the
-containing page had a different character set.
+Some services add an initial `utf8=✓` value to forms so that old Internet Explorer versions are more likely to submit the form as utf-8.
+Additionally, the server can check the value against wrong encodings of the checkmark character and detect that a query string or `application/x-www-form-urlencoded` body was *not* sent as utf-8, eg. if the form had an `accept-charset` parameter or the containing page had a different character set.
 
 **qs** supports this mechanism via the `charsetSentinel` option.
-If specified, the `utf8` parameter will be omitted from the
-returned object. It will be used to switch to `iso-8859-1`/`utf-8`
-mode depending on how the checkmark is encoded.
+If specified, the `utf8` parameter will be omitted from the returned object.
+It will be used to switch to `iso-8859-1`/`utf-8` mode depending on how the checkmark is encoded.
 
-**Important**: When you specify both the `charset` option and the
-`charsetSentinel` option, the `charset` will be overridden when
-the request contains a `utf8` parameter from which the actual
-charset can be deduced. In that sense the `charset` will behave
-as the default charset rather than the authoritative charset.
+**Important**: When you specify both the `charset` option and the `charsetSentinel` option, the `charset` will be overridden when the request contains a `utf8` parameter from which the actual charset can be deduced.
+In that sense the `charset` will behave as the default charset rather than the authoritative charset.
 
 ```javascript
 var detectedAsUtf8 = qs.parse('utf8=%E2%9C%93&a=%C3%B8', {
@@ -189,8 +205,7 @@ var detectedAsIso8859_1 = qs.parse('utf8=%26%2310003%3B&a=%F8', {
 assert.deepEqual(detectedAsIso8859_1, { a: 'ø' });
 ```
 
-If you want to decode the `&#...;` syntax to the actual character,
-you can specify the `interpretNumericEntities` option as well:
+If you want to decode the `&#...;` syntax to the actual character, you can specify the `interpretNumericEntities` option as well:
 
 ```javascript
 var detectedAsIso8859_1 = qs.parse('a=%26%239786%3B', {
@@ -200,8 +215,7 @@ var detectedAsIso8859_1 = qs.parse('a=%26%239786%3B', {
 assert.deepEqual(detectedAsIso8859_1, { a: '☺' });
 ```
 
-It also works when the charset has been detected in `charsetSentinel`
-mode.
+It also works when the charset has been detected in `charsetSentinel` mode.
 
 ### Parsing Arrays
 
@@ -219,9 +233,8 @@ var withIndexes = qs.parse('a[1]=c&a[0]=b');
 assert.deepEqual(withIndexes, { a: ['b', 'c'] });
 ```
 
-Note that the only difference between an index in an array and a key in an object is that the value between the brackets must be a number
-to create an array. When creating arrays with specific indices, **qs** will compact a sparse array to only the existing values preserving
-their order:
+Note that the only difference between an index in an array and a key in an object is that the value between the brackets must be a number to create an array.
+When creating arrays with specific indices, **qs** will compact a sparse array to only the existing values preserving their order:
 
 ```javascript
 var noSparse = qs.parse('a[1]=b&a[15]=c');
@@ -245,8 +258,9 @@ var withIndexedEmptyString = qs.parse('a[0]=b&a[1]=&a[2]=c');
 assert.deepEqual(withIndexedEmptyString, { a: ['b', '', 'c'] });
 ```
 
-**qs** will also limit specifying indices in an array to a maximum index of `20`. Any array members with an index of greater than `20` will
-instead be converted to an object with the index as the key. This is needed to handle cases when someone sent, for example, `a[999999999]` and it will take significant time to iterate over this huge array.
+**qs** will also limit specifying indices in an array to a maximum index of `20`.
+Any array members with an index of greater than `20` will instead be converted to an object with the index as the key.
+This is needed to handle cases when someone sent, for example, `a[999999999]` and it will take significant time to iterate over this huge array.
 
 ```javascript
 var withMaxIndex = qs.parse('a[100]=b');
@@ -290,7 +304,8 @@ assert.deepEqual(arraysOfObjects, { a: ['b', 'c'] })
 
 ### Parsing primitive/scalar values (numbers, booleans, null, etc)
 
-By default, all values are parsed as strings. This behavior will not change and is explained in [issue #91](https://github.com/ljharb/qs/issues/91).
+By default, all values are parsed as strings.
+This behavior will not change and is explained in [issue #91](https://github.com/ljharb/qs/issues/91).
 
 ```javascript
 var primitiveValues = qs.parse('a=15&b=true&c=null');
@@ -373,16 +388,17 @@ var decoded = qs.parse('x=z', { decoder: function (str, defaultDecoder, charset,
 }})
 ```
 
-Examples beyond this point will be shown as though the output is not URI encoded for clarity. Please note that the return values in these cases *will* be URI encoded during real usage.
+Examples beyond this point will be shown as though the output is not URI encoded for clarity.
+Please note that the return values in these cases *will* be URI encoded during real usage.
 
-When arrays are stringified, by default they are given explicit indices:
+When arrays are stringified, they follow the `arrayFormat` option, which defaults to `indices`:
 
 ```javascript
 qs.stringify({ a: ['b', 'c', 'd'] });
 // 'a[0]=b&a[1]=c&a[2]=d'
 ```
 
-You may override this by setting the `indices` option to `false`:
+You may override this by setting the `indices` option to `false`, or to be more explicit, the `arrayFormat` option to `repeat`:
 
 ```javascript
 qs.stringify({ a: ['b', 'c', 'd'] }, { indices: false });
@@ -418,6 +434,20 @@ qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { allowDots: true });
 // 'a.b.c=d&a.b.e=f'
 ```
 
+You may encode the dot notation in the keys of object with option `encodeDotInKeys` by setting it to `true`:
+Note: it implies `allowDots`, so `stringify` will error if you set `decodeDotInKeys` to `true`, and `allowDots` to `false`.
+Caveat: when `encodeValuesOnly` is `true` as well as `encodeDotInKeys`, only dots in keys and nothing else will be encoded.
+```javascript
+qs.stringify({ "name.obj": { "first": "John", "last": "Doe" } }, { allowDots: true, encodeDotInKeys: true })
+// 'name%252Eobj.first=John&name%252Eobj.last=Doe'
+```
+
+You may allow empty array values by setting the `allowEmptyArrays` option to `true`:
+```javascript
+qs.stringify({ foo: [], bar: 'baz' }, { allowEmptyArrays: true });
+// 'foo[]&bar=baz'
+```
+
 Empty strings and null values will omit the value, but the equals sign (=) remains in place:
 
 ```javascript
@@ -473,8 +503,8 @@ assert.equal(qs.stringify({ a: 'c', z: 'y', b : 'f' }, { sort: alphabeticalSort
 ```
 
 Finally, you can use the `filter` option to restrict which keys will be included in the stringified output.
-If you pass a function, it will be called for each key to obtain the replacement value. Otherwise, if you
-pass an array, it will be used to select properties and array indices for stringification:
+If you pass a function, it will be called for each key to obtain the replacement value.
+Otherwise, if you pass an array, it will be used to select properties and array indices for stringification:
 
 ```javascript
 function filterFunc(prefix, value) {
@@ -498,8 +528,8 @@ qs.stringify({ a: ['b', 'c', 'd'], e: 'f' }, { filter: ['a', 0, 2] });
 // 'a[0]=b&a[2]=d'
 ```
 
-You could also use `filter` to inject custom serialization for user defined types. Consider you're working with
-some api that expects query strings of the format for ranges:
+You could also use `filter` to inject custom serialization for user defined types.
+Consider you're working with some api that expects query strings of the format for ranges:
 
 ```
 https://domain.com/endpoint?range=30...70
@@ -545,7 +575,8 @@ var withNull = qs.stringify({ a: null, b: '' });
 assert.equal(withNull, 'a=&b=');
 ```
 
-Parsing does not distinguish between parameters with and without equal signs. Both are converted to empty strings.
+Parsing does not distinguish between parameters with and without equal signs.
+Both are converted to empty strings.
 
 ```javascript
 var equalsInsensitive = qs.parse('a&b=');
@@ -574,25 +605,21 @@ var nullsSkipped = qs.stringify({ a: 'b', c: null}, { skipNulls: true });
 assert.equal(nullsSkipped, 'a=b');
 ```
 
-If you're communicating with legacy systems, you can switch to `iso-8859-1`
-using the `charset` option:
+If you're communicating with legacy systems, you can switch to `iso-8859-1` using the `charset` option:
 
 ```javascript
 var iso = qs.stringify({ æ: 'æ' }, { charset: 'iso-8859-1' });
 assert.equal(iso, '%E6=%E6');
 ```
 
-Characters that don't exist in `iso-8859-1` will be converted to numeric
-entities, similar to what browsers do:
+Characters that don't exist in `iso-8859-1` will be converted to numeric entities, similar to what browsers do:
 
 ```javascript
 var numeric = qs.stringify({ a: '☺' }, { charset: 'iso-8859-1' });
 assert.equal(numeric, 'a=%26%239786%3B');
 ```
 
-You can use the `charsetSentinel` option to announce the character by
-including an `utf8=✓` parameter with the proper encoding if the checkmark,
-similar to what Ruby on Rails and others do when submitting forms.
+You can use the `charsetSentinel` option to announce the character by including an `utf8=✓` parameter with the proper encoding if the checkmark, similar to what Ruby on Rails and others do when submitting forms.
 
 ```javascript
 var sentinel = qs.stringify({ a: '☺' }, { charsetSentinel: true });
@@ -604,8 +631,7 @@ assert.equal(isoSentinel, 'utf8=%26%2310003%3B&a=%E6');
 
 ### Dealing with special character sets
 
-By default the encoding and decoding of characters is done in `utf-8`,
-and `iso-8859-1` support is also built in via the `charset` parameter.
+By default the encoding and decoding of characters is done in `utf-8`, and `iso-8859-1` support is also built in via the `charset` parameter.
 
 If you wish to encode querystrings to a different character set (i.e.
 [Shift JIS](https://en.wikipedia.org/wiki/Shift_JIS)) you can use the
@@ -644,7 +670,9 @@ Please email [@ljharb](https://github.com/ljharb) or see https://tidelift.com/se
 
 Available as part of the Tidelift Subscription
 
-The maintainers of qs and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-qs?utm_source=npm-qs&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
+The maintainers of qs and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications.
+Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use.
+[Learn more.](https://tidelift.com/subscription/pkg/npm-qs?utm_source=npm-qs&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
 
 [package-url]: https://npmjs.org/package/qs
 [npm-version-svg]: https://versionbadg.es/ljharb/qs.svg
@@ -661,3 +689,9 @@ The maintainers of qs and thousands of other packages are working with Tidelift
 [codecov-url]: https://app.codecov.io/gh/ljharb/qs/
 [actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/qs
 [actions-url]: https://github.com/ljharb/qs/actions
+
+## Acknowledgements
+
+qs logo by [NUMI](https://github.com/numi-hq/open-design):
+
+[<img src="https://raw.githubusercontent.com/numi-hq/open-design/main/assets/numi-lockup.png" alt="NUMI Logo" style="width: 200px;"/>](https://numi.tech/?ref=qs)