@pencroff-lab/kore 0.1.2 → 0.2.0

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

@@ -0,0 +1,340 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lvl = exports.log = void 0;
+exports.createLogger = createLogger;
+exports.prettyTransport = prettyTransport;
+const fast_safe_stringify_1 = require("fast-safe-stringify");
+const err_1 = require("../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",
+};
+exports.lvl = lvl;
+// ─── 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_1.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}${(0, fast_safe_stringify_1.default)(rest)}${RESET}` : "";
+                line = `${DIM}${ts}${RESET} ${levelColor}${tag}${RESET} ${modulePrefix}${entry.message}${ctxStr}`;
+            }
+            else {
+                const ctxStr = hasRest ? ` ${(0, fast_safe_stringify_1.default)(rest)}` : "";
+                line = `${ts} ${tag} ${modulePrefix}${entry.message}${ctxStr}`;
+            }
+            if (hasErr) {
+                let errStr;
+                if (err_1.Err.isErr(errVal)) {
+                    errStr = errVal.toString({ stack: 3, metadata: true });
+                }
+                else {
+                    errStr = (0, fast_safe_stringify_1.default)(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');
+ * ```
+ */
+exports.log = createLogger();
+//# sourceMappingURL=logger.js.map

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

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

package/dist/esm/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/esm/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/esm/src/utils/format_dt.js

@@ -5,7 +5,7 @@
  * 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)
@@ -14,22 +14,22 @@
  * // "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
@@ -40,8 +40,7 @@
  */
 export 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");
@@ -49,11 +48,16 @@ export 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;
@@ -61,6 +65,6 @@ export function dtStamp(date, options) {
     if (parts === "time") {
         return timePart;
     }
-    return `${datePart}${sep}${timePart}`;
+    return `${datePart}${delimiter}${timePart}`;
 }
 //# sourceMappingURL=format_dt.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"format_dt.js","sourceRoot":"","sources":["../../../../src/utils/format_dt.ts"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,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/esm/src/utils/index.d.ts

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

package/dist/esm/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/esm/src/utils/index.js

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

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

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