@pencroff-lab/kore 0.1.2 → 0.2.0

package/README.md

@@ -19,6 +19,8 @@ Detailed API documentation for each module:
 - [Err](docs/err.md) -- Immutable, value-based error type with wrapping, aggregation, and serialization
 - [Outcome\<T\>](docs/outcome.md) -- Monadic container for type-safe error handling with tuple-first API
 - [dtStamp](docs/format_dt.md) -- Filesystem/log-safe date formatting utility
+- [Logger](docs/logger.md) -- Structured logging with transport DI and Err integration
+- [Logging Guide](docs/logging_guide.md) -- Patterns, conventions, and integration strategies
 
 ## API
 
@@ -209,10 +211,39 @@ import { dtStamp } from "@pencroff-lab/kore";
 dtStamp(); // "20260218_153045"
 dtStamp(new Date(), { parts: "date" }); // "20260218"
 dtStamp(new Date(), { parts: "time", ms: true }); // "153045_123"
-dtStamp(new Date(), { compact: true }); // "20260218153045"
+dtStamp(new Date(), { readable: true }); // "2026-02-18_15:30:45"
 dtStamp(new Date(), { tz: "local" }); // uses local timezone
 ```
 
+#### Logger
+
+Structured, callable logger with transport DI, child loggers, and automatic `Err` formatting.
+
+```typescript
+import { log, createLogger } from "@pencroff-lab/kore";
+
+// Default logger
+log("Application started");
+log(log.WARN, "Connection slow");
+log(log.ERROR, "Failed to save", { userId: "123" });
+
+// Module-specific logger
+const dbLog = createLogger("database");
+dbLog("Connected to postgres");
+
+// Child loggers with inherited context
+const userLog = dbLog.child("users", { version: "1.0" });
+userLog("User created");
+// Output: [database] [users] User created {"version":"1.0"}
+
+// Err instances rendered automatically
+const [data, err] = fetchData();
+if (err) {
+  log(log.ERROR, "Fetch failed", err);
+  // Output includes indented Err.toString() below the log line
+}
+```
+
 ## Development
 
 ```bash

package/dist/cjs/src/utils/format_dt.d.ts

@@ -4,7 +4,6 @@
 export interface DtStampOptions {
     /**
      * Character(s) between date/time segments.
-     * Ignored when `compact` is `true`.
      * @default "_"
      */
     delimiter?: string;
@@ -23,16 +22,18 @@ export interface DtStampOptions {
     /**
      * Which parts of the stamp to include.
      * - `"datetime"` -- full stamp (date + time)
-     * - `"date"` -- date only (`YYYYMMDD`)
-     * - `"time"` -- time only (`HHmmss` or `HHmmss_SSS` with `ms`)
+     * - `"date"` -- date only
+     * - `"time"` -- time only
      * @default "datetime"
      */
     parts?: "datetime" | "date" | "time";
     /**
-     * When `true`, omits the delimiter entirely (equivalent to `delimiter: ""`).
+     * When `true`, formats with human-readable separators:
+     * dashes in date (`YYYY-MM-DD`), colons in time (`HH:MM:SS`),
+     * and `.` before milliseconds in time-only mode (`HH:MM:SS.mmm`).
      * @default false
      */
-    compact?: boolean;
+    readable?: boolean;
 }
 /**
  * Format a `Date` into a filesystem/log-safe timestamp string.
@@ -41,7 +42,7 @@ export interface DtStampOptions {
  * and anywhere a human-readable but machine-sortable date/time is needed.
  *
  * @param date - Date to format. Defaults to `new Date()` when `null` or omitted.
- * @param options - Formatting options (delimiter, milliseconds, timezone, parts, compact)
+ * @param options - Formatting options (delimiter, milliseconds, timezone, parts, readable)
  * @returns Formatted timestamp string
  *
  * @example Default (UTC datetime with underscore delimiter)
@@ -50,22 +51,22 @@ export interface DtStampOptions {
  * // "20240315_103045"
  * ```
  *
- * @example Compact with milliseconds
+ * @example Readable datetime with milliseconds
  * ```typescript
- * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { compact: true, ms: true });
- * // "20240315103045123"
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { readable: true, ms: true });
+ * // "2024-03-15_10:30:45_123"
  * ```
  *
- * @example Date only
+ * @example Readable date only
  * ```typescript
- * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "date" });
- * // "20240315"
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { readable: true, parts: "date" });
+ * // "2024-03-15"
  * ```
  *
- * @example Time only with milliseconds
+ * @example Readable time with milliseconds
  * ```typescript
- * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "time", ms: true });
- * // "103045_123"
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { readable: true, parts: "time", ms: true });
+ * // "10:30:45.123"
  * ```
  *
  * @example Custom delimiter

package/dist/cjs/src/utils/format_dt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format_dt.d.ts","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;;;OAKG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CA8C5E"}
+{"version":3,"file":"format_dt.d.ts","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;;;OAKG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAkD5E"}

package/dist/cjs/src/utils/format_dt.js

@@ -8,7 +8,7 @@ exports.dtStamp = dtStamp;
  * and anywhere a human-readable but machine-sortable date/time is needed.
  *
  * @param date - Date to format. Defaults to `new Date()` when `null` or omitted.
- * @param options - Formatting options (delimiter, milliseconds, timezone, parts, compact)
+ * @param options - Formatting options (delimiter, milliseconds, timezone, parts, readable)
  * @returns Formatted timestamp string
  *
  * @example Default (UTC datetime with underscore delimiter)
@@ -17,22 +17,22 @@ exports.dtStamp = dtStamp;
  * // "20240315_103045"
  * ```
  *
- * @example Compact with milliseconds
+ * @example Readable datetime with milliseconds
  * ```typescript
- * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { compact: true, ms: true });
- * // "20240315103045123"
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { readable: true, ms: true });
+ * // "2024-03-15_10:30:45_123"
  * ```
  *
- * @example Date only
+ * @example Readable date only
  * ```typescript
- * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "date" });
- * // "20240315"
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { readable: true, parts: "date" });
+ * // "2024-03-15"
  * ```
  *
- * @example Time only with milliseconds
+ * @example Readable time with milliseconds
  * ```typescript
- * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { parts: "time", ms: true });
- * // "103045_123"
+ * dtStamp(new Date("2024-03-15T10:30:45.123Z"), { readable: true, parts: "time", ms: true });
+ * // "10:30:45.123"
  * ```
  *
  * @example Custom delimiter
@@ -43,8 +43,7 @@ exports.dtStamp = dtStamp;
  */
 function dtStamp(date, options) {
     const d = date ?? new Date();
-    const { delimiter = "_", ms = false, tz = "utc", parts = "datetime", compact = false, } = options ?? {};
-    const sep = compact ? "" : delimiter;
+    const { delimiter = "_", ms = false, tz = "utc", parts = "datetime", readable = false, } = options ?? {};
     const utc = tz === "utc";
     const year = utc ? d.getUTCFullYear() : d.getFullYear();
     const month = String((utc ? d.getUTCMonth() : d.getMonth()) + 1).padStart(2, "0");
@@ -52,11 +51,16 @@ function dtStamp(date, options) {
     const hours = String(utc ? d.getUTCHours() : d.getHours()).padStart(2, "0");
     const minutes = String(utc ? d.getUTCMinutes() : d.getMinutes()).padStart(2, "0");
     const seconds = String(utc ? d.getUTCSeconds() : d.getSeconds()).padStart(2, "0");
-    const datePart = `${year}${month}${day}`;
-    let timePart = `${hours}${minutes}${seconds}`;
+    const datePart = readable
+        ? `${year}-${month}-${day}`
+        : `${year}${month}${day}`;
+    let timePart = readable
+        ? `${hours}:${minutes}:${seconds}`
+        : `${hours}${minutes}${seconds}`;
     if (ms) {
         const millis = String(utc ? d.getUTCMilliseconds() : d.getMilliseconds()).padStart(3, "0");
-        timePart = `${timePart}${sep}${millis}`;
+        const msSep = readable && parts === "time" ? "." : delimiter;
+        timePart = `${timePart}${msSep}${millis}`;
     }
     if (parts === "date") {
         return datePart;
@@ -64,6 +68,6 @@ function dtStamp(date, options) {
     if (parts === "time") {
         return timePart;
     }
-    return `${datePart}${sep}${timePart}`;
+    return `${datePart}${delimiter}${timePart}`;
 }
 //# sourceMappingURL=format_dt.js.map

package/dist/cjs/src/utils/format_dt.js.map

@@ -1 +1 @@
-{"version":3,"file":"format_dt.js","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":";;AA6EA,0BA8CC;AAtFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,SAAgB,OAAO,CAAC,IAAkB,EAAE,OAAwB;IACnE,MAAM,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;IAC7B,MAAM,EACL,SAAS,GAAG,GAAG,EACf,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,KAAK,GAAG,UAAU,EAClB,OAAO,GAAG,KAAK,GACf,GAAG,OAAO,IAAI,EAAE,CAAC;IAElB,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACrC,MAAM,GAAG,GAAG,EAAE,KAAK,KAAK,CAAC;IAEzB,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IACF,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CACxE,CAAC,EACD,GAAG,CACH,CAAC;IAEF,MAAM,QAAQ,GAAG,GAAG,IAAI,GAAG,KAAK,GAAG,GAAG,EAAE,CAAC;IACzC,IAAI,QAAQ,GAAG,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,EAAE,CAAC;IAE9C,IAAI,EAAE,EAAE,CAAC;QACR,MAAM,MAAM,GAAG,MAAM,CACpB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAClD,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACnB,QAAQ,GAAG,GAAG,QAAQ,GAAG,GAAG,GAAG,MAAM,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,QAAQ,GAAG,GAAG,GAAG,QAAQ,EAAE,CAAC;AACvC,CAAC"}
+{"version":3,"file":"format_dt.js","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":"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"}

package/dist/cjs/src/utils/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./format_dt";
+export * from "./logger";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/src/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC"}

package/dist/cjs/src/utils/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./format_dt"), exports);
+__exportStar(require("./logger"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/src/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,2CAAyB"}

package/dist/cjs/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/cjs/src/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../src/utils/logger.ts"],"names":[],"mappings":"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"}