@ontrails/logging 1.0.0-beta.0

package/dist/sinks.js

@@ -0,0 +1,58 @@
+import { createJsonFormatter, createPrettyFormatter } from './formatters.js';
+// ---------------------------------------------------------------------------
+// Console Sink
+// ---------------------------------------------------------------------------
+const CONSOLE_METHOD = {
+    debug: 'debug',
+    error: 'error',
+    fatal: 'error',
+    info: 'info',
+    trace: 'debug',
+    warn: 'warn',
+};
+/**
+ * Sink that writes to `console.*` methods.
+ *
+ * By default, uses `createPrettyFormatter()` when `TRAILS_ENV` is
+ * `"development"` and `createJsonFormatter()` otherwise.
+ */
+export const createConsoleSink = (options) => {
+    const isDev = process.env['TRAILS_ENV'] === 'development';
+    const formatter = options?.formatter ??
+        (isDev ? createPrettyFormatter() : createJsonFormatter());
+    const allStderr = options?.stderr === true;
+    return {
+        name: 'console',
+        write(record) {
+            const output = formatter.format(record);
+            const method = CONSOLE_METHOD[record.level] ?? 'info';
+            if (allStderr) {
+                console.error(output);
+            }
+            else {
+                console[method](output);
+            }
+        },
+    };
+};
+// ---------------------------------------------------------------------------
+// File Sink
+// ---------------------------------------------------------------------------
+/**
+ * Sink that appends log records to a file using `Bun.file()`.
+ */
+export const createFileSink = (options) => {
+    const formatter = options.formatter ?? createJsonFormatter();
+    const writer = Bun.file(options.path).writer();
+    return {
+        async flush() {
+            await writer.flush();
+        },
+        name: 'file',
+        write(record) {
+            const output = formatter.format(record);
+            writer.write(`${output}\n`);
+        },
+    };
+};
+//# sourceMappingURL=sinks.js.map

package/dist/sinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sinks.js","sourceRoot":"","sources":["../src/sinks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAQ7E,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,MAAM,cAAc,GAAwD;IAC1E,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAA4B,EAAW,EAAE;IACzE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,aAAa,CAAC;IAC1D,MAAM,SAAS,GACb,OAAO,EAAE,SAAS;QAClB,CAAC,KAAK,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAE3C,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,MAAiB;YACrB,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;YAEtD,IAAI,SAAS,EAAE,CAAC;gBACd,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC,CAAC;AAEF,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAwB,EAAW,EAAE;IAClE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,mBAAmB,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;IAE/C,OAAO;QACL,KAAK,CAAC,KAAK;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QACD,IAAI,EAAE,MAAM;QACZ,KAAK,CAAC,MAAiB;YACrB,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACxC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+export type LogMetadata = Record<string, unknown>;
+export interface LogRecord {
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly category: string;
+    readonly timestamp: Date;
+    readonly metadata: Record<string, unknown>;
+}
+export interface LogSink {
+    readonly name: string;
+    write(record: LogRecord): void;
+    flush?(): Promise<void>;
+}
+export interface LogFormatter {
+    format(record: LogRecord): string;
+}
+export interface ConsoleSinkOptions {
+    /** Formatter to use. Defaults to createPrettyFormatter() in dev, createJsonFormatter() in production. */
+    readonly formatter?: LogFormatter | undefined;
+    /** Send all output to stderr. Defaults to false (stderr only for warn/error/fatal). */
+    readonly stderr?: boolean | undefined;
+}
+export interface FileSinkOptions {
+    /** Path to the log file. */
+    readonly path: string;
+    /** Formatter. Defaults to createJsonFormatter(). */
+    readonly formatter?: LogFormatter | undefined;
+}
+export interface PrettyFormatterOptions {
+    /** Show timestamps. Defaults to true. */
+    readonly timestamps?: boolean | undefined;
+    /** Use colors (ANSI). Defaults to true when stdout is a TTY. */
+    readonly colors?: boolean | undefined;
+}
+export interface LoggerConfig {
+    /** Logger category name. Dot-separated for hierarchy: "app.db.queries" */
+    readonly name: string;
+    /** Base log level. Overridden by category-specific levels and env vars. */
+    readonly level?: LogLevel | undefined;
+    /** Category prefix -> level mapping for hierarchical filtering. */
+    readonly levels?: Record<string, LogLevel> | undefined;
+    /** Sinks to write log records to. Defaults to [createConsoleSink()]. */
+    readonly sinks?: readonly LogSink[] | undefined;
+    /** Redaction config. Defaults to core's DEFAULT_PATTERNS + DEFAULT_SENSITIVE_KEYS. */
+    readonly redaction?: {
+        readonly patterns?: RegExp[] | undefined;
+        readonly sensitiveKeys?: string[] | undefined;
+    } | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,OAAO,GACP,OAAO,GACP,QAAQ,CAAC;AAMb,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAMD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAMD,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;CACnC;AAMD,MAAM,WAAW,kBAAkB;IACjC,yGAAyG;IACzG,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAC9C,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAC/C;AAMD,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAMD,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAEtC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,SAAS,CAAC;IAEvD,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;IAEhD,sFAAsF;IACtF,QAAQ,CAAC,SAAS,CAAC,EACf;QACE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;KAC/C,GACD,SAAS,CAAC;CACf"}

package/dist/types.js

@@ -0,0 +1,5 @@
+// ---------------------------------------------------------------------------
+// Log Level
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@ontrails/logging",
+  "version": "1.0.0-beta.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./logtape": "./src/logtape/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "@ontrails/core": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@logtape/logtape": {
+      "optional": true
+    }
+  }
+}

package/src/__tests__/env.test.ts

@@ -0,0 +1,54 @@
+import { describe, test, expect } from 'bun:test';
+
+import { resolveLogLevel } from '../env.js';
+
+// ---------------------------------------------------------------------------
+// resolveLogLevel
+// ---------------------------------------------------------------------------
+
+describe('resolveLogLevel', () => {
+  test('reads from TRAILS_LOG_LEVEL', () => {
+    expect(resolveLogLevel({ TRAILS_LOG_LEVEL: 'debug' })).toBe('debug');
+    expect(resolveLogLevel({ TRAILS_LOG_LEVEL: 'error' })).toBe('error');
+    expect(resolveLogLevel({ TRAILS_LOG_LEVEL: 'trace' })).toBe('trace');
+  });
+
+  test('TRAILS_LOG_LEVEL takes precedence over TRAILS_ENV', () => {
+    expect(
+      resolveLogLevel({
+        TRAILS_ENV: 'development',
+        TRAILS_LOG_LEVEL: 'error',
+      })
+    ).toBe('error');
+  });
+
+  test('falls back to TRAILS_ENV profile defaults', () => {
+    expect(resolveLogLevel({ TRAILS_ENV: 'development' })).toBe('debug');
+  });
+
+  test('TRAILS_ENV=test returns undefined', () => {
+    expect(resolveLogLevel({ TRAILS_ENV: 'test' })).toBeUndefined();
+  });
+
+  test('TRAILS_ENV=production returns undefined', () => {
+    expect(resolveLogLevel({ TRAILS_ENV: 'production' })).toBeUndefined();
+  });
+
+  test('returns undefined when no env is set', () => {
+    expect(resolveLogLevel({})).toBeUndefined();
+  });
+
+  test('invalid TRAILS_LOG_LEVEL values are ignored', () => {
+    expect(resolveLogLevel({ TRAILS_LOG_LEVEL: 'banana' })).toBeUndefined();
+    expect(resolveLogLevel({ TRAILS_LOG_LEVEL: '' })).toBeUndefined();
+  });
+
+  test('invalid TRAILS_LOG_LEVEL falls through to TRAILS_ENV', () => {
+    expect(
+      resolveLogLevel({
+        TRAILS_ENV: 'development',
+        TRAILS_LOG_LEVEL: 'banana',
+      })
+    ).toBe('debug');
+  });
+});

package/src/__tests__/formatters.test.ts

@@ -0,0 +1,119 @@
+import { describe, test, expect } from 'bun:test';
+
+import { createJsonFormatter, createPrettyFormatter } from '../formatters.js';
+import type { LogRecord } from '../types.js';
+
+const makeRecord = (overrides?: Partial<LogRecord>): LogRecord => ({
+  category: 'app.entity',
+  level: 'info',
+  message: 'Entity created',
+  metadata: { entityId: 'e1', requestId: 'abc-123' },
+  timestamp: new Date('2026-03-25T10:00:00.000Z'),
+  ...overrides,
+});
+
+// ---------------------------------------------------------------------------
+// createJsonFormatter
+// ---------------------------------------------------------------------------
+
+describe('createJsonFormatter', () => {
+  test('produces valid JSON with all record fields', () => {
+    const formatter = createJsonFormatter();
+    const output = formatter.format(makeRecord());
+    const parsed = JSON.parse(output) as Record<string, unknown>;
+
+    expect(parsed['level']).toBe('info');
+    expect(parsed['message']).toBe('Entity created');
+    expect(parsed['category']).toBe('app.entity');
+    expect(parsed['timestamp']).toBe('2026-03-25T10:00:00.000Z');
+  });
+
+  test('flattens metadata into top-level object', () => {
+    const formatter = createJsonFormatter();
+    const output = formatter.format(makeRecord());
+    const parsed = JSON.parse(output) as Record<string, unknown>;
+
+    expect(parsed['requestId']).toBe('abc-123');
+    expect(parsed['entityId']).toBe('e1');
+    // metadata key itself should not appear
+    expect(parsed['metadata']).toBeUndefined();
+  });
+
+  test('handles empty metadata', () => {
+    const formatter = createJsonFormatter();
+    const output = formatter.format(makeRecord({ metadata: {} }));
+    const parsed = JSON.parse(output) as Record<string, unknown>;
+
+    expect(parsed['level']).toBe('info');
+    expect(parsed['message']).toBe('Entity created');
+  });
+
+  test('handles metadata with nested objects', () => {
+    const formatter = createJsonFormatter();
+    const output = formatter.format(
+      makeRecord({ metadata: { user: { id: 1 } } })
+    );
+    const parsed = JSON.parse(output) as Record<string, unknown>;
+
+    expect(parsed['user']).toEqual({ id: 1 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createPrettyFormatter
+// ---------------------------------------------------------------------------
+
+describe('createPrettyFormatter', () => {
+  test('produces human-readable output with level, category, and message', () => {
+    const formatter = createPrettyFormatter({ colors: false });
+    const output = formatter.format(makeRecord());
+
+    expect(output).toContain('INFO');
+    expect(output).toContain('[app.entity]');
+    expect(output).toContain('Entity created');
+  });
+
+  test('includes metadata as key=value pairs', () => {
+    const formatter = createPrettyFormatter({ colors: false });
+    const output = formatter.format(makeRecord());
+
+    expect(output).toContain('requestId=abc-123');
+    expect(output).toContain('entityId=e1');
+  });
+
+  test('respects timestamps: false', () => {
+    const formatter = createPrettyFormatter({
+      colors: false,
+      timestamps: false,
+    });
+    const output = formatter.format(makeRecord());
+
+    // Should NOT contain the time portion
+    expect(output).not.toContain('10:00:00');
+    // Should still contain message
+    expect(output).toContain('Entity created');
+  });
+
+  test('includes timestamp by default', () => {
+    const formatter = createPrettyFormatter({ colors: false });
+    const output = formatter.format(makeRecord());
+
+    expect(output).toContain('10:00:00');
+  });
+
+  test('respects colors: false', () => {
+    const formatter = createPrettyFormatter({ colors: false });
+    const output = formatter.format(makeRecord());
+
+    // No ANSI escape codes
+    expect(output).not.toContain('\u001B[');
+  });
+
+  test('adds ANSI escape codes when colors: true', () => {
+    const formatter = createPrettyFormatter({ colors: true });
+    const output = formatter.format(makeRecord());
+
+    // Should contain ANSI color codes
+    expect(output).toContain('\u001B[');
+  });
+});

package/src/__tests__/levels.test.ts

@@ -0,0 +1,82 @@
+import { describe, test, expect } from 'bun:test';
+
+import { shouldLog, resolveCategory, LEVEL_PRIORITY } from '../levels.js';
+
+// ---------------------------------------------------------------------------
+// LEVEL_PRIORITY
+// ---------------------------------------------------------------------------
+
+describe('LEVEL_PRIORITY', () => {
+  test('trace < debug < info < warn < error < fatal < silent', () => {
+    expect(LEVEL_PRIORITY.trace).toBeLessThan(LEVEL_PRIORITY.debug);
+    expect(LEVEL_PRIORITY.debug).toBeLessThan(LEVEL_PRIORITY.info);
+    expect(LEVEL_PRIORITY.info).toBeLessThan(LEVEL_PRIORITY.warn);
+    expect(LEVEL_PRIORITY.warn).toBeLessThan(LEVEL_PRIORITY.error);
+    expect(LEVEL_PRIORITY.error).toBeLessThan(LEVEL_PRIORITY.fatal);
+    expect(LEVEL_PRIORITY.fatal).toBeLessThan(LEVEL_PRIORITY.silent);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// shouldLog
+// ---------------------------------------------------------------------------
+
+describe('shouldLog', () => {
+  test('returns true when message level >= configured level', () => {
+    expect(shouldLog('info', 'info')).toBe(true);
+    expect(shouldLog('warn', 'info')).toBe(true);
+    expect(shouldLog('error', 'debug')).toBe(true);
+    expect(shouldLog('fatal', 'trace')).toBe(true);
+  });
+
+  test('returns false when message level < configured level', () => {
+    expect(shouldLog('debug', 'info')).toBe(false);
+    expect(shouldLog('trace', 'warn')).toBe(false);
+    expect(shouldLog('info', 'error')).toBe(false);
+  });
+
+  test('silent level suppresses all messages', () => {
+    expect(shouldLog('trace', 'silent')).toBe(false);
+    expect(shouldLog('debug', 'silent')).toBe(false);
+    expect(shouldLog('info', 'silent')).toBe(false);
+    expect(shouldLog('warn', 'silent')).toBe(false);
+    expect(shouldLog('error', 'silent')).toBe(false);
+    expect(shouldLog('fatal', 'silent')).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveCategory
+// ---------------------------------------------------------------------------
+
+describe('resolveCategory', () => {
+  test('returns exact match for a full category name', () => {
+    const levels = { 'app.db.queries': 'debug' as const };
+    expect(resolveCategory('app.db.queries', levels, 'info')).toBe('debug');
+  });
+
+  test('walks up hierarchy: app.db.queries -> app.db -> app', () => {
+    const levels = { app: 'warn' as const, 'app.db': 'debug' as const };
+    // "app.db.queries" not found, falls to "app.db"
+    expect(resolveCategory('app.db.queries', levels, 'info')).toBe('debug');
+  });
+
+  test('walks all the way to parent prefix', () => {
+    const levels = { app: 'error' as const };
+    expect(resolveCategory('app.db.queries', levels, 'info')).toBe('error');
+  });
+
+  test('returns fallback when no prefix matches', () => {
+    const levels = { other: 'debug' as const };
+    expect(resolveCategory('app.db.queries', levels, 'info')).toBe('info');
+  });
+
+  test('returns fallback when levels is undefined', () => {
+    expect(resolveCategory('app.db', undefined, 'warn')).toBe('warn');
+  });
+
+  test('returns fallback when category has no dots and no match', () => {
+    const levels = { other: 'debug' as const };
+    expect(resolveCategory('app', levels, 'info')).toBe('info');
+  });
+});