Contextor NPM | npm.io

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

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,
}));