exp-correlator is a Node.js library designed to manage and propagate a correlation ID across asynchronous operations and within Express.js applications. It leverages Node.js's `async_hooks` to automatically track a unique identifier through various async calls, eliminating the need to explicitly pass the ID between functions. The current stable version is 1.0.0, and while a specific release cadence isn't stated, active GitHub workflows suggest ongoing maintenance. Its primary differentiator is the use of `async_hooks` for transparent context propagation, integrating seamlessly as an Express middleware or through a standalone async handler, and providing direct examples for integration with logging libraries like Pino and HTTP clients like exp-fetch.
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
For `exp-correlator` v1.x, the primary export is CommonJS as shown in the documentation examples. While Node.js `>=14.17` supports ESM, direct `import` might require specific `package.json` configuration or a build step for seamless integration.
const { middleware } = require('exp-correlator');
Retrieves the correlation ID from the current async context. Returns `undefined` if no correlation ID context has been established by either the `middleware` or `attachCorrelationIdHandler` in the current async chain.
const { getId } = require('exp-correlator');
Used to manually establish an async context with a correlation ID for a given async function. The correlation ID will be available via `getId()` only within the execution chain of the wrapped function.
const { attachCorrelationIdHandler } = require('exp-correlator');
Demonstrates how to integrate `exp-correlator` as an Express middleware to automatically track and log correlation IDs across request handlers and nested asynchronous operations without explicitly passing the ID.
const express = require('express');
const { middleware, getId } = require('exp-correlator');
const app = express();
const port = 3000;
const logMessage = async (msg) => {
const correlationId = getId();
console.log({ timestamp: new Date().toISOString(), correlationId, msg });
};
// Simulate an external call that needs the correlation ID
const callToExternalSystem = async () => {
const correlationId = getId();
console.log({ timestamp: new Date().toISOString(), context: 'external-call', correlationId, message: 'Making external request' });
// In a real app, you'd add correlationId to headers, e.g., 'correlation-id'
await new Promise(resolve => setTimeout(resolve, 100)); // Simulate network delay
};
app.use(middleware); // Apply the correlation ID middleware to all incoming requests
app.get('/', async (req, res) => {
const initialCorrelationId = getId();
await logMessage("Request received for /");
await callToExternalSystem();
await logMessage("After external system call");
res.json({ message: 'Hello World!', correlationId: initialCorrelationId });
});
app.get('/test', async (req, res) => {
const initialCorrelationId = getId();
await logMessage("Request received for /test");
res.json({ message: 'Test endpoint', correlationId: initialCorrelationId });
});
app.listen(port, () => {
console.log(`Server listening on http://localhost:${port}`);
console.log('Try: curl -H "correlation-id: my-custom-id" http://localhost:3000');
console.log('Or: curl http://localhost:3000/test');
});
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.