odedglas
node-execution-context
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 implementation based if current node version supports it, otherwise it will fallback to raw async_hooks implementation for lower versions which mimics this behaviour.
Installation
npm i node-execution-contextGetting started
Let's start with creating the context initialisation point of our app, we will take a simple express app for this example
// main.js
const express = require('express');
const Context = require('node-execution-context');
const UserController = require('./controllers/user');
const app = express();
const port = 3000;
const ContextMiddleware = (req, res, next) => {
Context.run(next, { reference: Math.random() });
};
app.use('/', ContextMiddleware);
app.post('/user', UserController.create);
app.listen(port);
This will expose any point of your code form this point that handles that request.
// ./controller/user/index.js
const Context = require('node-execution-context');
const mongo = require('../service/mongo');
const logger = require('../service/logger');
export class UserController {
async create (req) {
const { user } = req.body;
// 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);
return await mongo.create('user', user);
}
}API
run(fn: Function, context: unknown)
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.
get()
Gets the current asynchronous execution context.
The
getresult is returned byreferencemeaning if you wish any immutability applied, it will have to be manually applied.
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
const Context = require('node-execution-context');
// context-events.js
const context = { id: Math.random() };
emitter.on('contextual-event', () => {
Context.create(context);
});
// service.js
emitter.on('contextual-event', () => {
Context.get(); // Returns { id: random }
});
// 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 shouldconfigureexecution context to monitor it's nodes. by default the data kept is as possible.
Example
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.Raw API Usage
const Context = require('node-execution-context');
Context.create({
value: true
});
Promise.resolve().then(() => {
console.log(Context.get()); // outputs: {"value": true}
Context.set({
value: false
});
return new Promise((resolve) => {
setTimeout(() => {
console.log(Context.get()); // outputs: {"value": false}
Context.set({
butter: 'fly'
});
process.nextTick(() => {
console.log(Context.get()); // outputs: {"butter": 'fly'}
resolve();
});
}, 1000);
console.log(Context.get()); // outputs: {"value": false}
});
});The following errors can be thrown while accessing to the context API :
| Code | When |
|---|---|
| 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. |