request-context

2.0.0 verified Sat Apr 25 auth: no javascript maintenance

Connect/Express middleware that wraps each request in a Node.js domain, providing a namespace to store and retrieve data across async callbacks within the same request lifecycle. Version 2.0.0 is the latest stable release. The package uses the deprecated Node.js 'domain' module, so it is not recommended for new projects. Alternatives include AsyncLocalStorage (Node.js 12.17+) or continuation-local-storage. It supports a simple key-value API with dot notation for nested property access.

Common errors

error TypeError: Cannot read properties of undefined (reading 'user') ↓

cause Attempting to get a context value without setting namespace middleware or wrong namespace name.

fix

Ensure app.use(contextService.middleware('request')) is called before any set/get calls, and use the matching namespace prefix.

error Error: Can't set headers after they are sent. ↓

cause Domain error handler not defined, causing unhandled error to crash the domain and emit on uncaughtException.

fix

Add Express error-handling middleware (4 arguments) or a domain error listener to prevent crashes.

error ReferenceError: contextService is not defined ↓

cause Missing require('request-context') or variable not in scope.

fix

Add const contextService = require('request-context'); at top of file.

Warnings

deprecated Node.js 'domain' module is pending deprecation and may be removed in future versions. ↓

fix Migrate to AsyncLocalStorage (Node.js 12.17+) or continuation-local-storage.

gotcha Context is bound to a domain, not the request directly; errors in async callbacks may cause the domain to crash if not handled. ↓

fix Always attach an error-handling middleware (Express) or use domain error handlers.

breaking Namespace is required in set/get keys; omitting colon causes undefined behavior. ↓

fix Use format 'namespace:key' for all set/get calls.

gotcha set() with dot notation in value key does not extend existing object; it overwrites the whole property. ↓

fix Use set with object path like 'namespace:obj.key' to set nested property, not set('namespace:obj', { key: val }).

deprecated setContext and getContext are aliases for set and get; may be removed in future. ↓

fix Use set() and get() directly.

Install

npm install request-context

yarn add request-context

pnpm add request-context

Imports

default (contextService)

wrong

import contextService from 'request-context';

correct

const contextService = require('request-context');

This package does not ship ESM; use CommonJS require.

middleware

wrong

const middleware = require('request-context').middleware;

correct

const { middleware } = require('request-context');

Both are valid; destructuring is idiomatic.

set
wrong
```
contextService.set('key', value);
```
correct
```
contextService.set('namespace:key', value);
```
Keys must contain a colon separator to identify the namespace, e.g. 'request:user'.

get

wrong

const val = contextService.get('key');

correct

const val = contextService.get('namespace:key');

Keys must include the namespace prefix with colon.

Quickstart

Sets up Express with request-context middleware, sets a user object, and retrieves nested property via dot notation in route handler.

const express = require('express');
const contextService = require('request-context');

const app = express();
app.use(contextService.middleware('request'));

app.use((req, res, next) => {
  contextService.set('request:user', { name: 'Alice' });
  next();
});

app.get('/', (req, res) => {
  const user = contextService.get('request:user.name');
  res.send(`Hello ${user}`);
});

app.use((err, req, res, next) => {
  res.status(500).send('Error');
});

app.listen(3000);