cls-q

library1.1.0jsnpmunverified

A shim that patches Q promises to preserve continuation-local storage (CLS) contexts when calling promise.then(). Specifically designed to fix interoperability issues between Q and modules like node-redis that perform non-standard async operations. Current version 1.1.0 (last release). Works by binding callbacks to ensure the active CLS namespace is propagated. Supports binding to multiple namespaces, but with performance overhead. Requires peer dependencies `continuation-local-storage` ~3.x and `q` >=0.9.7. Lightweight (~50 lines) but only suitable for legacy Q-based codebases; modern users should migrate to native promises or async/await.

testing

npm install cls-q

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLS-Q

cls-q

testingjavascriptv1.1.0

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.

patchQ

✓ const patchQ = require('cls-q');

✗ import patchQ from 'cls-q';

cls-q is CJS-only; no ESM exports available.

patchQ(ns)

✓ patchQ(ns);

✗ patchQ(ns, Q);

The function takes only a CLS namespace; Q is patched globally, not passed as argument.

Multiple namespaces

✓ patchQ(ns1); patchQ(ns2);

✗ patchQ([ns1, ns2]);

Call the function multiple times for each namespace, but overhead accumulates.

Sets up a CLS namespace, patches Q, and demonstrates preserved context inside a promise callback.

const cls = require('continuation-local-storage'); const ns = cls.createNamespace('example'); const Q = require('q'); const patchQ = require('cls-q'); patchQ(ns); // Now Q promises will preserve CLS context ns.run(() => { ns.set('key', 'value'); Q.resolve('data').then(() => { console.log(ns.get('key')); // 'value' }); });

Debug

Known issues

deprecatedQ and continuation-local-storage are both legacy; cls-q is unmaintained since 2016.

fix

Migrate to native promises (ES2015+) or async/await; use AsyncLocalStorage (Node 12+) for context propagation.

affects: >=1.0.0

gotchaPerformance overhead when binding multiple namespaces; each namespace adds overhead to every .then() call.

fix

Minimize the number of namespaces or use a single namespace with prefix keys.

affects: >=1.0.0

gotchaOnly patches Q's then method, not other promise methods like catch, finally, or spread.

fix

Manual context binding may be needed for other promise chain methods.

affects: >=1.0.0

breakingDoes not work with Q versions <0.9.7 due to internal API changes.

fix

Upgrade Q to >=0.9.7 or use a compatible version of cls-q (older releases).

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'cls-q' Require stack: - /path/to/your/project/index.js

Package not installed. cls-q has not been published to npm (only GitHub repository).

fix

Install from GitHub: `npm install othiym23/cls-q`.

TypeError: patchQ is not a function

Incorrect import method (ESM import used instead of require).

fix

Use `const patchQ = require('cls-q');`

AssertionError: expected 'undefined' to equal 'value'

Q promises not patched before promise creation, or wrong namespace used.

fix

Ensure `patchQ(ns)` is called before any Q promise is created, and that the same namespace is used in `run()` and `get()`.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

continuation-local-storagerequiredpeer dependency: provides the namespace infrastructure that cls-q patches into

qrequiredpeer dependency: targets Q promises specifically; does not work with other promise libraries

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/othiym23/cls-q ↗

packagecls-q ↗

homepagehttps://github.com/othiym23/cls-q ↗