Add a filter option

README.md

@@ -232,6 +232,32 @@ Qs.stringify({ a: 'b', c: 'd' }, { delimiter: ';' });
 // 'a=b;c=d'
 ```
 
+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:
+
+```javascript
+function filterFunc(prefix, value) {
+  if (prefix == 'b') {
+    // Return an `undefined` value to omit a property.
+    return;
+  }
+  if (prefix == 'e[f]') {
+    return value.getTime();
+  }
+  if (prefix == 'e[g][0]') {
+    return value * 2;
+  }
+  return value;
+}
+Qs.stringify({ a: 'b', c: 'd', e: { f: new Date(123), g: [2] } }, { filter: filterFunc })
+// 'a=b&c=d&e[f]=123&e[g][0]=4'
+Qs.stringify({ a: 'b', c: 'd', e: 'f' }, { filter: ['a', 'e'] })
+// 'a=b&e=f'
+Qs.stringify({ a: ['b', 'c', 'd'], e: 'f' }, { filter: ['a', 0, 2] })
+// 'a[0]=b&a[2]=d'
+```
+
 ### Handling of `null` values
 
 By default, `null` values are treated like empty strings:

lib/stringify.js

@@ -25,9 +25,12 @@ var internals = {
 };
 
 
-internals.stringify = function (obj, prefix, generateArrayPrefix, strictNullHandling) {
+internals.stringify = function (obj, prefix, generateArrayPrefix, strictNullHandling, filter) {
 
-    if (Utils.isBuffer(obj)) {
+    if (typeof filter === 'function') {
+        obj = filter(prefix, obj);
+    }
+    else if (Utils.isBuffer(obj)) {
         obj = obj.toString();
     }
     else if (obj instanceof Date) {
@@ -54,15 +57,15 @@ internals.stringify = function (obj, prefix, generateArrayPrefix, strictNullHand
         return values;
     }
 
-    var objKeys = Object.keys(obj);
+    var objKeys = Array.isArray(filter) ? filter : Object.keys(obj);
     for (var i = 0, il = objKeys.length; i < il; ++i) {
         var key = objKeys[i];
 
         if (Array.isArray(obj)) {
-            values = values.concat(internals.stringify(obj[key], generateArrayPrefix(prefix, key), generateArrayPrefix, strictNullHandling));
+            values = values.concat(internals.stringify(obj[key], generateArrayPrefix(prefix, key), generateArrayPrefix, strictNullHandling, filter));
         }
         else {
-            values = values.concat(internals.stringify(obj[key], prefix + '[' + key + ']', generateArrayPrefix, strictNullHandling));
+            values = values.concat(internals.stringify(obj[key], prefix + '[' + key + ']', generateArrayPrefix, strictNullHandling, filter));
         }
     }
 
@@ -75,6 +78,15 @@ module.exports = function (obj, options) {
     options = options || {};
     var delimiter = typeof options.delimiter === 'undefined' ? internals.delimiter : options.delimiter;
     var strictNullHandling = typeof options.strictNullHandling === 'boolean' ? options.strictNullHandling : internals.strictNullHandling;
+    var objKeys;
+    var filter;
+    if (typeof options.filter === 'function') {
+        filter = options.filter;
+        obj = filter('', obj);
+    }
+    else if (Array.isArray(options.filter)) {
+        objKeys = filter = options.filter;
+    }
 
     var keys = [];
 
@@ -97,10 +109,12 @@ module.exports = function (obj, options) {
 
     var generateArrayPrefix = internals.arrayPrefixGenerators[arrayFormat];
 
-    var objKeys = Object.keys(obj);
+    if (!objKeys) {
+        objKeys = Object.keys(obj);
+    }
     for (var i = 0, il = objKeys.length; i < il; ++i) {
         var key = objKeys[i];
-        keys = keys.concat(internals.stringify(obj[key], key, generateArrayPrefix, strictNullHandling));
+        keys = keys.concat(internals.stringify(obj[key], key, generateArrayPrefix, strictNullHandling, filter));
     }
 
     return keys.join(delimiter);

test/stringify.js

@@ -215,4 +215,40 @@ describe('stringify()', function () {
         global.Buffer = tempBuffer;
         done();
     });
+
+    it('selects properties when filter=array', function (done) {
+
+        expect(Qs.stringify({ a: 'b' }, { filter: ['a'] })).to.equal('a=b');
+        expect(Qs.stringify({ a: 1}, { filter: [] })).to.equal('');
+        expect(Qs.stringify({ a: { b: [1, 2, 3, 4], c: 'd' }, c: 'f' }, { filter: ['a', 'b', 0, 2]})).to.equal('a%5Bb%5D%5B0%5D=1&a%5Bb%5D%5B2%5D=3');
+        done();
+
+    });
+
+    it('supports custom representations when filter=function', function (done) {
+
+        var calls = 0;
+        var obj = { a: 'b', c: 'd', e: { f: new Date(1257894000000) } };
+        var filterFunc = function (prefix, value) {
+
+            calls++;
+            if (calls === 1) {
+                expect(prefix).to.be.empty();
+                expect(value).to.equal(obj);
+            }
+            else if (prefix === 'c') {
+                return;
+            }
+            else if (value instanceof Date) {
+                expect(prefix).to.equal('e[f]');
+                return value.getTime();
+            }
+            return value;
+        };
+
+        expect(Qs.stringify(obj, { filter: filterFunc })).to.equal('a=b&e%5Bf%5D=1257894000000');
+        expect(calls).to.equal(5);
+        done();
+
+    });
 });