Hono-correlation-id NPM

correlationId middleware for Hono

This middleware adds a unique (and customizable) correlation id to Hono requests.

Installation

npm i hono-correlation-id

Usage

Normal:

import { Hono } from 'hono'
import { useCorrelationId } from 'hono-correlation-id'

const app = new Hono()

app.use(useCorrelationId())
app.get('/', (c) => c.json({ id: c.get('x-correlation-id') }))

export default app

Custom:

import { Hono } from 'hono'
import { useCorrelationId } from 'hono-correlation-id'
import { nanoid } from 'nanoid'

const app = new Hono()

app.use(useCorrelationId({
    header: 'x-nano-id',
    generator: () => nanoid(),
    validator: (c) => /[\w_-]{21}/.test(c)
}))

export default app

API

`useCorrelationId()` MiddlewareHandler

Returns an instance of MiddlewareHandler for Hono that generates a v4 UUID correlation id and assigns it to the existing Hono Context object.

Retrievable via c.get('correlationId') wherever a Hono Context exists.

type `correlationIdOptions` Object

Options that let you configure the incoming/outgoing correlation id header, generator, and validator.

`header` String: x-correlation-id

Configures the name of the incoming Request header to check for a correlation id. Configures the name of the outgoing Response header containing a correlation id.

`generator` Function: () => string `() => pseudo-v4uuid`

Configures the function to use for generating a correlation id. Defaults to a v4 UUID from the crypto node package.

`validator` Function: (correlationId: string) => boolean `(correlationId: string) => true`

An optional function to validate the incoming correlation id header.
true by default.
If not successfully validated, will generate a correlation id using generator function.

Extra Info

Correlation ids are passed along a typical Hono request via the Context object using the correlationId key.
They can be retrieved in a Hono route via the Context.get() method.

This can be useful for things like tracing errors:

app.onError((err, c) => {
    const correlationId = c.get('correlationId');
    console.error({ err: err, x-correlation-id: correlationId});
	return c.json({
		details: "An internal server error occurred.",
		id: correlationId
	}, 500);
});