[V3] Migrating to AsyncLocalStorage. (#13)

Author: odeadglaz

.github/workflows/node.js.yml

@@ -16,7 +16,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [10.x, 12.x, 14.x]
+        node-version: [8.x, 10.x, 12.x, 14.x]
 
     steps:
     - uses: actions/checkout@v2

CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## 3.0.0 (January 03, 2021)
+
+- Introduces `AsyncLocaleStorage` based implementation for node `12.7.0` and above.
+- `AsyncHooksContext` domains are now created by default under the hood and no longer require consumers to supply a name.
+- `update` API changed to `set`.
+- `create` API no longer treats`context` as JS objects.
+
 ## 2.0.8 (December 20, 2020)
 
 - Better reporting, safe child getters.

README.md

@@ -1,5 +1,6 @@
 # node-execution-context
-A straightforward library that provides a persistent process-level context wrapper using node "async_hooks" feature. 
+A straightforward library that provides a persistent process-level context wrapper using node "async_hooks" feature.
+This library will try to use by default [`AsyncLocalStorage`](https://nodejs.org/api/async_hooks.html#async_hooks_class_asynclocalstorage) implementation based if current node version supports it, otherwise it will fallback to raw [`async_hooks`](https://nodejs.org/api/async_hooks.html) implementation for lower versions which mimics this behaviour. 
 
 ## Installation
 
@@ -21,7 +22,7 @@ const app = express();
 const port = 3000;
 
 const ContextMiddleware = (req, res, next) => {
-    Context.run(next, { val: true });
+    Context.run(next, { reference: Math.random() });
 };
 
 app.use('/', ContextMiddleware);
@@ -44,7 +45,7 @@ export class UserController {
     async create (req) {
         const { user } = req.body;
 
-        // This will return the reference number set by out ContextMiddleware
+        // This will return the reference number set by out ContextMiddleware (generated by Math.random())
         const { reference } = Context.get();
 
         logger.info('Created user for reference: ', reference);
@@ -56,48 +57,83 @@ export class UserController {
 
 ## API
 
-### create(initialContext?: object, domain? :string)
+### run(fn: Function, context: unknown)
 
-Creates for the current async resource an execution context entry identified with his asyncId.
-Any future processes that will be added to the async execution chain will be exposed to this context.
+Runs given callback that will be exposed to the given context.
+The context will be exposed to all callbacks and promise chains triggered from the given `fn`.
 
-> When passing custom domain to this method, the trigger point and all of it's sub processes will be exposed to a standalone context and won't effect / be effected by root context. 
+### get()
 
-### update(update: object)
+Gets the current asynchronous execution context.
 
-Updates the current execution context with a given update obect.
+> The `get` result is returned by `reference` meaning if you wish any immutability applied, it will have to be manually applied. 
 
-### get()
+> This API may throw CONTEXT_DOES_NOT_EXIST error if accessed without initializing the context properly.
+
+### set(context: unknown)
+
+Sets the current asynchronous execution context to given value.
+
+> This API may throw CONTEXT_DOES_NOT_EXIST error if accessed without initializing the context properly.
+
+### create(context?: unknown)
+
+Creates a given context for the current asynchronous execution.
+It is recommended to use the `run` method. This method should be used in special cases in which the `run` method cannot be used directly.
+
+> Note that if this method will be called not within a AsyncResource context, it will effect current execution context and should be used with caution. 
+
+#### Example
+
+```js
+const Context = require('node-execution-context');
+
+// context-events.js
+const context = { id: Math.random() };
 
-Returns the current execution context identified with the current asyncId.
+emitter.on('contextual-event', () => {
+  Context.create(context);
+});
 
-### run(fn: Function, initialContext: object)
+// service.js
+emitter.on('contextual-event', () => {
+  Context.get(); // Returns { id: random } 
+});
 
-Runs a given function under a dedicated AsyncResource, exposing given initial context to the process and it's child processes.
+// main.js
+emitter.emit('contextual-event');
+
+Context.get(); // Returns { id: random }
+```
 
 ### configure(config: ExecutionContextConfig) : void
 
 Configures execution context settings.
 
+> Relevant only for node versions lower than `v12.17.0`.
+
 ### monitor(): ExecutionMapUsage
 
 Returns an monitoring report over the current execution map resources
 
+> Relevant only for node versions lower than `v12.17.0`.
+
 > Before calling `monitor`, you should `configure` execution context to monitor it's nodes. by default the data kept is as possible.
 
+#### Example
+
 ```js
 const Context = require('node-execution-context');
 
 // Startup
 Context.configure({ monitor: true });
 
-
 // Later on
 const usage = Context.monitor();
 console.log(usage); // Prints execution context usage report.
 ```
 
-### API Usage
+### Raw API Usage
 
 ```js
 const Context = require('node-execution-context');
@@ -109,26 +145,26 @@ Context.create({
 Promise.resolve().then(() => {
     console.log(Context.get()); // outputs: {"value": true}
 
-    Context.update({
+    Context.set({
         value: false
     });
 
     return new Promise((resolve) => {
         setTimeout(() => {
             console.log(Context.get()); // outputs: {"value": false}
 
-            Context.update({
+            Context.set({
                 butter: 'fly'
             });
 
             process.nextTick(() => {
-                console.log(Context.get()); // outputs: {"value": false, "butter": 'fly'}
+                console.log(Context.get()); // outputs: {"butter": 'fly'}
                 resolve();
             });
 
         }, 1000);
 
-        console.log(Context.get()); // outputs: {"value": true}
+        console.log(Context.get()); // outputs: {"value": false}
     });
 });
 ```
@@ -137,7 +173,6 @@ The following errors can be thrown while accessing to the context API :
 
 | Code | When |
 |-|-
-| CONTEXT_ALREADY_DECLARED | When trying to `create` execution context, but current async resource already exists.
-| CONTEXT_DOES_NOT_EXISTS | When try to `get` / `update` the context, but it yet been created.
+| CONTEXT_DOES_NOT_EXIST | When attempting to `get` / `set` a context, that has not yet been created.
 | MONITOR_MISS_CONFIGURATION | When try to `monitor` without calling `configure` with monitoring option.
 

example/controller.js

@@ -8,22 +8,24 @@ class UserController {
 	get(req, res) {
 
 		delay(() => {
-			console.log('Callback : ', Context.get()); // { val: true }
+			console.log('Callback1: ', Context.get()); // Callback: { val: true }
 		});
 
-		// Creates a dedicate domain context ( exclude this following chain from root context )
-		// Updates mae from domain will not effect root context.
-		delay(() => {
-			Context.create({ specific: true }, 'custom-domain');
+		// Creates another context under Timeout AsyncResource un effected/effecting from current one.
+		setTimeout(() => {
+			Context.create({ value: 'domain' });
+			console.log('Domain: ', Context.get()); // Promise: { val: 'domain' }
 
 			delay(() => {
-				console.log('Domain callback ', Context.get()) // { val: true, specific: true }
-				Context.update({ inner: true });
+				console.log('Domain Callback: ', Context.get()) // Promise: { val: 'domain' }
+			}, 3000);
+		}, 300);
 
-			}, 400);
-		}, 4000)
+		delay(() => {
+			console.log('Callback2: ', Context.get()); // Callback: { val: true }
+		}, 500);
 
-		res.send(Context.get());
+		res.send(Context.get()); // { val: true }
 	}
 }
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-execution-context",
-  "version": "2.0.8",
+  "version": "3.0.0",
   "description": "Provides execution context wrapper for node JS, can be used to create execution wrapper for handling requests and more",
   "author": "Oded Goldglas <[email protected]>",
   "license": "ISC",

src/ExecutionContext/constants.js

@@ -3,8 +3,7 @@
  * @type {Object<String>}
  */
 exports.ExecutionContextErrors = {
-    CONTEXT_ALREADY_DECLARED: 'Execution context is already declared for the given domain, use the domain option to create a separate context.',
-    CONTEXT_DOES_NOT_EXISTS: 'Execution context does not exists, please ensure to call create/run before.',
+    CONTEXT_DOES_NOT_EXIST: 'Execution context does not exists, please ensure to call create/run before.',
     MONITOR_MISS_CONFIGURATION: 'Monitoring option is off by default, please call `configure` with the proper options.'
 };
 
@@ -15,9 +14,3 @@ exports.ExecutionContextErrors = {
 exports.DEFAULT_CONFIG = {
     monitor: false
 };
-
-/**
- * The default domain to create execution context roots under.
- * @type {String}
- */
-exports.ROOT_DOMAIN = 'ROOT';