Continuation Local Storage

The purpose with this module is to share contexts across async (and sync) calls. Contexts are accessed by keys and can be nested. It is an alternative to the deprecated domain. It is based on async_hooks that were introduced in node 8. Beware that async_hooks are still experimental in nodejs.

To avoid weird behavior with express

1. Make sure you require node-cls in the first row of your app. Some popular packages use async which breaks CLS.
2. If you are using body-parser and context is getting lost, register it in express before you register node-cls's middleware.

Request handler

A typical scenario is when you need to share context in a request handler.

1let http = require('http');
2let cls = require('node-cls');
3
4let server = http.createServer(function (request, response) {
5    let context = cls.create('request-context');
6    context.id = 1;
7    context.request = request;
8    context.response = response;   
9    context.run(doWork);
10})
11
12server.listen(8080)
13
14function doWork() {
15    let context = cls.get('request-context');
16    context.response.end(`End: ${context.id}`) //End: 1
17
18}

Async calls

Context is retained in async calls.

1let cls = require('node-cls');
2
3let context = cls.create('myContext');
4context.run(() => {
5    context.name = 'George';
6    setTimeout(onTimeout, 300);
7});
8
9function onTimeout() {
10    let context = cls.get('myContext');
11    console.log(context.name); //George
12}

Nesting

Contexts can be nested, even on the same key.

1let cls = require('node-cls');
2
3let context = cls.create('myContext');
4context.run(async () => {
5    context.name = 'George';
6    let context2 = cls.create('myContext');
7    await context2.run(onNested);
8    console.log(context.name) //George
9});
10
11async function onNested() {
12    await Promise.resolve();
13    let context = cls.get('myContext');
14    console.log(context.name); //undefined
15    context.name = 'John Nested';
16    setTimeout(onTimeout, 300);
17}
18
19function onTimeout() {
20    let context = cls.get('myContext');
21    console.log(context.name); //John Nested
22}

Symbol as key

If you are a library author, use a Symbol as key to avoid conflicts with other libraries.

1let cls = require('node-cls');
2let key = Symbol();
3
4let context = cls.create(key);
5context.run(() => {
6    context.name = 'George';
7    setTimeout(onTimeout, 300);
8});
9
10function onTimeout() {
11    let context = cls.get(key);
12    console.log(context.name); //George
13}

Start vs run

In node 12 and above you can start a context directly instead of wrapping it in the run function. The start function returns a promise. You can leave the current context by calling exit.

1let cls = require('node-cls');
2
3async function main() {
4    let context = cls.create('myContext');
5    context.name = 'George';
6    await context.start();
7
8    let context2 = cls.create('myContext');
9    context2.name = 'John Nested';
10    await context2.start();
11    console.log(cls.get('myContext').name); //John Nested
12
13    cls.exit('myContext');
14    console.log(cls.get('myContext').name); //George
15
16    cls.exit('myContext');
17    console.log(cls.get('myContext')); //undefined
18}
19
20main();