Custom stringify arrays and objects

README.md

@@ -381,6 +381,8 @@ qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'repeat' })
 // 'a=b&a=c'
 qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'comma' })
 // 'a=b,c'
+qs.stringify({ a: ['b', 'c'] }, { arrayFormat: function customFormat(prefix, key) { return prefix + '-' + key; } })
+// 'a-0=b&a-1=c'
 ```
 
 When objects are stringified, by default they use bracket notation:
@@ -390,11 +392,17 @@ qs.stringify({ a: { b: { c: 'd', e: 'f' } } });
 // 'a[b][c]=d&a[b][e]=f'
 ```
 
-You may override this to use dot notation by setting the `allowDots` option to `true`:
+You may use the `objectFormat` option to specify the format of the output object:
 
 ```javascript
-qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { allowDots: true });
+qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { arrayFormat: 'dots' });
 // 'a.b.c=d&a.b.e=f'
+qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { arrayFormat: 'brackets' });
+// 'a[b][c]=d&a[b][e]=f'
+qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { arrayFormat: 'curly' });
+// 'a{b}{c}=d&a{b}{e}=f'
+qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { arrayFormat: function customFormat(prefix, key) { return prefix + '/' + key; } });
+// 'a/b/c=d&a/b/e=f'
 ```
 
 Empty strings and null values will omit the value, but the equals sign (=) remains in place:

dist/qs.js

@@ -329,6 +329,18 @@ var arrayPrefixGenerators = {
     }
 };
 
+var objectPrefixGenerators = {
+    brackets: function brackets(prefix, key) {
+        return prefix + '[' + key + ']';
+    },
+    curly: function curly(prefix, key) {
+        return prefix + '{' + key + '}';
+    },
+    dots: function dots(prefix, key) {
+        return prefix + '.' + key;
+    }
+};
+
 var isArray = Array.isArray;
 var push = Array.prototype.push;
 var pushToArray = function (arr, valueOrArray) {
@@ -340,6 +352,7 @@ var toISO = Date.prototype.toISOString;
 var defaultFormat = formats['default'];
 var defaults = {
     addQueryPrefix: false,
+    // deprecated
     allowDots: false,
     charset: 'utf-8',
     charsetSentinel: false,
@@ -370,12 +383,12 @@ var stringify = function stringify(
     object,
     prefix,
     generateArrayPrefix,
+    generateObjectPrefix,
     strictNullHandling,
     skipNulls,
     encoder,
     filter,
     sort,
-    allowDots,
     serializeDate,
     formatter,
     encodeValuesOnly,
@@ -432,12 +445,12 @@ var stringify = function stringify(
                 obj[key],
                 typeof generateArrayPrefix === 'function' ? generateArrayPrefix(prefix, key) : prefix,
                 generateArrayPrefix,
+                generateObjectPrefix,
                 strictNullHandling,
                 skipNulls,
                 encoder,
                 filter,
                 sort,
-                allowDots,
                 serializeDate,
                 formatter,
                 encodeValuesOnly,
@@ -446,14 +459,14 @@ var stringify = function stringify(
         } else {
             pushToArray(values, stringify(
                 obj[key],
-                prefix + (allowDots ? '.' + key : '[' + key + ']'),
+                generateObjectPrefix(prefix, key),
                 generateArrayPrefix,
+                generateObjectPrefix,
                 strictNullHandling,
                 skipNulls,
                 encoder,
                 filter,
                 sort,
-                allowDots,
                 serializeDate,
                 formatter,
                 encodeValuesOnly,
@@ -532,16 +545,27 @@ module.exports = function (object, opts) {
         return '';
     }
 
-    var arrayFormat;
-    if (opts && opts.arrayFormat in arrayPrefixGenerators) {
-        arrayFormat = opts.arrayFormat;
+    var generateArrayPrefix;
+    if (opts && typeof opts.arrayFormat === 'function') {
+        generateArrayPrefix = opts.arrayFormat;
+    } else if (opts && opts.arrayFormat in arrayPrefixGenerators) {
+        generateArrayPrefix = arrayPrefixGenerators[opts.arrayFormat];
     } else if (opts && 'indices' in opts) {
-        arrayFormat = opts.indices ? 'indices' : 'repeat';
+        generateArrayPrefix = arrayPrefixGenerators[opts.indices ? 'indices' : 'repeat'];
     } else {
-        arrayFormat = 'indices';
+        generateArrayPrefix = arrayPrefixGenerators.indices;
     }
 
-    var generateArrayPrefix = arrayPrefixGenerators[arrayFormat];
+    var generateObjectPrefix;
+    if (opts && typeof opts.objectFormat === 'function') {
+        generateObjectPrefix = opts.objectFormat;
+    } else if (opts && opts.objectFormat in objectPrefixGenerators) {
+        generateObjectPrefix = objectPrefixGenerators[opts.objectFormat];
+    } else if (opts && opts.allowDots) {
+        generateObjectPrefix = objectPrefixGenerators.dots;
+    } else {
+        generateObjectPrefix = objectPrefixGenerators.brackets;
+    }
 
     if (!objKeys) {
         objKeys = Object.keys(obj);
@@ -561,12 +585,12 @@ module.exports = function (object, opts) {
             obj[key],
             key,
             generateArrayPrefix,
+            generateObjectPrefix,
             options.strictNullHandling,
             options.skipNulls,
             options.encode ? options.encoder : null,
             options.filter,
             options.sort,
-            options.allowDots,
             options.serializeDate,
             options.formatter,
             options.encodeValuesOnly,

lib/stringify.js

@@ -17,6 +17,18 @@ var arrayPrefixGenerators = {
     }
 };
 
+var objectPrefixGenerators = {
+    brackets: function brackets(prefix, key) {
+        return prefix + '[' + key + ']';
+    },
+    curly: function curly(prefix, key) {
+        return prefix + '{' + key + '}';
+    },
+    dots: function dots(prefix, key) {
+        return prefix + '.' + key;
+    }
+};
+
 var isArray = Array.isArray;
 var push = Array.prototype.push;
 var pushToArray = function (arr, valueOrArray) {
@@ -28,6 +40,7 @@ var toISO = Date.prototype.toISOString;
 var defaultFormat = formats['default'];
 var defaults = {
     addQueryPrefix: false,
+    // deprecated
     allowDots: false,
     charset: 'utf-8',
     charsetSentinel: false,
@@ -58,12 +71,12 @@ var stringify = function stringify(
     object,
     prefix,
     generateArrayPrefix,
+    generateObjectPrefix,
     strictNullHandling,
     skipNulls,
     encoder,
     filter,
     sort,
-    allowDots,
     serializeDate,
     formatter,
     encodeValuesOnly,
@@ -120,12 +133,12 @@ var stringify = function stringify(
                 obj[key],
                 typeof generateArrayPrefix === 'function' ? generateArrayPrefix(prefix, key) : prefix,
                 generateArrayPrefix,
+                generateObjectPrefix,
                 strictNullHandling,
                 skipNulls,
                 encoder,
                 filter,
                 sort,
-                allowDots,
                 serializeDate,
                 formatter,
                 encodeValuesOnly,
@@ -134,14 +147,14 @@ var stringify = function stringify(
         } else {
             pushToArray(values, stringify(
                 obj[key],
-                prefix + (allowDots ? '.' + key : '[' + key + ']'),
+                generateObjectPrefix(prefix, key),
                 generateArrayPrefix,
+                generateObjectPrefix,
                 strictNullHandling,
                 skipNulls,
                 encoder,
                 filter,
                 sort,
-                allowDots,
                 serializeDate,
                 formatter,
                 encodeValuesOnly,
@@ -220,16 +233,27 @@ module.exports = function (object, opts) {
         return '';
     }
 
-    var arrayFormat;
-    if (opts && opts.arrayFormat in arrayPrefixGenerators) {
-        arrayFormat = opts.arrayFormat;
+    var generateArrayPrefix;
+    if (opts && typeof opts.arrayFormat === 'function') {
+        generateArrayPrefix = opts.arrayFormat;
+    } else if (opts && opts.arrayFormat in arrayPrefixGenerators) {
+        generateArrayPrefix = arrayPrefixGenerators[opts.arrayFormat];
     } else if (opts && 'indices' in opts) {
-        arrayFormat = opts.indices ? 'indices' : 'repeat';
+        generateArrayPrefix = arrayPrefixGenerators[opts.indices ? 'indices' : 'repeat'];
     } else {
-        arrayFormat = 'indices';
+        generateArrayPrefix = arrayPrefixGenerators.indices;
     }
 
-    var generateArrayPrefix = arrayPrefixGenerators[arrayFormat];
+    var generateObjectPrefix;
+    if (opts && typeof opts.objectFormat === 'function') {
+        generateObjectPrefix = opts.objectFormat;
+    } else if (opts && opts.objectFormat in objectPrefixGenerators) {
+        generateObjectPrefix = objectPrefixGenerators[opts.objectFormat];
+    } else if (opts && opts.allowDots) {
+        generateObjectPrefix = objectPrefixGenerators.dots;
+    } else {
+        generateObjectPrefix = objectPrefixGenerators.brackets;
+    }
 
     if (!objKeys) {
         objKeys = Object.keys(obj);
@@ -249,12 +273,12 @@ module.exports = function (object, opts) {
             obj[key],
             key,
             generateArrayPrefix,
+            generateObjectPrefix,
             options.strictNullHandling,
             options.skipNulls,
             options.encode ? options.encoder : null,
             options.filter,
             options.sort,
-            options.allowDots,
             options.serializeDate,
             options.formatter,
             options.encodeValuesOnly,

test/stringify.js

@@ -284,6 +284,56 @@ test('stringify()', function (t) {
             'default => indices'
         );
 
+        st.equal(
+            qs.stringify(
+                { a: [{ b: 'c' }] },
+                { objectFormat: 'dots', encode: false, arrayFormat: 'indices' }
+            ),
+            'a[0].b=c',
+            'indices => indices'
+        );
+        st.equal(
+            qs.stringify(
+                { a: [{ b: 'c' }] },
+                { objectFormat: 'dots', encode: false, arrayFormat: 'brackets' }
+            ),
+            'a[].b=c',
+            'brackets => brackets'
+        );
+        st.equal(
+            qs.stringify(
+                { a: [{ b: 'c' }] },
+                { objectFormat: 'dots', encode: false }
+            ),
+            'a[0].b=c',
+            'default => indices'
+        );
+
+        st.equal(
+            qs.stringify(
+                { a: [{ b: { c: [1] } }] },
+                { objectFormat: 'dots', encode: false, arrayFormat: 'indices' }
+            ),
+            'a[0].b.c[0]=1',
+            'indices => indices'
+        );
+        st.equal(
+            qs.stringify(
+                { a: [{ b: { c: [1] } }] },
+                { objectFormat: 'dots', encode: false, arrayFormat: 'brackets' }
+            ),
+            'a[].b.c[]=1',
+            'brackets => brackets'
+        );
+        st.equal(
+            qs.stringify(
+                { a: [{ b: { c: [1] } }] },
+                { objectFormat: 'dots', encode: false }
+            ),
+            'a[0].b.c[0]=1',
+            'default => indices'
+        );
+
         st.end();
     });
 
@@ -317,11 +367,36 @@ test('stringify()', function (t) {
         st.end();
     });
 
+    t.test('uses custom function notation for arrays when no arrayFormat=function(){}', function (st) {
+        st.equal(qs.stringify({ a: ['b', 'c'] }, { arrayFormat: function (prefix, key) { return prefix + '-' + key; } }), 'a-0=b&a-1=c');
+        st.end();
+    });
+
     t.test('stringifies a complicated object', function (st) {
         st.equal(qs.stringify({ a: { b: 'c', d: 'e' } }), 'a%5Bb%5D=c&a%5Bd%5D=e');
         st.end();
     });
 
+    t.test('uses brackets notation for objects when no objectFormat=brackets', function (st) {
+        st.equal(qs.stringify({ a: { b: 'c', d: 'e' } }, { objectFormat: 'brackets' }), 'a%5Bb%5D=c&a%5Bd%5D=e');
+        st.end();
+    });
+
+    t.test('uses dots notation for objects when no objectFormat=dots', function (st) {
+        st.equal(qs.stringify({ a: { b: 'c', d: 'e' } }, { objectFormat: 'dots' }), 'a.b=c&a.d=e');
+        st.end();
+    });
+
+    t.test('uses curly notation for objects when no objectFormat=curly', function (st) {
+        st.equal(qs.stringify({ a: { b: 'c', d: 'e' } }, { objectFormat: 'curly' }), 'a%7Bb%7D=c&a%7Bd%7D=e');
+        st.end();
+    });
+
+    t.test('uses custom function notation for objects when no objectFormat=function(){}', function (st) {
+        st.equal(qs.stringify({ a: { b: 'c', d: 'e' } }, { objectFormat: function (prefix, key) { return prefix + '/' + key; } }), 'a%2Fb=c&a%2Fd=e');
+        st.end();
+    });
+
     t.test('stringifies an empty value', function (st) {
         st.equal(qs.stringify({ a: '' }), 'a=');
         st.equal(qs.stringify({ a: null }, { strictNullHandling: true }), 'a');