Merge pull request #5 from yahoo/extend

Create `extend()` API so any Express module instance can be extended

Author: ericf

HISTORY.md

@@ -1,6 +1,18 @@
 Express State Change History
 ============================
 
+NEXT
+----
+
+* Added `extend()` function which takes an `express` module instance and adds
+  the `expose()` method to its application and response prototype, if it does
+  not already exist.
+
+* Added `augment()` function which takes an Express app instance and adds the
+  `expose()` method to it application and its response prototype, if it does not
+  already exist.
+
+
 0.0.3 (2013-06-08)
 ------------------
 
@@ -16,7 +28,10 @@ Express State Change History
 * Added Travis CI integration.
 
 * Improved namespace rendering by removing the initialization of leaf namespaces
-  since exposed values will be assigned to them. (Issue #1)
+  since exposed values will be assigned to them. ([#1][])
+
+
+[#1]: https://github.com/yahoo/express-state/issues/1
 
 
 0.0.1 (2013-05-02)

index.js

@@ -1,25 +1,52 @@
 'use strict';
 
 var express = require('express'),
-    Exposed = require('./lib/exposed'),
-
-    appProto = express.application,
-    resProto = express.response;
+    Exposed = require('./lib/exposed');
 
 exports.local     = 'state';
 exports.namespace = null;
 
-// Protect against multiple copies of this module augmenting the Express
-// `application` and `response` prototypes.
-if (typeof appProto.expose === 'function' &&
-    typeof resProto.expose === 'function') {
+exports.augment = augment;
+exports.extend  = extend;
+
+extend(express);
+
+function extend(express) {
+    var appProto = express.application,
+        resProto = express.response;
+
+    // Protect against multiple express-state module instances augmenting the
+    // Express `application` and `response` prototypes.
+    if (typeof appProto.expose === 'function' &&
+        typeof resProto.expose === 'function') {
+
+        return;
+    }
+
+    // Modifies Express' `application` and `response` prototypes by adding the
+    // `expose()` method.
+    resProto.expose = appProto.expose = expose;
+}
+
+function augment(app) {
+    var resProto = app.response;
+
+    // Protect against multiple express-state module instances augmenting the
+    // Express `app` and its `response` prototypes.
+    if (typeof app.expose === 'function' &&
+        typeof resProto.expose === 'function') {
+
+        return;
+    }
 
-    return;
+    // Modifies the Express `app` and its `response` prototype by adding the
+    // `expose()` method.
+    resProto.expose = app.expose = expose;
 }
 
-// Modifies Express' `application` and `response` prototypes by adding the
-// `expose()` method.
-resProto.expose = appProto.expose = function (obj, namespace, local) {
+function expose(obj, namespace, local) {
+    /* jshint validthis:true */
+
     var app           = this.app || this,
         appLocals     = this.app && this.app.locals,
         locals        = this.locals,
@@ -64,4 +91,4 @@ resProto.expose = appProto.expose = function (obj, namespace, local) {
     }
 
     exposed.add(namespace, obj);
-};
+}

test/exports.js

@@ -6,7 +6,7 @@ var state  = require('../'),
 
 describe('exports', function () {
     describe('.local', function () {
-        it('should have a .local', function () {
+        it('should have a .local property', function () {
             expect(state).to.have.property('local');
         });
 
@@ -16,12 +16,32 @@ describe('exports', function () {
     });
 
     describe('.namespace', function () {
-        it('should have a .namespace', function () {
+        it('should have a .namespace property', function () {
             expect(state).to.have.property('namespace');
         });
 
         it('should be null', function () {
             expect(state.namespace).to.equal(null);
         });
     });
+
+    describe('.augment', function () {
+        it('should have a .augment property', function () {
+            expect(state).to.have.property('augment');
+        });
+
+        it('should respond to .augment()', function () {
+            expect(state).itself.to.respondTo('augment');
+        });
+    });
+
+    describe('.extend', function () {
+        it('should have a .extend property', function () {
+            expect(state).to.have.property('extend');
+        });
+
+        it('should respond to .extend()', function () {
+            expect(state).itself.to.respondTo('extend');
+        });
+    });
 });

test/exposed.js

@@ -9,7 +9,7 @@ describe('Exposed', function () {
         expect(Exposed).to.be.a('function');
     });
 
-    describe('.create([exposed])', function () {
+    describe('.create( [exposed] )', function () {
         it('should respond to .create()', function () {
             expect(Exposed).itself.to.respondTo('create');
         });
@@ -60,7 +60,7 @@ describe('Exposed', function () {
         });
     });
 
-    describe('.isExposed([obj])', function () {
+    describe('.isExposed( [obj] )', function () {
         it('should respond to .isExposed()', function () {
             expect(Exposed).itself.to.respondTo('isExposed');
         });
@@ -94,7 +94,7 @@ describe('Exposed', function () {
         });
     });
 
-    describe('#add(namespace, value)', function () {
+    describe('#add( namespace, value )', function () {
         var exposed;
 
         beforeEach(function () {

test/multiple.js

@@ -5,17 +5,21 @@ var expect  = require('chai').expect,
     mockery = require('mockery');
 
 describe('multiple', function () {
+    function createExpressMock() {
+        return {
+            application: {},
+            response   : {}
+        };
+    }
+
     beforeEach(function () {
         mockery.enable({
             useCleanCache     : true,
             warnOnReplace     : false,
             warnOnUnregistered: false
         });
 
-        mockery.registerMock('express', {
-            application: {},
-            response   : {}
-        });
+        mockery.registerMock('express', createExpressMock());
     });
 
     afterEach(function () {
@@ -33,4 +37,67 @@ describe('multiple', function () {
         expect(express.application.expose).to.equal(expose);
         expect(express.response.expose).to.equal(expose);
     });
+
+    describe('.extend( express )', function () {
+        it('should add `expose()`', function () {
+            var express = require('express'),
+                state   = require('../');
+
+            mockery.registerMock('express', createExpressMock());
+            express = require('express');
+
+            expect(express.application.expose).to.be.undefined;
+            expect(express.response.expose).to.be.undefined;
+
+            state.extend(express);
+
+            expect(express.application).itself.to.respondTo('expose');
+            expect(express.response).itself.to.respondTo('expose');
+        });
+
+        it('should not override `expose()` if it exists', function () {
+            var expose = function () {},
+                express, state;
+
+            express = require('express');
+            state   = require('../');
+
+            express.application.expose = express.response.expose = expose;
+            state.extend(express);
+
+            expect(express.application.expose).to.equal(expose);
+            expect(express.response.expose).to.equal(expose);
+        });
+    });
+
+    describe('.augment( app )', function () {
+        it('should add `expose()`', function () {
+            var express = require('express'),
+                state   = require('../'),
+                app     = {response: {}};
+
+            state.augment(app);
+
+            expect(app).itself.to.respondTo('expose');
+            expect(app.response).itself.to.respondTo('expose');
+        });
+
+        it('should not override `expose()` if it exists', function () {
+            var expose = function () {},
+                express, state, app;
+
+            express = require('express');
+            state   = require('../');
+
+            app = {
+                expose  : expose,
+                response: {expose: expose}
+            };
+
+            state.augment(app);
+
+            expect(app.expose).to.equal(expose);
+            expect(app.response.expose).to.equal(expose);
+        });
+    });
 });

test/state.js

@@ -14,7 +14,7 @@ describe('state', function () {
         app = express();
     });
 
-    describe('expose()', function () {
+    describe('expose( obj, [namespace], [local] )', function () {
         var expose, locals;
 
         beforeEach(function () {