Express Correlation ID Middleware

Common errors

• TypeError: correlator.getId is not a function

  cause 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

  cause 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

  cause 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.

Warnings

• breaking Version 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`.
• gotcha The `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.
• gotcha Calling `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.

Install

• npm install express-correlation-id npm
• yarn add express-correlation-id yarn
• pnpm add express-correlation-id pnpm

Imports

• correlator
  wrong:

  const correlator = require('express-correlation-id'); // CommonJS in ESM project
  import { correlator } from 'express-correlation-id'; // If correlator is default export

  correct:

  import correlator from 'express-correlation-id';

  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
  wrong:

  import { getId } from 'express-correlation-id'; // getId is a method on the default export, not a named export.

  correct:

  import correlator from 'express-correlation-id';
  const id = correlator.getId();

  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
  wrong:

  import { setId } from 'express-correlation-id'; // setId is a method on the default export, not a named export.

  correct:

  import correlator from 'express-correlation-id';
  correlator.setId('my-custom-id');

  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.

Quickstart

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}`);
});