Version 2.0.0 (#7)

Author: odeadglaz

.eslintignore

@@ -1,2 +1,3 @@
 dist
-node_modules
+node_modules
+example

.eslintrc.js

@@ -11,7 +11,7 @@ module.exports = {
         es6: true
     },
     rules: {
-        'no-console': 0,
+        'no-console': 2,
         'no-var': 2,
         'prefer-const': 2,
         semi: 2,

CHANGELOG.md

@@ -0,0 +1,13 @@
+# CHANGELOG
+
+## 2.0.0 (September 19, 2020)
+
+### New features
+
+- Domains - allow creating a domain under a certain context to split the chain into a standalone context root (parent chain will not depend on its completion for release).
+- Configurations settings.
+
+### Improvements
+
+- Favoring direct assign over spread calls.
+- Monitor now is controlled by config, will not enrich execution context nodes by default.

README.md

@@ -57,11 +57,13 @@ export class UserController {
 
 ## API
 
-### create(initialContext?: object)
+### create(initialContext?: object, domain? :string)
 
 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.
 
+> When passing custom domain to this method, the trigger point and all of it's sub processes will be exposed to a standalone context won't effect / be effected by root context. 
+
 ### update(update: object)
 
 Updates the current execution context with a given update obect.
@@ -74,12 +76,29 @@ Returns the current execution context identified with the current asyncId.
 
 Runs a given function under a dedicated AsyncResource, exposing given initial context to the process and it's child processes.
 
+### configure(config: ExecutionContextConfig) : void
+
+Configures execution context settings.
+
 ### monitor(): ExecutionMapUsage
 
 Returns an monitoring report over the current execution map resources
 
-### API Usage
+> Before calling `monitor`, you should `configure` execution context to monitor it's nodes. by default they are kept as lean as possible.
+
+```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
 
 ```js
 const Context = require('node-execution-context');
@@ -111,15 +130,15 @@ Promise.resolve().then(() => {
         }, 1000);
 
         console.log(Context.get()); // outputs: {"value": true}
-        console.log(Context.monitor) // Will result with monitor result 
     });
 });
 ```
 
 The following errors can be thrown while accessing to the context API :
 
-| Code | when |
+| 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.
+| MONITOR_MISS_CONFIGURATION | When try to `monitor` without calling `configure` with monitoring option.
 

example/controller.js

@@ -1,16 +1,28 @@
 const Context = require('../src');
 
-const delay = (callback) => setTimeout(() => {
+const delay = (callback, timeout = 1000) => setTimeout(() => {
 	callback();
-}, 2000);
+}, timeout);
 
 class UserController {
 	get(req, res) {
 
 		delay(() => {
-			console.log('Callback : ', Context.get());
+			console.log('Callback : ', Context.get()); // { 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');
+
+			delay(() => {
+				console.log('Domain callback ', Context.get()) // { val: true, specific: true }
+				Context.update({ inner: true });
+
+			}, 400);
+		}, 4000)
+
 		res.send(Context.get());
 	}
 }

example/server.js

@@ -14,6 +14,6 @@ app.use('/', ContextMiddleware);
 
 app.get('/user', UserController.get);
 
-app.listen(port, function(){
+app.listen(port, () => {
 	console.log('Server is running');
 });

package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-execution-context",
-  "version": "1.1.6",
+  "version": "2.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

@@ -0,0 +1,23 @@
+/**
+ * The Execution context error that can be thrown while accessing the execution context.
+ * @type {Object<String>}
+ */
+exports.ExecutionContextErrors = {
+    CONTEXT_ALREADY_DECLARED: 'Execution context is already declared for the default 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.',
+    MONITOR_MISS_CONFIGURATION: 'Monitoring option is off by default, please call `configure` with the proper options.'
+};
+
+/**
+ * The default configuration to use.
+ * @type {ExecutionContextConfig}
+ */
+exports.DEFAULT_CONFIG = {
+    monitor: false
+};
+
+/**
+ * The default domain to create execution context roots under.
+ * @type {String}
+ */
+exports.ROOT_DOMAIN = 'ROOT';

src/ExecutionContext/index.js

@@ -0,0 +1,167 @@
+const asyncHooks = require('async_hooks');
+const { isProduction, monitorMap, ExecutionContextResource } = require('../lib');
+const { create: createHooks, onChildProcessDestroy } = require('../hooks');
+const {
+    DEFAULT_CONFIG,
+    ROOT_DOMAIN,
+    ExecutionContextErrors
+} = require('./constants');
+
+/**
+ * The execution context maps which acts as the execution context in memory storage.
+ * @see ExecutionContext.monitor
+ * @type ExecutionContextMap
+ */
+const executionContextMap = new Map();
+
+/**
+ * Creates a root execution context node.
+ * @param {Number} asyncId - The current async id.
+ * @param {Object} initialContext - The initial context ro provide this execution chain.
+ * @param {Object} config - The configuration the root context created with.
+ * @param {Object} domain - The domain to create the execution context under.
+ * @return {ExecutionContextNode}
+ */
+const createRootContext = ({ asyncId, initialContext, config, domain = ROOT_DOMAIN }) => ({
+    asyncId,
+    domain,
+    context: { ...initialContext, executionId: asyncId },
+    children: [],
+    ...config,
+    ...(config.monitor && { created: Date.now() })
+});
+
+/**
+ * Handles execution context error, throws when none production.
+ * @param {String} code - The error code to log.
+ */
+const handleError = (code) => {
+    if (!isProduction()) {
+        throw code;
+    }
+
+    console.error(code); // eslint-disable-line no-console
+};
+
+class ExecutionContext {
+    constructor() {
+        this.config = { ...DEFAULT_CONFIG };
+
+        // Sets node async hooks setup
+        asyncHooks.createHook(
+            createHooks(executionContextMap)
+        ).enable();
+    }
+
+    /**
+     * Configures current execution context.
+     * @param {ExecutionContextConfig} config - the configuration to use.
+     */
+    configure(config) {
+        this.config = config;
+    }
+
+    /**
+     * Creates an execution context for the current asyncId process.
+     * This will expose Context get / update at any point after.
+     * @param {Object} initialContext - The initial context to be used.
+     * @param {String} domain - The domain the context is created under.
+     * @returns void
+     */
+    create(initialContext = {}, domain = ROOT_DOMAIN) {
+        const config = this.config;
+        const asyncId = asyncHooks.executionAsyncId();
+
+        const refContext = executionContextMap.get(asyncId);
+        if (refContext) {
+
+            // Execution context creation is allowed once per domain
+            if (domain === refContext.domain) return handleError(ExecutionContextErrors.CONTEXT_ALREADY_DECLARED);
+
+            // Setting up domain initial context
+            initialContext = { ...this.get(), ...initialContext };
+
+            // Disconnecting current async id from stored parent chain
+            onChildProcessDestroy(executionContextMap, asyncId, refContext.ref);
+        }
+
+        // Creating root context node
+        const rootContext = createRootContext({
+            asyncId,
+            initialContext,
+            config,
+            domain
+        });
+
+        executionContextMap.set(asyncId, rootContext);
+    }
+
+    /**
+     * Updates the current async process context.
+     * @param {Object} update - The update to apply on the current process context.
+     * @returns void
+     */
+    update(update = {}) {
+        const asyncId = asyncHooks.executionAsyncId();
+
+        if (!executionContextMap.has(asyncId)) return handleError(ExecutionContextErrors.CONTEXT_DOES_NOT_EXISTS);
+
+        const contextData = executionContextMap.get(asyncId);
+
+        // Update target is always the root context, ref updates will need to be channeled
+        const targetContextData = contextData.ref
+            ? executionContextMap.get(contextData.ref)
+            : contextData;
+
+        targetContextData.context = { ...targetContextData.context, ...update };
+    }
+
+    /**
+     * Gets the current async process execution context.
+     * @returns {Object}
+     */
+    get() {
+        const asyncId = asyncHooks.executionAsyncId();
+        if (!executionContextMap.has(asyncId)) return handleError(ExecutionContextErrors.CONTEXT_DOES_NOT_EXISTS);
+
+        const { context = {}, ref } = executionContextMap.get(asyncId);
+        if (ref) {
+
+            // Ref will be used to point out on the root context
+            return executionContextMap.get(ref).context;
+        }
+
+        // Root context
+        return context;
+    }
+
+    /**
+     * Runs a given function within "AsyncResource" context, this will ensure the function executed within a uniq execution context.
+     * @param {Function} fn - The function to run.
+     * @param {Object} initialContext - The initial context to expose to the function execution.
+     * @param {String} domain - The domain to create the exectuion context under.
+     */
+    run(fn, initialContext, domain) {
+        const resource = new ExecutionContextResource();
+
+        resource.runInAsyncScope(() => {
+            this.create(initialContext, domain);
+
+            fn();
+        });
+    }
+
+    /**
+     * Monitors current execution map usage
+     * @return {ExecutionMapUsage}
+     */
+    monitor() {
+        if (!this.config.monitor) {
+            throw new Error(ExecutionContextErrors.MONITOR_MISS_CONFIGURATION);
+        }
+
+        return monitorMap(executionContextMap);
+    }
+}
+
+module.exports = ExecutionContext;

src/spec.js src/ExecutionContext/spec.jssrc/spec.js renamed to src/ExecutionContext/spec.js

@@ -1,10 +1,13 @@
 const asyncHooks = require('async_hooks');
-const hooks = require('./hooks');
+const hooks = require('../hooks');
 const { ExecutionContextErrors } = require('./constants');
 
 describe('Context', () => {
     let Context;
-    beforeEach(() => Context = jest.requireActual('.'));
+    beforeEach(() => {
+        const ExecutionContext = jest.requireActual('.');
+        Context = new ExecutionContext();
+    });
 
     describe('Initialise node "async_hooks"', () => {
         const spies = {
@@ -116,8 +119,11 @@ describe('Context', () => {
                 Context.run(execute, initialContext);
             });
 
-            it('Creates context', () => {
-                expect(spies.contextCreate).toHaveBeenCalledWith(initialContext);
+            it('Creates context under root domain', () => {
+                expect(spies.contextCreate).toHaveBeenCalledWith(
+                    initialContext,
+                    undefined
+                );
             });
 
             it('Executes given function', () => {
@@ -212,5 +218,33 @@ describe('Context', () => {
                 });
             });
         });
+
+        describe('Domains', () => {
+            it('Blocks when creation is made under the same domain', () => {
+                create();
+
+                expect(create).toThrow();
+            });
+
+            it('Allows to create sub domains under a root context', (done) => {
+                create();
+
+                expect(Context.get().hey).toBeTruthy();
+
+                setTimeout(() => {
+                    Context.create({ some: 'where' }, 'that-domain');
+                    Context.update({ hey: false });
+
+                    expect(Context.get().hey).toBeFalsy();
+                    expect(Context.get().some).toEqual('where');
+                }, 500);
+
+                setTimeout(() => {
+                    expect(Context.get().hey).toBeTruthy();
+
+                    done();
+                }, 1500);
+            });
+        });
     });
 });