# express-correlation-id

> Express middleware to correlate requests across http calls

Latest version **3.0.1** (published 2024-07-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install express-correlation-id
pnpm add express-correlation-id
yarn add express-correlation-id
bun add express-correlation-id
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.1 |
| Published | 2024-07-18 |
| First published | 2016-12-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/express-correlation-id) |
| Module format | CommonJS |
| Node | >=12.17.0 |
| Dependencies | 1 |
| Unpacked size | 8.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | toboid |
| Maintainers | toboid |
| Keywords | express, logging, correlation, debug |

## Links

- npm: https://www.npmjs.com/package/express-correlation-id
- Repository: https://github.com/toboid/express-correlation-id
- Homepage: https://github.com/toboid/express-correlation-id#readme
- Issues: https://github.com/toboid/express-correlation-id/issues
- npm.io page: https://npm.io/package/express-correlation-id

## Dependencies (1)

- [correlation-id](https://npm.io/package/correlation-id.md) ^5.2.0

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 3.0.1 (latest) — 2024-07-18
- 2.0.1 — 2021-09-01
- 1.3.1 — 2019-10-06
- 1.3.0 — 2019-04-14
- 1.2.1 — 2018-12-24
- 1.2.0 — 2018-04-02
- 1.1.1 — 2018-03-10
- 1.0.2 — 2017-01-04
- 1.0.1 — 2017-01-04
- 1.0.0 — 2017-01-04
- 0.0.1 — 2016-12-07

## README

# Express correlation id

Express middleware to set a [correlation id](https://github.com/toboid/correlation-id) per route in express. The correlation id will be consistent across async calls within the handling of a request.

## Compatibility

From v3 onwards this library requires node >=16. For older node versions use v2.x.

## Installation

```shell
npm i express-correlation-id --save
```

## Middleware usage example

All middleware and route handlers following the `correlator()` middleware will be within a single correlation scope. If the incoming request has a header called `x-correlation-id` then it's value will be used as the id for this request, otherwise the id will be a new uuid.

**Note:** the correlator middleware should be placed after any other middleware.

```javascript
const correlator = require('express-correlation-id');
const express = require('express');

const app = express();
// app.use other middleware here
app.use(correlator());

app.get('/', (req, res) => {
  console.log('ID for this request is:', req.correlationId()); // id for this request
  console.log('ID for this request is:', correlator.getId()); // equal to above, not dependant on the req object
  res.end();
});
```

## API

### `correlator([options])`

Returns an express middleware that creates a correlation scope for all following middleware and route handlers. If the incoming request has a header with name `x-correlation-id` then it's value will be used as the id. The header name is configurable, see options below.
To ensure the correlation id is available to other middleware, ensure that it's applied after them.

```javascript
const app = express();
// app.use other middleware here
app.use(correlator());
```

#### options

Options to configure the correlator middleware.

##### `header`

Configures the name of the inbound header to check for a correlation id.

```javascript
const app = express();
app.use(correlator({ header: 'x-my-correlation-header-name' }));
```

### `correlator.getId()`

Returns the id for the current request. If called outside of a request returns `undefined`. This function is useful if you don't want to pass the `req` object or correlation id from the handler to downstream code.

```javascript
correlator.getId(); // Returns the current id or undefined
```

### `req.correlationId()`

Returns the id for the current request. This function is added to the incoming `req` by the middleware.

```javascript
req.correlationId(); // Returns the current id
```

### `correlator.setId(id)`

Sets the id for the current request. If called outside of a request throws and error. Useful if you
need to set the correlatiaon id and don't want to pass `req` object from the haandler to downstreama code.

```javascript
correlator.setId('my-new-id');
```

### `req.setCorrelationId()`

Sets the id for the current request. This function is added to the incoming `req` by the middleware.

```javascript
req.setCorrelationId('my-new-id');
```

## License

MIT

---
_Source: https://npm.io/package/express-correlation-id · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._