@sprqvntrs/logger 1.0.0

package/src/middleware/http.ts

@@ -0,0 +1,225 @@
+import pinoHttp from 'pino-http';
+import type { Options as PinoHttpOptions } from 'pino-http';
+import type { HttpLoggerOptions, LogLevel } from '../types';
+import { createLogger } from '../core/logger';
+import {
+  withRequestContext,
+  generateRequestId,
+} from '../context/async-context';
+
+/**
+ * Common static file extensions to exclude from logging
+ */
+const DEFAULT_EXCLUDE_EXTENSIONS = [
+  '.js',
+  '.css',
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.ico',
+  '.svg',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.eot',
+  '.map',
+];
+
+/**
+ * Common paths to exclude from logging
+ */
+const DEFAULT_EXCLUDE_PATHS = ['/health', '/healthz', '/ready', '/metrics', '/favicon.ico'];
+
+/**
+ * Determines log level based on response status code
+ */
+function defaultCustomLogLevel(
+  _req: unknown,
+  res: { statusCode?: number },
+  err?: Error
+): LogLevel {
+  if (err || (res.statusCode && res.statusCode >= 500)) {
+    return 'error';
+  }
+  if (res.statusCode && res.statusCode >= 400) {
+    return 'warn';
+  }
+  return 'info';
+}
+
+/**
+ * Check if a path should be excluded from logging
+ */
+function shouldExcludePath(url: string, excludePaths: string[]): boolean {
+  // Remove query string for path matching
+  const pathname = url.split('?')[0] ?? url;
+  return excludePaths.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+}
+
+/**
+ * Check if a URL has an excluded extension
+ */
+function shouldExcludeExtension(url: string, excludeExtensions: string[]): boolean {
+  const pathname = url.split('?')[0] ?? url;
+  return excludeExtensions.some((ext) => pathname.endsWith(ext));
+}
+
+interface HttpRequest {
+  id?: string;
+  method?: string;
+  url?: string;
+  headers?: Record<string, string | string[] | undefined>;
+}
+
+interface HttpResponse {
+  statusCode?: number;
+}
+
+/**
+ * Creates HTTP logging middleware using pino-http
+ *
+ * @example
+ * ```typescript
+ * import { createHttpLogger } from '@sprqvntrs/logger/http';
+ * import { createLogger } from '@sprqvntrs/logger';
+ *
+ * const logger = createLogger({ serviceName: 'api' });
+ * const httpLogger = createHttpLogger({
+ *   logger,
+ *   excludePaths: ['/health', '/metrics'],
+ * });
+ *
+ * // Express
+ * app.use(httpLogger);
+ *
+ * // Fastify
+ * fastify.addHook('onRequest', (req, reply, done) => {
+ *   httpLogger(req.raw, reply.raw, done);
+ * });
+ * ```
+ */
+export function createHttpLogger(options: HttpLoggerOptions = {}) {
+  const excludePaths = [...DEFAULT_EXCLUDE_PATHS, ...(options.excludePaths ?? [])];
+  const excludeExtensions = [
+    ...DEFAULT_EXCLUDE_EXTENSIONS,
+    ...(options.excludeExtensions ?? []),
+  ];
+
+  // Use provided logger or create a default one
+  const logger =
+    options.logger ??
+    createLogger({
+      serviceName: 'http',
+    });
+
+  const customLogLevel = options.customLogLevel ?? defaultCustomLogLevel;
+
+  const pinoHttpOptions: PinoHttpOptions = {
+    logger: logger.pino,
+
+    // Generate request ID if not present
+    genReqId: (req) => {
+      const httpReq = req as HttpRequest;
+      const existingId = httpReq.headers?.['x-request-id'];
+      if (typeof existingId === 'string') {
+        return existingId;
+      }
+      return generateRequestId();
+    },
+
+    // Control auto-logging based on path/extension exclusions
+    autoLogging: {
+      ignore: (req) => {
+        const httpReq = req as HttpRequest;
+        const url = httpReq.url ?? '';
+        return (
+          shouldExcludePath(url, excludePaths) ||
+          shouldExcludeExtension(url, excludeExtensions)
+        );
+      },
+    },
+
+    // Custom serializers for request/response
+    serializers: {
+      req: (req) => {
+        const httpReq = req as HttpRequest;
+        return {
+          id: httpReq.id,
+          method: httpReq.method,
+          url: httpReq.url,
+          // Only include safe headers
+          headers: httpReq.headers
+            ? {
+                'user-agent': httpReq.headers['user-agent'],
+                'content-type': httpReq.headers['content-type'],
+                'content-length': httpReq.headers['content-length'],
+                host: httpReq.headers['host'],
+              }
+            : undefined,
+        };
+      },
+      res: (res) => {
+        const httpRes = res as HttpResponse;
+        return {
+          statusCode: httpRes.statusCode,
+        };
+      },
+    },
+
+    // Status-based log level
+    customLogLevel: (req, res, err) => {
+      return customLogLevel(req, res as HttpResponse, err);
+    },
+
+    // Custom success message
+    customSuccessMessage: (req, res) => {
+      const httpReq = req as HttpRequest;
+      const httpRes = res as HttpResponse;
+      return `${httpReq.method} ${httpReq.url} ${httpRes.statusCode}`;
+    },
+
+    // Custom error message
+    customErrorMessage: (req, res, err) => {
+      const httpReq = req as HttpRequest;
+      const httpRes = res as HttpResponse;
+      return `${httpReq.method} ${httpReq.url} ${httpRes.statusCode} - ${err.message}`;
+    },
+
+    // Add custom properties to each log
+    customProps: options.customProps
+      ? (req, res) => options.customProps!(req, res)
+      : undefined,
+  };
+
+  const middleware = pinoHttp(pinoHttpOptions);
+
+  // Wrap middleware to set up request context
+  return (req: unknown, res: unknown, next: () => void) => {
+    const httpReq = req as HttpRequest;
+    const requestId =
+      (typeof httpReq.headers?.['x-request-id'] === 'string'
+        ? httpReq.headers['x-request-id']
+        : undefined) ?? generateRequestId();
+
+    // Set request ID on request object
+    (req as { id?: string }).id = requestId;
+
+    // Run in request context so all logs include requestId
+    withRequestContext({ requestId }, () => {
+      middleware(req as Parameters<typeof middleware>[0], res as Parameters<typeof middleware>[1], next);
+    });
+  };
+}
+
+/**
+ * Extract request ID from incoming request headers
+ * Falls back to generating a new ID
+ */
+export function extractRequestId(req: HttpRequest): string {
+  const headerValue = req.headers?.['x-request-id'];
+  if (typeof headerValue === 'string') {
+    return headerValue;
+  }
+  return generateRequestId();
+}

package/src/presets/server.ts

@@ -0,0 +1,206 @@
+import { createLogger } from '../core/logger';
+import type { Logger, ServerLogger, CreateLoggerOptions, LogLevel } from '../types';
+
+/**
+ * Options for creating a server logger
+ */
+export interface CreateServerLoggerOptions extends Omit<CreateLoggerOptions, 'serviceName'> {
+  /** Service name (required) */
+  serviceName: string;
+  /** Whether to register global error handlers (default: false) */
+  registerGlobalHandlers?: boolean;
+}
+
+/**
+ * Creates a server logger with lifecycle logging methods
+ *
+ * @example
+ * ```typescript
+ * import { createServerLogger } from '@sprqvntrs/logger/server';
+ *
+ * const { logger, logServerStart, logShutdown, logServerClosed } =
+ *   createServerLogger({ serviceName: 'api' });
+ *
+ * const server = app.listen(3000, () => {
+ *   logServerStart(3000, { url: 'http://localhost:3000' });
+ * });
+ *
+ * process.on('SIGTERM', () => {
+ *   logShutdown('SIGTERM');
+ *   server.close(() => logServerClosed());
+ * });
+ * ```
+ */
+export function createServerLogger(options: CreateServerLoggerOptions): ServerLogger {
+  const { serviceName, registerGlobalHandlers, ...loggerOptions } = options;
+  const logger = createLogger({ serviceName, ...loggerOptions });
+
+  const serverLogger: ServerLogger = {
+    logger,
+
+    logServerStart(port: number, metadata?: Record<string, unknown>): void {
+      logger.info(`${serviceName} started`, {
+        port,
+        pid: process.pid,
+        nodeVersion: process.version,
+        ...metadata,
+      });
+    },
+
+    logShutdown(signal: string): void {
+      logger.info(`${serviceName} received shutdown signal`, { signal });
+    },
+
+    logServerClosed(): void {
+      logger.info(`${serviceName} server closed`);
+    },
+
+    logUncaughtException(error: Error): void {
+      logger.fatal(`${serviceName} uncaught exception`, { error });
+    },
+
+    logUnhandledRejection(reason: unknown): void {
+      logger.error(`${serviceName} unhandled rejection`, {
+        error: reason instanceof Error ? reason : String(reason),
+      });
+    },
+  };
+
+  // Optionally register global error handlers
+  if (registerGlobalHandlers) {
+    process.on('uncaughtException', (error) => {
+      serverLogger.logUncaughtException(error);
+      process.exit(1);
+    });
+
+    process.on('unhandledRejection', (reason) => {
+      serverLogger.logUnhandledRejection(reason);
+    });
+  }
+
+  return serverLogger;
+}
+
+/**
+ * Standalone server lifecycle logging functions
+ * For when you want to use an existing logger
+ */
+export function createLifecycleLoggers(logger: Logger, serviceName: string) {
+  return {
+    logServerStart: (port: number, metadata?: Record<string, unknown>) => {
+      logger.info(`${serviceName} started`, {
+        port,
+        pid: process.pid,
+        nodeVersion: process.version,
+        ...metadata,
+      });
+    },
+
+    logShutdown: (signal: string) => {
+      logger.info(`${serviceName} received shutdown signal`, { signal });
+    },
+
+    logServerClosed: () => {
+      logger.info(`${serviceName} server closed`);
+    },
+
+    logUncaughtException: (error: Error) => {
+      logger.fatal(`${serviceName} uncaught exception`, { error });
+    },
+
+    logUnhandledRejection: (reason: unknown) => {
+      logger.error(`${serviceName} unhandled rejection`, {
+        error: reason instanceof Error ? reason : String(reason),
+      });
+    },
+  };
+}
+
+/**
+ * Creates a worker/background job logger with job-specific logging
+ *
+ * @example
+ * ```typescript
+ * const { logger, logJobStart, logJobComplete, logJobFailed } =
+ *   createWorkerLogger({ serviceName: 'background-worker' });
+ *
+ * async function processJob(job: Job) {
+ *   const startTime = Date.now();
+ *   logJobStart(job.id, job.type);
+ *
+ *   try {
+ *     await executeJob(job);
+ *     logJobComplete(job.id, job.type, Date.now() - startTime);
+ *   } catch (error) {
+ *     logJobFailed(job.id, job.type, error);
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export function createWorkerLogger(options: CreateServerLoggerOptions) {
+  const { serviceName, ...loggerOptions } = options;
+  const logger = createLogger({ serviceName, ...loggerOptions });
+
+  return {
+    logger,
+
+    logJobStart: (jobId: string, jobType: string, metadata?: Record<string, unknown>) => {
+      logger.info('Job started', { jobId, jobType, ...metadata });
+    },
+
+    logJobComplete: (
+      jobId: string,
+      jobType: string,
+      durationMs: number,
+      metadata?: Record<string, unknown>
+    ) => {
+      logger.info('Job completed', {
+        jobId,
+        jobType,
+        duration: durationMs,
+        ...metadata,
+      });
+    },
+
+    logJobFailed: (
+      jobId: string,
+      jobType: string,
+      error: unknown,
+      metadata?: Record<string, unknown>
+    ) => {
+      logger.error('Job failed', {
+        jobId,
+        jobType,
+        error: error instanceof Error ? error : String(error),
+        ...metadata,
+      });
+    },
+
+    logJobRetry: (
+      jobId: string,
+      jobType: string,
+      attempt: number,
+      maxAttempts: number,
+      error: unknown
+    ) => {
+      logger.warn('Job retry', {
+        jobId,
+        jobType,
+        attempt,
+        maxAttempts,
+        error: error instanceof Error ? error : String(error),
+      });
+    },
+  };
+}
+
+/**
+ * Log level appropriate for different HTTP status codes
+ * Useful for custom log level functions
+ */
+export function getLogLevelForStatus(statusCode: number): LogLevel {
+  if (statusCode >= 500) return 'error';
+  if (statusCode >= 400) return 'warn';
+  return 'info';
+}

package/src/testing/mock-logger.ts

@@ -0,0 +1,234 @@
+import pino from 'pino';
+import type { Logger, MockLogger, LogEntry, LogLevel, LogContext } from '../types';
+
+/**
+ * Creates a mock logger for testing purposes
+ * Captures all log entries for assertion
+ *
+ * @example
+ * ```typescript
+ * import { createMockLogger } from '@sprqvntrs/logger/testing';
+ *
+ * describe('MyService', () => {
+ *   let logger: MockLogger;
+ *
+ *   beforeEach(() => {
+ *     logger = createMockLogger();
+ *   });
+ *
+ *   it('logs user creation', () => {
+ *     const service = new MyService(logger);
+ *     service.createUser({ name: 'Test' });
+ *
+ *     expect(logger.hasLog((log) =>
+ *       log.level === 'info' &&
+ *       log.message.includes('User created')
+ *     )).toBe(true);
+ *   });
+ *
+ *   it('logs errors with context', () => {
+ *     const service = new MyService(logger);
+ *     service.failingOperation();
+ *
+ *     const errorLogs = logger.getLogsByLevel('error');
+ *     expect(errorLogs).toHaveLength(1);
+ *     expect(errorLogs[0]?.context?.error).toBeDefined();
+ *   });
+ * });
+ * ```
+ */
+export function createMockLogger(): MockLogger {
+  const logs: LogEntry[] = [];
+
+  // Create a silent pino instance for the pino property
+  const silentPino = pino({ level: 'silent' });
+
+  function createLogMethod(level: LogLevel) {
+    return (message: string, context?: LogContext) => {
+      logs.push({
+        level,
+        message,
+        context,
+        timestamp: new Date(),
+      });
+    };
+  }
+
+  const mockLogger: MockLogger = {
+    trace: createLogMethod('trace'),
+    debug: createLogMethod('debug'),
+    info: createLogMethod('info'),
+    warn: createLogMethod('warn'),
+    error: createLogMethod('error'),
+    fatal: createLogMethod('fatal'),
+
+    child(bindings: Record<string, unknown>): Logger {
+      // Create a child mock that merges bindings into context
+      const childLogs: LogEntry[] = [];
+
+      function createChildLogMethod(level: LogLevel) {
+        return (message: string, context?: LogContext) => {
+          const entry: LogEntry = {
+            level,
+            message,
+            context: { ...bindings, ...context },
+            timestamp: new Date(),
+          };
+          childLogs.push(entry);
+          // Also add to parent logs
+          logs.push(entry);
+        };
+      }
+
+      // Return a simplified child (not full MockLogger to avoid complexity)
+      return {
+        trace: createChildLogMethod('trace'),
+        debug: createChildLogMethod('debug'),
+        info: createChildLogMethod('info'),
+        warn: createChildLogMethod('warn'),
+        error: createChildLogMethod('error'),
+        fatal: createChildLogMethod('fatal'),
+        child: (moreBindings) =>
+          mockLogger.child({ ...bindings, ...moreBindings }),
+        pino: silentPino,
+      };
+    },
+
+    get pino() {
+      return silentPino;
+    },
+
+    // Test utility methods
+    getLogs(): LogEntry[] {
+      return [...logs];
+    },
+
+    clear(): void {
+      logs.length = 0;
+    },
+
+    hasLog(predicate: (log: LogEntry) => boolean): boolean {
+      return logs.some(predicate);
+    },
+
+    getLogsByLevel(level: LogLevel): LogEntry[] {
+      return logs.filter((log) => log.level === level);
+    },
+
+    getLogsByMessage(pattern: string | RegExp): LogEntry[] {
+      if (typeof pattern === 'string') {
+        return logs.filter((log) => log.message.includes(pattern));
+      }
+      return logs.filter((log) => pattern.test(log.message));
+    },
+  };
+
+  return mockLogger;
+}
+
+/**
+ * Creates a spy logger that wraps a real logger and captures calls
+ * Useful when you want real logging behavior but also want to assert on calls
+ *
+ * @example
+ * ```typescript
+ * const realLogger = createLogger({ serviceName: 'test' });
+ * const { logger, getCalls } = createSpyLogger(realLogger);
+ *
+ * // Use logger normally - it will log AND capture calls
+ * logger.info('test message');
+ *
+ * // Assert on calls
+ * expect(getCalls('info')).toContainEqual({
+ *   message: 'test message',
+ *   context: undefined,
+ * });
+ * ```
+ */
+export function createSpyLogger(realLogger: Logger) {
+  const calls: Record<LogLevel, Array<{ message: string; context?: LogContext }>> = {
+    trace: [],
+    debug: [],
+    info: [],
+    warn: [],
+    error: [],
+    fatal: [],
+  };
+
+  function createSpyMethod(level: LogLevel) {
+    return (message: string, context?: LogContext) => {
+      calls[level].push({ message, context });
+      realLogger[level](message, context);
+    };
+  }
+
+  const spyLogger: Logger = {
+    trace: createSpyMethod('trace'),
+    debug: createSpyMethod('debug'),
+    info: createSpyMethod('info'),
+    warn: createSpyMethod('warn'),
+    error: createSpyMethod('error'),
+    fatal: createSpyMethod('fatal'),
+    child: (bindings) => createSpyLogger(realLogger.child(bindings)).logger,
+    pino: realLogger.pino,
+  };
+
+  return {
+    logger: spyLogger,
+    getCalls: (level: LogLevel) => [...calls[level]],
+    getAllCalls: () => ({ ...calls }),
+    clearCalls: () => {
+      Object.keys(calls).forEach((key) => {
+        calls[key as LogLevel] = [];
+      });
+    },
+  };
+}
+
+/**
+ * Assertion helpers for testing log output
+ */
+export const logAssertions = {
+  /**
+   * Check if logs contain a message at a specific level
+   */
+  hasLogAtLevel(logs: LogEntry[], level: LogLevel, messagePattern: string | RegExp): boolean {
+    return logs.some((log) => {
+      if (log.level !== level) return false;
+      if (typeof messagePattern === 'string') {
+        return log.message.includes(messagePattern);
+      }
+      return messagePattern.test(log.message);
+    });
+  },
+
+  /**
+   * Check if any log contains specific context properties
+   */
+  hasLogWithContext(
+    logs: LogEntry[],
+    contextMatcher: Partial<LogContext>
+  ): boolean {
+    return logs.some((log) => {
+      if (!log.context) return false;
+      return Object.entries(contextMatcher).every(
+        ([key, value]) => log.context![key] === value
+      );
+    });
+  },
+
+  /**
+   * Get the most recent log at a specific level
+   */
+  getLastLogAtLevel(logs: LogEntry[], level: LogLevel): LogEntry | undefined {
+    const filtered = logs.filter((log) => log.level === level);
+    return filtered[filtered.length - 1];
+  },
+
+  /**
+   * Count logs at a specific level
+   */
+  countLogsAtLevel(logs: LogEntry[], level: LogLevel): number {
+    return logs.filter((log) => log.level === level).length;
+  },
+};