@blue.ts/logging

@blue.ts/logging

Structured logging for blue.ts. Pino-compatible JSON output with child loggers, pluggable transports, and per-request scoped context via the DI container.

Installation

bun add @blue.ts/logging

Quick Start

import { LoggingModule, ConsoleTransport } from '@blue.ts/logging';

app.registerProvider(
    new LoggingModule({
        transports: [new ConsoleTransport()],
        level: 'info',
        fields: { service: 'api', version: '1.0.0' },
    })
);

Logger

Logger writes structured JSON entries across six severity levels.

import { Logger, ConsoleTransport } from '@blue.ts/logging';

const logger = new Logger({
    transports: [new ConsoleTransport()],
    level: 'info',             // minimum level to emit (default: 'info')
    fields: { service: 'api' } // merged into every entry
});

logger.trace('Verbose detail');
logger.debug('Debug info');
logger.info('Server started', { port: 3000 });
logger.warn('Slow query', { durationMs: 320, query: 'SELECT ...' });
logger.error('Request failed', { error: err.message });
logger.fatal('Unrecoverable error');

Log levels (lowest → highest)

Level	Numeric	Use
trace	10	Highly verbose debugging
debug	20	Development debugging
info	30	Normal operational events
warn	40	Unexpected but recoverable
error	50	Failures that need attention
fatal	60	Process-ending errors

Child loggers

Child loggers inherit parent transports, level, and fields — and merge in their own:

const reqLogger = logger.child({ reqId: crypto.randomUUID(), userId: 'u123' });
reqLogger.info('Processing request');
// → { "level": 30, "msg": "Processing request", "service": "api", "reqId": "...", "userId": "u123" }

LoggingModule

LoggingModule is a ConfigProvider that wires the logger into the DI container.

It registers two tokens:

Token	Lifetime	Description
LoggerToken	singleton	Root logger — same instance for the process lifetime
RequestLoggerToken	scoped	Child logger with a unique reqId per request

import { LoggingModule, ConsoleTransport, LoggerToken, RequestLoggerToken } from '@blue.ts/logging';
import type { ILogger } from '@blue.ts/logging';

app.registerProvider(
    new LoggingModule({
        transports: [new ConsoleTransport()],
        level: 'debug',
        fields: { service: 'my-api', env: process.env.NODE_ENV },
    })
);

// Inject into a class-based handler
class MyHandler {
    constructor(private readonly log: ILogger) {}

    handle(ctx) {
        this.log.info('Handling request', { path: ctx.req.url });
        return Context.json({ ok: true });
    }
}

app.registerDependency(MyHandler, {
    lifetime: 'transient',
    factory: async (c) => new MyHandler(await c.get(RequestLoggerToken)),
});

Transports

ConsoleTransport

Writes JSON entries to stdout. Best for development and containerised deployments.

import { ConsoleTransport } from '@blue.ts/logging';

new ConsoleTransport()
// → {"level":30,"time":1712345678901,"pid":12345,"hostname":"host","msg":"..."}

FileTransport

Appends newline-delimited JSON to a file. Rotates when the file exceeds maxBytes.

import { FileTransport } from '@blue.ts/logging';

new FileTransport({
    path: './logs/app.log',
    maxBytes: 10 * 1024 * 1024, // 10 MB — rotate after this size
});

BunWorkerTransport

Offloads all I/O to a Bun Worker thread so the main thread is never blocked.

import { BunWorkerTransport } from '@blue.ts/logging';

const transport = new BunWorkerTransport({
    path: './logs/app.log',
    maxBytes: 10 * 1024 * 1024,
});

// At graceful shutdown — flush and close the worker
await transport.flush();
await transport.close();

Multiple transports

new LoggingModule({
    transports: [
        new ConsoleTransport(),
        new BunWorkerTransport({ path: './logs/app.log' }),
    ],
    level: 'info',
});

Custom transport

Implement the Transport interface to write to any backend:

import type { Transport, LogEntry } from '@blue.ts/logging';

class DatadogTransport implements Transport {
    write(entry: LogEntry): void {
        fetch('https://http-intake.logs.datadoghq.com/api/v2/logs', {
            method: 'POST',
            body: JSON.stringify(entry),
            headers: { 'DD-API-KEY': process.env.DD_API_KEY! },
        });
    }

    async flush(): Promise<void> { /* wait for in-flight requests */ }
}

Log Entry Shape

All entries follow the pino JSON format:

{
  "level": 30,
  "time": 1712345678901,
  "pid": 12345,
  "hostname": "api-server-1",
  "msg": "Request completed",
  "service": "api",
  "reqId": "a1b2c3d4",
  "method": "GET",
  "path": "/users",
  "durationMs": 12
}

Compatible with pino-pretty for human-readable local development output:

bun run index.ts | bunx pino-pretty