Document in README.md and test correct usage of cls-hooked

CHANGES.md

@@ -2,3 +2,8 @@
 =========================
 
  * First release!
+
+2016-08-10, Version 2.0.0-alpha.1
+=========================
+
+* Edited README.md and package.json in order to address both issues loopback-context#9 and async-listener#57 by permanently replacing continuation-local-storage with cls-hooked

README.md

@@ -3,6 +3,43 @@
 Current context for LoopBack applications, based on
 cls-hooked.
 
+## USAGE WARNING
+
+**Only if you use this package, do NOT run your app using `slc run` or `node .`**
+
+Run using:
+
+`node -r cls-hooked .`
+
+This uses the `-r` option in order to require `cls-hooked` before your app (see warnings below for more info).
+
+If you wish to use `strong-supervisor`, you would need to pass node options to `slc run`, which currently has issues, according to [strong-supervisor#56](https://github.com/strongloop/strong-supervisor/issues/56).
+
+## INSTALL WARNING
+
+**Only if you use this package, do NOT install your app using `npm install`.**
+
+Install using:
+
+```
+npm config set engine-strict true
+npm install
+```
+
+This keeps you from using Node < v0.4.5.
+
+## TEST WARNING
+
+**Do NOT test this package using `mocha .`.**
+
+Test using:
+
+```
+npm test
+```
+
+This adds the `-r` option to `mocha` command, needed in order to pass tests.
+
 ## WARNING
 
 **We recommend AGAINST using the loopback-context module until there is a stable solution to the issue below!**
@@ -13,8 +50,8 @@ As a result, loopback-context does not work in many situations, as can be
 seen from issues reported in LoopBack's
 [issue tracker](https://github.com/strongloop/loopback/issues?utf8=%E2%9C%93&q=is%3Aissue%20getCurrentcontext).
 
-If you are running on Node v6, you can try the new alternative
-[cls-hooked](https://github.com/Jeff-Lewis/cls-hooked).
+The new alternative
+[cls-hooked](https://github.com/Jeff-Lewis/cls-hooked) is known to possibly inherit these problems if it's not imported before everything else, that's why you are required to follow the advice above if using this.
 
 ## Usage
 

package.json

@@ -14,7 +14,7 @@
   "main": "server/current-context.js",
   "browser": "browser/current-context.js",
   "scripts": {
-    "test": "mocha",
+    "test": "mocha -r cls-hooked",
     "posttest": "npm run lint",
     "lint": "eslint ."
   },
@@ -23,6 +23,7 @@
     "cls-hooked": "^4.0.1"
   },
   "devDependencies": {
+    "async": "1.5.2",
     "chai": "^3.5.0",
     "dirty-chai": "^1.2.2",
     "eslint": "^2.13.1",

test/main.test.js

@@ -5,6 +5,8 @@
 
 'use strict';
 
+// ASYNC VERSION MATTERS! 1.5.2 is required in order for this test to work.
+var async = require('async');
 var LoopBackContext = require('..');
 var Domain = require('domain');
 var EventEmitter = require('events').EventEmitter;
@@ -98,4 +100,39 @@ describe('LoopBack Context', function() {
       });
     });
   });
+
+  // Credits for the original idea for this test case to @marlonkjoseph
+  // Original source of the POC gist of the idea:
+  // https://gist.github.com/marlonkjoseph/f42f3c71f746896a0d4b7279a34ea753
+  // Heavily edited by others
+  it('keeps context when using waterfall() from async 1.5.2',
+  function(done) {
+    LoopBackContext.runInContext(function() {
+      // function 1 which pulls context
+      var fn1 = function(cb) {
+        var ctx = LoopBackContext.getCurrentContext();
+        expect(ctx).is.an('object');
+        ctx.set('test-key', 'test-value');
+        cb();
+      };
+      // function 2 which pulls context
+      var fn2 =  function(cb) {
+        var ctx = LoopBackContext.getCurrentContext();
+        expect(ctx).is.an('object');
+        var testValue = ctx && ctx.get('test-key', 'test-value');
+        cb(null, testValue);
+      };
+      // Trigger async waterfall callbacks
+      var asyncFn = function() {
+        async.waterfall([
+          fn1,
+          fn2,
+        ], function(err, testValue) {
+          expect(testValue).to.equal('test-value');
+          done();
+        });
+      };
+      asyncFn();
+    });
+  });
 });