qs 6.5.0 → 6.6.0

package/.eslintrc

@@ -4,12 +4,15 @@
     "extends": "@ljharb",
 
     "rules": {
-        "complexity": [2, 28],
+        "complexity": 0,
         "consistent-return": 1,
+		"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.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)
+- [Dev Deps] update `browserify`, `eslint`, `iconv-lite`, `safer-buffer`, `tape`, `browserify`
+
+## **6.5.1**
+- [Fix] Fix parsing & compacting very deep objects (#224)
+- [Refactor] name utils functions
+- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `tape`
+- [Tests] up to `node` `v8.4`; use `nvm install-latest-npm` so newer npm doesn’t break older node
+- [Tests] Use precise dist for Node.js 0.6 runtime (#225)
+- [Tests] make 0.6 required, now that it’s passing
+- [Tests] on `node` `v8.2`; fix npm on node 0.6
+
 ## **6.5.0**
 - [New] add `utils.assign`
 - [New] pass default encoder/decoder to custom encoder/decoder functions (#206)

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:
@@ -426,10 +482,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: