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.
middleware
✓ const { middleware } = require('exp-correlator');
✗ import { middleware } from 'exp-correlator';
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.
getId
✓ const { getId } = require('exp-correlator');
✗ import { getId } from '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.
attachCorrelationIdHandler
✓ const { attachCorrelationIdHandler } = require('exp-correlator');
✗ import { attachCorrelationIdHandler } from '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.
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');
});
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'use')
The Express `app` instance was not properly initialized or is not available when `app.use(middleware)` is called.
fixEnsure `const app = express();` is executed before attempting to apply `exp-correlator`'s middleware.
correlationId is consistently 'undefined' in logs or when retrieved by getId()
The async context for the correlation ID was not properly established, or it was lost due to an unhandled async boundary (e.g., certain event emitter callbacks, `setImmediate` without proper async context propagation).
fixVerify that the `middleware` is correctly applied to your Express app or that `attachCorrelationIdHandler` wraps the entry point of your async operation. Review complex async patterns to ensure context is not inadvertently broken.
Error: `exp-correlator` requires Node.js version `14.17` or higher.
The application is running on an unsupported Node.js version, which lacks necessary `async_hooks` features or stability.
fixUpgrade your Node.js runtime to version `14.17` or newer to ensure compatibility and correct functionality.
Audit
Dependencies
No dependency data recorded yet.