Registry / web-framework / express-correlation-id

express-correlation-id

JSON →
library3.0.1jsnpmunverified

express-correlation-id is an Express middleware that provides a unique correlation identifier for each incoming HTTP request, ensuring consistency across all asynchronous operations within the request's lifecycle. It automatically generates a UUID if no `x-correlation-id` header is present (or a configurable custom header). The library is currently stable at version 3.0.1, with recent updates indicating active maintenance. Version 3.x introduced a breaking change by requiring Node.js 16 or newer, with Node.js 20 being recommended. Its key differentiators include a simple API to access the ID via both the `req` object (`req.correlationId()`) and a static module method (`correlator.getId()`), as well as the ability to programmatically set the ID. It differentiates itself by its focus on robust async context handling for the correlation ID.

npm install express-correlation-id
INSTALL
IMPORT
SIG · EXPRESS-CORRELATIO
E
express-correlation-id
web-frameworkjavascriptv3.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

correlator
import correlator from 'express-correlation-id';
const correlator = require('express-correlation-id'); // CommonJS in ESM project import { correlator } from 'express-correlation-id'; // If correlator is default export
The `correlator` module exports a default function which is the Express middleware. It also exposes static methods like `getId` and `setId` directly on the imported `correlator` object. Use `import correlator from 'express-correlation-id'` for modern ES Modules.
correlator.getId
import correlator from 'express-correlation-id'; const id = correlator.getId();
import { getId } from 'express-correlation-id'; // getId is a method on the default export, not a named export.
The `getId` function is a static method of the default exported `correlator` object, not a separate named export. It returns `undefined` if called outside an active request context.
correlator.setId
import correlator from 'express-correlation-id'; correlator.setId('my-custom-id');
import { setId } from 'express-correlation-id'; // setId is a method on the default export, not a named export.
The `setId` function is a static method of the default exported `correlator` object. It must be called within an active request context; otherwise, it will throw an error.

This quickstart demonstrates how to integrate the `express-correlation-id` middleware into an Express application, access the generated or provided correlation ID, and programmatically set a new ID for a request.

import express from 'express'; import correlator from 'express-correlation-id'; const app = express(); // The correlator middleware should generally be placed after other middleware // that might need to run before a correlation ID is established. app.use(express.json()); // Example: other middleware app.use(correlator()); app.get('/', (req, res) => { // Access the correlation ID via the request object console.log('ID for this request (from req.correlationId()):', req.correlationId()); // Access the correlation ID via the module's static method console.log('ID for this request (from correlator.getId()):', correlator.getId()); res.send(`Correlation ID: ${req.correlationId()}`); }); app.get('/set-id', (req, res) => { const newId = `custom-${Math.random().toString(36).substring(2, 9)}`; req.setCorrelationId(newId); // Set via req object // correlator.setId(newId); // Alternatively, set via static method console.log('New ID set for this request:', req.correlationId()); res.send(`New Correlation ID set: ${req.correlationId()}`); }); const PORT = process.env.PORT || 3000; app.listen(PORT, () => { console.log(`Server listening on port ${PORT}`); });
Debug
Known issues
breakingVersion 3.0.0 of `express-correlation-id` raised the minimum required Node.js version to 16. Previous versions (2.x) supported Node.js >=12.17.0. Running v3.x on older Node.js environments will lead to compatibility issues.
fix
Upgrade your Node.js environment to version 16 or higher (20 recommended). Alternatively, for older Node.js versions, use `express-correlation-id@2.x`.
affects: >=3.0.0
gotchaThe `correlator()` middleware should be placed strategically after any other middleware that needs to run before the correlation ID is established. The `README` specifically notes it should be placed *after* other middleware.
fix
Ensure `app.use(correlator())` is called after other relevant middleware, such as `express.json()` or authentication middleware, to guarantee the correlation scope correctly encompasses subsequent handlers.
affects: >=1.0.0
gotchaCalling `correlator.getId()` or `correlator.setId(id)` outside the context of an active HTTP request will result in `undefined` for `getId()` or an error for `setId()`.
fix
Always ensure that calls to `correlator.getId()` and `correlator.setId(id)` are made within a request's processing lifecycle, typically within Express middleware or route handlers. For setting the ID, consider using `req.setCorrelationId(id)` as it's scoped to the request object.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: correlator.getId is not a function
Attempting to destructure `getId` from the `express-correlation-id` module (e.g., `import { getId } from 'express-correlation-id'`) when `getId` is a method on the default exported middleware function object.
fix
Import the default export and access `getId` as a method: `import correlator from 'express-correlation-id'; const id = correlator.getId();`
Error: setId can only be called in the context of a request
The `correlator.setId()` method was invoked in a global context or outside an active HTTP request's asynchronous scope.
fix
Ensure `correlator.setId(id)` is only called from within an Express middleware or route handler. If available, use `req.setCorrelationId(id)` as it implicitly operates within the request context.
ERR_REQUIRE_ESM: require() of ES Module ... not supported
Attempting to use `require('express-correlation-id')` in an ES Module-only Node.js project or when a project explicitly configures itself for ESM.
fix
Use ES Module syntax: `import correlator from 'express-correlation-id';`. Ensure your project's `package.json` has `"type": "module"` or uses `.mjs` file extensions for ESM.
Upgrade
Version history
3.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
18 hits · last 30 days
node
14
OpenAI (training)
2
Resources
express-correlation-id — npm install express-correlation-id · libregistry