# node-cls

> Continuation Local Storage based on async_hooks

Latest version **1.0.7** (published 2020-08-11) · ISC license · 0 weekly downloads

## Install

```sh
npm install node-cls
pnpm add node-cls
yarn add node-cls
bun add node-cls
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.7 |
| Published | 2020-08-11 |
| First published | 2019-08-03 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 8.0.0 |
| Dependencies | 0 |
| Unpacked size | 15.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Lars-Erik Roald |
| Maintainers | lroal |
| Keywords | continuation-local-storage, continuation local storage, cls, async_hooks, context, domain, bluebird, context, session, async, thread |

## Links

- npm: https://www.npmjs.com/package/node-cls
- Repository: https://github.com/alfateam/node-cls
- Homepage: https://github.com/alfateam/node-cls/blob/master/README.md
- Issues: https://github.com/alfateam/node-cls/issues
- npm.io page: https://npm.io/package/node-cls

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 1.0.7 (latest) — 2020-08-11
- 1.0.6 — 2020-08-09
- 1.0.5 — 2020-03-12
- 1.0.4 — 2020-03-12
- 1.0.3 — 2019-11-19
- 1.0.2 — 2019-08-18
- 1.0.1 — 2019-08-07
- 1.0.0 — 2019-08-03

## README

__Continuation Local Storage__
------------------------------------- 
[![npm package][npm-image]][npm-url] 
[![Build Status][travis-image]][travis-url] 
[![Coverage Status][coveralls-image]][coveralls-url] 
[![Dependencies Status][david-image]][david-url]  
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](https://nodejs.org/docs/latest-v8.x/api/domain.html). It is based on [async_hooks](https://nodejs.org/docs/latest-v8.x/api/async_hooks.html) that were introduced in node 8. Beware that that the 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.
1. 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.  
```js
let http = require('http');
let cls = require('node-cls');

let server = http.createServer(function (request, response) {
    let context = cls.create('request-context');
    context.id = 1;
    context.request = request;
    context.response = response;   
    context.run(doWork);
})

server.listen(8080)

function doWork() {
    let context = cls.get('request-context');
    context.response.end(`End: ${context.id}`) //End: 1

}
```
__Async calls__  
Context is retained in async calls.  
```js
let cls = require('node-cls');

let context = cls.create('myContext');
context.run(() => {
    context.name = 'George';
    setTimeout(onTimeout, 300);
});

function onTimeout() {
    let context = cls.get('myContext');
    console.log(context.name); //George
}
```
__Nesting__  
Contexts can be nested, even on the same key.  
```js
let cls = require('node-cls');

let context = cls.create('myContext');
context.run(async () => {
    context.name = 'George';
    let context2 = cls.create('myContext');
    await context2.run(onNested);
    console.log(context.name) //George
});

async function onNested() {
    await Promise.resolve();
    let context = cls.get('myContext');
    console.log(context.name); //undefined
    context.name = 'John Nested';
    setTimeout(onTimeout, 300);
}

function onTimeout() {
    let context = cls.get('myContext');
    console.log(context.name); //John Nested
}
```
__Symbol as key__  
If you are a library author, use a Symbol as key to avoid conflicts with other libraries.  
```js
let cls = require('node-cls');
let key = Symbol();

let context = cls.create(key);
context.run(() => {
    context.name = 'George';
    setTimeout(onTimeout, 300);
});

function onTimeout() {
    let context = cls.get(key);
    console.log(context.name); //George
}
```
__Await instead of 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.  
```js
let cls = require('node-cls');

async function main() {
    let context = cls.create('myContext');
    context.name = 'George';
    await context.start();

    let context2 = cls.create('myContext');
    context2.name = 'John Nested';
    await context2.start();
    console.log(cls.get('myContext').name); //John Nested

    cls.exit('myContext');
    console.log(cls.get('myContext').name); //George

    cls.exit('myContext');
    console.log(cls.get('myContext')); //undefined
}

main();
```

[npm-image]:https://img.shields.io/npm/v/node-cls.svg
[npm-url]:http://npmjs.org/package/node-cls
[travis-image]:https://travis-ci.org/alfateam/node-cls.svg?branch=master
[travis-url]:https://travis-ci.org/alfateam/node-cls
[david-image]:https://david-dm.org/alfateam/node-cls/status.svg
[david-url]:https://david-dm.org/alfateam/node-cls
[coveralls-image]:https://coveralls.io/repos/github/alfateam/node-cls/badge.svg?branch=master
[coveralls-url]:https://coveralls.io/github/alfateam/node-cls?branch=master

---
_Source: https://npm.io/package/node-cls · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._