@sprqvntrs/logger 1.0.0

package/src/core/buffered-logger.ts

@@ -0,0 +1,210 @@
+import type {
+  Logger,
+  LogContext,
+  LogEntry,
+  LogLevel,
+  BufferedLogger,
+  BufferedLoggerOptions,
+  FlushDestination,
+} from '../types';
+
+/**
+ * Creates a buffered logger that wraps an existing logger
+ * Logs are sent to the underlying logger AND buffered for later retrieval
+ *
+ * Key behavior: Child loggers share the parent's buffer
+ *
+ * @example
+ * ```typescript
+ * import { createLogger, createBufferedLogger, jsonDestination } from '@sprqvntrs/logger';
+ *
+ * const baseLogger = createLogger({ serviceName: 'my-service' });
+ * const buffered = createBufferedLogger({ logger: baseLogger });
+ *
+ * buffered.info('Request started', { path: '/api/users' });
+ *
+ * // Child loggers contribute to parent's buffer
+ * const childLogger = buffered.child({ userId: '123' });
+ * childLogger.info('User action');
+ *
+ * // Get all logs (including child logs)
+ * const logs = buffered.getBuffer();
+ * // logs.length === 2
+ *
+ * // Flush to JSON and clear
+ * const json = await buffered.flush(jsonDestination());
+ * // buffered.bufferSize === 0
+ * ```
+ *
+ * @example
+ * // With auto-flush on buffer full
+ * ```typescript
+ * const buffered = createBufferedLogger({
+ *   logger: baseLogger,
+ *   maxBufferSize: 100,
+ *   onBufferFull: async (entries) => {
+ *     await sendToLogAggregator(entries);
+ *   },
+ * });
+ * ```
+ */
+export function createBufferedLogger(options: BufferedLoggerOptions): BufferedLogger {
+  const { logger, maxBufferSize, onBufferFull } = options;
+
+  // Shared buffer that child loggers will also write to
+  const buffer: LogEntry[] = [];
+
+  // Track if we're currently flushing to prevent re-entrancy
+  let isFlushing = false;
+
+  /**
+   * Adds an entry to the buffer and handles auto-flush if needed
+   */
+  async function addToBuffer(entry: LogEntry): Promise<void> {
+    buffer.push(entry);
+
+    // Check if we need to auto-flush
+    if (maxBufferSize && buffer.length >= maxBufferSize && onBufferFull && !isFlushing) {
+      isFlushing = true;
+      try {
+        const entriesToFlush = [...buffer];
+        buffer.length = 0;
+        await onBufferFull(entriesToFlush);
+      } finally {
+        isFlushing = false;
+      }
+    }
+  }
+
+  /**
+   * Creates a log method that logs to the underlying logger and buffers
+   */
+  function createLogMethod(level: LogLevel, underlyingLogger: Logger) {
+    return (message: string, context?: LogContext): void => {
+      // Log to underlying logger
+      underlyingLogger[level](message, context);
+
+      // Add to shared buffer (fire and forget for sync interface)
+      const entry: LogEntry = {
+        level,
+        message,
+        context,
+        timestamp: new Date(),
+      };
+      void addToBuffer(entry);
+    };
+  }
+
+  /**
+   * Creates a child buffered logger that shares the parent's buffer
+   */
+  function createChildBufferedLogger(
+    childLogger: Logger,
+    bindings: Record<string, unknown>
+  ): Logger {
+    // Note: Returns Logger, not BufferedLogger, because child should not
+    // expose buffer manipulation methods (only parent controls the buffer)
+    const child: Logger = {
+      trace: (message: string, context?: LogContext): void => {
+        childLogger.trace(message, context);
+        void addToBuffer({
+          level: 'trace',
+          message,
+          context: { ...bindings, ...context },
+          timestamp: new Date(),
+        });
+      },
+      debug: (message: string, context?: LogContext): void => {
+        childLogger.debug(message, context);
+        void addToBuffer({
+          level: 'debug',
+          message,
+          context: { ...bindings, ...context },
+          timestamp: new Date(),
+        });
+      },
+      info: (message: string, context?: LogContext): void => {
+        childLogger.info(message, context);
+        void addToBuffer({
+          level: 'info',
+          message,
+          context: { ...bindings, ...context },
+          timestamp: new Date(),
+        });
+      },
+      warn: (message: string, context?: LogContext): void => {
+        childLogger.warn(message, context);
+        void addToBuffer({
+          level: 'warn',
+          message,
+          context: { ...bindings, ...context },
+          timestamp: new Date(),
+        });
+      },
+      error: (message: string, context?: LogContext): void => {
+        childLogger.error(message, context);
+        void addToBuffer({
+          level: 'error',
+          message,
+          context: { ...bindings, ...context },
+          timestamp: new Date(),
+        });
+      },
+      fatal: (message: string, context?: LogContext): void => {
+        childLogger.fatal(message, context);
+        void addToBuffer({
+          level: 'fatal',
+          message,
+          context: { ...bindings, ...context },
+          timestamp: new Date(),
+        });
+      },
+      child(moreBindings: Record<string, unknown>): Logger {
+        const mergedBindings = { ...bindings, ...moreBindings };
+        return createChildBufferedLogger(childLogger.child(moreBindings), mergedBindings);
+      },
+      get pino() {
+        return childLogger.pino;
+      },
+    };
+    return child;
+  }
+
+  const bufferedLogger: BufferedLogger = {
+    trace: createLogMethod('trace', logger),
+    debug: createLogMethod('debug', logger),
+    info: createLogMethod('info', logger),
+    warn: createLogMethod('warn', logger),
+    error: createLogMethod('error', logger),
+    fatal: createLogMethod('fatal', logger),
+
+    child(bindings: Record<string, unknown>): Logger {
+      const underlyingChild = logger.child(bindings);
+      return createChildBufferedLogger(underlyingChild, bindings);
+    },
+
+    get pino() {
+      return logger.pino;
+    },
+
+    getBuffer(): LogEntry[] {
+      return [...buffer];
+    },
+
+    clearBuffer(): void {
+      buffer.length = 0;
+    },
+
+    async flush<T>(destination: FlushDestination<T>): Promise<T> {
+      const entriesToFlush = [...buffer];
+      buffer.length = 0;
+      return destination.flush(entriesToFlush);
+    },
+
+    get bufferSize(): number {
+      return buffer.length;
+    },
+  };
+
+  return bufferedLogger;
+}

package/src/core/destinations.ts

@@ -0,0 +1,63 @@
+import type { FlushDestination, LogEntry, SerializedLogEntry } from '../types';
+
+/**
+ * Options for the JSON destination
+ */
+export interface JsonDestinationOptions {
+  /** Additional metadata to include in the output */
+  metadata?: Record<string, unknown>;
+  /** Pretty print the JSON output (default: false) */
+  pretty?: boolean;
+}
+
+/**
+ * Serializes a LogEntry to a SerializedLogEntry with ISO timestamp
+ */
+function serializeLogEntry(entry: LogEntry): SerializedLogEntry {
+  return {
+    level: entry.level,
+    message: entry.message,
+    context: entry.context,
+    timestamp: entry.timestamp.toISOString(),
+  };
+}
+
+/**
+ * Creates a flush destination that returns a JSON string
+ *
+ * @example
+ * ```typescript
+ * const buffered = createBufferedLogger({ logger });
+ *
+ * buffered.info('Request started');
+ * buffered.info('Processing', { step: 1 });
+ * buffered.info('Complete');
+ *
+ * const json = await buffered.flush(jsonDestination());
+ * // Returns: {"entries":[...], "count": 3}
+ *
+ * // With metadata:
+ * const json = await buffered.flush(jsonDestination({
+ *   metadata: { requestId: '123', userId: 'user-1' }
+ * }));
+ * // Returns: {"entries":[...], "count": 3, "requestId": "123", "userId": "user-1"}
+ * ```
+ */
+export function jsonDestination(options?: JsonDestinationOptions): FlushDestination<string> {
+  return {
+    async flush(entries: LogEntry[]): Promise<string> {
+      const serializedEntries = entries.map(serializeLogEntry);
+
+      const output: Record<string, unknown> = {
+        entries: serializedEntries,
+        count: serializedEntries.length,
+        ...options?.metadata,
+      };
+
+      if (options?.pretty) {
+        return JSON.stringify(output, null, 2);
+      }
+      return JSON.stringify(output);
+    },
+  };
+}

package/src/core/logger.ts

@@ -0,0 +1,208 @@
+import type { Logger as PinoLogger } from 'pino';
+import { createPinoInstance } from './pino-config';
+import { getRequestContext } from '../context/async-context';
+import type {
+  Logger,
+  LogContext,
+  CreateLoggerOptions,
+  LoggerConfigureOptions,
+} from '../types';
+
+/**
+ * Wraps a Pino logger instance with our Logger interface
+ */
+function wrapPinoLogger(pinoLogger: PinoLogger): Logger {
+  /**
+   * Merges context with any request context from AsyncLocalStorage
+   */
+  function mergeContext(context?: LogContext): LogContext | undefined {
+    const requestContext = getRequestContext();
+    if (!requestContext && !context) {
+      return undefined;
+    }
+    return {
+      ...requestContext,
+      ...context,
+    };
+  }
+
+  const logger: Logger = {
+    trace(message: string, context?: LogContext): void {
+      const merged = mergeContext(context);
+      if (merged) {
+        pinoLogger.trace(merged, message);
+      } else {
+        pinoLogger.trace(message);
+      }
+    },
+
+    debug(message: string, context?: LogContext): void {
+      const merged = mergeContext(context);
+      if (merged) {
+        pinoLogger.debug(merged, message);
+      } else {
+        pinoLogger.debug(message);
+      }
+    },
+
+    info(message: string, context?: LogContext): void {
+      const merged = mergeContext(context);
+      if (merged) {
+        pinoLogger.info(merged, message);
+      } else {
+        pinoLogger.info(message);
+      }
+    },
+
+    warn(message: string, context?: LogContext): void {
+      const merged = mergeContext(context);
+      if (merged) {
+        pinoLogger.warn(merged, message);
+      } else {
+        pinoLogger.warn(message);
+      }
+    },
+
+    error(message: string, context?: LogContext): void {
+      const merged = mergeContext(context);
+      if (merged) {
+        pinoLogger.error(merged, message);
+      } else {
+        pinoLogger.error(message);
+      }
+    },
+
+    fatal(message: string, context?: LogContext): void {
+      const merged = mergeContext(context);
+      if (merged) {
+        pinoLogger.fatal(merged, message);
+      } else {
+        pinoLogger.fatal(message);
+      }
+    },
+
+    child(bindings: Record<string, unknown>): Logger {
+      return wrapPinoLogger(pinoLogger.child(bindings));
+    },
+
+    get pino(): PinoLogger {
+      return pinoLogger;
+    },
+  };
+
+  return logger;
+}
+
+/**
+ * Creates a new logger instance with the given options
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({
+ *   serviceName: 'my-service',
+ *   level: 'debug',
+ * });
+ *
+ * logger.info('Server started', { port: 3000 });
+ *
+ * // Create a child logger with bound context
+ * const requestLogger = logger.child({ requestId: '123' });
+ * requestLogger.info('Processing request');
+ * ```
+ */
+export function createLogger(options: CreateLoggerOptions): Logger {
+  const pinoLogger = createPinoInstance(options);
+  return wrapPinoLogger(pinoLogger);
+}
+
+/**
+ * Static Logger class for backward compatibility
+ * Provides a singleton logger that can be configured once
+ *
+ * @example
+ * ```typescript
+ * // Configure once at startup
+ * Logger.configure({ serviceName: 'my-service' });
+ *
+ * // Use anywhere
+ * Logger.info('message', { key: 'value' });
+ * ```
+ */
+export class StaticLogger {
+  private static instance: Logger | null = null;
+
+  /**
+   * Configure the static logger
+   * Should be called once at application startup
+   */
+  static configure(options: LoggerConfigureOptions): void {
+    StaticLogger.instance = createLogger({
+      serviceName: options.serviceName,
+      level: options.level,
+      pretty: options.pretty,
+      base: options.base,
+    });
+  }
+
+  /**
+   * Get the configured logger instance
+   * Creates a default logger if not configured
+   */
+  private static getLogger(): Logger {
+    if (!StaticLogger.instance) {
+      // Create a default logger with a warning
+      StaticLogger.instance = createLogger({
+        serviceName: 'unconfigured',
+      });
+      StaticLogger.instance.warn(
+        'Logger used before configure() was called. Call Logger.configure() at application startup.'
+      );
+    }
+    return StaticLogger.instance;
+  }
+
+  static trace(message: string, context?: LogContext): void {
+    StaticLogger.getLogger().trace(message, context);
+  }
+
+  static debug(message: string, context?: LogContext): void {
+    StaticLogger.getLogger().debug(message, context);
+  }
+
+  static info(message: string, context?: LogContext): void {
+    StaticLogger.getLogger().info(message, context);
+  }
+
+  static warn(message: string, context?: LogContext): void {
+    StaticLogger.getLogger().warn(message, context);
+  }
+
+  static error(message: string, context?: LogContext): void {
+    StaticLogger.getLogger().error(message, context);
+  }
+
+  static fatal(message: string, context?: LogContext): void {
+    StaticLogger.getLogger().fatal(message, context);
+  }
+
+  /**
+   * Create a child logger with bound context
+   */
+  static child(bindings: Record<string, unknown>): Logger {
+    return StaticLogger.getLogger().child(bindings);
+  }
+
+  /**
+   * Get the underlying Pino instance
+   */
+  static get pino(): PinoLogger {
+    return StaticLogger.getLogger().pino;
+  }
+
+  /**
+   * Reset the static logger (useful for testing)
+   */
+  static reset(): void {
+    StaticLogger.instance = null;
+  }
+}

package/src/core/pino-config.ts

@@ -0,0 +1,92 @@
+import pino from 'pino';
+import type { CreateLoggerOptions } from '../types';
+import { getSerializers } from './serializers';
+
+/** Default paths to redact from logs */
+const DEFAULT_REDACT_PATHS = [
+  'password',
+  'token',
+  'authorization',
+  'apiKey',
+  'api_key',
+  'secret',
+  'credential',
+  '*.password',
+  '*.token',
+  '*.authorization',
+  '*.apiKey',
+  '*.api_key',
+  '*.secret',
+  '*.credential',
+  'headers.authorization',
+  'headers.cookie',
+];
+
+/**
+ * Gets the log level from options or environment
+ */
+function getLogLevel(options: CreateLoggerOptions): string {
+  return options.level ?? process.env['LOG_LEVEL'] ?? 'info';
+}
+
+/**
+ * Creates the transport configuration for pretty printing
+ */
+function createPrettyTransport(): pino.TransportSingleOptions {
+  return {
+    target: 'pino-pretty',
+    options: {
+      colorize: true,
+      translateTime: 'UTC:yyyy-mm-dd HH:MM:ss.l',
+      ignore: 'pid,hostname',
+      messageFormat: '{msg}',
+    },
+  };
+}
+
+/**
+ * Creates a Pino logger configuration from options
+ */
+export function createPinoConfig(options: CreateLoggerOptions): pino.LoggerOptions {
+  const shouldPrettyPrint = options.pretty ?? false;
+  const logLevel = getLogLevel(options);
+  const redactPaths = [...DEFAULT_REDACT_PATHS, ...(options.redactPaths ?? [])];
+
+  const config: pino.LoggerOptions = {
+    level: logLevel,
+    base: {
+      service: options.serviceName,
+      version: options.version ?? process.env['npm_package_version'],
+      env: process.env['NODE_ENV'],
+      ...options.base,
+    },
+    timestamp: options.timestamp !== false ? pino.stdTimeFunctions.isoTime : false,
+    formatters: {
+      level: (label) => ({ level: label }),
+      bindings: (bindings) => {
+        // In production, keep hostname and pid; in dev, they're ignored by pino-pretty
+        return bindings;
+      },
+    },
+    redact: {
+      paths: redactPaths,
+      censor: '[REDACTED]',
+    },
+    serializers: getSerializers(),
+  };
+
+  // Only add transport in development mode with pretty printing
+  if (shouldPrettyPrint) {
+    config.transport = createPrettyTransport();
+  }
+
+  return config;
+}
+
+/**
+ * Creates a configured Pino logger instance
+ */
+export function createPinoInstance(options: CreateLoggerOptions): pino.Logger {
+  const config = createPinoConfig(options);
+  return pino(config);
+}

package/src/core/serializers.ts

@@ -0,0 +1,81 @@
+import pino from 'pino';
+
+/**
+ * Standard error serializer that handles Error objects
+ * and extracts useful information including cause chain
+ */
+export function errorSerializer(error: unknown): Record<string, unknown> | unknown {
+  if (error instanceof Error) {
+    return {
+      type: error.constructor.name,
+      message: error.message,
+      stack: error.stack,
+      ...(error.cause !== undefined && { cause: errorSerializer(error.cause) }),
+      // Include any additional properties on the error
+      ...Object.fromEntries(
+        Object.entries(error).filter(
+          ([key]) => !['message', 'stack', 'cause'].includes(key)
+        )
+      ),
+    };
+  }
+  return error;
+}
+
+/**
+ * Request serializer for HTTP requests
+ * Extracts commonly needed fields while excluding sensitive data
+ */
+export function requestSerializer(req: {
+  id?: string;
+  method?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  remoteAddress?: string;
+}): Record<string, unknown> {
+  return {
+    id: req.id,
+    method: req.method,
+    url: req.url,
+    // Only include non-sensitive headers
+    headers: req.headers
+      ? {
+          'user-agent': req.headers['user-agent'],
+          'content-type': req.headers['content-type'],
+          'content-length': req.headers['content-length'],
+          host: req.headers['host'],
+        }
+      : undefined,
+    remoteAddress: req.remoteAddress,
+  };
+}
+
+/**
+ * Response serializer for HTTP responses
+ */
+export function responseSerializer(res: {
+  statusCode?: number;
+  headers?: Record<string, string>;
+}): Record<string, unknown> {
+  return {
+    statusCode: res.statusCode,
+    headers: res.headers
+      ? {
+          'content-type': res.headers['content-type'],
+          'content-length': res.headers['content-length'],
+        }
+      : undefined,
+  };
+}
+
+/**
+ * Get all custom serializers
+ */
+export function getSerializers(): pino.LoggerOptions['serializers'] {
+  return {
+    err: pino.stdSerializers.err,
+    error: errorSerializer,
+    req: requestSerializer,
+    res: responseSerializer,
+  };
+}