xypriss 9.12.1 → 9.12.3

package/dist/cjs/src/server/routing/modules/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sources":["../../../../../../src/server/routing/modules/helpers.ts"],"sourcesContent":[null],"names":["BUILTIN_PARAM_PATTERNS","XyGuard"],"mappings":"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"}
+{"version":3,"file":"helpers.js","sources":["../../../../../../src/server/routing/modules/helpers.ts"],"sourcesContent":[null],"names":["BUILTIN_PARAM_PATTERNS","XyGuard"],"mappings":"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"}

package/dist/cjs/src/xhsc/UtilsApi.js

@@ -9,7 +9,32 @@ var AsyncUtils = require('./utils/AsyncUtils.js');
 var ValidationUtils = require('./utils/ValidationUtils.js');
 var IdUtils = require('./utils/IdUtils.js');
 var FunctionUtils = require('./utils/FunctionUtils.js');
+var LoggerUtils = require('./utils/LoggerUtils.js');
 
+/***************************************************************************
+ * XyPrissJS - Fast And Secure
+ *
+ * @author Nehonix
+ * @license Nehonix OSL (NOSL)
+ *
+ * Copyright (c) 2025 Nehonix. All rights reserved.
+ *
+ * This License governs the use, modification, and distribution of software
+ * provided by NEHONIX under its open source projects.
+ * NEHONIX is committed to fostering collaborative innovation while strictly
+ * protecting its intellectual property rights.
+ * Violation of any term of this License will result in immediate termination of all granted rights
+ * and may subject the violator to legal action.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+ * AND NON-INFRINGEMENT.
+ * IN NO EVENT SHALL NEHONIX BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+ * OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE,
+ * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+ *
+ ***************************************************************************** */
+// import { initializeNativeApiBlocker } from "./server/core/NativeApiBlocker";
 /**
  * **UtilsApi — XyPriss System Utility Module**
  *
@@ -23,6 +48,24 @@ var FunctionUtils = require('./utils/FunctionUtils.js');
  * __sys__.utils.num.formatBytes(1048576);      // "1 MB"
  * __sys__.utils.is.email("test@example.com");  // true
  * __sys__.utils.id.uuid();                     // "550e8400-e29b-41d4-a716-446655440000"
+ *
+ * // Logger — quick global usage
+ * __sys__.utils.log.info("Server started", { port: 3000 });
+ * __sys__.utils.log.success("User authenticated");
+ * __sys__.utils.log.error("Connection refused", new Error("ECONNREFUSED"));
+ *
+ * // Logger — scoped instance with namespace
+ * const log = __sys__.utils.createLogger({ namespace: "Auth", minLevel: "info" });
+ * log.warn("Token expiring soon", { expiresIn: "5m" });
+ *
+ * // Logger — child namespace
+ * const dbLog = log.child("DB"); // namespace → "Auth:DB"
+ * dbLog.debug("Query executed", { rows: 42 });
+ *
+ * // Logger — execution timer
+ * const stop = log.time("Fetch users");
+ * await fetchUsers();
+ * stop(); // ✅ [Auth] Fetch users — 38 ms
  * ```
  */
 class UtilsApi {
@@ -45,6 +88,38 @@ class UtilsApi {
         this.id = new IdUtils.IdUtils();
         /** **Functional Utilities** (`memo`) */
         this.fn = new FunctionUtils.FunctionUtils();
+        /**
+         * **Logger Utilities** — Structured, colorful console logger.
+         *
+         * This is the **global** logger instance (no namespace).
+         * For scoped/namespaced loggers, use {@link UtilsApi.createLogger}.
+         *
+         * @example
+         * ```ts
+         * __sys__.utils.log.info("App ready");
+         * __sys__.utils.log.warn("Low memory", { freeKb: 128 });
+         * __sys__.utils.log.error("Crash", new Error("OOM"));
+         * ```
+         */
+        this.log = new LoggerUtils.LoggerUtils();
+    }
+    /**
+     * **Create a scoped logger** with a custom namespace and options.
+     *
+     * Use this instead of `log` when you want per-module namespacing,
+     * a minimum level filter, or plain-text output for CI environments.
+     *
+     * @example
+     * ```ts
+     * const log = __sys__.utils.createLogger({ namespace: "DB", minLevel: "warn" });
+     * log.warn("Slow query detected", { ms: 850 });
+     *
+     * // Plain mode — no ANSI colors (great for log files / CI)
+     * const ciLog = __sys__.utils.createLogger({ namespace: "CI", plain: true });
+     * ```
+     */
+    createLogger(opts = {}) {
+        return new LoggerUtils.LoggerUtils(opts);
     }
 }
 

package/dist/cjs/src/xhsc/UtilsApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"UtilsApi.js","sources":["../../../../src/xhsc/UtilsApi.ts"],"sourcesContent":[null],"names":["StringUtils","NumberUtils","DateUtils","ObjectUtils","ArrayUtils","AsyncUtils","ValidationUtils","IdUtils","FunctionUtils"],"mappings":";;;;;;;;;;;;AAUA;;;;;;;;;;;;;;AAcG;MACU,QAAQ,CAAA;AAArB,IAAA,WAAA,GAAA;;AAEoB,QAAA,IAAA,CAAA,GAAG,GAAG,IAAIA,uBAAW,EAAE;;AAGvB,QAAA,IAAA,CAAA,GAAG,GAAG,IAAIC,uBAAW,EAAE;;AAGvB,QAAA,IAAA,CAAA,IAAI,GAAG,IAAIC,mBAAS,EAAE;;AAGtB,QAAA,IAAA,CAAA,GAAG,GAAG,IAAIC,uBAAW,EAAE;;AAGvB,QAAA,IAAA,CAAA,GAAG,GAAG,IAAIC,qBAAU,EAAE;;AAGtB,QAAA,IAAA,CAAA,KAAK,GAAG,IAAIC,qBAAU,EAAE;;AAGxB,QAAA,IAAA,CAAA,EAAE,GAAG,IAAIC,+BAAe,EAAE;;AAG1B,QAAA,IAAA,CAAA,EAAE,GAAG,IAAIC,eAAO,EAAE;;AAGlB,QAAA,IAAA,CAAA,EAAE,GAAG,IAAIC,2BAAa,EAAE;IAC5C;AAAC;;;;"}
+{"version":3,"file":"UtilsApi.js","sources":["../../../../src/xhsc/UtilsApi.ts"],"sourcesContent":[null],"names":["StringUtils","NumberUtils","DateUtils","ObjectUtils","ArrayUtils","AsyncUtils","ValidationUtils","IdUtils","FunctionUtils","LoggerUtils"],"mappings":";;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;AAsBiF;AACjF;AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCG;MACU,QAAQ,CAAA;AAArB,IAAA,WAAA,GAAA;;AAEoB,QAAA,IAAA,CAAA,GAAG,GAAG,IAAIA,uBAAW,EAAE;;AAGvB,QAAA,IAAA,CAAA,GAAG,GAAG,IAAIC,uBAAW,EAAE;;AAGvB,QAAA,IAAA,CAAA,IAAI,GAAG,IAAIC,mBAAS,EAAE;;AAGtB,QAAA,IAAA,CAAA,GAAG,GAAG,IAAIC,uBAAW,EAAE;;AAGvB,QAAA,IAAA,CAAA,GAAG,GAAG,IAAIC,qBAAU,EAAE;;AAGtB,QAAA,IAAA,CAAA,KAAK,GAAG,IAAIC,qBAAU,EAAE;;AAGxB,QAAA,IAAA,CAAA,EAAE,GAAG,IAAIC,+BAAe,EAAE;;AAG1B,QAAA,IAAA,CAAA,EAAE,GAAG,IAAIC,eAAO,EAAE;;AAGlB,QAAA,IAAA,CAAA,EAAE,GAAG,IAAIC,2BAAa,EAAE;AAExC;;;;;;;;;;;;AAYG;AACa,QAAA,IAAA,CAAA,GAAG,GAAG,IAAIC,uBAAW,EAAE;IAsB3C;AApBI;;;;;;;;;;;;;;AAcG;IACI,YAAY,CACf,OAAqD,EAAE,EAAA;AAEvD,QAAA,OAAO,IAAIA,uBAAW,CAAC,IAAI,CAAC;IAChC;AACH;;;;"}

package/dist/cjs/src/xhsc/utils/LoggerUtils.js

@@ -0,0 +1,545 @@
+'use strict';
+
+/***************************************************************************
+ * XyPrissJS - Fast And Secure
+ *
+ * @author Nehonix
+ * @license Nehonix OSL (NOSL)
+ *
+ * Copyright (c) 2025 Nehonix. All rights reserved.
+ ***************************************************************************** */
+// ─── ANSI color palette ───────────────────────────────────────────────────────
+const C = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    // foreground
+    white: "\x1b[97m",
+    gray: "\x1b[90m",
+    cyan: "\x1b[96m",
+    green: "\x1b[92m",
+    yellow: "\x1b[93m",
+    red: "\x1b[91m",
+    magenta: "\x1b[95m",
+    // background
+    bgBlue: "\x1b[44m",
+    bgGreen: "\x1b[42m",
+    bgYellow: "\x1b[43m",
+    bgRed: "\x1b[41m",
+    bgMagenta: "\x1b[45m",
+    bgCyan: "\x1b[46m",
+};
+const LEVELS = {
+    debug: {
+        rank: 0,
+        badge: " DEBUG ",
+        color: C.white,
+        bg: C.bgCyan,
+        icon: "🔍",
+        msgColor: C.gray,
+    },
+    info: {
+        rank: 1,
+        badge: "  INFO ",
+        color: C.white,
+        bg: C.bgBlue,
+        icon: "ℹ️ ",
+        msgColor: C.white,
+    },
+    success: {
+        rank: 2,
+        badge: "  OK   ",
+        color: C.white,
+        bg: C.bgGreen,
+        icon: "✅",
+        msgColor: C.green,
+    },
+    warn: {
+        rank: 3,
+        badge: "  WARN ",
+        color: C.white,
+        bg: C.bgYellow,
+        icon: "⚠️ ",
+        msgColor: C.yellow,
+    },
+    error: {
+        rank: 4,
+        badge: " ERROR ",
+        color: C.white,
+        bg: C.bgRed,
+        icon: "❌",
+        msgColor: C.red,
+    },
+    fatal: {
+        rank: 5,
+        badge: " FATAL ",
+        color: C.white,
+        bg: C.bgMagenta,
+        icon: "💀",
+        msgColor: C.magenta,
+    },
+};
+const RANK_ORDER = [
+    "debug",
+    "info",
+    "success",
+    "warn",
+    "error",
+    "fatal",
+];
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+function pad2(n) {
+    return n.toString().padStart(2, "0");
+}
+function timestamp() {
+    const d = new Date();
+    const date = `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+    const time = `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}.${d.getMilliseconds().toString().padStart(3, "0")}`;
+    return `${date} ${time}`;
+}
+function formatExtra(extra, plain) {
+    if (!extra.length)
+        return "";
+    const serialized = extra.map((e) => {
+        if (e instanceof Error)
+            return `\n  ${e.stack ?? e.message}`;
+        if (typeof e === "object" && e !== null) {
+            try {
+                return ("\n  " + JSON.stringify(e, null, 2).replace(/\n/g, "\n  "));
+            }
+            catch {
+                return String(e);
+            }
+        }
+        return String(e);
+    });
+    if (plain)
+        return " " + serialized.join(" ");
+    return C.dim + " " + serialized.join(" ") + C.reset;
+}
+// ─── Logger class ─────────────────────────────────────────────────────────────
+/**
+ * **LoggerUtils** — Structured, colorful console logger for XyPriss.
+ *
+ * Provides six severity levels, ANSI-colored output, optional namespacing,
+ * child loggers, execution timers, and visual log groups — all with zero
+ * external dependencies.
+ *
+ * ---
+ *
+ * ### Quick start
+ * ```ts
+ * // Global logger — no configuration needed
+ * const log = new LoggerUtils();
+ * log.info("App started");
+ *
+ * // Scoped logger — namespace visible in every line
+ * const log = new LoggerUtils({ namespace: "Auth", minLevel: "info" });
+ * log.success("User authenticated", { userId: "u_42" });
+ * ```
+ *
+ * ### Log levels (low → high severity)
+ * ```ts
+ * log.debug("Verbose trace");                          // 🔍 dev-only
+ * log.info("Server listening", { port: 3000 });        // ℹ️  general
+ * log.success("Migration complete");                   // ✅ confirmation
+ * log.warn("Rate limit at 90%", { remaining: 10 });    // ⚠️  attention needed
+ * log.error("Payment failed", new Error("Timeout"));   // ❌ recoverable
+ * log.fatal("DB unreachable — aborting");              // 💀 unrecoverable
+ * ```
+ *
+ * ### Advanced features
+ * ```ts
+ * // ── Execution timer
+ * const stop = log.time("Fetch users");
+ * await fetchUsers();
+ * stop(); // → ✅ [Auth] Fetch users — 38 ms
+ *
+ * // ── Visual group
+ * log.group("Bootstrap", () => {
+ *   log.info("Loading config");
+ *   log.info("Connecting to DB");
+ * });
+ *
+ * // ── Child logger (inherits namespace + options)
+ * const dbLog = log.child("DB"); // namespace → "Auth:DB"
+ * dbLog.debug("Query plan", { sql: "SELECT ..." });
+ *
+ * // ── CI / plain-text mode
+ * const ciLog = new LoggerUtils({ plain: true });
+ * ```
+ */
+class LoggerUtils {
+    /**
+     * Create a new `LoggerUtils` instance.
+     *
+     * All options are optional — calling `new LoggerUtils()` produces a ready-to-use
+     * global logger that prints every level with ANSI colors and timestamps.
+     *
+     * @param opts - {@link LoggerOptions} configuration bag.
+     *
+     * @example
+     * ```ts
+     * // Zero-config global logger
+     * const log = new LoggerUtils();
+     *
+     * // Namespaced, production-safe logger
+     * const log = new LoggerUtils({
+     *   namespace:  "PaymentService",
+     *   minLevel:   "warn",
+     *   timestamps: true,
+     *   plain:      false,
+     * });
+     * ```
+     */
+    constructor(opts = {}) {
+        this.ns = opts.namespace ?? "";
+        this.minRank = LEVELS[opts.minLevel ?? "debug"].rank;
+        this.timestamps = opts.timestamps ?? true;
+        this.plain = opts.plain ?? false;
+    }
+    // ── Core (private) ────────────────────────────────────────────────────────
+    emit(level, message, ...extra) {
+        const meta = LEVELS[level];
+        if (meta.rank < this.minRank)
+            return;
+        const method = level === "error" || level === "fatal"
+            ? "error"
+            : level === "warn"
+                ? "warn"
+                : "log";
+        const line = this.plain
+            ? this.buildPlain(meta, message, extra)
+            : this.buildAnsi(meta, message, extra);
+        console[method](line);
+    }
+    buildAnsi(meta, message, extra) {
+        const parts = [];
+        if (this.timestamps)
+            parts.push(`${C.dim}${timestamp()}${C.reset}`);
+        parts.push(`${meta.bg}${C.bold}${meta.color}${meta.badge}${C.reset}`);
+        parts.push(meta.icon);
+        if (this.ns)
+            parts.push(`${C.bold}${C.cyan}[${this.ns}]${C.reset}`);
+        parts.push(`${meta.msgColor}${message}${C.reset}`);
+        parts.push(formatExtra(extra, false));
+        return parts.filter(Boolean).join(" ");
+    }
+    buildPlain(meta, message, extra) {
+        const parts = [];
+        if (this.timestamps)
+            parts.push(`[${timestamp()}]`);
+        parts.push(`[${meta.badge.trim()}]`);
+        if (this.ns)
+            parts.push(`[${this.ns}]`);
+        parts.push(message);
+        parts.push(formatExtra(extra, true));
+        return parts.filter(Boolean).join(" ");
+    }
+    // ── Public log methods ────────────────────────────────────────────────────
+    /**
+     * Print a **debug** message — rank 0, lowest severity.
+     *
+     * Use for low-level diagnostic traces that are too noisy for production:
+     * variable states, iteration counters, internal decisions.
+     * Silenced whenever `minLevel` is set to `"info"` or above.
+     *
+     * Output style: `🔍` icon · gray message text · cyan `DEBUG` badge.
+     *
+     * @param message - Human-readable description of what is being traced.
+     * @param extra   - Any additional values to print after the message.
+     *                  Objects are pretty-printed as indented JSON.
+     *                  `Error` instances show the full stack trace.
+     *
+     * @example
+     * ```ts
+     * log.debug("Cache miss — fetching from DB", { key: "user:42" });
+     * log.debug("Loop iteration", { index: i, total: arr.length });
+     * ```
+     */
+    debug(message, ...extra) {
+        this.emit("debug", message, ...extra);
+    }
+    /**
+     * Print an **info** message — rank 1.
+     *
+     * Use for general operational milestones that are always relevant:
+     * server start, feature flags loaded, scheduled job triggered.
+     * Visible unless `minLevel` is set to `"success"` or above.
+     *
+     * Output style: `ℹ️` icon · white message text · blue `INFO` badge.
+     *
+     * @param message - A concise description of the event.
+     * @param extra   - Optional context values (objects, primitives, Errors).
+     *
+     * @example
+     * ```ts
+     * log.info("HTTP server listening", { port: 3000, env: "production" });
+     * log.info("Feature flag enabled", { flag: "new-checkout-flow" });
+     * ```
+     */
+    info(message, ...extra) {
+        this.emit("info", message, ...extra);
+    }
+    /**
+     * Print a **success** message — rank 2.
+     *
+     * Use to confirm that an operation completed as expected:
+     * migration applied, file uploaded, payment processed.
+     *
+     * Output style: `✅` icon · green message text · green `OK` badge.
+     *
+     * @param message - What succeeded.
+     * @param extra   - Optional result details or metadata.
+     *
+     * @example
+     * ```ts
+     * log.success("User authenticated", { userId: "u_42", method: "OAuth" });
+     * log.success("Email delivered", { to: "user@example.com", messageId: "msg_7" });
+     * ```
+     */
+    success(message, ...extra) {
+        this.emit("success", message, ...extra);
+    }
+    /**
+     * Print a **warn** message — rank 3.
+     *
+     * Use for non-fatal anomalies that should be investigated but do not
+     * stop the current operation: deprecated API usage, high latency,
+     * approaching a quota limit, missing optional configuration.
+     *
+     * Routes to `console.warn` so it appears in the Warnings channel of
+     * browser DevTools and some log aggregators.
+     *
+     * Output style: `⚠️` icon · yellow message text · yellow `WARN` badge.
+     *
+     * @param message - What is concerning and why.
+     * @param extra   - Any relevant context (thresholds, current values, etc.).
+     *
+     * @example
+     * ```ts
+     * log.warn("Memory usage above 80%", { usedMb: 820, limitMb: 1024 });
+     * log.warn("Deprecated endpoint called", { path: "/v1/users", caller: req.ip });
+     * ```
+     */
+    warn(message, ...extra) {
+        this.emit("warn", message, ...extra);
+    }
+    /**
+     * Print an **error** message — rank 4.
+     *
+     * Use when an operation has failed but the system can continue running:
+     * a failed HTTP request, a rejected promise, an unexpected null value.
+     * Always pass the originating `Error` object as an extra argument so the
+     * stack trace is preserved in the output.
+     *
+     * Routes to `console.error`.
+     *
+     * Output style: `❌` icon · red message text · red `ERROR` badge.
+     *
+     * @param message - What failed.
+     * @param extra   - The originating `Error` and/or contextual metadata.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   await db.query(sql);
+     * } catch (err) {
+     *   log.error("Query execution failed", err, { sql, params });
+     * }
+     *
+     * log.error("Stripe charge rejected", { code: "card_declined", userId: "u_7" });
+     * ```
+     */
+    error(message, ...extra) {
+        this.emit("error", message, ...extra);
+    }
+    /**
+     * Print a **fatal** message — rank 5, highest severity.
+     *
+     * Use when the system has entered an unrecoverable state and must halt:
+     * database unreachable at startup, a required secret missing, an invariant
+     * violated that makes further execution unsafe.
+     *
+     * After calling `fatal`, you should typically terminate the process
+     * (`process.exit(1)`) or trigger a circuit-breaker.
+     *
+     * Routes to `console.error`.
+     *
+     * Output style: `💀` icon · magenta message text · magenta `FATAL` badge.
+     *
+     * @param message - What went wrong and why it is unrecoverable.
+     * @param extra   - The originating `Error` and/or diagnostic context.
+     *
+     * @example
+     * ```ts
+     * if (!process.env.DATABASE_URL) {
+     *   log.fatal("DATABASE_URL is not set — cannot start", { env: process.env.NODE_ENV });
+     *   process.exit(1);
+     * }
+     *
+     * process.on("uncaughtException", (err) => {
+     *   log.fatal("Uncaught exception — shutting down", err);
+     *   process.exit(1);
+     * });
+     * ```
+     */
+    fatal(message, ...extra) {
+        this.emit("fatal", message, ...extra);
+    }
+    // ── Utilities ─────────────────────────────────────────────────────────────
+    /**
+     * Start a high-resolution execution timer and return a **stop function**.
+     *
+     * Call the stop function when the measured work is done; it logs a
+     * {@link success} line with the elapsed time in milliseconds (2 decimal places).
+     *
+     * Internally uses `performance.now()` for sub-millisecond precision.
+     *
+     * > **Tip:** the stop function can be called multiple times — each call
+     * > measures from the original `time()` invocation, so it doubles as a
+     * > checkpoint logger.
+     *
+     * @param label - A short description of the operation being timed.
+     *                Shown verbatim in the success message.
+     * @returns A zero-argument function that stops the timer and emits the result.
+     *
+     * @example
+     * ```ts
+     * // Async operation
+     * const stop = log.time("Fetch user profile");
+     * const user = await userService.getById(id);
+     * stop(); // ✅ [Auth] Fetch user profile — 42.31 ms
+     *
+     * // Sync operation
+     * const stop = log.time("Parse config");
+     * const cfg = JSON.parse(raw);
+     * stop(); // ✅ Parse config — 0.18 ms
+     *
+     * // Checkpoint pattern
+     * const stop = log.time("DB seed");
+     * await insertUsers(users);
+     * stop(); // ✅ DB seed — 120 ms  (users done)
+     * await insertPosts(posts);
+     * stop(); // ✅ DB seed — 380 ms  (total, from start)
+     * ```
+     */
+    time(label) {
+        const start = performance.now();
+        return () => {
+            const ms = (performance.now() - start).toFixed(2);
+            this.success(`${label} — ${ms} ms`);
+        };
+    }
+    /**
+     * Wrap a synchronous callback in a **visually separated log group**.
+     *
+     * Prints a labeled divider line before and a closing divider after the
+     * callback, making it easy to visually isolate related log output (e.g.
+     * a startup sequence, a batch job, a request lifecycle).
+     *
+     * > **Note:** this method is synchronous. For async callbacks, await the
+     * > work inside the callback and let the outer caller handle the promise:
+     * > ```ts
+     * > log.group("Init", () => { /* sync logs only *\/ });
+     * > // For async: manually print dividers with log.spacer() instead.
+     * > ```
+     *
+     * @param label - Title shown in the opening divider.
+     * @param fn    - Synchronous callback containing the grouped log calls.
+     *
+     * @example
+     * ```ts
+     * log.group("Bootstrap", () => {
+     *   log.info("Loading environment variables");
+     *   log.info("Connecting to PostgreSQL");
+     *   log.success("All systems ready");
+     * });
+     * // ── Bootstrap ────────────────────────────────
+     * // ℹ️  Loading environment variables
+     * // ℹ️  Connecting to PostgreSQL
+     * // ✅ All systems ready
+     * // ────────────────────────────────────────────
+     *
+     * // Nested groups are supported
+     * log.group("DB", () => {
+     *   log.group("Migrations", () => {
+     *     log.success("Applied 3 migrations");
+     *   });
+     *   log.info("Seeding complete");
+     * });
+     * ```
+     */
+    group(label, fn) {
+        const divider = this.plain
+            ? `── ${label} ${"─".repeat(Math.max(0, 40 - label.length))}`
+            : `${C.bold}${C.cyan}── ${label} ${C.dim}${"─".repeat(Math.max(0, 40 - label.length))}${C.reset}`;
+        console.log(divider);
+        fn();
+        console.log(this.plain ? "─".repeat(44) : `${C.dim}${"─".repeat(44)}${C.reset}`);
+    }
+    /**
+     * Create a **child logger** that inherits all options from this instance
+     * but appends `subNamespace` to the current namespace with a `:` separator.
+     *
+     * Child loggers are useful for module or layer-level scoping without
+     * repeating configuration. The parent's `minLevel`, `timestamps`, and
+     * `plain` settings are all propagated automatically.
+     *
+     * Namespaces are composed as `"<parent>:<child>"`. Nesting is unlimited:
+     * `App → App:DB → App:DB:Pool → App:DB:Pool:Query`.
+     *
+     * @param subNamespace - The label appended to the current namespace.
+     * @returns A new {@link LoggerUtils} instance with the extended namespace.
+     *
+     * @example
+     * ```ts
+     * const log     = new LoggerUtils({ namespace: "App", minLevel: "info" });
+     * const dbLog   = log.child("DB");       // namespace → "App:DB"
+     * const poolLog = dbLog.child("Pool");   // namespace → "App:DB:Pool"
+     *
+     * dbLog.info("Connected to postgres");
+     * // ℹ️  [App:DB] Connected to postgres
+     *
+     * poolLog.warn("Pool exhausted", { size: 10, waiting: 3 });
+     * // ⚠️  [App:DB:Pool] Pool exhausted { size: 10, waiting: 3 }
+     *
+     * // minLevel is inherited — debug calls on dbLog are silenced too
+     * dbLog.debug("This won't print"); // ← silenced (minLevel = "info")
+     * ```
+     */
+    child(subNamespace) {
+        return new LoggerUtils({
+            namespace: this.ns ? `${this.ns}:${subNamespace}` : subNamespace,
+            minLevel: RANK_ORDER[this.minRank],
+            timestamps: this.timestamps,
+            plain: this.plain,
+        });
+    }
+    /**
+     * Emit a **blank line** to the console — no level, no badge, no timestamp.
+     *
+     * A small but effective tool for creating visual breathing room between
+     * unrelated log blocks, section separators, or before a {@link group}.
+     *
+     * @example
+     * ```ts
+     * log.success("Phase 1 complete");
+     * log.spacer();
+     * log.info("Starting phase 2...");
+     *
+     * // Combine with group for clear section separation
+     * log.spacer();
+     * log.group("Cleanup", () => {
+     *   log.info("Removing temp files");
+     * });
+     * log.spacer();
+     * ```
+     */
+    spacer() {
+        console.log();
+    }
+}
+
+exports.LoggerUtils = LoggerUtils;
+//# sourceMappingURL=LoggerUtils.js.map