voltlog-io 1.0.1 → 1.0.2

package/dist/index.d.mts

@@ -19,7 +19,7 @@ declare const LogLevelNameMap: Record<string, number>;
 /** Map from numeric value to level name */
 declare const LogLevelValueMap: Record<number, LogLevelName>;
 interface LogEntry<TMeta = Record<string, unknown>> {
-    /** Unique log ID (cuid2) */
+    /** Unique log ID */
     id: string;
     /** Numeric log level */
     level: number;
@@ -37,12 +37,16 @@ interface LogEntry<TMeta = Record<string, unknown>> {
     correlationId?: string;
     /** Error information */
     error?: LogError;
+    /** @internal Cached JSON serialization — avoids redundant stringify across transports */
+    _json?: string;
 }
 interface LogError {
     message: string;
     stack?: string;
     code?: string;
     name?: string;
+    /** Nested cause chain (ES2022 Error.cause support) */
+    cause?: LogError;
 }
 interface OcppExchangeMeta {
     /** Charge point / station identity */
@@ -108,6 +112,12 @@ interface AlertRule<TMeta = Record<string, unknown>> {
     /** Callback fired when alert conditions are met */
     onAlert: (entries: LogEntry<TMeta>[]) => void | Promise<void>;
 }
+interface TimerResult<TMeta = Record<string, unknown>> {
+    /** End the timer and log the duration */
+    done(message: string, meta?: Partial<TMeta>): void;
+    /** Get elapsed time in ms without logging */
+    elapsed(): number;
+}
 interface LoggerOptions<TMeta = Record<string, unknown>> {
     /** Minimum log level (default: INFO) */
     level?: LogLevelName;
@@ -138,6 +148,12 @@ interface LoggerOptions<TMeta = Record<string, unknown>> {
     exchangeLog?: boolean | "only";
     /** Custom timestamp function (default: Date.now) */
     timestamp?: () => number;
+    /**
+     * Custom ID generator function.
+     * Default: `crypto.randomUUID()` (native, fast).
+     * Set to `false` to disable ID generation entirely for max performance.
+     */
+    idGenerator?: (() => string) | false;
 }
 interface Logger<TMeta = Record<string, unknown>> {
     trace(message: string, meta?: Partial<TMeta>): void;
@@ -154,6 +170,16 @@ interface Logger<TMeta = Record<string, unknown>> {
     removeTransport(name: string): void;
     /** Add middleware at runtime */
     addMiddleware(middleware: LogMiddleware<TMeta>): void;
+    /** Remove middleware by reference */
+    removeMiddleware(middleware: LogMiddleware<TMeta>): void;
+    /** Change the minimum log level at runtime */
+    setLevel(level: LogLevelName): void;
+    /** Get the current minimum log level */
+    getLevel(): LogLevelName;
+    /** Check if a given level would produce output (useful to guard expensive meta computation) */
+    isLevelEnabled(level: LogLevelName): boolean;
+    /** Start a timer — call `.done(msg)` to log elapsed duration */
+    startTimer(level?: LogLevelName): TimerResult<TMeta>;
     /** Flush all transports */
     flush(): Promise<void>;
     /** Close all transports gracefully */
@@ -354,6 +380,75 @@ declare function createOpenAiErrorAnalyzer(apiKey: string, model?: string, syste
  */
 declare function alertMiddleware<TMeta = Record<string, unknown>>(rules: AlertRule<TMeta>[]): LogMiddleware<TMeta>;
 
+/**
+ * @module voltlog-io
+ * @description AsyncLocalStorage context middleware — automatically propagates
+ * context across async boundaries without manual child logger threading.
+ *
+ * @server-only Requires Node.js 16+ (AsyncLocalStorage).
+ *
+ * @example
+ * ```ts
+ * import { createLogger, prettyTransport } from 'voltlog-io';
+ * import { asyncContextMiddleware } from 'voltlog-io';
+ *
+ * const asyncCtx = asyncContextMiddleware();
+ *
+ * const logger = createLogger({
+ *   middleware: [asyncCtx.middleware],
+ *   transports: [prettyTransport()],
+ * });
+ *
+ * // In Express middleware — set context once
+ * app.use((req, res, next) => {
+ *   asyncCtx.runInContext({ requestId: req.id, userId: req.user?.id }, next);
+ * });
+ *
+ * // Anywhere downstream — context is automatic
+ * async function processOrder(orderId: string) {
+ *   logger.info('Processing', { orderId });
+ *   // → auto-includes: { requestId: 'req-123', userId: 'u-42', orderId: '...' }
+ *
+ *   await chargePayment(orderId);
+ *   logger.info('Payment charged');
+ *   // → still has requestId and userId, even after await!
+ * }
+ * ```
+ */
+
+interface AsyncContextResult<TMeta = Record<string, unknown>> {
+    /** Middleware to add to your logger — injects async context into entries */
+    middleware: LogMiddleware<TMeta>;
+    /**
+     * Run a function with the given context.
+     * All logs within the function (and any async calls it makes) will
+     * automatically include this context in their metadata.
+     */
+    runInContext: (context: Record<string, unknown>, fn: () => void) => void;
+    /**
+     * Get the current async context, or undefined if not inside a runInContext call.
+     */
+    getContext: () => Record<string, unknown> | undefined;
+    /**
+     * Update the current async context by merging new values.
+     * Only works inside a runInContext call.
+     */
+    updateContext: (updates: Record<string, unknown>) => void;
+}
+/**
+ * Creates an AsyncLocalStorage-based context system.
+ *
+ * Returns a middleware (to add to the logger) and helper functions
+ * to manage the async context.
+ *
+ * How it works:
+ * 1. Call `runInContext({ requestId, userId }, handler)` at the start of a request
+ * 2. The middleware automatically injects that context into every log entry
+ * 3. Context propagates across await, setTimeout, Promise.then, etc.
+ * 4. Each request gets its own isolated context (no cross-contamination)
+ */
+declare function asyncContextMiddleware<TMeta = Record<string, unknown>>(): AsyncContextResult<TMeta>;
+
 /**
  * @module voltlog-io
  * @description Correlation ID middleware — adds tracing IDs to logs.
@@ -442,6 +537,78 @@ interface HeapUsageOptions {
  */
 declare function heapUsageMiddleware<TMeta = Record<string, unknown>>(options?: HeapUsageOptions): LogMiddleware<TMeta>;
 
+/**
+ * @module voltlog-io
+ * @description Universal HTTP middleware builder. Allows integration with Express, Fastify, exact node:http, etc.
+ * without introducing third-party framework dependencies.
+ */
+
+/**
+ * Extracts essential logic from a given raw HTTP Request object
+ * regardless of the underlying framework (Express, Fastify, etc.)
+ */
+interface HttpRequestMapper<TReq = any> {
+    getMethod: (req: TReq) => string;
+    getUrl: (req: TReq) => string;
+    getIp?: (req: TReq) => string | undefined;
+    getUserAgent?: (req: TReq) => string | undefined;
+    /** Extract a particular header value */
+    getHeader?: (req: TReq, name: string) => string | undefined;
+}
+/**
+ * Extracts essential logic from a given raw HTTP Response object
+ */
+interface HttpResponseMapper<TRes = any> {
+    getStatusCode: (res: TRes) => number;
+    /** Execute callback when response is fully sent to the client */
+    onFinish: (res: TRes, callback: () => void) => void;
+}
+/**
+ * Options for configuring the HTTP access logger
+ */
+interface HttpLoggerOptions<TReq = any, TRes = any> {
+    reqMapper: HttpRequestMapper<TReq>;
+    resMapper: HttpResponseMapper<TRes>;
+    /** Log level to use for HTTP requests (default: INFO) */
+    level?: "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL";
+    /** Extract specific dynamic context values from the request to add to meta */
+    extractContext?: (req: TReq, res: TRes) => Record<string, unknown>;
+    /** Function to skip logging certain requests (e.g., /health) */
+    skip?: (req: TReq) => boolean;
+}
+/**
+ * Common mappers for the raw Node.js `http.IncomingMessage` and `http.ServerResponse`.
+ * Since Express and many others extend these objects, they work universally.
+ */
+declare const nodeHttpMappers: {
+    req: HttpRequestMapper;
+    res: HttpResponseMapper;
+};
+/**
+ * Creates a generic HTTP logging middleware function.
+ * Use this inside Express, Fastify, or custom routers.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createHttpLogger, nodeHttpMappers, createLogger } from 'voltlog-io';
+ *
+ * const app = express();
+ * const logger = createLogger();
+ *
+ * const httpLogger = createHttpLogger(logger, {
+ *   reqMapper: nodeHttpMappers.req,
+ *   resMapper: nodeHttpMappers.res,
+ * });
+ *
+ * app.use((req, res, next) => {
+ *   httpLogger(req, res);
+ *   next();
+ * });
+ * ```
+ */
+declare function createHttpLogger<TReq = any, TRes = any>(logger: Logger, options: HttpLoggerOptions<TReq, TRes>): (req: TReq, res: TRes) => void;
+
 /**
  * @module voltlog-io
  * @description IP middleware — extracts client IP from headers (x-forwarded-for, etc.).
@@ -532,6 +699,61 @@ interface OcppMiddlewareOptions {
  */
 declare function ocppMiddleware(options?: OcppMiddlewareOptions): LogMiddleware<OcppExchangeMeta>;
 
+/**
+ * @module voltlog-io
+ * @description OpenTelemetry middleware — automatically picks up the active trace context.
+ * Works like Winston's @opentelemetry/instrumentation-winston but as a simple middleware.
+ *
+ * @server-only Requires `@opentelemetry/api` as an optional peer dependency.
+ *
+ * When the OpenTelemetry SDK is active (e.g., with SigNoz, Jaeger, Grafana Tempo),
+ * this middleware automatically injects traceId, spanId, and traceFlags into every log entry.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, otelTraceMiddleware, otelTransport } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   middleware: [otelTraceMiddleware()],
+ *   transports: [
+ *     otelTransport({
+ *       endpoint: 'http://localhost:4318',
+ *       serviceName: 'my-app',
+ *     }),
+ *   ],
+ * });
+ *
+ * // If an OTel span is active, every log automatically gets:
+ * // { traceId: "abc123...", spanId: "def456...", traceFlags: 1 }
+ * logger.info("Processing request");
+ * ```
+ */
+
+interface OtelTraceMiddlewareOptions {
+    /**
+     * Custom reference to `@opentelemetry/api` trace module.
+     * If not provided, we attempt `require('@opentelemetry/api')` or dynamic import.
+     * This allows the middleware to work without a hard dependency.
+     */
+    traceApi?: {
+        trace: {
+            getActiveSpan: () => unknown;
+        };
+    };
+}
+/**
+ * Middleware that automatically injects OpenTelemetry trace context into log entries.
+ *
+ * How it works:
+ * 1. On each log call, checks for an active OTel span
+ * 2. If found, extracts traceId, spanId, and traceFlags
+ * 3. Injects them into the log entry's metadata
+ *
+ * This is the equivalent of Winston's @opentelemetry/instrumentation-winston
+ * but implemented as a zero-dependency middleware.
+ */
+declare function otelTraceMiddleware<TMeta = Record<string, unknown>>(options?: OtelTraceMiddlewareOptions): LogMiddleware<TMeta>;
+
 /**
  * @module voltlog-io
  * @description Redaction middleware — masks sensitive data in log entries.
@@ -799,7 +1021,7 @@ declare function discordTransport(options: DiscordTransportOptions): Transport;
 
 /**
  * @module voltlog-io
- * @description File transformer — writes logs to disk with daily rotation.
+ * @description File transformer — writes logs to disk with daily rotation and optional size-based rotation.
  * @server-only
  * This transport relies on the `node:fs` module to write files to the local filesystem.
  * Browsers do not have direct access to the filesystem for security reasons.
@@ -815,10 +1037,16 @@ interface FileTransportOptions {
     filename?: string;
     /** Per-transport level filter */
     level?: LogLevelName;
+    /**
+     * Maximum file size in bytes before rotating to a new file.
+     * When exceeded, the current file is renamed with a numeric suffix.
+     * Default: no size limit (daily rotation only).
+     */
+    maxSize?: number;
 }
 /**
  * Creates a file transport that writes newline-delimited JSON.
- * Rotates files daily based on the `%DATE%` pattern.
+ * Rotates files daily based on the `%DATE%` pattern and optionally by size.
  */
 declare function fileTransport(options: FileTransportOptions): Transport;
 
@@ -885,14 +1113,30 @@ interface LokiTransportOptions {
     basicAuthPassword?: string;
     /** Tenant ID (header X-Scope-OrgID) */
     tenantId?: string;
-    /** Labels to attach to every stream (e.g. { app: 'volt-server' }) */
+    /** Static labels to attach to every stream (e.g. { app: 'volt-server' }) */
     labels?: Record<string, string>;
+    /**
+     * Extract dynamic labels from each log entry.
+     * These are merged with static labels and used as Loki stream labels.
+     * Keep cardinality low — use only a few well-known values.
+     * @example (entry) => ({ level: entry.levelName, service: entry.context?.service })
+     */
+    dynamicLabels?: (entry: LogEntry) => Record<string, string | undefined>;
+    /**
+     * Include context, error, and correlationId in the Loki log payload.
+     * Default: true
+     */
+    includeMetadata?: boolean;
     /** Transport level filter */
     level?: LogLevelName;
     /** Batch size (default: 10) */
     batchSize?: number;
     /** Batch interval ms (default: 5000) */
     interval?: number;
+    /** Enable retry on push failure (default: false) */
+    retry?: boolean;
+    /** Maximum retries (default: 3) */
+    maxRetries?: number;
 }
 /**
  * Pushes logs to Grafana Loki via HTTP API.
@@ -900,6 +1144,75 @@ interface LokiTransportOptions {
  */
 declare function lokiTransport(options: LokiTransportOptions): Transport;
 
+/**
+ * @module voltlog-io
+ * @description OpenTelemetry OTLP transport — sends logs via OTLP HTTP/JSON protocol.
+ * @server-only Uses `fetch()` to send logs to an OTLP-compatible collector.
+ *
+ * Compatible with: SigNoz, Jaeger, Grafana Alloy, OpenTelemetry Collector, and any OTLP endpoint.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, otelTraceMiddleware, otelTransport } from 'voltlog-io';
+ *
+ * // SigNoz Cloud
+ * const logger = createLogger({
+ *   middleware: [otelTraceMiddleware()],
+ *   transports: [
+ *     otelTransport({
+ *       endpoint: 'https://ingest.signoz.io',
+ *       headers: { 'signoz-access-token': 'YOUR_TOKEN' },
+ *       serviceName: 'my-app',
+ *     }),
+ *   ],
+ * });
+ *
+ * // Self-hosted OTel Collector
+ * const logger2 = createLogger({
+ *   transports: [
+ *     otelTransport({
+ *       endpoint: 'http://localhost:4318', // OTLP HTTP port
+ *       serviceName: 'volt-csms',
+ *       resource: {
+ *         'deployment.environment': 'production',
+ *         'service.version': '2.0.0',
+ *       },
+ *     }),
+ *   ],
+ * });
+ *
+ * logger.info('Request processed', { userId: 'u-42' });
+ * // → Sent to SigNoz with traceId, spanId, severity, resource attributes
+ * ```
+ */
+
+interface OtelTransportOptions {
+    /**
+     * OTLP HTTP endpoint (e.g. http://localhost:4318 or https://ingest.signoz.io).
+     * The `/v1/logs` path is appended automatically.
+     */
+    endpoint: string;
+    /** Service name reported to the collector */
+    serviceName: string;
+    /** Additional resource attributes (e.g. deployment.environment, service.version) */
+    resource?: Record<string, string>;
+    /** Extra headers (e.g. signoz-access-token, Authorization) */
+    headers?: Record<string, string>;
+    /** Transport level filter */
+    level?: LogLevelName;
+    /** Batch size before flush (default: 20) */
+    batchSize?: number;
+    /** Batch interval in ms (default: 5000) */
+    interval?: number;
+}
+/**
+ * Creates an OTLP HTTP/JSON transport for OpenTelemetry-compatible backends.
+ *
+ * Sends logs using the OTLP Logs protocol:
+ * https://opentelemetry.io/docs/specs/otlp/#otlphttp-request
+ */
+declare function otelTransport(options: OtelTransportOptions): Transport;
+
 /**
  * @module voltlog-io
  * @description Pretty transformer — human-readable colored output with OCPP exchange formatting.
@@ -939,6 +1252,10 @@ interface PrettyTransportOptions {
     timestamps?: boolean;
     /** Use colors in output (default: true) */
     colors?: boolean;
+    /** Hide meta object in output (default: false) */
+    hideMeta?: boolean;
+    /** Pretty-print meta object with indentation (default: false) */
+    prettyMeta?: boolean;
 }
 /**
  * Create a pretty-print transport for dev/debug use.
@@ -1034,6 +1351,58 @@ interface RedisTransportOptions {
  */
 declare function redisTransport(options: RedisTransportOptions): Transport;
 
+/**
+ * @module voltlog-io
+ * @description Ring buffer transport — stores last N log entries in memory for on-demand retrieval.
+ * @universal Works in all environments.
+ *
+ * Useful for debugging, in-app log viewers, and diagnostic endpoints.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, ringBufferTransport } from 'voltlog-io';
+ *
+ * const ring = ringBufferTransport({ maxSize: 500 });
+ * const logger = createLogger({ transports: [ring] });
+ *
+ * logger.info('Hello');
+ * logger.error('Oops', new Error('fail'));
+ *
+ * // Retrieve buffered entries
+ * const entries = ring.getEntries();
+ * const errors = ring.getEntries({ level: 'ERROR' });
+ * ```
+ */
+
+interface RingBufferTransportOptions {
+    /** Maximum number of entries to keep (default: 1000) */
+    maxSize?: number;
+    /** Per-transport level filter */
+    level?: LogLevelName;
+}
+interface RingBufferQueryOptions {
+    /** Filter by minimum level */
+    level?: LogLevelName;
+    /** Return only entries after this timestamp */
+    since?: number;
+    /** Maximum entries to return (default: all) */
+    limit?: number;
+}
+interface RingBufferTransport extends Transport {
+    /** Retrieve buffered log entries with optional filtering */
+    getEntries(query?: RingBufferQueryOptions): LogEntry[];
+    /** Clear all buffered entries */
+    clear(): void;
+    /** Get current buffer size */
+    size: number;
+}
+/**
+ * Creates a ring buffer (circular buffer) transport.
+ * Stores the most recent `maxSize` entries in memory.
+ * Oldest entries are evicted when the buffer is full.
+ */
+declare function ringBufferTransport(options?: RingBufferTransportOptions): RingBufferTransport;
+
 /**
  * @module voltlog-io
  * @description Sentry transformer — pushes errors to Sentry.
@@ -1139,4 +1508,4 @@ interface WebhookTransportOptions {
  */
 declare function webhookTransport(options: WebhookTransportOptions): Transport;
 
-export { type AiEnrichmentOptions, type AlertRule, type BatchTransportOptions, type BrowserJsonStreamTransportOptions, type ConsoleTransportOptions, type CorrelationIdOptions, type DatadogTransportOptions, type DeduplicationOptions, type DiscordTransportOptions, type FileTransportOptions, type JsonStreamTransportOptions, type LevelOverrideOptions, type LogEntry, type LogError, LogLevel, type LogLevelName, LogLevelNameMap, type LogLevelValue, LogLevelValueMap, type LogMiddleware, type Logger, type LoggerOptions, type LokiTransportOptions, type OcppExchangeMeta, type OcppMiddlewareOptions, type PrettyTransportOptions, type RedactionOptions, type RedisClient, type RedisTransportOptions, type SamplingOptions, type SentryInstance, type SentryTransportOptions, type SlackTransportOptions, type Transport, type UserAgentOptions, type WebhookTransportOptions, aiEnrichmentMiddleware, alertMiddleware, batchTransport, browserJsonStreamTransport, consoleTransport, correlationIdMiddleware, createLogger, createMiddleware, createOpenAiErrorAnalyzer, createTransport, datadogTransport, deduplicationMiddleware, discordTransport, fileTransport, heapUsageMiddleware, ipMiddleware, jsonStreamTransport, levelOverrideMiddleware, lokiTransport, ocppMiddleware, prettyTransport, redactionMiddleware, redisTransport, resolveLevel, samplingMiddleware, sentryTransport, shouldIncludeStack, shouldLog, slackTransport, userAgentMiddleware, webhookTransport };
+export { type AiEnrichmentOptions, type AlertRule, type AsyncContextResult, type BatchTransportOptions, type BrowserJsonStreamTransportOptions, type ConsoleTransportOptions, type CorrelationIdOptions, type DatadogTransportOptions, type DeduplicationOptions, type DiscordTransportOptions, type FileTransportOptions, type HttpLoggerOptions, type HttpRequestMapper, type HttpResponseMapper, type JsonStreamTransportOptions, type LevelOverrideOptions, type LogEntry, type LogError, LogLevel, type LogLevelName, LogLevelNameMap, type LogLevelValue, LogLevelValueMap, type LogMiddleware, type Logger, type LoggerOptions, type LokiTransportOptions, type OcppExchangeMeta, type OcppMiddlewareOptions, type OtelTraceMiddlewareOptions, type OtelTransportOptions, type PrettyTransportOptions, type RedactionOptions, type RedisClient, type RedisTransportOptions, type RingBufferQueryOptions, type RingBufferTransport, type RingBufferTransportOptions, type SamplingOptions, type SentryInstance, type SentryTransportOptions, type SlackTransportOptions, type TimerResult, type Transport, type UserAgentOptions, type WebhookTransportOptions, aiEnrichmentMiddleware, alertMiddleware, asyncContextMiddleware, batchTransport, browserJsonStreamTransport, consoleTransport, correlationIdMiddleware, createHttpLogger, createLogger, createMiddleware, createOpenAiErrorAnalyzer, createTransport, datadogTransport, deduplicationMiddleware, discordTransport, fileTransport, heapUsageMiddleware, ipMiddleware, jsonStreamTransport, levelOverrideMiddleware, lokiTransport, nodeHttpMappers, ocppMiddleware, otelTraceMiddleware, otelTransport, prettyTransport, redactionMiddleware, redisTransport, resolveLevel, ringBufferTransport, samplingMiddleware, sentryTransport, shouldIncludeStack, shouldLog, slackTransport, userAgentMiddleware, webhookTransport };