xypriss 9.12.1 → 9.12.2

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import * as reliant_type from 'reliant-type';
 import { Readable, Writable } from 'node:stream';
 
 declare const LOG_LEVELS: readonly ["silent", "error", "warn", "info", "debug", "verbose"];
-type LogLevel = (typeof LOG_LEVELS)[number];
+type LogLevel$1 = (typeof LOG_LEVELS)[number];
 declare const LOG_COMPONENTS: readonly ["middleware", "server", "cache", "cluster", "performance", "plugins", "security", "routes", "userApp", "typescript", "console", "other", "router", "acpes", "ipc", "memory", "lifecycle", "routing", "xems"];
 type LogComponent = (typeof LOG_COMPONENTS)[number];
 declare const LOG_TYPES: readonly ["startup", "warnings", "errors", "performance", "debug", "hotReload", "portSwitching", "lifecycle"];
@@ -17,11 +17,11 @@ interface ComponentLogConfig {
     /** Enable/disable logging for this component */
     enabled?: boolean;
     /** Override log level for this component */
-    level?: LogLevel;
+    level?: LogLevel$1;
     /** Component-specific type filtering */
     types?: Partial<Record<LogType, boolean>>;
     /** Custom formatter for this component */
-    formatter?: (level: LogLevel, message: string, ...args: any[]) => string;
+    formatter?: (level: LogLevel$1, message: string, ...args: any[]) => string;
     /** Rate limiting for this component */
     rateLimit?: {
         /** Maximum logs per time window */
@@ -80,7 +80,7 @@ declare class Logger {
     _internal_debug(component: LogComponent, message: string, ...args: any[]): void;
     updateConfig(config: LoggerConfig): void;
     getConfig(): LoggerConfig;
-    getLevel(): LogLevel;
+    getLevel(): LogLevel$1;
     isEnabled(): boolean;
     getStats(): {
         errorCount: number;
@@ -6669,6 +6669,502 @@ declare class FunctionUtils {
     memo<T extends (...args: any[]) => any>(fn: T): T;
 }
 
+/***************************************************************************
+ * XyPrissJS - Fast And Secure
+ *
+ * @author Nehonix
+ * @license Nehonix OSL (NOSL)
+ *
+ * Copyright (c) 2025 Nehonix. All rights reserved.
+ ***************************************************************************** */
+/**
+ * All supported log levels, ordered by increasing severity.
+ *
+ * | Level     | Rank | Use case                                              |
+ * |-----------|------|-------------------------------------------------------|
+ * | `debug`   | 0    | Low-level diagnostic traces, dev-only                 |
+ * | `info`    | 1    | General operational messages                          |
+ * | `success` | 2    | Confirmation that an operation completed successfully |
+ * | `warn`    | 3    | Non-fatal issues that deserve attention               |
+ * | `error`   | 4    | Recoverable failures — operation did not complete     |
+ * | `fatal`   | 5    | Unrecoverable failures — system integrity at risk     |
+ *
+ * Used as the `minLevel` option to silence everything below a given rank.
+ *
+ * @example
+ * ```ts
+ * const log = new LoggerUtils({ minLevel: "warn" });
+ * // → only "warn", "error", and "fatal" are printed
+ * ```
+ */
+type LogLevel = "debug" | "info" | "success" | "warn" | "error" | "fatal";
+/**
+ * Configuration options accepted by the {@link LoggerUtils} constructor.
+ *
+ * All fields are optional — the logger works out of the box with zero config.
+ *
+ * @example
+ * ```ts
+ * // Minimal — global logger, all levels visible, ANSI colors on
+ * new LoggerUtils();
+ *
+ * // Scoped production logger — only warnings and above, no colors
+ * new LoggerUtils({ namespace: "API", minLevel: "warn", plain: true });
+ *
+ * // Dev logger with timestamps disabled (cleaner for rapid iteration)
+ * new LoggerUtils({ namespace: "Dev", timestamps: false });
+ * ```
+ */
+interface LoggerOptions {
+    /**
+     * A short label prepended to every log line, rendered in bold cyan.
+     *
+     * Namespaces are composable: {@link LoggerUtils.child} automatically
+     * concatenates parent and child names with a colon separator.
+     *
+     * @example
+     * ```ts
+     * new LoggerUtils({ namespace: "DB" });
+     * // output → ... [DB] Connected to postgres
+     *
+     * const child = log.child("Pool");
+     * // output → ... [DB:Pool] Acquired connection
+     * ```
+     *
+     * @default "" (no prefix)
+     */
+    namespace?: string;
+    /**
+     * The lowest {@link LogLevel} that will be printed.
+     * Any level with a lower rank is silently discarded.
+     *
+     * Typical environment presets:
+     * - Development → `"debug"` (see everything)
+     * - Staging     → `"info"`  (skip debug noise)
+     * - Production  → `"warn"`  (only actionable signals)
+     *
+     * @example
+     * ```ts
+     * const log = new LoggerUtils({ minLevel: "info" });
+     * log.debug("Verbose trace"); // ← silently dropped
+     * log.info("User signed in"); // ← printed ✔
+     * ```
+     *
+     * @default "debug"
+     */
+    minLevel?: LogLevel;
+    /**
+     * When `true`, each line is prefixed with a full `YYYY-MM-DD HH:mm:ss.mmm`
+     * timestamp, which helps correlate logs with external events or other systems.
+     *
+     * Disable when timestamps are added by an outer log aggregator (e.g. Docker,
+     * systemd, Datadog) to avoid duplication.
+     *
+     * @example
+     * ```ts
+     * new LoggerUtils({ timestamps: false });
+     * // output → [INFO] ℹ️  [App] Server started
+     * //        (no date prefix)
+     * ```
+     *
+     * @default true
+     */
+    timestamps?: boolean;
+    /**
+     * When `true`, all ANSI escape codes (colors, bold, dim) are stripped from
+     * the output, producing clean plain text.
+     *
+     * Recommended for:
+     * - CI environments (GitHub Actions, GitLab CI, Jenkins)
+     * - Log files that will be processed by grep / awk / sed
+     * - Terminals that do not support ANSI (some Windows consoles)
+     *
+     * @example
+     * ```ts
+     * const log = new LoggerUtils({ plain: true });
+     * log.warn("Disk usage high");
+     * // output → [2025-06-01 12:00:00.000] [WARN] ⚠️  Disk usage high
+     * ```
+     *
+     * @default false
+     */
+    plain?: boolean;
+}
+/**
+ * **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 });
+ * ```
+ */
+declare class LoggerUtils {
+    private readonly ns;
+    private readonly minRank;
+    private readonly timestamps;
+    private readonly plain;
+    /**
+     * 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?: LoggerOptions);
+    private emit;
+    private buildAnsi;
+    private buildPlain;
+    /**
+     * 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: string, ...extra: unknown[]): void;
+    /**
+     * 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: string, ...extra: unknown[]): void;
+    /**
+     * 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: string, ...extra: unknown[]): void;
+    /**
+     * 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: string, ...extra: unknown[]): void;
+    /**
+     * 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: string, ...extra: unknown[]): void;
+    /**
+     * 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: string, ...extra: unknown[]): void;
+    /**
+     * 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: string): () => void;
+    /**
+     * 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: string, fn: () => void): void;
+    /**
+     * 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: string): LoggerUtils;
+    /**
+     * 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(): void;
+}
+
+/***************************************************************************
+ * 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.
+ *
+ ***************************************************************************** */
+
 /**
  * **UtilsApi — XyPriss System Utility Module**
  *
@@ -6682,6 +7178,24 @@ declare class FunctionUtils {
  * __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
  * ```
  */
 declare class UtilsApi {
@@ -6703,6 +7217,36 @@ declare class UtilsApi {
     readonly id: IdUtils;
     /** **Functional Utilities** (`memo`) */
     readonly fn: 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"));
+     * ```
+     */
+    readonly log: 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?: ConstructorParameters<typeof LoggerUtils>[0]): LoggerUtils;
 }
 
 /**
@@ -7475,13 +8019,107 @@ type XyPrisResponse$1 = XyPrisResponse;
 type ParamType = "string" | "number" | "integer" | "boolean" | "uuid" | "alpha" | "alphanumeric" | `string(${number},${number})` | `number(${number},${number})` | `enum(${string})`;
 /** A declarative guard: returns true to allow, false/string to deny */
 type RouteGuard = (req: XyPrisRequest$1, res: XyPrisResponse$1) => boolean | string | Promise<boolean | string>;
-/** Named built-in guards for common patterns */
-interface BuiltInGuards {
+/**
+ * Declarative guard configuration for a route or group.
+ *
+ * Built-in properties (`authenticated`, `roles`, `permissions`) are resolved
+ * automatically by the framework using resolvers registered via `XyGuard.define()`.
+ *
+ * Custom guards can be declared using any additional string key. The key must
+ * correspond to a resolver registered via `XyGuard.define(name, resolver)`.
+ * If no resolver is found for a key, it is silently ignored.
+ *
+ * @example
+ * ```typescript
+ * // Register a custom guard globally (e.g. in server.ts)
+ * XyGuard.define("ipWhitelist", (req) => {
+ *     return req.ip === "127.0.0.1" ? true : "Forbidden IP";
+ * });
+ *
+ * // Use it declaratively alongside built-ins
+ * router.get("/admin", {
+ *     guards: {
+ *         authenticated: true,
+ *         roles: ["admin"],
+ *         ipWhitelist: true,
+ *     },
+ * }, handler);
+ * ```
+ *
+ * @remarks
+ * BREAKING CHANGE (v2): The `custom` property has been removed.
+ * Inline guard arrays must now be passed directly as the value of `guards`
+ * instead of being nested inside `custom`.
+ *
+ * @example
+ * ```typescript
+ * // Before (v1 — no longer supported)
+ * guards: { authenticated: true, custom: [myGuardFn] }
+ *
+ * // After (v2 — use the array form directly)
+ * guards: [myGuardFn]
+ *
+ * // Or register the guard globally and use the declarative key form
+ * XyGuard.define("myGuard", myGuardFn);
+ * guards: { authenticated: true, myGuard: true }
+ * ```
+ */
+type BuiltInGuards = {
+    /**
+     * Requires the request to be authenticated.
+     * The resolver must be registered via `XyGuard.define("authenticated", ...)`.
+     * Returns `true` to allow, `false` to block with 403, or a `string` to block with 401.
+     */
     authenticated?: boolean;
+    /**
+     * Restricts access to the specified roles.
+     * The resolver must be registered via `XyGuard.define("roles", ...)`.
+     * The resolver receives the required roles array as a second argument.
+     */
     roles?: string[];
+    /**
+     * Restricts access to the specified permissions.
+     * The resolver must be registered via `XyGuard.define("permissions", ...)`.
+     * The resolver receives the required permissions array as a second argument.
+     */
     permissions?: string[];
-    /** Custom guard functions, evaluated after built-in ones */
-    custom?: RouteGuard[];
+    /**
+     * @deprecated Removed in v2. The `custom` property no longer exists.
+     *
+     * Migrate by passing guard functions directly as the `guards` array, or by
+     * registering them as named guards via `XyGuard.define()`.
+     *
+     * @example
+     * ```typescript
+     * // Before (v1 — triggers a TypeScript error)
+     * guards: { authenticated: true, custom: [myGuardFn] }
+     *
+     * // After — option 1: array form
+     * guards: [myGuardFn]
+     *
+     * // After — option 2: named declarative form
+     * XyGuard.define("myGuard", myGuardFn);
+     * guards: { authenticated: true, myGuard: true }
+     * ```
+     */
+    custom?: never;
+} & CustomGuards & Record<string, any>;
+/**
+ * Interface for TypeScript Declaration Merging.
+ * Developers can augment this interface in their project to get auto-completion
+ * for their custom guards.
+ *
+ * @example
+ * ```typescript
+ * declare module "xypriss" {
+ *     interface CustomGuards {
+ *         ipWhitelist?: boolean;
+ *         plan?: "free" | "premium";
+ *     }
+ * }
+ * ```
+ */
+interface CustomGuards {
 }
 /** Per-route rate limit config */
 interface RoutRateLimit {
@@ -7539,16 +8177,126 @@ type RouteCondition = boolean | (() => boolean) | {
     env?: string | string[];
     feature?: string;
 };
-/** Full rich route options */
+/**
+ * **Comprehensive route configuration object.**
+ * Provides full control over the route's lifecycle, security, caching, and matching behavior.
+ */
 interface RichRouteOptions {
+    /**
+     * **Declarative Security Guards.**
+     * Injects protection layers before the controller execution.
+     * Supports built-ins (`authenticated`, `roles`) as well as custom-defined guards.
+     *
+     * @example
+     * ```ts
+     * guards: {
+     *     authenticated: true,
+     *     roles: ["admin", "super-admin"],
+     *     customIpWhitelist: true
+     * }
+     * ```
+     */
     guards?: BuiltInGuards | RouteGuard[];
+    /**
+     * **Lifecycle Hooks.**
+     * Attach custom logic to specific stages of the route's execution.
+     * Includes `beforeEnter`, `afterLeave` (with execution duration), and `onError`.
+     *
+     * @example
+     * ```ts
+     * lifecycle: {
+     *     beforeEnter: (req, res, next) => {
+     *         if (req.headers["x-block"]) return res.status(403).send("Blocked");
+     *         next();
+     *     },
+     *     afterLeave: (req, res, durationMs) => {
+     *         console.log(`Request completed in ${durationMs}ms`);
+     *     },
+     *     onError: (err, req, res, next) => {
+     *         res.status(500).json({ error: "Custom error handler" });
+     *     }
+     * }
+     * ```
+     */
     lifecycle?: RouteLifecycle;
+    /**
+     * **Route-specific Rate Limiting.**
+     * Protect this endpoint from abuse by restricting the maximum number of requests.
+     *
+     * @example
+     * ```ts
+     * rateLimit: {
+     *     max: 100,
+     *     window: "1m", // or windowMs: 60000
+     *     message: "Too many requests, try again later.",
+     *     keyBy: (req) => req.headers["x-api-key"] as string // Defaults to "ip"
+     * }
+     * ```
+     */
     rateLimit?: RoutRateLimit;
+    /**
+     * **Response Caching Strategy.**
+     * Declaratively cache the response of this route to improve performance.
+     *
+     * @example
+     * ```ts
+     * // Shorthand (string):
+     * cache: "5m"
+     *
+     * // Advanced:
+     * cache: {
+     *     ttl: 300, // seconds
+     *     vary: ["Authorization", "Accept-Language"],
+     *     key: (req) => `custom_key_${req.query.id}`
+     * }
+     * ```
+     */
     cache?: RouteCache;
+    /**
+     * **Route Metadata.**
+     * Used for OpenAPI generation, tagging, versioning, or attaching custom
+     * payload data accessible by plugins.
+     *
+     * @example
+     * ```ts
+     * meta: {
+     *     summary: "Get User Profile",
+     *     description: "Fetches the profile details of the authenticated user.",
+     *     tags: ["Users", "Profile"],
+     *     version: "v2",
+     *     deprecated: { since: "2.5", sunset: "2027-01-01", replacement: "/v3/user/profile" },
+     *     internal: false
+     * }
+     * ```
+     */
     meta?: RouteMeta;
-    /** Explicit priority (higher = matched first). Default: 0 */
+    /**
+     * **Router Resolution Priority.**
+     * Determines the evaluation order when multiple routes could match.
+     * A higher number means higher priority.
+     *
+     * @default 0
+     * @example priority: 100
+     */
     priority?: number;
-    /** Whether this route is active. Default: true */
+    /**
+     * **Dynamic Activation (Feature Flagging).**
+     * Determines if this route is exposed. If evaluated to `false`, the route
+     * is completely ignored by the engine (returns 404 Not Found).
+     *
+     * @default true
+     * @example
+     * ```ts
+     * // Static boolean
+     * active: false
+     *
+     * // Dynamic function (using Environment Security Shield)
+     * active: () => __sys__.__env__.get("ENABLE_BETA") === "true"
+     *
+     * // Environment/Feature-based config
+     * active: { env: ["development", "staging"], feature: "new-admin-panel" }
+     * ```
+     */
     active?: RouteCondition;
 }
 /** Internal extended route definition */
@@ -8213,7 +8961,7 @@ interface XServerOptions {
     };
     logging?: {
         enabled?: boolean;
-        level?: LogLevel;
+        level?: LogLevel$1;
         instanceName?: string;
         components?: {
             server?: boolean;
@@ -8236,7 +8984,7 @@ interface XServerOptions {
             routing?: boolean;
             xems?: boolean;
         };
-        componentLevels?: Partial<Record<LogComponent, ComponentLogConfig | LogLevel>>;
+        componentLevels?: Partial<Record<LogComponent, ComponentLogConfig | LogLevel$1>>;
         types?: {
             startup?: boolean;
             warnings?: boolean;
@@ -8248,7 +8996,7 @@ interface XServerOptions {
             lifecycle?: boolean;
         };
         consoleInterception?: DeepPartial<ConsoleInterceptionConfig>;
-        customLogger?: (level: LogLevel, component: LogComponent, message: string, ...args: any[]) => void;
+        customLogger?: (level: LogLevel$1, component: LogComponent, message: string, ...args: any[]) => void;
         format?: {
             timestamps?: boolean;
             colors?: boolean;
@@ -10889,8 +11637,6 @@ declare const Plugin: Readonly<Omit<PluginAPI, "register">>;
  */
 declare function quickServer(port?: number): XyApp;
 
-/** Supported built-in guard names */
-type BuiltInGuardName = "authenticated" | "roles" | "permissions";
 type GuardResolver = (req: XyPrisRequest$1, options?: any) => boolean | string | Promise<boolean | string>;
 /**
  * XyGuard - Global registry for built-in guard resolvers.
@@ -10915,11 +11661,15 @@ declare class XyGuard {
      * Define a resolver for 'roles' or 'permissions' guards.
      */
     static define(name: "roles" | "permissions", resolver: (req: XyPrisRequest$1, required: string[]) => boolean | string | Promise<boolean | string>): void;
+    /**
+     * Define a resolver for any custom guard.
+     */
+    static define(name: string & {}, resolver: GuardResolver): void;
     /**
      * Get an existing resolver by name.
      * @internal
      */
-    static get(name: BuiltInGuardName): GuardResolver | undefined;
+    static get(name: string): GuardResolver | undefined;
 }
 
 /**