Registry / devops / asynchronous-local-storage

asynchronous-local-storage

library1.0.2jsnpmunverified

Provides a unified API for asynchronous local storage in Node.js, using the native AsyncLocalStorage (available since Node.js 12.17.0 / 14.0.0) with automatic fallback to cls-hooked for older Node.js versions (>=6). Version 1.0.2 is the latest stable release. It offers a simple get/set/runWith interface and is designed to be a drop-in replacement for CLS-based libraries, making it easier to manage request-scoped data without worrying about Node.js version compatibility. Ships TypeScript definitions.

devops

npm install asynchronous-local-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ASYNCHRONOUS-LOCAL

asynchronous-local-storage

devopsjavascriptv1.0.2

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.

als

✓ import { als } from 'asynchronous-local-storage'

✗ const als = require('asynchronous-local-storage')

TypeScript/ESM usage: named import. CommonJS users can use destructuring require.

runWith

✓ import { runWith } from 'asynchronous-local-storage'

✗ const { runWith } = require('asynchronous-local-storage');

runWith is exported as a named function. The default export is the als object so you can also do `import als from 'asynchronous-local-storage'` and use `als.runWith()`.

default (als object)

✓ import als from 'asynchronous-local-storage'

✗ import { als } from 'asynchronous-local-storage' // This is also correct but redundant

Default export is the als instance. Named export `{ als }` is the same object.

Demonstrates creating a request-scoped context with Express, setting a default value, then retrieving it in a route handler.

import { als, runWith } from 'asynchronous-local-storage'; import express from 'express'; const app = express(); app.use((req, res, next) => { runWith(() => next(), { requestId: req.headers['x-request-id'] ?? 'unknown' }); }); app.get('/', (req, res) => { const requestId = als.get('requestId'); res.json({ requestId }); }); app.listen(3000, () => console.log('Server running on port 3000'));

Debug

Known issues

gotchaals.set/als.get only work within a context started by runWith. Outside a context, set silently does nothing and get returns undefined.

fix

Always wrap your code in runWith before using set/get, or check als.getActiveContext() to see if a context exists.

affects: >=0.0.0

breakingThe default export changed from a function to an object in v1.0.0. Previously you could do `require('asynchronous-local-storage')(callback)` now you must use `als.runWith(callback)`.

fix

Update code: replace `require('asynchronous-local-storage')(fn)` with `als.runWith(fn)`.

affects: <1.0.0

deprecatedThe legacy API `createContext` and `destroyContext` have been deprecated since v1.0.0 in favor of runWith.

fix

Use runWith instead of manual context creation/destruction.

affects: >=1.0.0 <1.1.0

Errors

Common errors & fixes

TypeError: als.runWith is not a function

Trying to import the default export as a function when it is an object.

fix

Use `import als from 'asynchronous-local-storage'` and then `als.runWith(...)` or destructure `{ runWith }`.

Cannot read property 'get' of undefined

als is undefined because import failed (e.g., missing named export).

fix

Ensure you import correctly: `import { als } from 'asynchronous-local-storage'` (type: module) or `const { als } = require('asynchronous-local-storage')`.

als.get('key') returns undefined even inside runWith

The key was set inside a different context scope (e.g., in a callback that escaped the async context).

fix

Make sure you call set/get within the same async chain started by runWith. Consider using AsyncResource to bind callbacks if needed.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

cls-hookedoptionalUsed as fallback for Node.js versions < 12.17.0 / < 14.0.0 where AsyncLocalStorage is not available.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubgit://github.com/kibertoad/asynchronous-local-storage ↗

packageasynchronous-local-storage ↗

homepagehttps://github.com/kibertoad/asynchronous-local-storage ↗