Registry / devops / node-context-storage

node-context-storage

library1.0.4jsnpmunverified

A lightweight utility for managing asynchronous context in Node.js using AsyncLocalStorage. v1.0.4 provides a simple API to create, get, set, and run context across async boundaries, with built-in Express middleware for request-level context. Unlike heavy solutions like continuation-local-storage or cls-hooked, it leverages Node's native AsyncLocalStorage for performance and reliability. Ships TypeScript definitions. Updated infrequently (last release Nov 2023).

devops

npm install node-context-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-CONTEXT-STORA

node-context-storage

devopsjavascriptv1.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createContext

✓ import { createContext } from 'node-context-storage'

✗ const createContext = require('node-context-storage')

Package is ESM-first but also supports CJS require(). Use named import for ESM.

createContextMiddleware

✓ import { createContextMiddleware } from 'node-context-storage'

✗ import { createContextMiddleware } from 'node-context-storage/middleware'

The middleware is exported from the main entry point, not a subpath.

ContextAPI

✓ import type { ContextAPI } from 'node-context-storage'

✗ import { ContextAPI } from 'node-context-storage'

ContextAPI is a TypeScript type, not a runtime value. Use type import to avoid errors in isolatedModules.

Creates a typed context, runs an async function within it, and demonstrates get/set/exists methods.

import { createContext } from 'node-context-storage'; const context = createContext<{ userId: string }>(); async function main() { const userId = 'user-123'; await context.run({ context: { userId } }, async () => { console.log(context.get()); // { userId: 'user-123' } context.set({ userId: 'updated' }); console.log(context.get()); // { userId: 'updated' } }); console.log(context.exists()); // false (context cleaned up) } main().catch(console.error);

Debug

Known issues

breakingCalling context.get() outside an async function run will throw. Always guard with exists() or ensure you are inside run().

fix

Use context.exists() before calling context.get() to avoid runtime errors.

affects: >=0.0.1

gotchacontext.set() merges partial context objects, not replacing the entire context. This may cause unintended mutations if you assume a full replacement.

fix

If you need to replace the entire context, call context.set() with all properties or use a new run().

affects: >=0.0.1

deprecatedThe package is actively maintained but has a low release cadence. No known deprecations yet.

fix

Check GitHub for updates; consider alternatives like @opentelemetry/api if you need more features.

affects: >=1.0.0

gotchaContext is lost when using async boundaries that are not supported by AsyncLocalStorage (e.g., worker_threads).

fix

For worker threads, manually pass context or use a dedicated context propagation library.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: Cannot destructure property 'context' of 'store' as it is undefined.

Calling context.get() or context.getStore() outside of a context.run() callback.

fix

Wrap the code inside context.run() or check context.exists() before accessing context.

Property 'context' does not exist on type '{}'.

TypeScript strict typing when passing an empty object to context.run() without the required shape.

fix

Provide an initial store with the correct shape: context.run({ context: { userId: '...' } }, ...).

Module '"node-context-storage"' has no exported member 'createContextMiddleware'.

Attempting to import from a subpath that does not exist; middleware is part of the main export.

fix

Import from the package root: import { createContextMiddleware } from 'node-context-storage'.

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

@types/expressoptionalRequired for TypeScript users to type Express middleware correctly

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/paripsky/node-context-storage ↗

packagenode-context-storage ↗

homepagehttps://github.com/paripsky/node-context-storage#readme ↗