request-ctxt

Request Context

Minimal Node.js library for managing per-request context and enhancing your logger automatically.

Features

• Scoped context per request using AsyncLocalStorage
• Pluggable logger (Pino, Winston, Console, etc.)
• Auto-injects traceId, userId, path into logs
• Framework agnostic - supports Express, Fastify, and native HTTP
• Clean, small, production-ready

Installation

npm install request-context

Usage

Express

import express from 'express';
import { expressMiddleware, logger } from 'request-context';

const app = express();

// Add the middleware early in your middleware chain
app.use(expressMiddleware({
    // Optional configuration
    requestIdHeader: 'x-request-id',
    getUserId: req => req.user?.id,
    getExtra: req => ({
        // Add any extra context you want
        ip: req.ip
    })
}));

// Now all your logs will automatically include request context
app.get('/', (req, res) => {
    logger.info('Hello world!');  // Will include requestId, path, userId, etc.
    res.send('Hello!');
});

Fastify

import fastify from 'fastify';
import { fastifyMiddleware, logger } from 'request-context';

const app = fastify();

// Register the middleware
app.addHook('onRequest', fastifyMiddleware({
    // Optional configuration
    requestIdHeader: 'x-request-id',
    getUserId: request => request.user?.id,
    getExtra: request => ({
        // Add any extra context you want
        ip: request.ip
    })
}));

// Now all your logs will automatically include request context
app.get('/', (request, reply) => {
    logger.info('Hello world!');  // Will include requestId, path, userId, etc.
    reply.send('Hello!');
});

Native HTTP Server

import http from 'http';
import { httpMiddleware, logger } from 'request-context';

const middleware = httpMiddleware({
    // Optional configuration
    requestIdHeader: 'x-request-id',
    getUserId: req => req.user?.id,
    getExtra: req => ({
        // Add any extra context you want
        ip: req.socket.remoteAddress
    })
});

const server = http.createServer((req, res) => {
    middleware(req, res, () => {
        logger.info('Hello world!');  // Will include requestId, path, userId, etc.
        res.end('Hello!');
    });
});

server.listen(3000);

Configuration Options

All middleware functions accept these options:

• requestIdHeader (string): Header to use for request ID. Defaults to 'x-request-id'
• getUserId (function): Function to extract user ID from request. Defaults to req.user?.id
• getExtra (function): Function to extract additional context from request. Defaults to empty object

Logger Configuration

import pino from 'pino';
import { logger } from 'request-context';

// Configure with your preferred logger
logger.configure(pino());

// Now all logs will be handled by pino
logger.info('Hello world!');

Context Values

The following context values are automatically added to every request:

• requestId: Unique ID for each request (from header or generated)
• path: Request path
• method: HTTP method
• userId: User ID (if available)
• Any additional values from getExtra()

Examples

Check out the examples directory for complete working examples using:

• Express
• Fastify
• Native HTTP Server

Each example demonstrates:

• Middleware setup
• Logger configuration
• Request handling
• Error handling
• Context propagation

Publishing

A publish script is included to help with releasing new versions. The script handles:

• npm login
• version bumping
• publishing to npm
• git tagging
• pushing changes

To use it:

# Make the script executable (one-time setup)
chmod +x publish.sh

# Publish a new version
./publish.sh <version_type>

# where version_type is one of:
# - major (for breaking changes)
# - minor (for new features)
# - patch (for bug fixes)

The script will:

• Validate your working directory is clean
• Log you into npm if needed
• Run tests if they exist
• Bump the version
• Publish to npm
• Push changes and tags to git

License

MIT