contextor

contextor is a powerful but simple tool helping you to pass a context along an asynchronous process.

Note that, contextor is build on async hooks available since version 8 of Node.js and still in experimental state as of version 12.

Here is a simple example with an express request context:

const express = require('express');
const contextualizer = require('./index');

const app = express();
let id = 0;

function getCurrentRequestId() {
  // Retrieve current request id.
  return contextualizer.get('request').id;
}

function logSomething(message) {
  console.log({
    requestId: getCurrentRequestId(),
    message
  });
}

app.use((req, res, next) => {
  req.id = id++;
  // Create a new context and add current request and response objects to it.
  contextualizer.create()
    .set('request', req)
    .set('response', res);
  next();
});

app.use((req, res, next) => {
  logSomething('something');
  next();
});

app.get('/', (req, res) => {
  res.send({
    requestId: req.id,
    contextRequestId: getCurrentRequestId()
  });
  // `requestId` and `contextRequestId` should be the same!
});

app.listen(3000);

Summary

• Installation
• Use
  • Create a context
  • Set a value in the current context
  • Get a value in the current context
  • Customize cleaning
• Debugging
• Testing
• Contributing
• License

Installation

Run the following command to add the package to your dependencies:

$ npm install --save contextor

Use

// CommonJS
const contextor = require('contextor');

// ES6 modules
import contextor from 'contextor';

Create a context

You can create a context just calling following method:

contextor.create();

This will create a context associated with the current asynchronous resource processing and all its descendants, overriding the one of its ancestors.

Set a value in the current context

You can set a value in the current context:

contextor.set('foo', 'bar');

Get a value in the current context

You can get a value of the current context:

contextor.get('foo');

This will throw a ReferenceError if the key does not exist.

Instead, you can specify a default value in case the key does not exist:

contextor.get('foo', 'bar');

Customize cleaning

Some environment variables are available in order to customize context cleaning:

• CONTEXTOR_CLEAN_CHECK_CONTEXT_SIZE: number of created contexts before a cleaning is executed (default: 100)
• CONTEXTOR_CONTEXT_TTL: TTL of contexts in ms; set to 0 to make it infinite (default: 6e4)

Debugging

Contextor create context for async hooks. A bad usage can lead to memory leaks. Function getMemoryUsage has been build to help you investigate that kind of issue:

const { inspect } = require('util');

const memoryUsage = contextor.getMemoryUsage();

console.log(inspect(memoryUsage, {
  compact: false,
  colors: true,
  depth: 6,
}));

Testing

Many npm scripts are available to help testing:

$ npm run {script}

• check: lint and check unit and integration tests
• lint: lint
• lint-fix: try to fix lint automatically
• test: check unit tests
• test-coverage: check coverage of unit tests
• test-debug: debug unit tests
• test-watch: work in TDD!

Use npm run check to check that everything is ok.

Contributing

If you want to contribute, just fork this repository and make a pull request!

Your development must respect these rules:

• fast
• easy
• light

You must keep test coverage at 100%.

License

MIT