@ontrails/logging 1.0.0-beta.0

package/src/__tests__/logger.test.ts

@@ -0,0 +1,279 @@
+import { describe, test, expect } from 'bun:test';
+
+import { createLogger } from '../logger.js';
+import type { LogRecord, LogSink } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const captureSink = (): { records: LogRecord[]; sink: LogSink } => {
+  const records: LogRecord[] = [];
+  const sink: LogSink = {
+    name: 'capture',
+    write(record: LogRecord): void {
+      records.push(record);
+    },
+  };
+  return { records, sink };
+};
+
+// ---------------------------------------------------------------------------
+// createLogger basics
+// ---------------------------------------------------------------------------
+
+describe('createLogger', () => {
+  test('produces a working logger with default config', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({ name: 'app', sinks: [sink] });
+
+    logger.info('hello');
+    expect(records).toHaveLength(1);
+    const [first] = records;
+    expect(first?.message).toBe('hello');
+    expect(first?.category).toBe('app');
+    expect(first?.level).toBe('info');
+  });
+
+  test('logger.name returns the category', () => {
+    const logger = createLogger({ name: 'my.app', sinks: [] });
+    expect(logger.name).toBe('my.app');
+  });
+
+  test('logger with no sinks does not throw', () => {
+    const logger = createLogger({ name: 'silent', sinks: [] });
+    expect(() => logger.info('hello')).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Level methods
+// ---------------------------------------------------------------------------
+
+describe('log level methods', () => {
+  test('all six methods dispatch to sinks at appropriate levels', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'trace',
+      name: 'app',
+      sinks: [sink],
+    });
+
+    logger.trace('t');
+    logger.debug('d');
+    logger.info('i');
+    logger.warn('w');
+    logger.error('e');
+    logger.fatal('f');
+
+    expect(records).toHaveLength(6);
+    expect(records.map((r) => r.level)).toEqual([
+      'trace',
+      'debug',
+      'info',
+      'warn',
+      'error',
+      'fatal',
+    ]);
+  });
+
+  test('messages below configured level are suppressed', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'warn',
+      name: 'app',
+      sinks: [sink],
+    });
+
+    logger.trace('t');
+    logger.debug('d');
+    logger.info('i');
+    logger.warn('w');
+    logger.error('e');
+
+    expect(records).toHaveLength(2);
+    expect(records.map((r) => r.level)).toEqual(['warn', 'error']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// child()
+// ---------------------------------------------------------------------------
+
+describe('child()', () => {
+  test('inherits parent config and merges metadata', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'trace',
+      name: 'app',
+      sinks: [sink],
+    });
+
+    const child = logger.child({ requestId: 'r1' });
+    child.info('hello');
+
+    expect(records).toHaveLength(1);
+    const [first] = records;
+    expect(first?.metadata).toEqual({ requestId: 'r1' });
+  });
+
+  test('child logger metadata appears on every log record', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'trace',
+      name: 'app',
+      sinks: [sink],
+    });
+
+    const child = logger.child({ traceId: 't1' });
+    child.info('a');
+    child.warn('b');
+
+    expect(records[0]?.metadata).toEqual({ traceId: 't1' });
+    expect(records[1]?.metadata).toEqual({ traceId: 't1' });
+  });
+
+  test('multiple child() calls compose metadata correctly', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'trace',
+      name: 'app',
+      sinks: [sink],
+    });
+
+    const child1 = logger.child({ requestId: 'r1' });
+    const child2 = child1.child({ userId: 'u1' });
+    child2.info('hello');
+
+    const [first] = records;
+    expect(first?.metadata).toEqual({ requestId: 'r1', userId: 'u1' });
+  });
+
+  test('child metadata merges with per-call metadata', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'trace',
+      name: 'app',
+      sinks: [sink],
+    });
+
+    const child = logger.child({ requestId: 'r1' });
+    child.info('hello', { extra: true });
+
+    const [first] = records;
+    expect(first?.metadata).toEqual({ extra: true, requestId: 'r1' });
+  });
+
+  test('child preserves parent name', () => {
+    const logger = createLogger({ name: 'app.db', sinks: [] });
+    const child = logger.child({ rid: 'x' });
+    expect(child.name).toBe('app.db');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Redaction
+// ---------------------------------------------------------------------------
+
+describe('redaction', () => {
+  test('redaction is applied to messages before sink dispatch', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'trace',
+      name: 'app',
+      sinks: [sink],
+    });
+
+    logger.info('card: 4111-1111-1111-1111');
+    const [first] = records;
+    expect(first?.message).toBe('card: [REDACTED]');
+  });
+
+  test('redaction is applied to metadata before sink dispatch', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'trace',
+      name: 'app',
+      sinks: [sink],
+    });
+
+    logger.info('hello', { password: 's3cret' });
+    const [first] = records;
+    expect(first?.metadata['password']).toBe('[REDACTED]');
+  });
+
+  test('default redaction scrubs patterns matching DEFAULT_PATTERNS', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'trace',
+      name: 'app',
+      sinks: [sink],
+    });
+
+    logger.info('key: sk-abc123def456ghi');
+    const [first] = records;
+    expect(first?.message).toBe('key: [REDACTED]');
+  });
+
+  test('default redaction scrubs keys matching DEFAULT_SENSITIVE_KEYS', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'trace',
+      name: 'app',
+      sinks: [sink],
+    });
+
+    logger.info('auth', { apiKey: 'key-123', token: 'secret-value' });
+    const [first] = records;
+    expect(first?.metadata['token']).toBe('[REDACTED]');
+    expect(first?.metadata['apiKey']).toBe('[REDACTED]');
+  });
+
+  test('custom redaction patterns are applied when provided', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'trace',
+      name: 'app',
+      redaction: {
+        patterns: [/secret-\w+/g],
+      },
+      sinks: [sink],
+    });
+
+    logger.info('found secret-banana here');
+    const [first] = records;
+    expect(first?.message).toBe('found [REDACTED] here');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Hierarchical category filtering
+// ---------------------------------------------------------------------------
+
+describe('hierarchical category filtering', () => {
+  test('uses category-specific level', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'info',
+      levels: { 'app.db': 'debug' },
+      name: 'app.db',
+      sinks: [sink],
+    });
+
+    logger.debug('query executed');
+    expect(records).toHaveLength(1);
+  });
+
+  test('walks up to parent category level', () => {
+    const { records, sink } = captureSink();
+    const logger = createLogger({
+      level: 'error',
+      levels: { 'app.db': 'debug' },
+      name: 'app.db.queries',
+      sinks: [sink],
+    });
+
+    logger.debug('query executed');
+    expect(records).toHaveLength(1);
+  });
+});

package/src/__tests__/sinks.test.ts

@@ -0,0 +1,181 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+import { createConsoleSink, createFileSink } from '../sinks.js';
+import type { LogFormatter, LogRecord } from '../types.js';
+
+const makeRecord = (overrides?: Partial<LogRecord>): LogRecord => ({
+  category: 'app.test',
+  level: 'info',
+  message: 'test message',
+  metadata: {},
+  timestamp: new Date('2026-03-25T10:00:00.000Z'),
+  ...overrides,
+});
+
+const formattedSink = () =>
+  createConsoleSink({
+    formatter: { format: () => 'formatted' },
+  });
+
+const parseJsonLines = async (
+  path: string
+): Promise<Record<string, unknown>[]> => {
+  const content = await Bun.file(path).text();
+  return content
+    .trim()
+    .split('\n')
+    .map((line) => JSON.parse(line) as Record<string, unknown>);
+};
+
+// ---------------------------------------------------------------------------
+// createConsoleSink
+// ---------------------------------------------------------------------------
+
+describe('createConsoleSink', () => {
+  const originalDebug = console.debug;
+  const originalInfo = console.info;
+  const originalWarn = console.warn;
+  const originalError = console.error;
+
+  beforeEach(() => {
+    // oxlint-disable-next-line no-empty-function
+    console.debug = mock(() => {
+      // noop
+    });
+    // oxlint-disable-next-line no-empty-function
+    console.info = mock(() => {
+      // noop
+    });
+    // oxlint-disable-next-line no-empty-function
+    console.warn = mock(() => {
+      // noop
+    });
+    // oxlint-disable-next-line no-empty-function
+    console.error = mock(() => {
+      // noop
+    });
+  });
+
+  afterEach(() => {
+    console.debug = originalDebug;
+    console.info = originalInfo;
+    console.warn = originalWarn;
+    console.error = originalError;
+  });
+
+  describe('level routing', () => {
+    test('writes to console.debug for trace level', () => {
+      const sink = formattedSink();
+      sink.write(makeRecord({ level: 'trace' }));
+      expect(console.debug).toHaveBeenCalledWith('formatted');
+    });
+
+    test('writes to console.debug for debug level', () => {
+      const sink = formattedSink();
+      sink.write(makeRecord({ level: 'debug' }));
+      expect(console.debug).toHaveBeenCalledWith('formatted');
+    });
+
+    test('writes to console.info for info level', () => {
+      const sink = formattedSink();
+      sink.write(makeRecord({ level: 'info' }));
+      expect(console.info).toHaveBeenCalledWith('formatted');
+    });
+
+    test('writes to console.warn for warn level', () => {
+      const sink = formattedSink();
+      sink.write(makeRecord({ level: 'warn' }));
+      expect(console.warn).toHaveBeenCalledWith('formatted');
+    });
+
+    test('writes to console.error for error level', () => {
+      const sink = formattedSink();
+      sink.write(makeRecord({ level: 'error' }));
+      expect(console.error).toHaveBeenCalledWith('formatted');
+    });
+
+    test('writes to console.error for fatal level', () => {
+      const sink = formattedSink();
+      sink.write(makeRecord({ level: 'fatal' }));
+      expect(console.error).toHaveBeenCalledWith('formatted');
+    });
+  });
+
+  describe('configuration', () => {
+    test('uses the provided formatter', () => {
+      const formatter: LogFormatter = {
+        format: (record) => `custom: ${record.message}`,
+      };
+      const sink = createConsoleSink({ formatter });
+      sink.write(makeRecord({ message: 'hello' }));
+      expect(console.info).toHaveBeenCalledWith('custom: hello');
+    });
+
+    test("sink has name 'console'", () => {
+      const sink = createConsoleSink();
+      expect(sink.name).toBe('console');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createFileSink
+// ---------------------------------------------------------------------------
+
+describe('createFileSink', () => {
+  test('appends records to the specified file', async () => {
+    const tmpPath = `/tmp/test-logging-sink-${Date.now()}.log`;
+    const sink = createFileSink({ path: tmpPath });
+
+    sink.write(makeRecord({ message: 'line 1' }));
+    sink.write(makeRecord({ message: 'line 2' }));
+    await sink.flush?.();
+
+    const lines = await parseJsonLines(tmpPath);
+
+    expect(lines).toHaveLength(2);
+    expect(lines[0]?.['message']).toBe('line 1');
+    expect(lines[1]?.['message']).toBe('line 2');
+  });
+
+  test('flush completes pending writes', async () => {
+    const tmpPath = `/tmp/test-logging-flush-${Date.now()}.log`;
+    const sink = createFileSink({ path: tmpPath });
+
+    sink.write(makeRecord({ message: 'flushed' }));
+    await sink.flush?.();
+
+    const content = await Bun.file(tmpPath).text();
+    expect(content).toContain('flushed');
+  });
+
+  test("sink has name 'file'", () => {
+    const tmpPath = `/tmp/test-logging-name-${Date.now()}.log`;
+    const sink = createFileSink({ path: tmpPath });
+    expect(sink.name).toBe('file');
+  });
+
+  test('write receives a well-formed LogRecord', () => {
+    const tmpPath = `/tmp/test-logging-record-${Date.now()}.log`;
+    const formatter: LogFormatter = {
+      format: (record) => {
+        // Verify shape
+        expect(record.level).toBe('warn');
+        expect(record.message).toBe('check shape');
+        expect(record.category).toBe('test.shape');
+        expect(record.timestamp).toBeInstanceOf(Date);
+        expect(record.metadata).toEqual({ key: 'val' });
+        return 'ok';
+      },
+    };
+    const sink = createFileSink({ formatter, path: tmpPath });
+    sink.write(
+      makeRecord({
+        category: 'test.shape',
+        level: 'warn',
+        message: 'check shape',
+        metadata: { key: 'val' },
+      })
+    );
+  });
+});

package/src/env.ts

@@ -0,0 +1,49 @@
+import { LEVEL_PRIORITY } from './levels.js';
+import type { LogLevel } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Valid log level set (for validation)
+// ---------------------------------------------------------------------------
+
+const VALID_LEVELS = new Set<string>(Object.keys(LEVEL_PRIORITY));
+
+const isValidLogLevel = (value: string): value is LogLevel =>
+  VALID_LEVELS.has(value);
+
+// ---------------------------------------------------------------------------
+// resolveLogLevel
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve log level from environment variables.
+ *
+ * 1. `TRAILS_LOG_LEVEL` -- explicit override (if valid).
+ * 2. `TRAILS_ENV` profile defaults:
+ *    - `development` -> `"debug"`
+ *    - `test` -> `undefined` (no logging by default)
+ *    - `production` -> `undefined` (caller falls through to `"info"`)
+ * 3. `undefined` -- no env-based level configured.
+ */
+export const resolveLogLevel = (
+  env?: Record<string, string | undefined>
+): LogLevel | undefined => {
+  const source = env ?? process.env;
+
+  // 1. Explicit override
+  const explicit = source['TRAILS_LOG_LEVEL'];
+  if (explicit !== undefined && isValidLogLevel(explicit)) {
+    return explicit;
+  }
+
+  // 2. Profile defaults
+  const profile = source['TRAILS_ENV'];
+  if (profile === 'development') {
+    return 'debug';
+  }
+  if (profile === 'test') {
+    return undefined;
+  }
+
+  // production and everything else -- no opinion
+  return undefined;
+};

package/src/formatters.ts

@@ -0,0 +1,101 @@
+import type {
+  LogFormatter,
+  LogRecord,
+  PrettyFormatterOptions,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// JSON Formatter
+// ---------------------------------------------------------------------------
+
+/**
+ * One JSON object per log record, newline-delimited.
+ * Metadata fields are flattened into the top-level object.
+ */
+export const createJsonFormatter = (): LogFormatter => ({
+  format(record: LogRecord): string {
+    const { level, message, category, timestamp, metadata } = record;
+    const obj: Record<string, unknown> = {
+      category,
+      level,
+      message,
+      timestamp: timestamp.toISOString(),
+      ...metadata,
+    };
+    return JSON.stringify(obj);
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Pretty Formatter
+// ---------------------------------------------------------------------------
+
+const LEVEL_COLORS: Record<string, string> = {
+  debug: '\u001B[36m',
+  error: '\u001B[31m',
+  fatal: '\u001B[35m',
+  info: '\u001B[32m',
+  trace: '\u001B[90m',
+  warn: '\u001B[33m',
+};
+
+const RESET = '\u001B[0m';
+
+const formatMetadata = (metadata: Record<string, unknown>): string => {
+  const entries = Object.entries(metadata);
+  if (entries.length === 0) {
+    return '';
+  }
+  return `  ${entries
+    .map(([k, v]) => {
+      const display = typeof v === 'string' ? v : JSON.stringify(v);
+      return `${k}=${display}`;
+    })
+    .join(' ')}`;
+};
+
+/**
+ * Human-readable formatter.
+ *
+ * Output: `10:00:00 INFO  [app.entity] Entity created  requestId=abc-123`
+ */
+const formatTimestamp = (timestamp: Date): string =>
+  `${timestamp.toISOString().slice(11, 19)} `;
+
+const formatLevelAndMessage = (
+  level: string,
+  levelLabel: string,
+  category: string,
+  message: string,
+  useColors: boolean
+): string => {
+  if (useColors) {
+    const color = LEVEL_COLORS[level] ?? '';
+    return `${color}${levelLabel}${RESET} [${category}] ${message}`;
+  }
+  return `${levelLabel} [${category}] ${message}`;
+};
+
+export const createPrettyFormatter = (
+  options?: PrettyFormatterOptions
+): LogFormatter => {
+  const showTimestamps = options?.timestamps !== false;
+  const useColors = options?.colors ?? process.stdout?.isTTY === true;
+
+  return {
+    format(record: LogRecord): string {
+      const { level, message, category, timestamp, metadata } = record;
+      const levelLabel = level.toUpperCase().padEnd(5);
+      const meta = formatMetadata(metadata);
+      const prefix = showTimestamps ? formatTimestamp(timestamp) : '';
+      const body = formatLevelAndMessage(
+        level,
+        levelLabel,
+        category,
+        message,
+        useColors
+      );
+      return meta.length > 0 ? `${prefix}${body}${meta}` : `${prefix}${body}`;
+    },
+  };
+};

package/src/index.ts

@@ -0,0 +1,28 @@
+// Logger
+export { createLogger } from './logger.js';
+
+// Re-exports from core
+export type { Logger } from '@ontrails/core';
+
+// Sinks and formatters
+export { createConsoleSink, createFileSink } from './sinks.js';
+export { createJsonFormatter, createPrettyFormatter } from './formatters.js';
+
+// Level resolution
+export { resolveLogLevel } from './env.js';
+
+// Levels
+export { LEVEL_PRIORITY, shouldLog, resolveCategory } from './levels.js';
+
+// Types
+export type {
+  LogLevel,
+  LogMetadata,
+  LogRecord,
+  LoggerConfig,
+  LogSink,
+  LogFormatter,
+  ConsoleSinkOptions,
+  FileSinkOptions,
+  PrettyFormatterOptions,
+} from './types.js';

package/src/levels.ts

@@ -0,0 +1,69 @@
+import type { LogLevel } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Level Priority
+// ---------------------------------------------------------------------------
+
+export const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 1,
+  error: 4,
+  fatal: 5,
+  info: 2,
+  silent: 6,
+  trace: 0,
+  warn: 3,
+};
+
+// ---------------------------------------------------------------------------
+// shouldLog
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if a message at `messageLevel` should be emitted given the
+ * configured threshold `configuredLevel`.
+ */
+export const shouldLog = (
+  messageLevel: LogLevel,
+  configuredLevel: LogLevel
+): boolean => LEVEL_PRIORITY[messageLevel] >= LEVEL_PRIORITY[configuredLevel];
+
+// ---------------------------------------------------------------------------
+// resolveCategory
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk up the dot-separated category hierarchy to find the most specific
+ * configured level.
+ *
+ * Example: "app.db.queries" -> "app.db" -> "app" -> fallback
+ */
+/** Walk up the dot-separated hierarchy looking for a configured level. */
+const findLevel = (
+  name: string,
+  levels: Record<string, LogLevel>
+): LogLevel | undefined => {
+  let prefix = name;
+  while (prefix.length > 0) {
+    const level = levels[prefix];
+    if (level !== undefined) {
+      return level;
+    }
+    const lastDot = prefix.lastIndexOf('.');
+    if (lastDot === -1) {
+      break;
+    }
+    prefix = prefix.slice(0, lastDot);
+  }
+  return undefined;
+};
+
+export const resolveCategory = (
+  name: string,
+  levels: Record<string, LogLevel> | undefined,
+  fallback: LogLevel
+): LogLevel => {
+  if (!levels) {
+    return fallback;
+  }
+  return findLevel(name, levels) ?? fallback;
+};