qs 6.5.2 → 6.7.0

package/.editorconfig

@@ -7,7 +7,7 @@ end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
-max_line_length = 140
+max_line_length = 160
 
 [test/*]
 max_line_length = off

package/.eslintrc

@@ -9,8 +9,10 @@
 		"func-name-matching": 0,
         "id-length": [2, { "min": 1, "max": 25, "properties": "never" }],
         "indent": [2, 4],
-        "max-params": [2, 12],
-        "max-statements": [2, 45],
+        "max-lines-per-function": [2, { "max": 150 }],
+        "max-params": [2, 14],
+        "max-statements": [2, 52],
+        "multiline-comment-style": 0,
         "no-continue": 1,
         "no-magic-numbers": 0,
         "no-restricted-syntax": [2, "BreakStatement", "DebuggerStatement", "ForInStatement", "LabeledStatement", "WithStatement"],

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+## **6.7.0**
+- [New] `stringify`/`parse`: add `comma` as an `arrayFormat` option (#276, #219)
+- [Fix] correctly parse nested arrays (#212)
+- [Fix] `utils.merge`: avoid a crash with a null target and a truthy non-array source, also with an array source
+- [Robustness] `stringify`: cache `Object.prototype.hasOwnProperty`
+- [Refactor] `utils`: `isBuffer`: small tweak; add tests
+- [Refactor] use cached `Array.isArray`
+- [Refactor] `parse`/`stringify`: make a function to normalize the options
+- [Refactor] `utils`: reduce observable [[Get]]s
+- [Refactor] `stringify`/`utils`: cache `Array.isArray`
+- [Tests] always use `String(x)` over `x.toString()`
+- [Tests] fix Buffer tests to work in node < 4.5 and node < 5.10
+- [Tests] temporarily allow coverage to fail
+
+## **6.6.0**
+- [New] Add support for iso-8859-1, utf8 "sentinel" and numeric entities (#268)
+- [New] move two-value combine to a `utils` function (#189)
+- [Fix] `stringify`: fix a crash with `strictNullHandling` and a custom `filter`/`serializeDate` (#279)
+- [Fix] when `parseArrays` is false, properly handle keys ending in `[]` (#260)
+- [Fix] `stringify`: do not crash in an obscure combo of `interpretNumericEntities`, a bad custom `decoder`, & `iso-8859-1`
+- [Fix] `utils`: `merge`: fix crash when `source` is a truthy primitive & no options are provided
+- [refactor] `stringify`: Avoid arr = arr.concat(...), push to the existing instance (#269)
+- [Refactor] `parse`: only need to reassign the var once
+- [Refactor] `parse`/`stringify`: clean up `charset` options checking; fix defaults
+- [Refactor] add missing defaults
+- [Refactor] `parse`: one less `concat` call
+- [Refactor] `utils`: `compactQueue`: make it explicitly side-effecting
+- [Dev Deps] update `browserify`, `eslint`, `@ljharb/eslint-config`, `iconv-lite`, `safe-publish-latest`, `tape`
+- [Tests] up to `node` `v10.10`, `v9.11`, `v8.12`, `v6.14`, `v4.9`; pin included builds to LTS
+
 ## **6.5.2**
 - [Fix] use `safer-buffer` instead of `Buffer` constructor
 - [Refactor] utils: `module.exports` one thing, instead of mutating `exports` (#230)

package/README.md

@@ -146,6 +146,62 @@ 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:
+
+```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.
+
+**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.
+
+**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', {
+    charset: 'iso-8859-1',
+    charsetSentinel: true
+});
+assert.deepEqual(detectedAsUtf8, { a: 'ø' });
+
+// Browsers encode the checkmark as ✓ when submitting as iso-8859-1:
+var detectedAsIso8859_1 = qs.parse('utf8=%26%2310003%3B&a=%F8', {
+    charset: 'utf-8',
+    charsetSentinel: true
+});
+assert.deepEqual(detectedAsIso8859_1, { a: 'ø' });
+```
+
+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', {
+    charset: 'iso-8859-1',
+    interpretNumericEntities: true
+});
+assert.deepEqual(detectedAsIso8859_1, { a: '☺' });
+```
+
+It also works when the charset has been detected in `charsetSentinel`
+mode.
+
 ### Parsing Arrays
 
 **qs** can also parse arrays using a similar `[]` notation:
@@ -182,7 +238,7 @@ 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:
+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');
@@ -217,6 +273,13 @@ var arraysOfObjects = qs.parse('a[][b]=c');
 assert.deepEqual(arraysOfObjects, { a: [{ b: 'c' }] });
 ```
 
+Some people use comma to join array, **qs** can parse it:
+```javascript
+var arraysOfObjects = qs.parse('a=b,c', { comma: true })
+assert.deepEqual(arraysOfObjects, { a: ['b', 'c'] })
+```
+(_this cannot convert nested objects, such as `a={b:1},{c:d}`_)
+
 ### Stringifying
 
 [](#preventEval)
@@ -292,6 +355,8 @@ qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'brackets' })
 // 'a[]=b&a[]=c'
 qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'repeat' })
 // 'a=b&a=c'
+qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'comma' })
+// 'a=b,c'
 ```
 
 When objects are stringified, by default they use bracket notation:
@@ -426,10 +491,40 @@ 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:
+
+```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:
+
+```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.
+
+```javascript
+var sentinel = qs.stringify({ a: '☺' }, { charsetSentinel: true });
+assert.equal(sentinel, 'utf8=%E2%9C%93&a=%E2%98%BA');
+
+var isoSentinel = qs.stringify({ a: 'æ' }, { charsetSentinel: true, charset: 'iso-8859-1' });
+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`. If you
-wish to encode querystrings to a different character set (i.e.
+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
 [`qs-iconv`](https://github.com/martinheidegger/qs-iconv) library: