uri encode brackets for #8, dont omit equals signs when value is null for #9, update readme

Author: nlf

README.md

@@ -17,7 +17,7 @@ var obj = Qs.parse('a=c');    // { a: 'c' }
 var str = Qs.stringify(obj);  // 'a=c'
 ```
 
-### Objects
+### Parsing Objects
 
 **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 +30,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 +79,7 @@ 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
+### Parsing Arrays
 
 **qs** can also parse arrays using a similar `[]` notation:
 
@@ -127,3 +134,37 @@ You can also create arrays of objects:
 Qs.parse('a[][b]=c');
 // { a: [{ b: 'c' }] }
 ```
+
+### Stringifying
+
+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='
+```

lib/stringify.js

@@ -14,23 +14,22 @@ internals.stringify = function (obj, prefix) {
     else if (obj instanceof Date) {
         obj = obj.toISOString();
     }
+    else if (obj === null) {
+        obj = '';
+    }
 
     if (typeof obj === 'string' ||
         typeof obj === 'number' ||
         typeof obj === 'boolean') {
 
-        return [prefix + '=' + encodeURIComponent(obj)];
-    }
-
-    if (obj === null) {
-        return [prefix];
+        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 + ']'));
         }
     }
 
@@ -44,7 +43,7 @@ module.exports = function (obj) {
 
     for (var key in obj) {
         if (obj.hasOwnProperty(key)) {
-            keys = keys.concat(internals.stringify(obj[key], encodeURIComponent(key)));
+            keys = keys.concat(internals.stringify(obj[key], key));
         }
     }
 

test/stringify.js

@@ -30,49 +30,49 @@ 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();
     });
 
     it('stringifies an empty value', function (done) {
 
         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,24 +100,24 @@ 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[b]=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[c]=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[b]=test');
+        expect(Qs.stringify({ a: { b: new Buffer('test') } })).to.equal('a%5Bb%5D=test');
         done();
     });
 });