README.md

request-local-storage

This module uses continuation-local-storage to provide access to objects that are scoped to the lifespan of a request.

Usage:

Storage access

Use getNamespace to retrieve a module-level object provider.

Note that getNamespace returns a function. It should be called at the module level. The function that's returned must be called for each access.

Example:

const RLS = require('request-local-storage').getNamespace();

function getInstance() {

	// Call `RLS()` to get the _current_ request's local object.
	if (!RLS().instance) {
		RLS().instance = new Instance();
	}

	return RLS().instance;
}

Request initialization

It's easy!

Server

Say you have a request handling function that looks like:

function handle(req, res, next) {
	...
}

You can initialize request-local-storage like this:

const RequestLocalStorage = require('request-local-storage');

function handle(req, res, next) { RequestLocalStorage.startRequest(() => {
	...
}}

Browser

In the browser you don't need to wrap a function. Just call RequestLocalStorage.startRequest() whenever you start a new request.

What is Error: RLS() access outside of request!?

It is an error to call the RLS() function returned by getNamespace() outside of a request context. If you see this error it usually means either:

• Something asynchronous hasn't been patched.
• Something is getting called when you don't expect it to.

If you are sure that you need to call RLS() from someplace where you don't know ahead of time whether you'll be in a request context or not, you can use the RLS.isActive() helper to check and avoid a try/catch.

const RLS = require('request-local-storage').getNamespace();

function getCurrentFoo() {
  if (RLS.isActive()) {
    return RLS().foo;
  }
  return null;
}

Patching 3rd party packages

Need to patch Q or some other package? No problem!

RequestLocalStorage.patch(require('cls-q'));

Find out more

Check out the design doc