Add res.append(field, val) to append headers

closes #2455

History.md

@@ -1,6 +1,7 @@
 unreleased
 ==========
 
+  * Add `res.append(field, val)` to append headers
   * Deprecate leading `:` in `name` for `app.param(name, fn)`
   * Deprecate `req.param()` -- use `req.params`, `req.body`, or `req.query` instead
   * Deprecate `app.param(fn)`

lib/response.js

@@ -636,6 +636,35 @@ res.attachment = function attachment(filename) {
   return this;
 };
 
+/**
+ * Append additional header `field` with value `val`.
+ *
+ * Example:
+ *
+ *    res.append('Link', ['<http://localhost/>', '<http://localhost:3000/>']);
+ *    res.append('Set-Cookie', 'foo=bar; Path=/; HttpOnly');
+ *    res.append('Warning', '199 Miscellaneous warning');
+ *
+ * @param {String} field
+ * @param {String|Array} val
+ * @return {ServerResponse} for chaining
+ * @api public
+ */
+
+res.append = function append(field, val) {
+  var prev = this.get(field);
+  var value = val;
+
+  if (prev) {
+    // concat the new and prev vals
+    value = Array.isArray(prev) ? prev.concat(val)
+      : Array.isArray(val) ? [prev].concat(val)
+      : [prev, val];
+  }
+
+  return this.set(field, value);
+};
+
 /**
  * Set header `field` to `val`, or pass
  * an object of header fields.

test/res.append.js

@@ -0,0 +1,104 @@
+
+var express = require('..')
+var request = require('supertest')
+var should = require('should')
+
+describe('res', function () {
+  // note about these tests: "Link" and "X-*" are chosen because
+  // the common node.js versions white list which _incoming_
+  // headers can appear multiple times; there is no such white list
+  // for outgoing, though
+  describe('.append(field, val)', function () {
+    it('should append multiple headers', function (done) {
+      var app = express()
+
+      app.use(function (req, res, next) {
+        res.append('Link', '<http://localhost/>')
+        next()
+      })
+
+      app.use(function (req, res) {
+        res.append('Link', '<http://localhost:80/>')
+        res.end()
+      })
+
+      request(app)
+      .get('/')
+      .expect('Link', '<http://localhost/>, <http://localhost:80/>', done)
+    })
+
+    it('should accept array of values', function (done) {
+      var app = express()
+
+      app.use(function (req, res, next) {
+        res.append('Set-Cookie', ['foo=bar', 'fizz=buzz'])
+        res.end()
+      })
+
+      request(app)
+      .get('/')
+      .expect(function (res) {
+        should(res.headers['set-cookie']).eql(['foo=bar', 'fizz=buzz'])
+      })
+      .expect(200, done)
+    })
+
+    it('should get reset by res.set(field, val)', function (done) {
+      var app = express()
+
+      app.use(function (req, res, next) {
+        res.append('Link', '<http://localhost/>')
+        res.append('Link', '<http://localhost:80/>')
+        next()
+      })
+
+      app.use(function (req, res) {
+        res.set('Link', '<http://127.0.0.1/>')
+        res.end()
+      });
+
+      request(app)
+      .get('/')
+      .expect('Link', '<http://127.0.0.1/>', done)
+    })
+
+    it('should work with res.set(field, val) first', function (done) {
+      var app = express()
+
+      app.use(function (req, res, next) {
+        res.set('Link', '<http://localhost/>')
+        next()
+      })
+
+      app.use(function(req, res){
+        res.append('Link', '<http://localhost:80/>')
+        res.end()
+      })
+
+      request(app)
+      .get('/')
+      .expect('Link', '<http://localhost/>, <http://localhost:80/>', done)
+    })
+
+    it('should work with cookies', function (done) {
+      var app = express()
+
+      app.use(function (req, res, next) {
+        res.cookie('foo', 'bar')
+        next()
+      })
+
+      app.use(function (req, res) {
+        res.append('Set-Cookie', 'bar=baz')
+        res.end()
+      })
+
+      request(app)
+      .get('/')
+      .expect(function (res) {
+        should(res.headers['set-cookie']).eql(['foo=bar; Path=/', 'bar=baz'])
+      })
+      .expect(200, done)
+    })
+  })
+})