@ontrails/logging 1.0.0-beta.0

package/src/logger.ts

@@ -0,0 +1,135 @@
+import {
+  createRedactor,
+  DEFAULT_PATTERNS,
+  DEFAULT_SENSITIVE_KEYS,
+} from '@ontrails/core/redaction';
+
+import type { Logger } from '@ontrails/core';
+
+import { resolveLogLevel } from './env.js';
+import { resolveCategory, shouldLog } from './levels.js';
+import { createConsoleSink } from './sinks.js';
+import type {
+  LogLevel,
+  LogMetadata,
+  LoggerConfig,
+  LogRecord,
+  LogSink,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Internal instance builder
+// ---------------------------------------------------------------------------
+
+interface RedactorLike {
+  redact(value: string): string;
+  redactObject<T extends Record<string, unknown>>(obj: T): T;
+}
+
+interface BuildInstanceConfig {
+  readonly baseLevel: LogLevel;
+  readonly levels: Record<string, LogLevel> | undefined;
+}
+
+const buildInstance = (
+  name: string,
+  effectiveLevel: LogLevel,
+  redactor: RedactorLike,
+  sinks: readonly LogSink[],
+  // oxlint-disable-next-line only-used-in-recursion
+  config: BuildInstanceConfig,
+  baseMetadata: Record<string, unknown>
+): Logger => {
+  const log = (
+    level: LogLevel,
+    message: string,
+    metadata?: LogMetadata
+  ): void => {
+    if (!shouldLog(level, effectiveLevel)) {
+      return;
+    }
+
+    const mergedMeta: Record<string, unknown> = {
+      ...baseMetadata,
+      ...metadata,
+    };
+
+    const record: LogRecord = {
+      category: name,
+      level,
+      message: redactor.redact(message),
+      metadata:
+        Object.keys(mergedMeta).length > 0
+          ? redactor.redactObject(mergedMeta)
+          : {},
+      timestamp: new Date(),
+    };
+
+    for (const sink of sinks) {
+      sink.write(record);
+    }
+  };
+
+  return {
+    child(metadata: LogMetadata): Logger {
+      return buildInstance(name, effectiveLevel, redactor, sinks, config, {
+        ...baseMetadata,
+        ...metadata,
+      });
+    },
+    debug(message: string, metadata?: LogMetadata): void {
+      log('debug', message, metadata);
+    },
+    error(message: string, metadata?: LogMetadata): void {
+      log('error', message, metadata);
+    },
+    fatal(message: string, metadata?: LogMetadata): void {
+      log('fatal', message, metadata);
+    },
+    info(message: string, metadata?: LogMetadata): void {
+      log('info', message, metadata);
+    },
+    name,
+    trace(message: string, metadata?: LogMetadata): void {
+      log('trace', message, metadata);
+    },
+    warn(message: string, metadata?: LogMetadata): void {
+      log('warn', message, metadata);
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// createLogger
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a structured logger with hierarchical category filtering,
+ * automatic redaction, and pluggable sinks.
+ *
+ * This is the **only** API for creating loggers in `@ontrails/logging`.
+ */
+export const createLogger = (config: LoggerConfig): Logger => {
+  const envLevel = resolveLogLevel();
+  const baseLevel: LogLevel = config.level ?? envLevel ?? 'info';
+  const effectiveLevel = resolveCategory(config.name, config.levels, baseLevel);
+
+  const redactor = createRedactor({
+    patterns: [...DEFAULT_PATTERNS, ...(config.redaction?.patterns ?? [])],
+    sensitiveKeys: [
+      ...DEFAULT_SENSITIVE_KEYS,
+      ...(config.redaction?.sensitiveKeys ?? []),
+    ],
+  });
+
+  const sinks: readonly LogSink[] = config.sinks ?? [createConsoleSink()];
+
+  return buildInstance(
+    config.name,
+    effectiveLevel,
+    redactor,
+    sinks,
+    { baseLevel, levels: config.levels },
+    {}
+  );
+};

package/src/logtape/index.ts

@@ -0,0 +1,68 @@
+import type { LogRecord, LogSink } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Minimal logtape logger interface (avoids importing @logtape/logtape)
+// ---------------------------------------------------------------------------
+
+/**
+ * Subset of the logtape Logger interface that we forward records to.
+ * Accepts any object that provides the standard log-level methods.
+ */
+export interface LogtapeLoggerLike {
+  trace(message: string, props?: Record<string, unknown>): void;
+  debug(message: string, props?: Record<string, unknown>): void;
+  info(message: string, props?: Record<string, unknown>): void;
+  warn(message: string, props?: Record<string, unknown>): void;
+  error(message: string, props?: Record<string, unknown>): void;
+  fatal(message: string, props?: Record<string, unknown>): void;
+}
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface LogtapeSinkOptions {
+  /** An existing logtape logger (or compatible object) to forward records to. */
+  readonly logger: LogtapeLoggerLike;
+}
+
+// ---------------------------------------------------------------------------
+// logtapeSink
+// ---------------------------------------------------------------------------
+
+type ForwardMethod = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+const LEVEL_MAP: Record<string, ForwardMethod> = {
+  debug: 'debug',
+  error: 'error',
+  fatal: 'fatal',
+  info: 'info',
+  trace: 'trace',
+  warn: 'warn',
+};
+
+/**
+ * Sink adapter that forwards `LogRecord` instances to an existing logtape
+ * logger. Redaction runs _before_ the sink receives records, so sensitive
+ * data is scrubbed regardless of the backend.
+ */
+export const logtapeSink = (options: LogtapeSinkOptions): LogSink => {
+  const { logger } = options;
+
+  return {
+    name: 'logtape',
+    write(record: LogRecord): void {
+      const method = LEVEL_MAP[record.level];
+      if (method === undefined) {
+        return;
+      }
+
+      const props: Record<string, unknown> = {
+        category: record.category,
+        ...record.metadata,
+      };
+
+      logger[method](record.message, props);
+    },
+  };
+};

package/src/sinks.ts

@@ -0,0 +1,71 @@
+import { createJsonFormatter, createPrettyFormatter } from './formatters.js';
+import type {
+  ConsoleSinkOptions,
+  FileSinkOptions,
+  LogRecord,
+  LogSink,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Console Sink
+// ---------------------------------------------------------------------------
+
+const CONSOLE_METHOD: Record<string, 'debug' | 'info' | 'warn' | 'error'> = {
+  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?: ConsoleSinkOptions): LogSink => {
+  const isDev = process.env['TRAILS_ENV'] === 'development';
+  const formatter =
+    options?.formatter ??
+    (isDev ? createPrettyFormatter() : createJsonFormatter());
+  const allStderr = options?.stderr === true;
+
+  return {
+    name: 'console',
+    write(record: LogRecord): void {
+      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: FileSinkOptions): LogSink => {
+  const formatter = options.formatter ?? createJsonFormatter();
+  const writer = Bun.file(options.path).writer();
+
+  return {
+    async flush(): Promise<void> {
+      await writer.flush();
+    },
+    name: 'file',
+    write(record: LogRecord): void {
+      const output = formatter.format(record);
+      writer.write(`${output}\n`);
+    },
+  };
+};

package/src/types.ts

@@ -0,0 +1,99 @@
+// ---------------------------------------------------------------------------
+// Log Level
+// ---------------------------------------------------------------------------
+
+export type LogLevel =
+  | 'trace'
+  | 'debug'
+  | 'info'
+  | 'warn'
+  | 'error'
+  | 'fatal'
+  | 'silent';
+
+// ---------------------------------------------------------------------------
+// Log Metadata & Record
+// ---------------------------------------------------------------------------
+
+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>;
+}
+
+// ---------------------------------------------------------------------------
+// Sink
+// ---------------------------------------------------------------------------
+
+export interface LogSink {
+  readonly name: string;
+  write(record: LogRecord): void;
+  flush?(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Formatter
+// ---------------------------------------------------------------------------
+
+export interface LogFormatter {
+  format(record: LogRecord): string;
+}
+
+// ---------------------------------------------------------------------------
+// Sink Options
+// ---------------------------------------------------------------------------
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// Pretty Formatter Options
+// ---------------------------------------------------------------------------
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// Logger Config
+// ---------------------------------------------------------------------------
+
+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;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/env.ts","./src/formatters.ts","./src/index.ts","./src/levels.ts","./src/logger.ts","./src/sinks.ts","./src/types.ts","./src/logtape/index.ts"],"version":"5.9.3"}