@pencroff-lab/kore 0.1.1 → 0.2.0

package/dist/esm/src/utils/logger.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview Structured logging utility with transport DI and Err integration.
+ *
+ * This module provides a flexible, callable logger with a transport abstraction,
+ * built-in pretty console transport, and zero external runtime dependencies
+ * beyond `fast-safe-stringify`.
+ *
+ * ## Design Philosophy
+ *
+ * The logger is designed as a callable function with overloaded signatures.
+ * Transports are injectable, making the logger testable without streams or
+ * process-level side effects. The built-in pretty transport renders to stderr
+ * with ANSI colors and automatic Err formatting.
+ *
+ * ## Basic Usage
+ *
+ * @example Simple logging
+ * ```typescript
+ * import { log } from './utils/logger';
+ *
+ * log('Application started');                           // INFO level by default
+ * log(log.WARN, 'Connection slow');                     // Explicit level
+ * log(log.ERROR, 'Failed to save', { userId: '123' });  // With context
+ * ```
+ *
+ * @example Logging with Err instances
+ * ```typescript
+ * import { Err } from './types/err';
+ * import { log } from './utils/logger';
+ *
+ * const [data, err] = fetchData();
+ * if (err) {
+ *   log(log.ERROR, 'Data fetch failed', err);
+ *   return;
+ * }
+ * ```
+ *
+ * @example Child loggers with module context
+ * ```typescript
+ * const dbLogger = log.child('database', { version: '1.0' });
+ * dbLogger('Connected to postgres');
+ * // Output: [database] Connected to postgres
+ *
+ * const userLogger = dbLogger.child('users');
+ * userLogger('User created');
+ * // Output: [database] [users] User created
+ * ```
+ *
+ * @example Custom transport for testing
+ * ```typescript
+ * import { createLogger, lvl } from './utils/logger';
+ * import type { LogEntry, LogTransport } from './utils/logger';
+ *
+ * const entries: LogEntry[] = [];
+ * const spy: LogTransport = { write(e) { entries.push(e); } };
+ * const testLogger = createLogger('test', { transports: [spy], level: lvl.TRACE });
+ * ```
+ *
+ * ## Configuration
+ *
+ * The logger reads configuration from environment variables:
+ * - `LOG_LEVEL`: Minimum level to log (trace|debug|info|warn|error|fatal). Default: 'info'
+ *
+ * @module logger
+ */
+import { Err } from "../types/err";
+/**
+ * Log level constants for type-safe level specification.
+ *
+ * **Level Hierarchy** (lowest to highest):
+ * - `TRACE`: Detailed debugging information
+ * - `DEBUG`: Debugging information
+ * - `INFO`: General informational messages
+ * - `WARN`: Warning messages
+ * - `ERROR`: Error messages for failures
+ * - `FATAL`: Fatal errors causing termination
+ */
+declare const lvl: {
+    readonly TRACE: "trace";
+    readonly DEBUG: "debug";
+    readonly INFO: "info";
+    readonly WARN: "warn";
+    readonly ERROR: "error";
+    readonly FATAL: "fatal";
+};
+/**
+ * Type representing valid log level values.
+ */
+type LevelValue = (typeof lvl)[keyof typeof lvl];
+/**
+ * A single structured log entry passed to transports.
+ */
+interface LogEntry {
+    /** Log level */
+    level: LevelValue;
+    /** Unix timestamp in milliseconds (Date.now()) */
+    timestamp: number;
+    /** Log message */
+    message: string;
+    /** Merged bindings + call-site context */
+    context: Record<string, unknown>;
+    /** Module chain accumulated by child() calls */
+    modules: string[];
+}
+/**
+ * Transport interface — receives a `LogEntry` for each log call that passes
+ * the level filter. Implement this to integrate any logging backend.
+ *
+ * @example Pino transport
+ * ```typescript
+ * import pino from 'pino';
+ * import type { LogTransport, LogEntry } from '@pencroff-lab/kore';
+ *
+ * const pinoInstance = pino();
+ * const pinoTransport: LogTransport = {
+ *   write(entry: LogEntry) {
+ *     const prefix = entry.modules.map(m => `[${m}] `).join('');
+ *     pinoInstance[entry.level](entry.context, prefix + entry.message);
+ *   }
+ * };
+ * ```
+ */
+interface LogTransport {
+    write(entry: LogEntry): void;
+}
+/**
+ * Options for the built-in pretty console transport.
+ */
+interface PrettyOptions {
+    /** Output stream. Default: `process.stderr` */
+    output?: {
+        write(data: string): void;
+    };
+    /**
+     * Enable ANSI colors.
+     * - `'auto'` (default): enable when output is a TTY
+     * - `true`: always enable
+     * - `false`: always disable
+     */
+    colors?: boolean | "auto";
+    /** Override default level colors (ANSI escape sequences) */
+    levelColors?: Partial<Record<LevelValue, string>>;
+    /**
+     * Timestamp format.
+     * - `'short'` (default): `HH:MM:SS.mmm` local time
+     * - `'iso'`: ISO 8601 string
+     * - Custom function receiving `Date.now()` timestamp
+     */
+    timestamp?: "short" | "iso" | ((ts: number) => string);
+}
+/**
+ * Options for `createLogger`.
+ */
+interface LoggerOptions {
+    /** Minimum log level. Default: from `LOG_LEVEL` env or `'info'` */
+    level?: LevelValue;
+    /** Transports to write entries to. Default: `[prettyTransport()]` */
+    transports?: LogTransport[];
+}
+/**
+ * Callable logger interface with overloaded signatures.
+ *
+ * The Logger is both a function (for logging) and an object (with level
+ * constants and the `child` method).
+ *
+ * ## Call Signatures
+ * 1. `log(message)` - Log at INFO level
+ * 2. `log(message, context)` - Log at INFO level with context object or Err
+ * 3. `log(message, detail)` - Log at INFO level with detail string
+ * 4. `log(level, message)` - Log at specific level
+ * 5. `log(level, message, context)` - Log at specific level with context
+ */
+interface Logger {
+    /** Trace level constant */
+    readonly TRACE: "trace";
+    /** Debug level constant */
+    readonly DEBUG: "debug";
+    /** Info level constant */
+    readonly INFO: "info";
+    /** Warning level constant */
+    readonly WARN: "warn";
+    /** Error level constant */
+    readonly ERROR: "error";
+    /** Fatal level constant */
+    readonly FATAL: "fatal";
+    /** Log a message at INFO level. */
+    (message: string): void;
+    /** Log a message at INFO level with context. */
+    (message: string, context: object | Err): void;
+    /** Log a message at INFO level with detail string. */
+    (message: string, detail: string): void;
+    /** Log a message at a specific level. */
+    (level: LevelValue, message: string): void;
+    /** Log a message at a specific level with context. */
+    (level: LevelValue, message: string, context: object | Err): void;
+    /**
+     * Create a child logger with module-specific context.
+     *
+     * @param module - Module name added to the modules array
+     * @param bindings - Optional bindings merged into every log entry's context
+     * @returns New Logger instance
+     */
+    child(module: string, bindings?: object): Logger;
+}
+/**
+ * Create a built-in pretty console transport.
+ *
+ * Renders log entries to a human-readable format with optional ANSI colors.
+ *
+ * Output format:
+ * ```
+ * {dim timestamp} {colored TAG} {[mod] [mod]} {message} {dim context}
+ * ```
+ *
+ * Err instances in context are rendered via `Err.toString()` on their own
+ * indented line below the main line.
+ *
+ * @param options - Optional configuration
+ */
+declare function prettyTransport(options?: PrettyOptions): LogTransport;
+/**
+ * Create a logger instance with optional module name and configuration.
+ *
+ * @param module - Optional module name added as the first entry in `modules`
+ * @param options - Optional configuration
+ * @returns New Logger instance
+ *
+ * @example Basic usage
+ * ```typescript
+ * const logger = createLogger();
+ * logger('Application ready');
+ * ```
+ *
+ * @example Module-specific logger
+ * ```typescript
+ * const dbLogger = createLogger('database');
+ * dbLogger('Connected');
+ * ```
+ *
+ * @example Testing with spy transport
+ * ```typescript
+ * import type { LogEntry, LogTransport } from './utils/logger';
+ *
+ * const entries: LogEntry[] = [];
+ * const spy: LogTransport = { write(e) { entries.push(e); } };
+ * const testLogger = createLogger('test', { transports: [spy], level: lvl.TRACE });
+ * ```
+ */
+declare function createLogger(module?: string, options?: LoggerOptions): Logger;
+/**
+ * Default logger instance for application-wide logging.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { log } from './utils/logger';
+ *
+ * log('Application started');
+ * log(log.INFO, 'Server listening', { port: 3000 });
+ * log(log.ERROR, 'Startup failed', err);
+ * ```
+ *
+ * @example Module-specific logging via child
+ * ```typescript
+ * const dbLogger = log.child('database');
+ * dbLogger('Connection pool initialized');
+ * ```
+ */
+export declare const log: Logger;
+export { createLogger, prettyTransport, lvl };
+export type { Logger, LevelValue, LogEntry, LogTransport, LoggerOptions, PrettyOptions, };
+//# sourceMappingURL=logger.d.ts.map

package/dist/esm/src/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,QAAA,MAAM,GAAG;;;;;;;CAOC,CAAC;AAEX;;GAEG;AACH,KAAK,UAAU,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC;AAEjD;;GAEG;AACH,UAAU,QAAQ;IACjB,gBAAgB;IAChB,KAAK,EAAE,UAAU,CAAC;IAClB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,gDAAgD;IAChD,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,UAAU,YAAY;IACrB,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC7B;AAED;;GAEG;AACH,UAAU,aAAa;IACtB,+CAA+C;IAC/C,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;CACvD;AAED;;GAEG;AACH,UAAU,aAAa;IACtB,mEAAmE;IACnE,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,qEAAqE;IACrE,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,UAAU,MAAM;IACf,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAExB,mCAAmC;IACnC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gDAAgD;IAChD,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC;IAC/C,sDAAsD;IACtD,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,yCAAyC;IACzC,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,sDAAsD;IACtD,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC;IAElE;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACjD;AA8GD;;;;;;;;;;;;;;GAcG;AACH,iBAAS,eAAe,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,CA2D9D;AAwDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iBAAS,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAKtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,GAAG,QAAiB,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,GAAG,EAAE,CAAC;AAC9C,YAAY,EACX,MAAM,EACN,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,aAAa,GACb,CAAC"}

package/dist/esm/src/utils/logger.js

@@ -0,0 +1,335 @@
+/**
+ * @fileoverview Structured logging utility with transport DI and Err integration.
+ *
+ * This module provides a flexible, callable logger with a transport abstraction,
+ * built-in pretty console transport, and zero external runtime dependencies
+ * beyond `fast-safe-stringify`.
+ *
+ * ## Design Philosophy
+ *
+ * The logger is designed as a callable function with overloaded signatures.
+ * Transports are injectable, making the logger testable without streams or
+ * process-level side effects. The built-in pretty transport renders to stderr
+ * with ANSI colors and automatic Err formatting.
+ *
+ * ## Basic Usage
+ *
+ * @example Simple logging
+ * ```typescript
+ * import { log } from './utils/logger';
+ *
+ * log('Application started');                           // INFO level by default
+ * log(log.WARN, 'Connection slow');                     // Explicit level
+ * log(log.ERROR, 'Failed to save', { userId: '123' });  // With context
+ * ```
+ *
+ * @example Logging with Err instances
+ * ```typescript
+ * import { Err } from './types/err';
+ * import { log } from './utils/logger';
+ *
+ * const [data, err] = fetchData();
+ * if (err) {
+ *   log(log.ERROR, 'Data fetch failed', err);
+ *   return;
+ * }
+ * ```
+ *
+ * @example Child loggers with module context
+ * ```typescript
+ * const dbLogger = log.child('database', { version: '1.0' });
+ * dbLogger('Connected to postgres');
+ * // Output: [database] Connected to postgres
+ *
+ * const userLogger = dbLogger.child('users');
+ * userLogger('User created');
+ * // Output: [database] [users] User created
+ * ```
+ *
+ * @example Custom transport for testing
+ * ```typescript
+ * import { createLogger, lvl } from './utils/logger';
+ * import type { LogEntry, LogTransport } from './utils/logger';
+ *
+ * const entries: LogEntry[] = [];
+ * const spy: LogTransport = { write(e) { entries.push(e); } };
+ * const testLogger = createLogger('test', { transports: [spy], level: lvl.TRACE });
+ * ```
+ *
+ * ## Configuration
+ *
+ * The logger reads configuration from environment variables:
+ * - `LOG_LEVEL`: Minimum level to log (trace|debug|info|warn|error|fatal). Default: 'info'
+ *
+ * @module logger
+ */
+import stringifySafe from "fast-safe-stringify";
+import { Err } from "../types/err";
+/**
+ * Log level constants for type-safe level specification.
+ *
+ * **Level Hierarchy** (lowest to highest):
+ * - `TRACE`: Detailed debugging information
+ * - `DEBUG`: Debugging information
+ * - `INFO`: General informational messages
+ * - `WARN`: Warning messages
+ * - `ERROR`: Error messages for failures
+ * - `FATAL`: Fatal errors causing termination
+ */
+const lvl = {
+    TRACE: "trace",
+    DEBUG: "debug",
+    INFO: "info",
+    WARN: "warn",
+    ERROR: "error",
+    FATAL: "fatal",
+};
+// ─── Internal constants ───────────────────────────────────────────────────────
+const levelSet = new Set(Object.values(lvl));
+const LEVEL_NUMBERS = {
+    trace: 0,
+    debug: 1,
+    info: 2,
+    warn: 3,
+    error: 4,
+    fatal: 5,
+};
+const LEVEL_TAGS = {
+    trace: "TRC",
+    debug: "DBG",
+    info: "INF",
+    warn: "WRN",
+    error: "ERR",
+    fatal: "FTL",
+};
+const DEFAULT_LEVEL_COLORS = {
+    trace: "\x1b[2m",
+    debug: "\x1b[36m",
+    info: "\x1b[32m",
+    warn: "\x1b[38;5;208m",
+    error: "\x1b[31m",
+    fatal: "\x1b[1m\x1b[31m",
+};
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function isLevel(val) {
+    return (typeof val === "string" &&
+        levelSet.has(val.toLocaleLowerCase()));
+}
+function normalizeContext(ctx) {
+    if (Err.isErr(ctx))
+        return { err: ctx };
+    if (typeof ctx === "string")
+        return { detail: ctx };
+    if (typeof ctx === "object" && ctx !== null)
+        return ctx;
+    return {};
+}
+function resolveCall(...args) {
+    // 1 arg: [msg]
+    if (args.length === 1) {
+        return { level: lvl.INFO, message: String(args[0]), context: {} };
+    }
+    // 2 args
+    if (args.length === 2) {
+        const [first, second] = args;
+        if (isLevel(first)) {
+            return { level: first, message: String(second), context: {} };
+        }
+        return {
+            level: lvl.INFO,
+            message: String(first),
+            context: normalizeContext(second),
+        };
+    }
+    // 3+ args: [lvl, msg, ctx]
+    if (args.length >= 3) {
+        const [first, second, third] = args;
+        if (isLevel(first)) {
+            return {
+                level: first,
+                message: String(second),
+                context: normalizeContext(third),
+            };
+        }
+    }
+    // Fallback
+    return { level: lvl.INFO, message: String(args[0] ?? ""), context: {} };
+}
+function getLogLevel() {
+    const envLevel = process.env.LOG_LEVEL?.toLowerCase();
+    return isLevel(envLevel) ? envLevel : lvl.INFO;
+}
+// ─── Timestamp formatters ─────────────────────────────────────────────────────
+function formatShortTimestamp(ts) {
+    const d = new Date(ts);
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mm = String(d.getMinutes()).padStart(2, "0");
+    const ss = String(d.getSeconds()).padStart(2, "0");
+    const ms = String(d.getMilliseconds()).padStart(3, "0");
+    return `${hh}:${mm}:${ss}.${ms}`;
+}
+// ─── Pretty transport ─────────────────────────────────────────────────────────
+/**
+ * Create a built-in pretty console transport.
+ *
+ * Renders log entries to a human-readable format with optional ANSI colors.
+ *
+ * Output format:
+ * ```
+ * {dim timestamp} {colored TAG} {[mod] [mod]} {message} {dim context}
+ * ```
+ *
+ * Err instances in context are rendered via `Err.toString()` on their own
+ * indented line below the main line.
+ *
+ * @param options - Optional configuration
+ */
+function prettyTransport(options) {
+    const output = options?.output ?? process.stderr;
+    const colorsOpt = options?.colors ?? "auto";
+    const tsOpt = options?.timestamp ?? "short";
+    const levelColors = { ...DEFAULT_LEVEL_COLORS, ...options?.levelColors };
+    const isTTY = "isTTY" in output && output.isTTY === true;
+    const useColors = colorsOpt === "auto" ? isTTY : colorsOpt === true;
+    function formatTimestamp(ts) {
+        if (typeof tsOpt === "function")
+            return tsOpt(ts);
+        if (tsOpt === "iso")
+            return new Date(ts).toISOString();
+        return formatShortTimestamp(ts);
+    }
+    return {
+        write(entry) {
+            const ts = formatTimestamp(entry.timestamp);
+            const tag = LEVEL_TAGS[entry.level] ?? entry.level.toUpperCase();
+            const levelColor = levelColors[entry.level] ?? "";
+            // Module prefix
+            const modulePrefix = entry.modules.length > 0
+                ? `${entry.modules.map((m) => `[${m}]`).join(" ")} `
+                : "";
+            // Split err from rest of context
+            const { err: errVal, ...rest } = entry.context;
+            const hasErr = errVal !== undefined;
+            const hasRest = Object.keys(rest).length > 0;
+            let line;
+            if (useColors) {
+                const ctxStr = hasRest ? ` ${DIM}${stringifySafe(rest)}${RESET}` : "";
+                line = `${DIM}${ts}${RESET} ${levelColor}${tag}${RESET} ${modulePrefix}${entry.message}${ctxStr}`;
+            }
+            else {
+                const ctxStr = hasRest ? ` ${stringifySafe(rest)}` : "";
+                line = `${ts} ${tag} ${modulePrefix}${entry.message}${ctxStr}`;
+            }
+            if (hasErr) {
+                let errStr;
+                if (Err.isErr(errVal)) {
+                    errStr = errVal.toString({ stack: 3, metadata: true });
+                }
+                else {
+                    errStr = stringifySafe(errVal);
+                }
+                const indented = errStr
+                    .split("\n")
+                    .map((l) => `  ${l}`)
+                    .join("\n");
+                line += `\n  err: ${indented.trimStart()}`;
+            }
+            output.write(`${line}\n`);
+        },
+    };
+}
+// ─── Core logger builder ──────────────────────────────────────────────────────
+function buildLogger(modules, bindings, level, transports) {
+    const configNum = LEVEL_NUMBERS[level];
+    const logFn = (...args) => {
+        const { level: callLevel, message, context } = resolveCall(...args);
+        if ((LEVEL_NUMBERS[callLevel] ?? 0) < configNum)
+            return;
+        const entry = {
+            level: callLevel,
+            timestamp: Date.now(),
+            message,
+            context: { ...bindings, ...context },
+            modules,
+        };
+        for (const transport of transports) {
+            transport.write(entry);
+        }
+    };
+    // Attach level constants
+    const keys = Object.keys(lvl);
+    for (const key of keys) {
+        Object.defineProperty(logFn, key, {
+            value: lvl[key],
+            writable: false,
+            enumerable: true,
+        });
+    }
+    // Attach child()
+    logFn.child = (name, childBindings) => {
+        const mergedBindings = {
+            ...bindings,
+            ...childBindings,
+        };
+        return buildLogger([...modules, name], mergedBindings, level, transports);
+    };
+    return logFn;
+}
+// ─── Public factory ───────────────────────────────────────────────────────────
+/**
+ * Create a logger instance with optional module name and configuration.
+ *
+ * @param module - Optional module name added as the first entry in `modules`
+ * @param options - Optional configuration
+ * @returns New Logger instance
+ *
+ * @example Basic usage
+ * ```typescript
+ * const logger = createLogger();
+ * logger('Application ready');
+ * ```
+ *
+ * @example Module-specific logger
+ * ```typescript
+ * const dbLogger = createLogger('database');
+ * dbLogger('Connected');
+ * ```
+ *
+ * @example Testing with spy transport
+ * ```typescript
+ * import type { LogEntry, LogTransport } from './utils/logger';
+ *
+ * const entries: LogEntry[] = [];
+ * const spy: LogTransport = { write(e) { entries.push(e); } };
+ * const testLogger = createLogger('test', { transports: [spy], level: lvl.TRACE });
+ * ```
+ */
+function createLogger(module, options) {
+    const level = options?.level ?? getLogLevel();
+    const transports = options?.transports ?? [prettyTransport()];
+    const modules = module ? [module] : [];
+    return buildLogger(modules, {}, level, transports);
+}
+/**
+ * Default logger instance for application-wide logging.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { log } from './utils/logger';
+ *
+ * log('Application started');
+ * log(log.INFO, 'Server listening', { port: 3000 });
+ * log(log.ERROR, 'Startup failed', err);
+ * ```
+ *
+ * @example Module-specific logging via child
+ * ```typescript
+ * const dbLogger = log.child('database');
+ * dbLogger('Connection pool initialized');
+ * ```
+ */
+export const log = createLogger();
+export { createLogger, prettyTransport, lvl };
+//# sourceMappingURL=logger.js.map

package/dist/esm/src/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,aAAa,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,MAAM,GAAG,GAAG;IACX,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;CACL,CAAC;AA+HX,iFAAiF;AAEjF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7C,MAAM,aAAa,GAA+B;IACjD,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;CACR,CAAC;AAEF,MAAM,UAAU,GAA+B;IAC9C,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,KAAK;IACZ,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,KAAK;IACX,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,KAAK;CACZ,CAAC;AAEF,MAAM,oBAAoB,GAA+B;IACxD,KAAK,EAAE,SAAS;IAChB,KAAK,EAAE,UAAU;IACjB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,UAAU;IACjB,KAAK,EAAE,iBAAiB;CACxB,CAAC;AAEF,MAAM,KAAK,GAAG,SAAS,CAAC;AACxB,MAAM,GAAG,GAAG,SAAS,CAAC;AAEtB,gFAAgF;AAEhF,SAAS,OAAO,CAAC,GAAY;IAC5B,OAAO,CACN,OAAO,GAAG,KAAK,QAAQ;QACvB,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,iBAAiB,EAAgB,CAAC,CACnD,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAY;IACrC,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IACpD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAC1C,OAAO,GAA8B,CAAC;IACvC,OAAO,EAAE,CAAC;AACX,CAAC;AAED,SAAS,WAAW,CAAC,GAAG,IAAe;IAKtC,eAAe;IACf,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACnE,CAAC;IAED,SAAS;IACT,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;QAC7B,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACpB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAC/D,CAAC;QACD,OAAO;YACN,KAAK,EAAE,GAAG,CAAC,IAAI;YACf,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;YACtB,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC;SACjC,CAAC;IACH,CAAC;IAED,2BAA2B;IAC3B,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC;QACpC,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACpB,OAAO;gBACN,KAAK,EAAE,KAAK;gBACZ,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;gBACvB,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC;aAChC,CAAC;QACH,CAAC;IACF,CAAC;IAED,WAAW;IACX,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AACzE,CAAC;AAED,SAAS,WAAW;IACnB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,CAAC;IACtD,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;AAChD,CAAC;AAED,iFAAiF;AAEjF,SAAS,oBAAoB,CAAC,EAAU;IACvC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;IACvB,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACjD,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACnD,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACnD,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACxD,OAAO,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;AAClC,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;GAcG;AACH,SAAS,eAAe,CAAC,OAAuB;IAC/C,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IACjD,MAAM,SAAS,GAAG,OAAO,EAAE,MAAM,IAAI,MAAM,CAAC;IAC5C,MAAM,KAAK,GAAG,OAAO,EAAE,SAAS,IAAI,OAAO,CAAC;IAC5C,MAAM,WAAW,GAAG,EAAE,GAAG,oBAAoB,EAAE,GAAG,OAAO,EAAE,WAAW,EAAE,CAAC;IAEzE,MAAM,KAAK,GACV,OAAO,IAAI,MAAM,IAAK,MAA8B,CAAC,KAAK,KAAK,IAAI,CAAC;IACrE,MAAM,SAAS,GAAG,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC;IAEpE,SAAS,eAAe,CAAC,EAAU;QAClC,IAAI,OAAO,KAAK,KAAK,UAAU;YAAE,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC;QAClD,IAAI,KAAK,KAAK,KAAK;YAAE,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACvD,OAAO,oBAAoB,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,OAAO;QACN,KAAK,CAAC,KAAe;YACpB,MAAM,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YAC5C,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;YACjE,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAElD,gBAAgB;YAChB,MAAM,YAAY,GACjB,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;gBACvB,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG;gBACpD,CAAC,CAAC,EAAE,CAAC;YAEP,iCAAiC;YACjC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC;YAC/C,MAAM,MAAM,GAAG,MAAM,KAAK,SAAS,CAAC;YACpC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;YAE7C,IAAI,IAAY,CAAC;YACjB,IAAI,SAAS,EAAE,CAAC;gBACf,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtE,IAAI,GAAG,GAAG,GAAG,GAAG,EAAE,GAAG,KAAK,IAAI,UAAU,GAAG,GAAG,GAAG,KAAK,IAAI,YAAY,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,EAAE,CAAC;YACnG,CAAC;iBAAM,CAAC;gBACP,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxD,IAAI,GAAG,GAAG,EAAE,IAAI,GAAG,IAAI,YAAY,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,EAAE,CAAC;YAChE,CAAC;YAED,IAAI,MAAM,EAAE,CAAC;gBACZ,IAAI,MAAc,CAAC;gBACnB,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;oBACvB,MAAM,GAAI,MAAc,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;gBACjE,CAAC;qBAAM,CAAC;oBACP,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;gBAChC,CAAC;gBACD,MAAM,QAAQ,GAAG,MAAM;qBACrB,KAAK,CAAC,IAAI,CAAC;qBACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;qBACpB,IAAI,CAAC,IAAI,CAAC,CAAC;gBACb,IAAI,IAAI,YAAY,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;YAC5C,CAAC;YAED,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;QAC3B,CAAC;KACD,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF,SAAS,WAAW,CACnB,OAAiB,EACjB,QAAiC,EACjC,KAAiB,EACjB,UAA0B;IAE1B,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEvC,MAAM,KAAK,GAAG,CAAC,GAAG,IAAe,EAAQ,EAAE;QAC1C,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC;QACpE,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS;YAAE,OAAO;QAExD,MAAM,KAAK,GAAa;YACvB,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,OAAO;YACP,OAAO,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,EAAE;YACpC,OAAO;SACP,CAAC;QAEF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACpC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACF,CAAC,CAAC;IAEF,yBAAyB;IACzB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAyB,CAAC;IACtD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,GAAG,EAAE;YACjC,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC;YACf,QAAQ,EAAE,KAAK;YACf,UAAU,EAAE,IAAI;SAChB,CAAC,CAAC;IACJ,CAAC;IAED,iBAAiB;IAChB,KAA+C,CAAC,KAAK,GAAG,CACxD,IAAY,EACZ,aAAsB,EACb,EAAE;QACX,MAAM,cAAc,GAA4B;YAC/C,GAAG,QAAQ;YACX,GAAI,aAAqD;SACzD,CAAC;QACF,OAAO,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;IAC3E,CAAC,CAAC;IAEF,OAAO,KAA0B,CAAC;AACnC,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAS,YAAY,CAAC,MAAe,EAAE,OAAuB;IAC7D,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,CAAC;IAC9C,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvC,OAAO,WAAW,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,GAAG,EAAE,CAAC"}