qs 1.0.0 → 1.2.0

package/README.md

@@ -6,7 +6,7 @@ A querystring parsing and stringifying library with some added security.
 
 Lead Maintainer: [Nathan LaFreniere](https://github.com/nlf)
 
-The **qs** module was original created and maintained by [TJ Holowaychuk](https://github.com/visionmedia/node-querystring).
+The **qs** module was originally created and maintained by [TJ Holowaychuk](https://github.com/visionmedia/node-querystring).
 
 ## Usage
 
@@ -17,7 +17,11 @@ var obj = Qs.parse('a=c');    // { a: 'c' }
 var str = Qs.stringify(obj);  // 'a=c'
 ```
 
-### Objects
+### Parsing Objects
+
+```javascript
+Qs.parse(string, [depth], [delimiter]);
+```
 
 **qs** allows you to create nested objects within your query strings, by surrounding the name of sub-keys with square brackets `[]`.
 For example, the string `'foo[bar]=baz'` converts to:
@@ -30,6 +34,13 @@ For example, the string `'foo[bar]=baz'` converts to:
 }
 ```
 
+URI encoded strings work too:
+
+```javascript
+Qs.parse('a%5Bb%5D=c');
+// { a: { b: 'c' } }
+```
+
 You can also nest your objects, like `'foo[bar][baz]=foobarbaz'`:
 
 ```javascript
@@ -72,7 +83,14 @@ Qs.parse('a[b][c][d][e][f][g][h][i]=j', 1);
 
 The depth limit mitigate abuse when **qs** is used to parse user input, and it is recommended to keep it a reasonably small number.
 
-### Arrays
+An optional delimiter can also be passed:
+
+```javascript
+Qs.parse('a=b;c=d', ';');
+// { a: 'b', c: 'd' }
+```
+
+### Parsing Arrays
 
 **qs** can also parse arrays using a similar `[]` notation:
 
@@ -97,6 +115,15 @@ Qs.parse('a[1]=b&a[15]=c');
 // { a: ['b', 'c'] }
 ```
 
+Note that an empty string is also a value, and will be preserved:
+
+```javascript
+Qs.parse('a[]=&a[]=b');
+// { a: ['', 'b'] }
+Qs.parse('a[0]=b&a[1]=&a[2]=c');
+// { 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:
 
@@ -117,4 +144,48 @@ You can also create arrays of objects:
 ```javascript
 Qs.parse('a[][b]=c');
 // { a: [{ b: 'c' }] }
-```
+```
+
+### Stringifying
+
+```javascript
+Qs.stringify(object, [delimiter]);
+```
+
+When stringifying, **qs** always URI encodes output. Objects are stringified as you would expect:
+
+```javascript
+Qs.stringify({ a: 'b' });
+// 'a=b'
+Qs.stringify({ a: { b: 'c' } });
+// 'a%5Bb%5D=c'
+```
+
+Examples beyond this point will be shown as though the output is not URI encoded for clarity. Please note that the return values in these cases *will* be URI encoded during real usage.
+
+When arrays are stringified, they are always given explicit indices:
+
+```javascript
+Qs.stringify({ a: ['b', 'c', 'd'] });
+// 'a[0]=b&a[1]=c&a[2]=d'
+```
+
+Empty strings and null values will omit the value, but the equals sign (=) remains in place:
+
+```javascript
+Qs.stringify({ a: '' });
+// 'a='
+```
+
+Properties that are set to `undefined` will be omitted entirely:
+
+```javascript
+Qs.stringify({ a: null, b: undefined });
+// 'a='
+```
+
+The delimiter may be overridden with stringify as well:
+
+```javascript
+Qs.stringify({ a: 'b', c: 'd' }, ';');
+// 'a=b;c=d'

package/lib/parse.js

@@ -6,16 +6,19 @@ var Utils = require('./utils');
 // Declare internals
 
 var internals = {
+    delimiter: '&',
     depth: 5,
     arrayLimit: 20,
     parametersLimit: 1000
 };
 
 
-internals.parseValues = function (str) {
+internals.parseValues = function (str, delimiter) {
+
+    delimiter = typeof delimiter === 'undefined' ? internals.delimiter : delimiter;
 
     var obj = {};
-    var parts = str.split('&').slice(0, internals.parametersLimit);
+    var parts = str.split(delimiter, internals.parametersLimit);
 
     for (var i = 0, il = parts.length; i < il; ++i) {
         var part = parts[i];
@@ -79,8 +82,6 @@ internals.parseKeys = function (key, val, depth) {
         return;
     }
 
-    depth = typeof depth === 'undefined' ? internals.depth : depth;
-
     // The regex chunks
 
     var parent = /^([^\[\]]*)/;
@@ -124,7 +125,7 @@ internals.parseKeys = function (key, val, depth) {
 };
 
 
-module.exports = function (str, depth) {
+module.exports = function (str, depth, delimiter) {
 
     if (str === '' ||
         str === null ||
@@ -133,11 +134,16 @@ module.exports = function (str, depth) {
         return {};
     }
 
-    var tempObj = typeof str === 'string' ? internals.parseValues(str) : Utils.clone(str);
+    if (typeof depth !== 'number') {
+        delimiter = depth;
+        depth = internals.depth;
+    }
+
+    var tempObj = typeof str === 'string' ? internals.parseValues(str, delimiter) : Utils.clone(str);
     var obj = {};
 
     // Iterate over the keys and setup the new object
-
+    //
     for (var key in tempObj) {
         if (tempObj.hasOwnProperty(key)) {
             var newObj = internals.parseKeys(key, tempObj[key], depth);

package/lib/stringify.js

@@ -3,26 +3,35 @@
 
 // Declare internals
 
-var internals = {};
+var internals = {
+    delimiter: '&'
+};
 
 
 internals.stringify = function (obj, prefix) {
 
-    if (typeof obj === 'string' ||
-        typeof obj === 'number') {
-
-        return [prefix + '=' + encodeURIComponent(obj)];
+    if (Buffer.isBuffer(obj)) {
+        obj = obj.toString();
+    }
+    else if (obj instanceof Date) {
+        obj = obj.toISOString();
+    }
+    else if (obj === null) {
+        obj = '';
     }
 
-    if (obj === null) {
-        return [prefix];
+    if (typeof obj === 'string' ||
+        typeof obj === 'number' ||
+        typeof obj === 'boolean') {
+
+        return [encodeURIComponent(prefix) + '=' + encodeURIComponent(obj)];
     }
 
     var values = [];
 
     for (var key in obj) {
         if (obj.hasOwnProperty(key)) {
-            values = values.concat(internals.stringify(obj[key], prefix + '[' + encodeURIComponent(key) + ']'));
+            values = values.concat(internals.stringify(obj[key], prefix + '[' + key + ']'));
         }
     }
 
@@ -30,16 +39,17 @@ internals.stringify = function (obj, prefix) {
 };
 
 
-module.exports = function (obj) {
+module.exports = function (obj, delimiter) {
+
+    delimiter = typeof delimiter === 'undefined' ? internals.delimiter : delimiter;
 
     var keys = [];
-    var value = JSON.parse(JSON.stringify(obj));
 
-    for (var key in value) {
-        if (value.hasOwnProperty(key)) {
-            keys = keys.concat(internals.stringify(value[key], encodeURIComponent(key)));
+    for (var key in obj) {
+        if (obj.hasOwnProperty(key)) {
+            keys = keys.concat(internals.stringify(obj[key], key));
         }
     }
 
-    return keys.join('&');
+    return keys.join(delimiter);
 };

package/lib/utils.js

@@ -10,7 +10,10 @@ exports.arrayToObject = function (source) {
 
     var obj = {};
     for (var i = 0, il = source.length; i < il; ++i) {
-        obj[i] = source[i];
+        if (typeof source[i] !== 'undefined') {
+
+            obj[i] = source[i];
+        }
     }
 
     return obj;
@@ -50,8 +53,13 @@ exports.merge = function (target, source) {
 
     if (Array.isArray(source)) {
         for (var i = 0, il = source.length; i < il; ++i) {
-            if (source[i] !== undefined) {
-                obj[i] = source[i];
+            if (typeof source[i] !== 'undefined') {
+                if (typeof obj[i] === 'object') {
+                    obj[i] = exports.merge(obj[i], source[i]);
+                }
+                else {
+                    obj[i] = source[i];
+                }
             }
         }
 
@@ -110,9 +118,7 @@ exports.compact = function (obj) {
                 compacted[key] = [];
 
                 for (var i = 0, l = obj[key].length; i < l; i++) {
-                    if (obj[key].hasOwnProperty(i) &&
-                        obj[key][i]) {
-
+                    if (typeof obj[key][i] !== 'undefined') {
                         compacted[key].push(obj[key][i]);
                     }
                 }

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "qs",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A querystring parser that supports nesting and arrays, with a depth limit",
   "homepage": "https://github.com/hapijs/qs",
   "main": "index.js",
-  "dependencies": {
-  },
+  "dependencies": {},
   "devDependencies": {
     "lab": "3.x.x"
   },

package/test/parse.js

@@ -138,6 +138,13 @@ describe('#parse', function () {
         expect(Qs.parse('foo[bad]=baz&foo[]=bar')).to.deep.equal({ foo: { bad: 'baz', '0': 'bar' } });
         expect(Qs.parse('foo[]=bar&foo[bad]=baz')).to.deep.equal({ foo: { '0': 'bar', bad: 'baz' } });
         expect(Qs.parse('foo[bad]=baz&foo[]=bar&foo[]=foo')).to.deep.equal({ foo: { bad: 'baz', '0': 'bar', '1': 'foo' } });
+        expect(Qs.parse('foo[0][a]=a&foo[0][b]=b&foo[1][a]=aa&foo[1][b]=bb')).to.deep.equal({foo: [ {a: 'a', b: 'b'}, {a: 'aa', b: 'bb'} ]});
+        done();
+    });
+
+    it('correctly prunes undefined values when converting an array to an object', function (done) {
+
+        expect(Qs.parse('a[2]=b&a[99999999]=c')).to.deep.equal({ a: { '2': 'b', '99999999': 'c' } });
         done();
     });
 
@@ -178,6 +185,13 @@ describe('#parse', function () {
         done();
     });
 
+    it('allows for empty strings in arrays', function (done) {
+
+        expect(Qs.parse('a[]=b&a[]=&a[]=c')).to.deep.equal({ a: ['b', '', 'c'] });
+        expect(Qs.parse('a[0]=b&a[1]=&a[2]=c&a[19]=')).to.deep.equal({ a: ['b', '', 'c', ''] });
+        done();
+    });
+
     it('should compact sparse arrays', function (done) {
 
         expect(Qs.parse('a[10]=1&a[2]=2')).to.deep.equal({ a: ['2', '1'] });
@@ -223,8 +237,19 @@ describe('#parse', function () {
     it('should not throw when a native prototype has an enumerable property', { parallel: false }, function (done) {
 
         Object.prototype.crash = '';
-        expect(Qs.parse.bind(null, 'test')).to.not.throw();
+        Array.prototype.crash = '';
+        expect(Qs.parse.bind(null, 'a=b')).to.not.throw();
+        expect(Qs.parse('a=b')).to.deep.equal({ a: 'b' });
+        expect(Qs.parse.bind(null, 'a[][b]=c')).to.not.throw();
+        expect(Qs.parse('a[][b]=c')).to.deep.equal({ a: [{ b: 'c' }] });
         delete Object.prototype.crash;
+        delete Array.prototype.crash;
+        done();
+    });
+
+    it('parses a string with an alternative delimiter', function (done) {
+
+        expect(Qs.parse('a=b;c=d', ';')).to.deep.equal({ a: 'b', c: 'd' });
         done();
     });
 });

package/test/stringify.js

@@ -30,33 +30,33 @@ describe('#stringify', function () {
 
     it('stringifies a nested object', function (done) {
 
-        expect(Qs.stringify({ a: { b: 'c' } })).to.equal('a[b]=c');
-        expect(Qs.stringify({ a: { b: { c: { d: 'e' } } } })).to.equal('a[b][c][d]=e');
+        expect(Qs.stringify({ a: { b: 'c' } })).to.equal('a%5Bb%5D=c');
+        expect(Qs.stringify({ a: { b: { c: { d: 'e' } } } })).to.equal('a%5Bb%5D%5Bc%5D%5Bd%5D=e');
         done();
     });
 
     it('stringifies an array value', function (done) {
 
-        expect(Qs.stringify({ a: ['b', 'c', 'd'] })).to.equal('a[0]=b&a[1]=c&a[2]=d');
+        expect(Qs.stringify({ a: ['b', 'c', 'd'] })).to.equal('a%5B0%5D=b&a%5B1%5D=c&a%5B2%5D=d');
         done();
     });
 
     it('stringifies a nested array value', function (done) {
 
-        expect(Qs.stringify({ a: { b: ['c', 'd'] } })).to.equal('a[b][0]=c&a[b][1]=d');
+        expect(Qs.stringify({ a: { b: ['c', 'd'] } })).to.equal('a%5Bb%5D%5B0%5D=c&a%5Bb%5D%5B1%5D=d');
         done();
     });
 
     it('stringifies an object inside an array', function (done) {
 
-        expect(Qs.stringify({ a: [{ b: 'c' }] })).to.equal('a[0][b]=c');
-        expect(Qs.stringify({ a: [{ b: { c: [1] } }] })).to.equal('a[0][b][c][0]=1');
+        expect(Qs.stringify({ a: [{ b: 'c' }] })).to.equal('a%5B0%5D%5Bb%5D=c');
+        expect(Qs.stringify({ a: [{ b: { c: [1] } }] })).to.equal('a%5B0%5D%5Bb%5D%5Bc%5D%5B0%5D=1');
         done();
     });
 
     it('stringifies a complicated object', function (done) {
 
-        expect(Qs.stringify({ a: { b: 'c', d: 'e' } })).to.equal('a[b]=c&a[d]=e');
+        expect(Qs.stringify({ a: { b: 'c', d: 'e' } })).to.equal('a%5Bb%5D=c&a%5Bd%5D=e');
         done();
     });
 
@@ -64,15 +64,15 @@ describe('#stringify', function () {
 
         expect(Qs.stringify({ a: '' })).to.equal('a=');
         expect(Qs.stringify({ a: '', b: '' })).to.equal('a=&b=');
-        expect(Qs.stringify({ a: null })).to.equal('a');
-        expect(Qs.stringify({ a: { b: null } })).to.equal('a[b]');
+        expect(Qs.stringify({ a: null })).to.equal('a=');
+        expect(Qs.stringify({ a: { b: null } })).to.equal('a%5Bb%5D=');
         done();
     });
 
     it('drops keys with a value of undefined', function (done) {
 
         expect(Qs.stringify({ a: undefined })).to.equal('');
-        expect(Qs.stringify({ a: { b: undefined, c: null } })).to.equal('a[c]');
+        expect(Qs.stringify({ a: { b: undefined, c: null } })).to.equal('a%5Bc%5D=');
         done();
     });
 
@@ -100,8 +100,30 @@ describe('#stringify', function () {
 
         Object.prototype.crash = 'test';
         expect(Qs.stringify({ a: 'b'})).to.equal('a=b');
-        expect(Qs.stringify({ a: { b: 'c' } })).to.equal('a[b]=c');
+        expect(Qs.stringify({ a: { b: 'c' } })).to.equal('a%5Bb%5D=c');
         delete Object.prototype.crash;
         done();
     });
+
+    it('stringifies boolean values', function (done) {
+
+        expect(Qs.stringify({ a: true })).to.equal('a=true');
+        expect(Qs.stringify({ a: { b: true } })).to.equal('a%5Bb%5D=true');
+        expect(Qs.stringify({ b: false })).to.equal('b=false');
+        expect(Qs.stringify({ b: { c: false } })).to.equal('b%5Bc%5D=false');
+        done();
+    });
+
+    it('stringifies buffer values', function (done) {
+
+        expect(Qs.stringify({ a: new Buffer('test') })).to.equal('a=test');
+        expect(Qs.stringify({ a: { b: new Buffer('test') } })).to.equal('a%5Bb%5D=test');
+        done();
+    });
+
+    it('stringifies an object using an alternative delimiter', function (done) {
+
+        expect(Qs.stringify({ a: 'b', c: 'd' }, ';')).to.equal('a=b;c=d');
+        done();
+    });
 });