[New] parse: add strictMerge option to wrap object/primitive conflicts in an array

ljharb · ljharb · commit cb41a545a324 · 2026-02-13T09:02:24.000-08:00
When `strictMerge` is `true` (the default), merging a primitive into an object wraps both in an array instead of using the primitive as a key with value `true`. Set `strictMerge` to `false` to restore legacy behavior. Fixes #425. Fixes #122.
diff --git a/README.md b/README.md
@@ -330,6 +330,19 @@ var mixedNotation = qs.parse('a[0]=b&a[b]=c');
 assert.deepEqual(mixedNotation, { a: { '0': 'b', b: 'c' } });
 ```
 
+When a key appears as both a plain value and an object, **qs** will by default wrap the conflicting values in an array (`strictMerge` defaults to `true`):
+
+```javascript
+assert.deepEqual(qs.parse('a[b]=c&a=d'), { a: [{ b: 'c' }, 'd'] });
+assert.deepEqual(qs.parse('a=d&a[b]=c'), { a: ['d', { b: 'c' }] });
+```
+
+To restore the legacy behavior (where the primitive is used as a key with value `true`), set `strictMerge` to `false`:
+
+```javascript
+assert.deepEqual(qs.parse('a[b]=c&a=d', { strictMerge: false }), { a: { b: 'c', d: true } });
+```
+
 You can also create arrays of objects:
 
 ```javascript
diff --git a/lib/parse.js b/lib/parse.js
@@ -25,6 +25,7 @@ var defaults = {
     parseArrays: true,
     plainObjects: false,
     strictDepth: false,
+    strictMerge: true,
     strictNullHandling: false,
     throwOnLimitExceeded: false
 };
@@ -339,6 +340,7 @@ var normalizeParseOptions = function normalizeParseOptions(opts) {
         parseArrays: opts.parseArrays !== false,
         plainObjects: typeof opts.plainObjects === 'boolean' ? opts.plainObjects : defaults.plainObjects,
         strictDepth: typeof opts.strictDepth === 'boolean' ? !!opts.strictDepth : defaults.strictDepth,
+        strictMerge: typeof opts.strictMerge === 'boolean' ? !!opts.strictMerge : defaults.strictMerge,
         strictNullHandling: typeof opts.strictNullHandling === 'boolean' ? opts.strictNullHandling : defaults.strictNullHandling,
         throwOnLimitExceeded: typeof opts.throwOnLimitExceeded === 'boolean' ? opts.throwOnLimitExceeded : false
     };
diff --git a/lib/utils.js b/lib/utils.js
@@ -85,6 +85,8 @@ var merge = function merge(target, source, options) {
                 var newIndex = getMaxIndex(target) + 1;
                 target[newIndex] = source;
                 setMaxIndex(target, newIndex);
+            } else if (options && options.strictMerge) {
+                return [target, source];
             } else if (
                 (options && (options.plainObjects || options.allowPrototypes))
                 || !has.call(Object.prototype, source)
diff --git a/test/parse.js b/test/parse.js
@@ -784,32 +784,60 @@ test('parse()', function (t) {
 
     t.test('add keys to objects', function (st) {
         st.deepEqual(
-            qs.parse('a[b]=c&a=d'),
+            qs.parse('a[b]=c&a=d', { strictMerge: false }),
             { a: { b: 'c', d: true } },
             'can add keys to objects'
         );
 
         st.deepEqual(
-            qs.parse('a[b]=c&a=toString'),
+            qs.parse('a[b]=c&a=toString', { strictMerge: false }),
             { a: { b: 'c' } },
             'can not overwrite prototype'
         );
 
         st.deepEqual(
-            qs.parse('a[b]=c&a=toString', { allowPrototypes: true }),
+            qs.parse('a[b]=c&a=toString', { strictMerge: false, allowPrototypes: true }),
             { a: { b: 'c', toString: true } },
             'can overwrite prototype with allowPrototypes true'
         );
 
         st.deepEqual(
-            qs.parse('a[b]=c&a=toString', { plainObjects: true }),
+            qs.parse('a[b]=c&a=toString', { strictMerge: false, plainObjects: true }),
             { __proto__: null, a: { __proto__: null, b: 'c', toString: true } },
             'can overwrite prototype with plainObjects true'
         );
 
         st.end();
     });
 
+    t.test('strictMerge wraps object and primitive into an array', function (st) {
+        st.deepEqual(
+            qs.parse('a[b]=c&a=d'),
+            { a: [{ b: 'c' }, 'd'] },
+            'object then primitive produces array'
+        );
+
+        st.deepEqual(
+            qs.parse('a=d&a[b]=c'),
+            { a: ['d', { b: 'c' }] },
+            'primitive then object produces array'
+        );
+
+        st.deepEqual(
+            qs.parse('a[b]=c&a=toString'),
+            { a: [{ b: 'c' }, 'toString'] },
+            'prototype-colliding value is preserved in array'
+        );
+
+        st.deepEqual(
+            qs.parse('a[b]=c&a=toString', { plainObjects: true }),
+            { __proto__: null, a: [{ __proto__: null, b: 'c' }, 'toString'] },
+            'plainObjects preserved in array wrapping'
+        );
+
+        st.end();
+    });
+
     t.test('dunder proto is ignored', function (st) {
         var payload = 'categories[__proto__]=login&categories[__proto__]&categories[length]=42';
         var result = qs.parse(payload, { allowPrototypes: true });
diff --git a/test/utils.js b/test/utils.js
@@ -95,6 +95,13 @@ test('merge()', function (t) {
             s2t.end();
         });
 
+        st.test('with strictMerge, wraps object and primitive in array', function (s2t) {
+            var obj = { foo: 'bar' };
+            var merged = utils.merge(obj, 'baz', { strictMerge: true });
+            s2t.deepEqual(merged, [{ foo: 'bar' }, 'baz'], 'wraps in array with strictMerge');
+            s2t.end();
+        });
+
         st.test('merges overflow object into primitive', function (s2t) {
             // Create an overflow object via combine: 2 elements (indices 0-1) with limit 0
             var overflow = utils.combine(['a'], 'b', 0, false);
