Change constructor to signature new Cookies(req, res, [options])

closes #43

History.md

@@ -1,6 +1,8 @@
 0.6.x
 =====
 
+  * Change constructor to signature `new Cookies(req, res, [options])`
+    - Replace `new Cookies(req, res, key)` with `new Cookies(req, res, {'keys': keys})`
   * Change prototype construction for proper "constructor" property
 
 0.5.1 / 2014-07-27

README.md

@@ -26,9 +26,11 @@ Cookies is a [node.js](http://nodejs.org/) module for getting and setting HTTP(S
 
 ## API
 
-### cookies = new Cookies( request, response, [ keys ] )
+### cookies = new Cookies( request, response, [ options ] )
 
-This creates a cookie jar corresponding to the current _request_ and _response_. A [Keygrip](https://www.npmjs.com/package/keygrip) object or an array of keys can optionally be passed as the third argument _keygrip_ to enable cryptographic signing based on SHA1 HMAC, using rotated credentials.
+This creates a cookie jar corresponding to the current _request_ and _response_, additionally passing an object _options_.
+
+A [Keygrip](https://www.npmjs.com/package/keygrip) object or an array of keys can optionally be passed as _options.keys_ to enable cryptographic signing based on SHA1 HMAC, using rotated credentials.
 
 Note that since this only saves parameters without any other processing, it is very lightweight. Cookies are only parsed on demand when they are accessed.
 
@@ -73,7 +75,7 @@ var http    = require( "http" )
 var Cookies = require( "cookies" )
 
 server = http.createServer( function( req, res ) {
-  var cookies = new Cookies( req, res, keys )
+  var cookies = new Cookies( req, res, { "keys": keys } )
     , unsigned, signed, tampered
 
   if ( req.url == "/set" ) {

lib/cookies.js

@@ -1,3 +1,4 @@
+var deprecate = require('depd')('cookies')
 var Keygrip = require('keygrip')
 var http = require('http')
 var cache = {}
@@ -12,18 +13,24 @@ var cache = {}
 
 var fieldContentRegExp = /^[\u0009\u0020-\u007e\u0080-\u00ff]+$/;
 
-function Cookies(request, response, keys) {
-  if (!(this instanceof Cookies)) return new Cookies(request, response, keys)
+function Cookies(request, response, options) {
+  if (!(this instanceof Cookies)) return new Cookies(request, response, options)
 
   this.request = request
   this.response = response
-  if (keys) {
-    // array of key strings
-    if (Array.isArray(keys))
-      this.keys = new Keygrip(keys)
-    // any keygrip constructor to allow different versions
-    else if (keys.constructor && keys.constructor.name === 'Keygrip')
-      this.keys = keys
+
+  if (options) {
+    if (Array.isArray(options)) {
+      // array of key strings
+      deprecate('"keys" argument; provide using options {"key": [...]}')
+      this.keys = new Keygrip(options)
+    } else if (options.constructor && options.constructor.name === 'Keygrip') {
+      // any keygrip constructor to allow different versions
+      deprecate('"keys" argument; provide using options {"key": keygrip}')
+      this.keys = options
+    } else {
+      this.keys = options.keys
+    }
   }
 }
 
@@ -167,7 +174,10 @@ function pushCookie(cookies, cookie) {
 
 Cookies.connect = Cookies.express = function(keys) {
   return function(req, res, next) {
-    req.cookies = res.cookies = new Cookies(req, res, keys)
+    req.cookies = res.cookies = new Cookies(req, res, {
+      keys: keys
+    })
+
     next()
   }
 }

package.json

@@ -4,6 +4,7 @@
   "description": "Cookies, optionally signed using Keygrip.",
   "main": "./lib/cookies",
   "dependencies": {
+    "depd": "~1.1.0",
     "keygrip": "~1.0.0"
   },
   "devDependencies": {
@@ -25,6 +26,6 @@
     "README.md"
   ],
   "scripts": {
-    "test": "mocha --reporter spec"
+    "test": "mocha --require test/support/env --reporter spec"
   }
 }

test/support/env.js

@@ -0,0 +1,2 @@
+process.env.NODE_ENV = 'test'
+process.env.NO_DEPRECATION = 'cookies'