Product
Introducing Java Support in Socket
We're excited to announce that Socket now supports the Java programming language.
continuation-local-storage
Advanced tools
userland implementation of https://github.com/joyent/node/issues/5243
The continuation-local-storage (CLS) npm package provides a way to maintain context across asynchronous calls in Node.js. It allows you to create a namespace to store data that is accessible across different asynchronous operations, which is useful for tasks like logging, error tracking, and request tracing.
Creating a Namespace
This feature allows you to create a namespace where you can store and retrieve data across asynchronous calls.
const cls = require('continuation-local-storage');
const namespace = cls.createNamespace('myNamespace');
Setting and Getting Data
Within a namespace, you can set and get data that will be available throughout the asynchronous call chain.
namespace.run(() => {
namespace.set('key', 'value');
console.log(namespace.get('key')); // Outputs: value
});
Using with Asynchronous Functions
This feature demonstrates how to use CLS with asynchronous functions, ensuring that the context is maintained across asynchronous boundaries.
const asyncFunction = async () => {
namespace.set('key', 'value');
await new Promise(resolve => setTimeout(resolve, 1000));
console.log(namespace.get('key')); // Outputs: value
};
namespace.run(() => {
asyncFunction();
});
The async_hooks module is a core Node.js module that provides an API to track asynchronous resources. It is more low-level compared to continuation-local-storage and offers more control but requires more boilerplate code.
cls-hooked is a modern alternative to continuation-local-storage that uses the async_hooks module under the hood. It provides a similar API to CLS but with better performance and support for newer Node.js versions.
zone.js is a library that provides execution contexts (zones) that persist across asynchronous operations. It is more commonly used in Angular applications but can be used in Node.js as well. It offers more features but is also more complex.
Continuation-local storage works like thread-local storage in threaded programming, but is based on chains of Node-style callbacks instead of threads. The standard Node convention of functions calling functions is very similar to something called "continuation-passing style" in functional programming, and the name comes from the way this module allows you to set and get values that are scoped to the lifetime of these chains of function calls.
Suppose you're writing a module that fetches a user and adds it to a session before calling a function passed in by a user to continue execution:
// setup.js
var createNamespace = require('continuation-local-storage').createNamespace;
var session = createNamespace('my session');
var db = require('./lib/db.js');
function start(options, next) {
db.fetchUserById(options.id, function (error, user) {
if (error) return next(error);
session.set('user', user);
next();
});
}
Later on in the process of turning that user's data into an HTML page, you call another function (maybe defined in another module entirely) that wants to fetch the value you set earlier:
// send_response.js
var getNamespace = require('continuation-local-storage').getNamespace;
var session = getNamespace('my session');
var render = require('./lib/render.js')
function finish(response) {
var user = session.get('user');
render({user: user}).pipe(response);
}
When you set values in continuation-local storage, those values are accessible
until all functions called from the original function – synchronously or
asynchronously – have finished executing. This includes callbacks passed to
process.nextTick
and the timer functions (setImmediate,
setTimeout, and setInterval), as well as callbacks passed to
asynchronous functions that call native functions (such as those exported from
the fs
, dns
, zlib
and crypto
modules).
A simple rule of thumb is anywhere where you might have set a property on the
request
or response
objects in an HTTP handler, you can (and should) now
use continuation-local storage. This API is designed to allow you extend the
scope of a variable across a sequence of function calls, but with values
specific to each sequence of calls.
Values are grouped into namespaces, created with createNamespace()
. Sets of
function calls are grouped together by calling them within the function passed
to .run()
on the namespace object. Calls to .run()
can be nested, and each
nested context this creates has its own copy of the set of values from the
parent context. When a function is making multiple asynchronous calls, this
allows each child call to get, set, and pass along its own context without
overwriting the parent's.
A simple, annotated example of how this nesting behaves:
var createNamespace = require('continuation-local-storage').createNamespace;
var writer = createNamespace('writer');
writer.run(function () {
writer.set('value', 0);
requestHandler();
});
function requestHandler() {
writer.run(function(outer) {
// writer.get('value') returns 0
// outer.value is 0
writer.set('value', 1);
// writer.get('value') returns 1
// outer.value is 1
process.nextTick(function() {
// writer.get('value') returns 1
// outer.value is 1
writer.run(function(inner) {
// writer.get('value') returns 1
// outer.value is 1
// inner.value is 1
writer.set('value', 2);
// writer.get('value') returns 2
// outer.value is 1
// inner.value is 2
});
});
});
setTimeout(function() {
// runs with the default context, because nested contexts have ended
console.log(writer.get('value')); // prints 0
}, 1000);
}
Each application wanting to use continuation-local values should create its own namespace. Reading from (or, more significantly, writing to) namespaces that don't belong to you is a faux pas.
Look up an existing namespace.
Dispose of an existing namespace. WARNING: be sure to dispose of any references to destroyed namespaces in your old code, as contexts associated with them will no longer be propagated.
Completely reset all continuation-local storage namespaces. WARNING: while this will stop the propagation of values in any existing namespaces, if there are remaining references to those namespaces in code, the associated storage will still be reachable, even though the associated state is no longer being updated. Make sure you clean up any references to destroyed namespaces yourself.
Continuation-local storage has a performance cost, and so it isn't enabled
until the module is loaded for the first time. Once the module is loaded, the
current set of namespaces is available in process.namespaces
, so library code
that wants to use continuation-local storage only when it's active should test
for the existence of process.namespaces
.
Application-specific namespaces group values local to the set of functions
whose calls originate from a callback passed to namespace.run()
or
namespace.bind()
.
value
Set a value on the current continuation context. Must be set within an active
continuation chain started with namespace.run()
or namespace.bind()
.
undefined
Look up a value on the current continuation context. Recursively searches from
the innermost to outermost nested continuation context for a value associated
with a given key. Must be set within an active continuation chain started with
namespace.run()
or namespace.bind()
.
Create a new context on which values can be set or read. Run all the functions that are called (either directly, or indirectly through asynchronous functions that take callbacks themselves) from the provided callback within the scope of that namespace. The new context is passed as an argument to the callback when it's called.
Create a new context on which values can be set or read. Run all the functions that are called (either directly, or indirectly through asynchronous functions that take callbacks themselves) from the provided callback within the scope of that namespace. The new context is passed as an argument to the callback when it's called.
Same as namespace.run()
but returns the return value of the callback rather
than the context.
Bind a function to the specified namespace. Works analogously to
Function.bind()
or domain.bind()
. If context is omitted, it will default to
the currently active context in the namespace, or create a new context if none
is currently defined.
Bind an EventEmitter to a namespace. Operates similarly to domain.add
, with a
less generic name and the additional caveat that unlike domains, namespaces
never implicitly bind EventEmitters to themselves when they're created within
the context of an active namespace.
The most likely time you'd want to use this is when you're using Express or Connect and want to make sure your middleware execution plays nice with CLS, or are doing other things with HTTP listeners:
http.createServer(function (req, res) {
writer.bindEmitter(req);
writer.bindEmitter(res);
// do other stuff, some of which is asynchronous
});
Use this with namespace.bind()
, if you want to have a fresh context at invocation time,
as opposed to binding time:
function doSomething(p) {
console.log("%s = %s", p, ns.get(p));
}
function bindLater(callback) {
return writer.bind(callback, writer.createContext());
}
setInterval(function () {
var bound = bindLater(doSomething);
bound('test');
}, 100);
A context is a plain object created using the enclosing context as its prototype.
See LICENSE
for the details of the BSD 2-clause "simplified" license used by
continuation-local-storage
. This package was developed in 2012-2013 (and is
maintained now) by Forrest L Norvell, @othiym23,
with considerable help from Timothy Caswell,
@creationix, working for The Node Firm. This
work was underwritten by New Relic for use in their Node.js instrumentation
agent, so maybe give that a look if you have some Node.js
performance-monitoring needs.
FAQs
userland implementation of https://github.com/joyent/node/issues/5243
The npm package continuation-local-storage receives a total of 1,172,309 weekly downloads. As such, continuation-local-storage popularity was classified as popular.
We found that continuation-local-storage demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
We're excited to announce that Socket now supports the Java programming language.
Security News
Socket detected a malicious Python package impersonating a popular browser cookie library to steal passwords, screenshots, webcam images, and Discord tokens.
Security News
Deno 2.0 is now available with enhanced package management, full Node.js and npm compatibility, improved performance, and support for major JavaScript frameworks.