xypriss 9.6.97 → 9.7.0

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { Server, IncomingMessage, ServerResponse } from 'http';
 import { SecureCacheAdapter } from 'xypriss-security';
-export { XyPriStringify, fastStringify, safeStringify } from 'xypriss-security';
 import * as reliant_type from 'reliant-type';
 import { Readable, Writable } from 'node:stream';
 
@@ -1268,6 +1267,8 @@ interface SQLInjectionConfig {
     logAttempts?: boolean;
     /** False positive threshold (0-1) */
     falsePositiveThreshold?: number;
+    /** Maximum allowed length for input strings before triggering 'Excessive length' detection */
+    maxLength?: number;
 }
 /**
  * Path Traversal Protection Configuration
@@ -1843,6 +1844,20 @@ interface SecurityConfig {
      * ```
      */
     bruteForce?: boolean | RateLimitConfig;
+    /**
+     * Honeypot Tarpit Configuration (Bot & Scanner Neutralization)
+     *
+     * Instantly blocks vulnerability scanners by performing an ultra-fast O(1)
+     * lookup on common malicious payload signatures (e.g., `/.env`, `/.git`).
+     * Prevents wasted CPU cycles from regex ReDoS and framework routing.
+     * By default, this is implicitly **TRUE**.
+     *
+     * @example Disable honeypot tarpit (Not recommended)
+     * ```typescript
+     * honeypotTarpit: false
+     * ```
+     */
+    honeypotTarpit?: boolean;
     /**
      * Rate Limiting Configuration
      *
@@ -2845,13 +2860,13 @@ declare class XyPrissRunner {
  *
  * Serves as the foundational layer for all XyPriss domain-specific APIs.
  * It encapsulates the `XyPrissRunner` instance, ensuring that all subclasses
- * have unified access to the underlying Rust bridge for high-performance system operations.
+ * have unified access to the underlying XHSC bridge for high-performance system operations.
  */
 declare class BaseApi {
     protected runner: XyPrissRunner;
     /**
      * Initializes the Base API with a shared runner instance.
-     * @param runner The XyPrissRunner instance responsible for executing system commands.
+     * @param runner - The XyPrissRunner used to invoke native XHSC binaries.
      */
     constructor(runner: XyPrissRunner);
 }
@@ -2860,7 +2875,7 @@ declare class BaseApi {
  *
  * The `PathApi` class provides a comprehensive suite of robust, platform-independent
  * utilities for working with file and directory paths. By bridging directly to
- * the native engine's internal path module, it ensures rigorous adherence to filesystem standards
+ * the XHSC native binary, it ensures rigorous adherence to filesystem standards
  * across Windows, macOS, and Linux environments.
  *
  * **Key Benefits:**
@@ -3082,10 +3097,41 @@ declare class PathApi extends BaseApi {
      * @returns {boolean} True if the path is absolute, false otherwise.
      */
     isAbsolute: (p: string) => boolean;
+    /**
+     * **Smart Path Correction**
+     *
+     * Attempts to fix path inconsistencies, such as doubled segments or redundant separators.
+     * Prioritizes the high-performance XHSC implementation.
+     *
+     * @param p - Path to correct.
+     * @param tentative - Maximum number of correction attempts.
+     */
+    correct(path: string, options?: {
+        tentative?: number;
+        verify?: boolean;
+    }): string;
     /**
      * **Get System Temp Directory**
      */
     tempDir: () => string;
+    /**
+     * **User-Scoped Temp Directory**
+     *
+     * Resolves and ensures a unique, ephemeral temporary directory scoped
+     * to the current user session under the XyPriss shared temp root
+     * (`<os.tmpdir>/nehonix.xypriss.data/xuser/<hex4>`).
+     *
+     * Each access generates a fresh random sub-path — suited for
+     * short-lived scratch space that must not collide across concurrent
+     * processes or requests.
+     *
+     * @returns {string} Absolute path to the isolated user temp directory.
+     *
+     * @example
+     * const scratch = __sys__.path.tmpUserDir;
+     * __sys__.fs.writeFile(scratch + "/output.json", data);
+     */
+    get tmpUserDir(): string;
     /**
      * **Check Existence**
      */
@@ -3112,7 +3158,7 @@ declare class PathApi extends BaseApi {
  * **System Information Types**
  *
  * Standardized interfaces for the XyPriss System API.
- * Maps directly to the underlying Rust structures.
+ * Maps directly to the underlying native core structures.
  */
 interface SystemInfo {
     hostname: string;
@@ -3292,12 +3338,12 @@ interface FileStats {
     size: number;
     is_file: boolean;
     is_dir: boolean;
-    is_symlink: boolean;
     modified: number;
-    created: number;
-    accessed: number;
-    readonly: boolean;
     permissions: number;
+    is_symlink?: boolean;
+    created?: number;
+    accessed?: number;
+    readonly?: boolean;
 }
 interface DirUsage {
     path: string;
@@ -3336,6 +3382,45 @@ interface BatchRenameChange {
     old_path: string;
     new_path: string;
 }
+/**
+ * **Filesystem Open Flags**
+ *
+ * Standardized flags for opening files, following Node.js conventions
+ * and mapping to native XHSC `os` constants.
+ *
+ * ---
+ *
+ * ### Read flags
+ * - `"r"`   — Open for **reading only**. Fails if the file does not exist.
+ * - `"r+"`  — Open for **reading and writing**. Fails if the file does not exist.
+ * - `"rs+"` — Open for **reading and writing in synchronous mode**. Instructs the OS
+ *             to bypass the local file system cache. Useful for NFS mounts or
+ *             scenarios where cache coherency is critical.
+ *
+ * ### Write flags
+ * - `"w"`   — Open for **writing only**. The file is **created** if it does not exist,
+ *             or **truncated to zero length** if it does.
+ * - `"wx"`  — Like `"w"`, but **fails if the file already exists** (exclusive create).
+ * - `"w+"`  — Open for **reading and writing**. The file is **created** if it does not
+ *             exist, or **truncated** if it does.
+ * - `"wx+"` — Like `"w+"`, but **fails if the file already exists** (exclusive create).
+ *
+ * ### Append flags
+ * - `"a"`   — Open for **appending only**. The file is **created** if it does not exist.
+ *             The write position is always set to the end of the file.
+ * - `"ax"`  — Like `"a"`, but **fails if the file already exists** (exclusive create).
+ * - `"a+"`  — Open for **reading and appending**. The file is **created** if it does
+ *             not exist. Reading is allowed from any position; writes always go to EOF.
+ * - `"ax+"` — Like `"a+"`, but **fails if the file already exists** (exclusive create).
+ *
+ * ---
+ *
+ * > **`x` suffix** — The exclusive flag (`x`) maps to `O_EXCL` at the OS level.
+ * > It guarantees atomicity: the operation succeeds only if *this* call creates the file,
+ * > preventing race conditions in concurrent environments.
+ */
+type OpenFlag = "r" | "r+" | "rs+" | "w" | "wx" | "w+" | "wx+" | "a" | "ax" | "a+" | "ax+";
+type FileOpenFlags = OpenFlag | number;
 
 /**
  * **Operating System & Hardware API**
@@ -3420,6 +3505,45 @@ declare class FSBase extends PathApi {
     constructor(runner: XyPrissRunner);
 }
 
+/**
+ * **High-Performance File Toolbox**
+ * Exposed via __sys__.fs.open(path, callback)
+ */
+declare class FileHandle {
+    private id;
+    private runner;
+    private ipc;
+    constructor(id: number, runner: any);
+    /**
+     * **Get Native Handle ID**
+     */
+    get nativeId(): number;
+    /**
+     * **Read from File**
+     * @param length - Max bytes to read
+     */
+    read(length: number): Promise<Buffer>;
+    /**
+     * **Write to File**
+     * @param data - Buffer or String
+     */
+    write(data: Buffer | string): Promise<number>;
+    /**
+     * **Seek within File**
+     * @param offset - Position
+     * @param whence - 0: Start, 1: Current, 2: End
+     */
+    seek(offset: number, whence?: number): Promise<number>;
+    /**
+     * **Get File Statistics**
+     */
+    stat(): Promise<FileStats>;
+    /**
+     * **Close Handle**
+     */
+    close(): Promise<void>;
+}
+
 /**
  * **Core Filesystem Operations**
  */
@@ -3619,6 +3743,88 @@ declare class FSCore extends FSBase {
      * **Find Duplicates**
      */
     dedupe: (p: string) => DedupeGroup[];
+    /**
+     * **Open File**
+     *
+     * Opens a file and returns a numeric file descriptor (or runs a scoped callback).
+     *
+     * ---
+     *
+     * ### Modes via `flags`
+     *
+     * | Flag    | Behavior                                                        |
+     * |---------|-----------------------------------------------------------------|
+     * | `"r"`   | Read-only. Fails if the file does not exist.                    |
+     * | `"r+"`  | Read-write. Fails if the file does not exist.                   |
+     * | `"rs+"` | Read-write, bypasses OS cache (useful for NFS / shared drives). |
+     * | `"w"`   | Write-only. Creates the file or truncates it if it exists.      |
+     * | `"wx"`  | Write-only. Fails if the file already exists (atomic create).   |
+     * | `"w+"`  | Read-write. Creates the file or truncates it if it exists.      |
+     * | `"wx+"` | Read-write. Fails if the file already exists (atomic create).   |
+     * | `"a"`   | Append-only. Creates the file if missing. Writes go to EOF.     |
+     * | `"ax"`  | Append-only. Fails if the file already exists (atomic create).  |
+     * | `"a+"`  | Read-append. Creates the file if missing. Writes always at EOF. |
+     * | `"ax+"` | Read-append. Fails if the file already exists (atomic create).  |
+     *
+     * > **`x` suffix** — Maps to `O_EXCL` at the OS level: the call succeeds only if
+     * > *this* invocation creates the file, preventing race conditions.
+     *
+     * ---
+     *
+     * ### Transport strategy
+     *
+     * The method resolves the file descriptor through two transports, in order:
+     *
+     * 1. **IPC** (`XYPRISS_IPC_PATH` set) — communicates with the XHSC daemon via a
+     *    Unix socket. File descriptors are **stateful and persistent** across calls.
+     * 2. **Runner fallback** — used when IPC is unavailable or the environment variable
+     *    is not set. Descriptors are **not persistent** across multiple independent calls;
+     *    a warning is emitted to the console.
+     *
+     * ---
+     *
+     * ### Callback (scoped) mode
+     *
+     * When a `callback` is provided, the file is opened, passed as a {@link FileHandle}
+     * toolbox to the callback, then **automatically closed** in a `finally` block —
+     * even if the callback throws. In this mode the method returns `void`.
+     *
+     * When no callback is provided, the raw numeric file descriptor is returned and
+     * **the caller is responsible for closing it**.
+     *
+     * ---
+     *
+     * @param p        - Absolute or relative path to the target file.
+     * @param flags    - Open mode, as a string flag (default: `"r"`) or a numeric
+     *                   `os` constant. See the flag table above.
+     * @param callback - Optional scoped handler receiving a {@link FileHandle}.
+     *                   When supplied, the handle is closed automatically on completion.
+     *
+     * @returns The numeric file descriptor when no callback is given; `void` otherwise.
+     *
+     * @example <caption>Scoped read (handle closed automatically)</caption>
+     * ```typescript
+     * await __sys__.fs.open("data.bin", "r", async (file) => {
+     *     const chunk = await file.read(1024);
+     *     console.log(chunk.toString());
+     * });
+     * ```
+     *
+     * @example <caption>Manual descriptor (caller must close)</caption>
+     * ```typescript
+     * const fd = await __sys__.fs.open("output.log", "a");
+     * // ... write operations ...
+     * await __sys__.fs.close(fd);
+     * ```
+     */
+    open(p: string, flags?: FileOpenFlags, callback?: (handle: FileHandle) => Promise<void> | void): Promise<number | void>;
+    /**
+     * **Close File Handle**
+     *
+     * @param handle - The file handle to close.
+     */
+    close: (handle: number) => Promise<void>;
+    private mapFlags;
 }
 
 /**
@@ -4416,233 +4622,1715 @@ declare class EnvApi implements IEnvApi {
      * const timeout = __sys__.__env__.get("REQUEST_TIMEOUT_MS", "5000");
      * const ms = parseInt(timeout, 10);
      *
-     * // Concise fallback with nullish coalescing
-     * const logLevel = __sys__.__env__.get("LOG_LEVEL") ?? "info";
+     * // Concise fallback with nullish coalescing
+     * const logLevel = __sys__.__env__.get("LOG_LEVEL") ?? "info";
+     */
+    get(key: string): string | undefined;
+    get(key: string, defaultValue: string): string;
+    /**
+     * Reads a required variable from the secure internal store and throws if
+     * it cannot be resolved.
+     *
+     * Use this method for every variable that is mandatory for application
+     * correctness. It surfaces configuration errors at startup rather than
+     * silently producing `undefined` at the point of use.
+     *
+     * @param key     - Variable name to look up.
+     * @param options - Optional validation settings.
+     * @returns The stored value, guaranteed non-undefined.
+     * @throws {EnvAccessError} When the variable is missing or empty.
+     * @throws {EnvStoreError}  When the store has not been initialised.
+     *
+     * @example
+     * // Fail fast at boot if a critical variable is absent
+     * const databaseUrl = __sys__.__env__.getStrict("DATABASE_URL");
+     * const jwtSecret   = __sys__.__env__.getStrict("JWT_SECRET", { rejectEmpty: true });
+     * const smtpHost    = __sys__.__env__.getStrict("SMTP_HOST");
+     *
+     * // Collect all required variables once at module initialisation
+     * const config = {
+     *   db:   __sys__.__env__.getStrict("DATABASE_URL"),
+     *   jwt:  __sys__.__env__.getStrict("JWT_SECRET", { rejectEmpty: true }),
+     *   smtp: __sys__.__env__.getStrict("SMTP_HOST"),
+     * };
+     */
+    getStrict(key: string, options?: EnvGetStrictOptions): string;
+    /**
+     * Returns `true` when the given key is present in the secure internal
+     * store, regardless of its value (including empty strings).
+     *
+     * @param key - Variable name to test.
+     * @throws {EnvStoreError} When the store has not been initialised.
+     *
+     * @example
+     * if (__sys__.__env__.has("SENTRY_DSN")) {
+     *   Sentry.init({ dsn: __sys__.__env__.get("SENTRY_DSN") });
+     * }
+     *
+     * const betaEnabled = __sys__.__env__.has("ENABLE_BETA_UI");
+     */
+    has(key: string): boolean;
+    /**
+     * Returns a frozen, point-in-time snapshot of stored variables.
+     *
+     * The object is frozen at the moment of the call; subsequent `set` or
+     * `delete` calls do not affect it.
+     *
+     * Providing `options.keys` is strongly recommended in production code.
+     * Returning the full store risks inadvertently capturing secrets in log
+     * statements or JSON serialisations.
+     *
+     * @param options - Optional filter configuration.
+     * @returns A frozen {@link EnvSnapshot}.
+     * @throws {EnvStoreError} When the store has not been initialised.
+     *
+     * @example
+     * // Filtered snapshot — preferred in all production code paths
+     * const dbConfig = __sys__.__env__.all({
+     *   keys: ["DATABASE_URL", "DATABASE_POOL_SIZE", "DATABASE_TIMEOUT_MS"],
+     * });
+     *
+     * // Full snapshot — use only for diagnostics / startup validation
+     * const full = __sys__.__env__.all();
+     * logger.debug("Env snapshot", { count: Object.keys(full).length });
+     */
+    all(options?: EnvAllOptions): EnvSnapshot;
+    /**
+     * Returns `true` when the execution mode is `"production"`.
+     *
+     * @example
+     * const logger = createLogger({
+     *   level: __sys__.__env__.isProduction() ? "error" : "debug",
+     * });
+     */
+    isProduction(): boolean;
+    /**
+     * Returns `true` when the execution mode is `"development"`.
+     *
+     * @example
+     * if (__sys__.__env__.isDevelopment()) {
+     *   app.use(requestLogger({ colorize: true }));
+     * }
+     */
+    isDevelopment(): boolean;
+    /**
+     * Returns `true` when the execution mode is `"staging"`.
+     *
+     * @example
+     * if (__sys__.__env__.isStaging()) {
+     *   payment.useSandbox();
+     * }
+     */
+    isStaging(): boolean;
+    /**
+     * Returns `true` when the execution mode is `"test"`.
+     *
+     * @example
+     * const dbUrl = __sys__.__env__.isTest()
+     *   ? __sys__.__env__.getStrict("TEST_DATABASE_URL")
+     *   : __sys__.__env__.getStrict("DATABASE_URL");
+     */
+    isTest(): boolean;
+    /**
+     * Returns `true` when the execution mode exactly matches `envName`
+     * (case-sensitive).
+     *
+     * @param envName - Mode name to compare against.
+     *
+     * @example
+     * if (__sys__.__env__.is("canary")) {
+     *   featureFlags.enableAll();
+     * }
+     */
+    is(envName: string): boolean;
+    /**
+     * Retrieves the OS-level username of the current process owner by invoking
+     * the XHSC native Go binary.
+     *
+     * This method is synchronous and blocks until the native call completes.
+     * Do not call it in request hot paths. Returns `""` on failure so callers
+     * can safely use the result without null checks.
+     *
+     * @returns The current OS username, or `""` on failure.
+     *
+     * @example
+     * const actor = __sys__.__env__.user() || "<unknown>";
+     * auditLog.write({ actor, action: "deploy" });
+     */
+    user(): string;
+    /**
+     * Returns the internal store, throwing {@link EnvStoreError} if it has not
+     * yet been initialised.
+     *
+     * SECURITY: This is the single point of store access. Every read and write
+     * method must go through here — never access `globalThis[XY_ENV_STORE_KEY]`
+     * directly outside this method.
+     *
+     * Eliminating the `?? process.env` fallback is intentional. A silent
+     * fallback to `process.env` during the bootstrap race window would bypass
+     * the Shield and leak values without any warning. A thrown error is
+     * immediately visible during development and integration testing.
+     *
+     * @internal
+     * @throws {EnvStoreError}
+     */
+    private requireStoreMap;
+    private getStoreForCaller;
+    /**
+     * Asserts that `key` is a valid environment variable name.
+     *
+     * @internal
+     * @throws {EnvKeyError}
+     */
+    private validateKey;
+    /**
+     * Asserts that `value` does not contain characters that can corrupt
+     * downstream parsers, log sinks, or HTTP serialisers.
+     *
+     * Rejected characters:
+     * - CR (`\r`) and LF (`\n`) — break line-oriented `.env` parsers and
+     *   enable log injection attacks.
+     * - NUL (`\0`) — truncates strings in C-based runtimes and can bypass
+     *   suffix-based extension checks in some file path handling code.
+     *
+     * @internal
+     * @throws {EnvKeyError}
+     */
+    private validateValue;
+    /**
+     * **Environment Security Shield**
+     *
+     * Replaces the `process.env` object with a hardened Proxy that enforces
+     * the following policies on every property access:
+     *
+     * **Read trap**
+     * - Whitelisted keys (see {@link EnvApi.whitelistedFields}) and keys
+     *   matching the prefixes `XY_`, `XYPRISS_`, `ENC_`, `DOTENV_`, or `__`
+     *   pass through to the real value.
+     * - All other reads return `undefined`. A one-time per-key warning is
+     *   written to `process.stderr` (suppressed when
+     *   `XYPRISS_ENV_SHIELD=silent`).
+     *
+     * **`ownKeys` and `has` traps**
+     * - Restrict the apparent key set to the whitelist. This prevents
+     *   third-party code from enumerating the real store through
+     *   `Object.keys(process.env)`, `JSON.stringify(process.env)`, or spread
+     *   operators — all of which bypass the `get` trap.
+     *
+     * The descriptor is applied with `writable: false` to prevent replacement
+     * by application code, and `configurable: true` to allow test teardown.
+     *
+     * @internal
+     */
+    /**
+     * **Environment Security Shield**
+     *
+     * Replaces the `process.env` object with a hardened Proxy that enforces
+     * the following policies on every property access:
+     *
+     * **Read trap**
+     * - Whitelisted keys (see {@link EnvApi.whitelistedFields}) and keys
+     *   matching the prefixes `XY_`, `XYPRISS_`, `ENC_`, `DOTENV_`, or `__`
+     *   pass through to the real value.
+     * - All other reads return `undefined`. A one-time per-key warning is
+     *   written to `process.stderr` (suppressed when
+     *   `XYPRISS_ENV_SHIELD=silent`).
+     *
+     * **`ownKeys` and `has` traps**
+     * - Restrict the apparent key set to the whitelist. This prevents
+     *   third-party code from enumerating the real store through
+     *   `Object.keys(process.env)`, `JSON.stringify(process.env)`, or spread
+     *   operators — all of which bypass the `get` trap.
+     *
+     * The descriptor is applied with `writable: false` to prevent replacement
+     * by application code, and `configurable: true` to allow test teardown.
+     *
+     * @internal
+     */
+    private applyShield;
+    private isCallerProjectCode;
+}
+
+/**
+ * **StringUtils — XyPriss String Utilities**
+ */
+declare class StringUtils {
+    /**
+     * **Generate a Random String**
+     *
+     * Generates a pseudo-random character sequence of a specified length.
+     * Uses alphanumeric characters (A-Z, a-z, 0-9).
+     *
+     * @param length - The desired length of the string (default: `10`).
+     * @returns A random alphanumeric string.
+     *
+     * @example
+     * ```ts
+     * utils.randomString(8); // "a7B2k9Xz"
+     * ```
+     */
+    randomString(length?: number): string;
+    /**
+     * **Slugify a String**
+     *
+     * Converts a string into a URL-friendly "slug" by lowering case,
+     * removing non-alphanumeric characters, and replacing spaces with hyphens.
+     *
+     * @param text - The string to slugify.
+     * @returns The URL-friendly slug.
+     *
+     * @example
+     * ```ts
+     * utils.slugify("Hello World!"); // "hello-world"
+     * ```
+     */
+    slugify(text: string): string;
+    /**
+     * **Truncate a String**
+     *
+     * Shortens a string to a specified length and appends a suffix (default: `...`)
+     * if the original string was longer than the limit.
+     *
+     * @param text      - The string to truncate.
+     * @param maxLength - Maximum length including the suffix.
+     * @param suffix    - The string to append (default: `"..."`).
+     * @returns The truncated string.
+     *
+     * @example
+     * ```ts
+     * utils.truncate("Very long sentence", 10); // "Very lo..."
+     * ```
+     */
+    truncate(text: string, maxLength: number, suffix?: string): string;
+    /**
+     * **Capitalize a String**
+     *
+     * Uppercases the first character of the string.
+     *
+     * @param text - The string to capitalize.
+     * @returns The capitalized string.
+     */
+    capitalize(text: string): string;
+    /**
+     * **Convert to camelCase**
+     *
+     * Converts hyphen-separated, underscore-separated, or space-separated
+     * strings into camelCase.
+     *
+     * @param text - The string to convert.
+     * @returns The camelCase string.
+     */
+    toCamelCase(text: string): string;
+    /**
+     * **Pad a String**
+     *
+     * Adds padding characters to the start or end of a string until it
+     * reaches the target length.
+     *
+     * @param text     - The source string.
+     * @param length   - Target length.
+     * @param char     - Padding character (default: `" "`).
+     * @param position - Whether to pad at `"start"` or `"end"`.
+     * @returns The padded string.
+     */
+    pad(text: string, length: number, char?: string, position?: "start" | "end"): string;
+    /**
+     * **Count Word/Substring Occurrences**
+     *
+     * Returns the number of times a specific word or substring appears.
+     *
+     * @param text          - The body of text to search.
+     * @param word          - The substring to look for.
+     * @param caseSensitive - Whether to respect case (default: `false`).
+     * @returns The number of occurrences.
+     */
+    countOccurrences(text: string, word: string, caseSensitive?: boolean): number;
+    /**
+     * **toQueryString**
+     *
+     * Serializes a flat record into a URL-encoded query string format.
+     *
+     * @param params The object to serialize.
+     * @returns The query string.
+     */
+    toQueryString(params: Record<string, unknown>): string;
+}
+
+/**
+ * **NumberUtils — XyPriss Number & Math Utilities**
+ */
+declare class NumberUtils {
+    /**
+     * **Clamp a Value**
+     *
+     * Restricts a numeric value to a defined range [min, max].
+     *
+     * @param value - The value to clamp.
+     * @param min   - The lower bound.
+     * @param max   - The upper bound.
+     * @returns The clamped value.
+     */
+    clamp(value: number, min: number, max: number): number;
+    /**
+     * **Linear Interpolation (LERP)**
+     *
+     * Returns the linear interpolation between `start` and `end` for a factor `t`.
+     *
+     * @param start - The start value.
+     * @param end   - The end value.
+     * @param t     - The interpolation factor (0.0 to 1.0).
+     * @returns The interpolated value.
+     */
+    lerp(start: number, end: number, t: number): number;
+    /**
+     * **Get a Random Integer**
+     *
+     * Returns a random integer between min (inclusive) and max (inclusive).
+     *
+     * @param min - Minimum value.
+     * @param max - Maximum value.
+     * @returns A random integer.
+     */
+    randomInt(min: number, max: number): number;
+    /**
+     * **Format Number**
+     *
+     * Locale-aware number formatting.
+     *
+     * @param value   - The number to format.
+     * @param locale  - Optional locale (default: `en-US`).
+     * @param options - Intl.NumberFormatOptions.
+     * @returns A localized string.
+     */
+    formatNumber(value: number, locale?: string, options?: Intl.NumberFormatOptions): string;
+    /**
+     * **Format Bytes**
+     *
+     * Converts raw bytes into a human-readable size string (KB, MB, GB, etc.).
+     *
+     * @param bytes    - The number of bytes.
+     * @param decimals - Decimal precision.
+     * @returns A human-readable size string.
+     */
+    formatBytes(bytes: number, decimals?: number): string;
+}
+
+/**
+ * @file DateUtils.ts
+ * @description XyPriss Date & Time Utilities — A comprehensive, zero-dependency
+ * date/time utility class built on the native `Date` object and the `Intl` API.
+ *
+ * @remarks
+ * All methods are pure and side-effect-free unless otherwise noted.
+ * Timestamps can be provided in either **seconds** (Unix) or **milliseconds**
+ * (JavaScript). The class auto-detects the unit using the heuristic:
+ * values below `1e11` are treated as seconds; values at or above `1e11` are
+ * treated as milliseconds. This heuristic is valid until **November 2286**.
+ *
+ * @example
+ * ```ts
+ * const du = new DateUtils();
+ *
+ * du.format(Date.now());            // "Apr 15, 2026"
+ * du.timeAgo(Date.now() - 90_000); // "2 minutes ago"
+ * du.formatDuration(3_661_000);    // "1h 1m 1s"
+ * du.startOf("month");             // 2026-04-01T00:00:00.000Z
+ * ```
+ */
+declare class DateUtils {
+    /**
+     * Converts any supported input value to a `Date` object.
+     *
+     * Supported inputs:
+     * - `Date` — returned as-is (not cloned).
+     * - `number` — auto-detected as Unix seconds (`< 1e11`) or milliseconds.
+     * - `string` — parsed via `new Date(string)` (ISO 8601 recommended).
+     *
+     * @param date - The value to convert.
+     * @returns The corresponding `Date` object.
+     * @throws {RangeError} If the resulting `Date` is invalid.
+     *
+     * @internal
+     */
+    private toDate;
+    /**
+     * Converts any supported input value to a millisecond timestamp.
+     *
+     * @param date - The value to convert.
+     * @returns Milliseconds since the Unix epoch.
+     *
+     * @internal
+     */
+    private toMs;
+    /**
+     * Returns the current Unix timestamp in **seconds**.
+     *
+     * @returns The current time as a Unix timestamp (integer seconds).
+     *
+     * @example
+     * ```ts
+     * du.now(); // e.g. 1776287197
+     * ```
+     */
+    now(): number;
+    /**
+     * Returns the current time as a JavaScript timestamp in **milliseconds**.
+     *
+     * Equivalent to `Date.now()`.
+     *
+     * @returns The current time in milliseconds since the Unix epoch.
+     *
+     * @example
+     * ```ts
+     * du.nowMs(); // e.g. 1776287197000
+     * ```
+     */
+    nowMs(): number;
+    /**
+     * Returns the current time as a `Date` object.
+     *
+     * @returns A new `Date` representing the current instant.
+     *
+     * @example
+     * ```ts
+     * du.today(); // Date { ... }
+     * ```
+     */
+    today(): Date;
+    /**
+     * Serializes a date value into a localized string using `Intl.DateTimeFormat`.
+     *
+     * Automatically handles Unix timestamps (seconds) and JavaScript timestamps
+     * (milliseconds) via the `< 1e11` heuristic.
+     *
+     * @param date    - The input to format: `Date`, number (timestamp), or ISO string.
+     * @param locale  - BCP 47 locale tag (default: `"en-US"`).
+     * @param options - `Intl.DateTimeFormatOptions` to customize the output.
+     * @returns A localized date string.
+     *
+     * @example
+     * ```ts
+     * du.format(1776287197);
+     * // → "Apr 15, 2026"
+     *
+     * du.format(new Date(), "fr-FR", { dateStyle: "full" });
+     * // → "mercredi 15 avril 2026"
+     *
+     * du.format("2026-04-15T12:00:00Z", "en-GB", { timeStyle: "short" });
+     * // → "12:00"
+     * ```
+     */
+    format(date: Date | number | string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+    /**
+     * Formats a date as an ISO 8601 string (`YYYY-MM-DDTHH:mm:ss.sssZ`).
+     *
+     * This is the format recommended for data interchange and storage.
+     *
+     * @param date - The date to format (default: current time).
+     * @returns An ISO 8601 UTC string.
+     *
+     * @example
+     * ```ts
+     * du.toISO();
+     * // → "2026-04-15T10:30:00.000Z"
+     *
+     * du.toISO(1776287197);
+     * // → "2026-04-15T..."
+     * ```
+     */
+    toISO(date?: Date | number | string): string;
+    /**
+     * Formats a date as a plain date string: `YYYY-MM-DD`.
+     *
+     * The date is rendered in **local time** unless a UTC flag is set.
+     *
+     * @param date - The date to format (default: current time).
+     * @param utc  - If `true`, use UTC date components instead of local time (default: `false`).
+     * @returns A date-only string in `YYYY-MM-DD` format.
+     *
+     * @example
+     * ```ts
+     * du.toDateString();
+     * // → "2026-04-15"
+     *
+     * du.toDateString(new Date("2026-12-31T23:59:00Z"), true);
+     * // → "2026-12-31"
+     * ```
+     */
+    toDateString(date?: Date | number | string, utc?: boolean): string;
+    /**
+     * Formats a date as a time string: `HH:mm:ss`.
+     *
+     * The time is rendered in **local time** unless the UTC flag is set.
+     *
+     * @param date - The date to format (default: current time).
+     * @param utc  - If `true`, use UTC time components (default: `false`).
+     * @returns A time-only string in `HH:mm:ss` format.
+     *
+     * @example
+     * ```ts
+     * du.toTimeString(new Date("2026-04-15T08:05:03Z"), true);
+     * // → "08:05:03"
+     * ```
+     */
+    toTimeString(date?: Date | number | string, utc?: boolean): string;
+    /**
+     * Converts a duration into a human-readable string (e.g., `"1d 2h 30m 5s"`).
+     *
+     * Components are omitted when their value is zero, except for seconds which
+     * always appear when the total duration is less than one minute.
+     *
+     * @param value - The duration to format.
+     * @param unit  - The unit of `value`: `"ms"` (milliseconds, default) or `"s"` (seconds).
+     * @returns A compact, space-separated duration string.
+     *
+     * @example
+     * ```ts
+     * du.formatDuration(3_661_000);       // → "1h 1m 1s"
+     * du.formatDuration(90, "s");         // → "1m 30s"
+     * du.formatDuration(0);              // → "0s"
+     * du.formatDuration(86_400_000);     // → "1d"
+     * ```
+     */
+    formatDuration(value: number, unit?: "ms" | "s"): string;
+    /**
+     * Returns a relative time string (e.g., `"5 minutes ago"`, `"in 2 hours"`).
+     *
+     * Uses `Intl.RelativeTimeFormat` for locale-aware output. Automatically
+     * selects the most appropriate unit (second → minute → hour → day → month → year).
+     *
+     * @param date   - The reference date, in the past or future.
+     * @param locale - BCP 47 locale tag (default: `"en-US"`).
+     * @returns A localized relative time string.
+     *
+     * @example
+     * ```ts
+     * du.timeAgo(Date.now() - 90_000);       // → "2 minutes ago"
+     * du.timeAgo(Date.now() + 3_600_000);    // → "in 1 hour"
+     * du.timeAgo(Date.now() - 90_000, "fr"); // → "il y a 2 minutes"
+     * ```
+     */
+    timeAgo(date: Date | number | string, locale?: string): string;
+    /**
+     * Adds a given amount of time to a date and returns a new `Date`.
+     *
+     * Supported units: `"ms"`, `"s"` (seconds), `"m"` (minutes), `"h"` (hours),
+     * `"d"` (days), `"w"` (weeks), `"mo"` (months), `"y"` (years).
+     *
+     * Month and year arithmetic is handled using `setMonth` / `setFullYear`,
+     * which correctly accounts for varying month lengths (e.g., adding 1 month
+     * to January 31 yields February 28/29).
+     *
+     * @param date  - The starting date.
+     * @param value - The amount to add (can be negative to subtract).
+     * @param unit  - The time unit.
+     * @returns A new `Date` offset by the specified amount.
+     *
+     * @example
+     * ```ts
+     * du.add(new Date("2026-01-31"), 1, "mo");
+     * // → Date("2026-02-28") — accounts for shorter February
+     *
+     * du.add(new Date("2026-04-15"), -7, "d");
+     * // → Date("2026-04-08")
+     *
+     * du.add(Date.now(), 2, "h");
+     * // → Date 2 hours from now
+     * ```
+     */
+    add(date: Date | number | string, value: number, unit: "ms" | "s" | "m" | "h" | "d" | "w" | "mo" | "y"): Date;
+    /**
+     * Subtracts a given amount of time from a date and returns a new `Date`.
+     *
+     * This is a convenience wrapper around {@link add} with a negated `value`.
+     *
+     * @param date  - The starting date.
+     * @param value - The amount to subtract (must be positive).
+     * @param unit  - The time unit (same options as {@link add}).
+     * @returns A new `Date` shifted back by the specified amount.
+     *
+     * @example
+     * ```ts
+     * du.subtract(new Date("2026-03-01"), 1, "mo");
+     * // → Date("2026-02-01")
+     * ```
+     */
+    subtract(date: Date | number | string, value: number, unit: "ms" | "s" | "m" | "h" | "d" | "w" | "mo" | "y"): Date;
+    /**
+     * Returns the difference between two dates in the specified unit.
+     *
+     * The result is the **signed** difference `(dateA - dateB)` truncated
+     * toward zero. A positive value means `dateA` is later than `dateB`.
+     *
+     * Supported units: `"ms"`, `"s"`, `"m"`, `"h"`, `"d"`, `"w"`.
+     * Month and year differences are intentionally excluded because their
+     * variable length makes a lossless inverse impossible; use {@link add}
+     * and calendar-aware logic for those cases.
+     *
+     * @param dateA - The first date.
+     * @param dateB - The second date.
+     * @param unit  - The unit for the result (default: `"ms"`).
+     * @returns The signed integer difference in the requested unit.
+     *
+     * @example
+     * ```ts
+     * du.diff("2026-04-20", "2026-04-15", "d");  // → 5
+     * du.diff("2026-04-10", "2026-04-15", "d");  // → -5
+     * du.diff(Date.now(), Date.now() - 3600_000, "h"); // → 1
+     * ```
+     */
+    diff(dateA: Date | number | string, dateB: Date | number | string, unit?: "ms" | "s" | "m" | "h" | "d" | "w"): number;
+    /**
+     * Returns `true` if `dateA` is strictly before `dateB`.
+     *
+     * @param dateA - The first date.
+     * @param dateB - The second date.
+     * @returns `true` if `dateA < dateB`.
+     *
+     * @example
+     * ```ts
+     * du.isBefore("2026-01-01", "2026-06-01"); // → true
+     * ```
+     */
+    isBefore(dateA: Date | number | string, dateB: Date | number | string): boolean;
+    /**
+     * Returns `true` if `dateA` is strictly after `dateB`.
+     *
+     * @param dateA - The first date.
+     * @param dateB - The second date.
+     * @returns `true` if `dateA > dateB`.
+     *
+     * @example
+     * ```ts
+     * du.isAfter("2026-12-31", "2026-06-01"); // → true
+     * ```
+     */
+    isAfter(dateA: Date | number | string, dateB: Date | number | string): boolean;
+    /**
+     * Returns `true` if two dates represent the same instant in time.
+     *
+     * Comparison is performed at millisecond precision.
+     *
+     * @param dateA - The first date.
+     * @param dateB - The second date.
+     * @returns `true` if both dates resolve to the same millisecond.
+     *
+     * @example
+     * ```ts
+     * du.isSame(new Date("2026-04-15"), 1776268800000); // → true (if same instant)
+     * ```
+     */
+    isSame(dateA: Date | number | string, dateB: Date | number | string): boolean;
+    /**
+     * Returns `true` if `date` falls within the range `[start, end]` (inclusive).
+     *
+     * @param date  - The date to test.
+     * @param start - The start of the range.
+     * @param end   - The end of the range.
+     * @returns `true` if `start ≤ date ≤ end`.
+     *
+     * @example
+     * ```ts
+     * du.isBetween("2026-04-15", "2026-01-01", "2026-12-31"); // → true
+     * du.isBetween("2025-12-31", "2026-01-01", "2026-12-31"); // → false
+     * ```
+     */
+    isBetween(date: Date | number | string, start: Date | number | string, end: Date | number | string): boolean;
+    /**
+     * Returns a new `Date` set to the **start** of the specified unit
+     * (i.e., all smaller components zeroed out).
+     *
+     * Supported units: `"day"`, `"week"` (Monday = start), `"month"`, `"year"`.
+     *
+     * @param unit - The boundary unit.
+     * @param date - The reference date (default: current time).
+     * @returns A new `Date` at the beginning of the unit.
+     *
+     * @example
+     * ```ts
+     * du.startOf("day");
+     * // → 2026-04-15T00:00:00.000 (local)
+     *
+     * du.startOf("month", new Date("2026-04-15"));
+     * // → 2026-04-01T00:00:00.000
+     *
+     * du.startOf("year", "2026-06-15");
+     * // → 2026-01-01T00:00:00.000
+     * ```
+     */
+    startOf(unit: "day" | "week" | "month" | "year", date?: Date | number | string): Date;
+    /**
+     * Returns a new `Date` set to the **end** of the specified unit
+     * (i.e., the last millisecond of that unit).
+     *
+     * Supported units: `"day"`, `"week"` (Sunday = end), `"month"`, `"year"`.
+     *
+     * @param unit - The boundary unit.
+     * @param date - The reference date (default: current time).
+     * @returns A new `Date` at the very last millisecond of the unit.
+     *
+     * @example
+     * ```ts
+     * du.endOf("month", new Date("2026-02-01"));
+     * // → 2026-02-28T23:59:59.999
+     *
+     * du.endOf("year", "2026-01-01");
+     * // → 2026-12-31T23:59:59.999
+     * ```
+     */
+    endOf(unit: "day" | "week" | "month" | "year", date?: Date | number | string): Date;
+    /**
+     * Returns `true` if the given year is a leap year.
+     *
+     * A year is a leap year if it is divisible by 4, except for century years,
+     * which must also be divisible by 400.
+     *
+     * @param year - The four-digit year to test (default: current year).
+     * @returns `true` if the year is a leap year.
+     *
+     * @example
+     * ```ts
+     * du.isLeapYear(2024); // → true
+     * du.isLeapYear(2100); // → false
+     * du.isLeapYear(2000); // → true
+     * ```
+     */
+    isLeapYear(year?: number): boolean;
+    /**
+     * Returns the number of days in a given month of a given year.
+     *
+     * Correctly accounts for leap years when querying February.
+     *
+     * @param month - The 1-based month index (1 = January, 12 = December).
+     * @param year  - The four-digit year (default: current year).
+     * @returns The number of days in the specified month (28–31).
+     *
+     * @example
+     * ```ts
+     * du.daysInMonth(2, 2024); // → 29  (leap year)
+     * du.daysInMonth(2, 2023); // → 28
+     * du.daysInMonth(1, 2026); // → 31
+     * ```
+     */
+    daysInMonth(month: number, year?: number): number;
+    /**
+     * Returns the ISO 8601 week number (1–53) for a given date.
+     *
+     * ISO 8601 defines Week 1 as the week containing the year's first Thursday.
+     * Weeks run Monday–Sunday. A date in early January may belong to the
+     * final week of the previous year (e.g., January 1, 2016 → Week 53 of 2015).
+     *
+     * @param date - The reference date (default: current time).
+     * @returns The ISO week number.
+     *
+     * @example
+     * ```ts
+     * du.weekNumber(new Date("2026-01-01")); // → 1
+     * du.weekNumber(new Date("2016-01-03")); // → 53 (belongs to 2015)
+     * ```
+     */
+    weekNumber(date?: Date | number | string): number;
+    /**
+     * Returns the day of the year (1–366) for a given date.
+     *
+     * @param date - The reference date (default: current time).
+     * @returns An integer from 1 to 366.
+     *
+     * @example
+     * ```ts
+     * du.dayOfYear(new Date("2026-02-01")); // → 32
+     * du.dayOfYear(new Date("2026-12-31")); // → 365
+     * ```
+     */
+    dayOfYear(date?: Date | number | string): number;
+    /**
+     * Returns the ISO 8601 quarter (1–4) in which the given date falls.
+     *
+     * @param date - The reference date (default: current time).
+     * @returns A quarter number: `1`, `2`, `3`, or `4`.
+     *
+     * @example
+     * ```ts
+     * du.quarter(new Date("2026-04-15")); // → 2  (Apr–Jun)
+     * du.quarter(new Date("2026-11-01")); // → 4  (Oct–Dec)
+     * ```
+     */
+    quarter(date?: Date | number | string): 1 | 2 | 3 | 4;
+    /**
+     * Returns `true` if the given date falls on a weekend (Saturday or Sunday).
+     *
+     * The check uses **local time**.
+     *
+     * @param date - The date to check (default: current time).
+     * @returns `true` if the date is a Saturday or Sunday.
+     *
+     * @example
+     * ```ts
+     * du.isWeekend(new Date("2026-04-18")); // → true  (Saturday)
+     * du.isWeekend(new Date("2026-04-15")); // → false (Wednesday)
+     * ```
+     */
+    isWeekend(date?: Date | number | string): boolean;
+    /**
+     * Returns `true` if the given date falls on a weekday (Monday–Friday).
+     *
+     * @param date - The date to check (default: current time).
+     * @returns `true` if the date is Monday through Friday.
+     *
+     * @example
+     * ```ts
+     * du.isWeekday(new Date("2026-04-15")); // → true
+     * du.isWeekday(new Date("2026-04-19")); // → false (Sunday)
+     * ```
+     */
+    isWeekday(date?: Date | number | string): boolean;
+    /**
+     * Returns `true` if two dates fall on the same calendar day (in local time).
+     *
+     * Only the year, month, and date components are compared; time is ignored.
+     *
+     * @param dateA - The first date.
+     * @param dateB - The second date.
+     * @returns `true` if both dates share the same year, month, and day.
+     *
+     * @example
+     * ```ts
+     * du.isSameDay("2026-04-15T08:00:00", "2026-04-15T22:00:00"); // → true
+     * du.isSameDay("2026-04-15", "2026-04-16");                   // → false
+     * ```
+     */
+    isSameDay(dateA: Date | number | string, dateB: Date | number | string): boolean;
+    /**
+     * Returns `true` if the given date is today (in local time).
+     *
+     * @param date - The date to test.
+     * @returns `true` if `date` falls on the current calendar day.
+     *
+     * @example
+     * ```ts
+     * du.isToday(new Date()); // → true
+     * du.isToday("2020-01-01"); // → false
+     * ```
+     */
+    isToday(date: Date | number | string): boolean;
+    /**
+     * Returns `true` if the given date is in the past (before the current instant).
+     *
+     * @param date - The date to check.
+     * @returns `true` if `date` is strictly before `Date.now()`.
+     *
+     * @example
+     * ```ts
+     * du.isPast("2020-01-01"); // → true
+     * du.isPast(Date.now() + 1000); // → false
+     * ```
+     */
+    isPast(date: Date | number | string): boolean;
+    /**
+     * Returns `true` if the given date is in the future (after the current instant).
+     *
+     * @param date - The date to check.
+     * @returns `true` if `date` is strictly after `Date.now()`.
+     *
+     * @example
+     * ```ts
+     * du.isFuture(Date.now() + 5000); // → true
+     * du.isFuture("2020-01-01");       // → false
+     * ```
+     */
+    isFuture(date: Date | number | string): boolean;
+    /**
+     * Clamps a date to a `[min, max]` range.
+     *
+     * If `date` is before `min`, `min` is returned.
+     * If `date` is after `max`, `max` is returned.
+     * Otherwise, `date` is returned unchanged (as a new `Date`).
+     *
+     * @param date - The date to clamp.
+     * @param min  - The lower bound.
+     * @param max  - The upper bound.
+     * @returns A new `Date` clamped within `[min, max]`.
+     *
+     * @example
+     * ```ts
+     * du.clamp("2025-01-01", "2026-01-01", "2026-12-31");
+     * // → Date("2026-01-01")  — clamped to min
+     *
+     * du.clamp("2026-06-15", "2026-01-01", "2026-12-31");
+     * // → Date("2026-06-15")  — within range, unchanged
+     * ```
+     */
+    clamp(date: Date | number | string, min: Date | number | string, max: Date | number | string): Date;
+    /**
+     * Generates an array of `Date` objects representing each day in the range
+     * `[start, end]`, inclusive.
+     *
+     * The range is capped at **3 650 days** (~10 years) to prevent accidental
+     * allocation of enormous arrays.
+     *
+     * @param start - The first day of the range.
+     * @param end   - The last day of the range.
+     * @returns An ordered array of `Date` objects, one per day.
+     * @throws {RangeError} If the range exceeds 3 650 days.
+     *
+     * @example
+     * ```ts
+     * du.dateRange("2026-04-13", "2026-04-15");
+     * // → [Date("2026-04-13"), Date("2026-04-14"), Date("2026-04-15")]
+     * ```
+     */
+    dateRange(start: Date | number | string, end: Date | number | string): Date[];
+    /**
+     * Returns `true` if the given value can be successfully interpreted
+     * as a valid, finite date.
+     *
+     * Accepts `Date`, `number`, and `string` inputs. A `Date` whose
+     * `getTime()` returns `NaN` is considered invalid.
+     *
+     * @param value - The value to validate.
+     * @returns `true` if the value represents a valid date.
+     *
+     * @example
+     * ```ts
+     * du.isValid(new Date());           // → true
+     * du.isValid("2026-04-15");         // → true
+     * du.isValid("not-a-date");         // → false
+     * du.isValid(new Date("invalid"));  // → false
+     * du.isValid(NaN);                  // → false
+     * ```
+     */
+    isValid(value: unknown): boolean;
+    /**
+     * Parses a date string using an ordered list of format patterns and returns
+     * the first successfully parsed `Date`, or `null` if none match.
+     *
+     * Supported format tokens:
+     * - `YYYY` — 4-digit year
+     * - `MM`   — 2-digit month (01–12)
+     * - `DD`   — 2-digit day (01–31)
+     * - `HH`   — 2-digit hours (00–23)
+     * - `mm`   — 2-digit minutes (00–59)
+     * - `ss`   — 2-digit seconds (00–59)
+     *
+     * @param value   - The date string to parse.
+     * @param formats - An ordered list of format strings to attempt.
+     * @returns The first successfully parsed `Date`, or `null`.
+     *
+     * @example
+     * ```ts
+     * du.parse("15/04/2026", ["DD/MM/YYYY"]);
+     * // → Date("2026-04-15")
+     *
+     * du.parse("2026-04-15 08:30:00", ["YYYY-MM-DD HH:mm:ss"]);
+     * // → Date("2026-04-15T08:30:00")
+     *
+     * du.parse("bad-input", ["YYYY-MM-DD"]);
+     * // → null
+     * ```
+     */
+    parse(value: string, formats: string[]): Date | null;
+    /**
+     * Returns the UTC offset of the local environment in minutes.
+     *
+     * Positive values indicate zones **behind** UTC (e.g., UTC-5 → `300`),
+     * mirroring the behaviour of `Date.prototype.getTimezoneOffset()`.
+     *
+     * @returns The UTC offset in minutes.
+     *
+     * @example
+     * ```ts
+     * du.timezoneOffset(); // → -120 for UTC+2, 300 for UTC-5
+     * ```
+     */
+    timezoneOffset(): number;
+    /**
+     * Formats a date in a specific IANA timezone using `Intl.DateTimeFormat`.
+     *
+     * Requires the runtime to support the `timeZone` option (all modern
+     * environments do).
+     *
+     * @param date     - The date to format.
+     * @param timeZone - A valid IANA timezone identifier (e.g., `"America/New_York"`).
+     * @param locale   - BCP 47 locale tag (default: `"en-US"`).
+     * @param options  - Additional `Intl.DateTimeFormatOptions`.
+     * @returns A localized date string in the given timezone.
+     *
+     * @example
+     * ```ts
+     * du.formatInTimezone(Date.now(), "Asia/Tokyo", "ja-JP", { dateStyle: "full", timeStyle: "short" });
+     * // → "2026年4月15日水曜日 19:00"
+     * ```
+     */
+    formatInTimezone(date: Date | number | string, timeZone: string, locale?: string, options?: Omit<Intl.DateTimeFormatOptions, "timeZone">): string;
+}
+
+/**
+ * **ObjectUtils — XyPriss Object Utilities**
+ */
+declare class ObjectUtils {
+    /**
+     * **Deep Clone an Object**
+     *
+     * Creates a deep copy of `obj` using `XStringify` for serialization,
+     * which handles cyclic references and offers better performance
+     * than the native `JSON.stringify` in complex object graphs.
+     *
+     * @param obj - The object to clone. Must be serializable.
+     * @returns A completely independent deep copy of the input object.
+     *
+     * @example
+     * ```ts
+     * const original = { a: 1, nested: { b: 2 } };
+     * const clone = utils.deepClone(original);
+     * clone.nested.b = 99;
+     * // original.nested.b is still 2
+     * ```
+     */
+    deepClone<T>(obj: T): T;
+    /**
+     * **Pick Specific Keys from an Object**
+     *
+     * Returns a new object containing only the key-value pairs whose
+     * keys appear in the `keys` array. Non-existent keys are silently ignored.
+     *
+     * @param obj  - The source object.
+     * @param keys - Array of keys to extract.
+     * @returns A new object with only the specified keys.
+     *
+     * @example
+     * ```ts
+     * utils.pick({ a: 1, b: 2, c: 3 }, ["a", "c"]);   // { a: 1, c: 3 }
+     * ```
+     */
+    pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+    /**
+     * **Omit Specific Keys from an Object**
+     *
+     * Returns a new object that is a shallow copy of `obj` with the
+     * specified keys removed.
+     *
+     * @param obj  - The source object.
+     * @param keys - Array of keys to exclude.
+     * @returns A new object without the specified keys.
+     *
+     * @example
+     * ```ts
+     * utils.omit({ a: 1, b: 2, c: 3 }, ["b"]);   // { a: 1, c: 3 }
+     * ```
+     */
+    omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+    /**
+     * **Check if an Object is Empty**
+     *
+     * Returns `true` if the object has no own enumerable keys.
+     * Works correctly with objects created via `Object.create(null)`.
+     *
+     * @param obj - The object to inspect.
+     * @returns `true` if the object has no own keys, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * utils.isEmpty({});             // true
+     * utils.isEmpty({ a: 1 });       // false
+     * utils.isEmpty(Object.create(null)); // true
+     * ```
+     */
+    isEmpty(obj: object): boolean;
+    /**
+     * **flattenObject**
+     *
+     * Collapses nested objects into flat dot-notation (or custom) keys.
+     * Useful for configuration mapping or CSV generation.
+     *
+     * @param obj - The object to flatten.
+     * @param separator - Optional path separator (default: `"."`).
+     * @returns A shallow object with path-based keys.
+     */
+    flattenObject(obj: Record<string, unknown>, separator?: string): Record<string, unknown>;
+    /**
+     * **parse**
+     *
+     * Safely parses a JSON string. If the parsing fails, the provided fallback
+     * value is returned instead of throwing an exception.
+     *
+     * @param json The JSON string to parse.
+     * @param fallback The fallback value to return on failure.
+     * @returns The parsed object or the fallback value.
+     */
+    parse<T>(json: string, fallback?: T | null): T | null;
+}
+
+/**
+ * **ArrayUtils — XyPriss Array Utilities**
+ */
+declare class ArrayUtils {
+    /**
+     * **Chunk an Array**
+     *
+     * Splits an array into sub-arrays of a fixed maximum size.
+     */
+    chunk<T>(arr: T[], size: number): T[][];
+    /**
+     * **Unique Elements**
+     *
+     * Returns a new array with all duplicates removed.
+     */
+    unique<T>(arr: T[]): T[];
+    /**
+     * **Shuffle Elements**
+     *
+     * Randomly reorders an array using the Fisher-Yates algorithm.
+     */
+    shuffle<T>(arr: T[]): T[];
+    /**
+     * **Group Elements**
+     *
+     * Groups array elements into an object based on a key-mapping function.
+     */
+    groupBy<T>(arr: T[], keyFn: (item: T) => string): Record<string, T[]>;
+    /**
+     * **Pick Random Sample**
+     */
+    sample<T>(arr: T[]): T | undefined;
+    /**
+     * **Flatten One Level**
+     */
+    flatten<T>(arr: T[][]): T[];
+}
+
+/**
+ * # AsyncUtils — XyPriss Async Control Flow
+ *
+ * A comprehensive library of asynchronous control flow primitives for TypeScript.
+ * Each method is designed to be safe, performant, and composable.
+ *
+ * @example
+ * ```ts
+ * const async = new AsyncUtils();
+ *
+ * // Auto-retry + debounce + performance measurement in a few lines
+ * const save = async.debounce(async (data: string) => {
+ *   const { result, durationMs } = await async.measure(() =>
+ *     async.retry(() => api.save(data), { maxAttempts: 3, delay: 1000 })
+ *   );
+ *   console.log(`Saved in ${durationMs.toFixed(1)}ms`, result);
+ * }, 500);
+ * ```
+ *
+ * @module AsyncUtils
+ */
+/** Advanced options for {@link AsyncUtils.retry}. */
+interface RetryOptions {
+    /** Maximum number of attempts. @default 3 */
+    maxAttempts?: number;
+    /** Initial delay between attempts (ms). @default 500 */
+    delay?: number;
+    /** Multiplicative factor for the delay at each attempt (exponential backoff). @default 1 */
+    backoffFactor?: number;
+    /** Maximum delay regardless of backoff (ms). @default Infinity */
+    maxDelay?: number;
+    /** Abort signal allowing to interrupt attempts at any time. */
+    signal?: AbortSignal;
+    /**
+     * Optional predicate — returns `true` if the error is "retryable".
+     * Useful for not retrying a 400 or 401 error that won't change.
+     *
+     * @example
+     * ```ts
+     * retryIf: (err) => err instanceof NetworkError
+     * ```
+     */
+    retryIf?: (error: unknown, attempt: number) => boolean;
+    /**
+     * Callback called at each failed attempt (ideal for telemetry).
+     *
+     * @example
+     * ```ts
+     * onRetry: (err, attempt) => logger.warn(`Attempt ${attempt} failed`, err)
+     * ```
+     */
+    onRetry?: (error: unknown, attempt: number) => void;
+}
+/** Options for {@link AsyncUtils.timeout}. */
+interface TimeoutOptions {
+    /** Message of the error thrown in case of timeout. @default "Operation timed out" */
+    message?: string;
+    /** External signal allowing to cancel the promise before timeout. */
+    signal?: AbortSignal;
+}
+/** Result of an execution via {@link AsyncUtils.measure}. */
+interface MeasureResult<T> {
+    result: T;
+    /** Operation duration in milliseconds (µs precision via `performance.now()`). */
+    durationMs: number;
+}
+/** Result of an execution via {@link AsyncUtils.attempt}. */
+type AttemptResult<T> = {
+    ok: true;
+    value: T;
+    error?: never;
+} | {
+    ok: false;
+    error: unknown;
+    value?: never;
+};
+declare class AsyncUtils {
+    /**
+     * ## Asynchronous Pause
+     *
+     * Suspends execution for a given duration.
+     * Compatible with `AbortSignal`: sleep will be interrupted cleanly
+     * if the signal is triggered (the promise **resolves** without error in this case).
+     *
+     * @param ms    - Pause duration in milliseconds.
+     * @param signal - Optional cancellation signal (AbortController).
+     * @returns A promise that resolves after `ms` ms (or earlier if signal triggered).
+     *
+     * @example Simple pause
+     * ```ts
+     * await utils.sleep(2000); // waits 2 seconds
+     * ```
+     *
+     * @example Cancellation via AbortController
+     * ```ts
+     * const controller = new AbortController();
+     * setTimeout(() => controller.abort(), 500);
+     *
+     * await utils.sleep(5000, controller.signal); // resolves after ~500ms
+     * ```
+     */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * ## Asynchronous Pause (alias of `sleep`)
+     *
+     * @alias sleep
+     * @see {@link sleep}
+     */
+    wait(ms: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * ## Retry with Exponential Backoff
+     *
+     * Retries an asynchronous operation up to `maxAttempts` times.
+     * Supports exponential backoff, maximum delay, filter predicate,
+     * and `AbortSignal` to interrupt the retry cycle.
+     *
+     * Delay formula: `min(delay × backoffFactor^attempt, maxDelay)`.
+     *
+     * @param fn      - The asynchronous function to execute.
+     * @param options - Retry options (see {@link RetryOptions}).
+     * @returns Resolved value of `fn` on the first successful attempt.
+     * @throws Last error if all attempts fail.
+     *
+     * @example Basic retry (3 attempts, 500ms between each)
+     * ```ts
+     * const data = await utils.retry(() => fetch("/api/data").then(r => r.json()));
+     * ```
+     *
+     * @example Exponential backoff: 200ms → 400ms → 800ms → max 1000ms
+     * ```ts
+     * const result = await utils.retry(() => unstableApi(), {
+     *   maxAttempts: 4,
+     *   delay: 200,
+     *   backoffFactor: 2,
+     *   maxDelay: 1000,
+     *   onRetry: (err, n) => console.warn(`Retry #${n}`, err),
+     * });
+     * ```
+     *
+     * @example Do not retry auth errors
+     * ```ts
+     * await utils.retry(() => api.call(), {
+     *   retryIf: (err) => !(err instanceof AuthError),
+     * });
+     * ```
+     */
+    retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+    /**
+     * ## Promise Timeout
+     *
+     * Wraps a promise with a maximum duration. If the promise does not
+     * resolve within the given time, an `Error` is thrown.
+     *
+     * Automatically handles internal timer cleanup to prevent memory leaks.
+     *
+     * @param fn      - Function returning the promise to monitor.
+     * @param ms      - Maximum delay in milliseconds before rejecting.
+     * @param options - Additional options (error message, cancellation signal).
+     * @returns Resolved value if the promise succeeds within delay.
+     * @throws `Error` with `options.message` if timeout is reached.
+     *
+     * @example
+     * ```ts
+     * const result = await utils.timeout(
+     *   () => fetch("/slow-api").then(r => r.json()),
+     *   3000,
+     *   { message: "API took too long to respond" }
+     * );
+     * ```
+     */
+    timeout<T>(fn: () => Promise<T>, ms: number, options?: TimeoutOptions): Promise<T>;
+    /**
+     * ## Safe Execution (Never Throws)
+     *
+     * Executes an asynchronous function and always captures the result as a
+     * discriminated object `{ ok, value }` or `{ ok, error }`.
+     * **Never throws exceptions**, simplifying control flow.
+     *
+     * Ideal for API calls, parsing, or any operation where failure is a normal outcome
+     * and must be handled explicitly.
+     *
+     * @param fn - Asynchronous function to execute safely.
+     * @returns Discriminated object indicating success or failure.
+     *
+     * @example Without `attempt` (verbose)
+     * ```ts
+     * let user;
+     * try { user = await fetchUser(id); }
+     * catch (e) { console.error(e); return; }
+     * ```
+     *
+     * @example With `attempt` (concise)
+     * ```ts
+     * const { ok, value: user, error } = await utils.attempt(() => fetchUser(id));
+     * if (!ok) { console.error(error); return; }
+     * // `user` is guaranteed defined here
+     * ```
+     *
+     * @example Combined with `retry`
+     * ```ts
+     * const { ok, value } = await utils.attempt(() =>
+     *   utils.retry(() => api.getData(), { maxAttempts: 5 })
+     * );
+     * ```
+     */
+    attempt<T>(fn: () => Promise<T>): Promise<AttemptResult<T>>;
+    /**
+     * ## Debounce
+     *
+     * Delays execution of `fn` until `wait` ms have elapsed since the last call.
+     * If a new call arrives before the delay ends, the previous one is cancelled
+     * and the timer restarts from zero.
+     *
+     * Typical use cases: search fields (prevents one request per keystroke),
+     * resize listeners, auto-save.
+     *
+     * The returned version exposes a `.cancel()` method to manually cancel the
+     * pending timer, and `.flush()` to trigger execution immediately.
+     *
+     * @param fn   - Function to debounce.
+     * @param wait - Quiet period required before execution (ms). @default 300
+     * @returns Debounced version of `fn` with `.cancel()` and `.flush()` methods.
+     *
+     * @example Real-time search
+     * ```ts
+     * const search = utils.debounce((query: string) => {
+     *   fetch(`/api/search?q=${query}`);
+     * }, 400);
+     *
+     * input.addEventListener("input", (e) => search(e.target.value));
+     * ```
+     *
+     * @example Explicit cancellation (e.g., on component unmount)
+     * ```ts
+     * const save = utils.debounce(saveToServer, 1000);
+     * onUnmount(() => save.cancel());
+     * ```
+     *
+     * @example Immediate flush (e.g., before navigation)
+     * ```ts
+     * window.addEventListener("beforeunload", () => save.flush());
+     * ```
      */
-    get(key: string): string | undefined;
-    get(key: string, defaultValue: string): string;
+    debounce<T extends (...args: any[]) => any>(fn: T, wait?: number): ((...args: Parameters<T>) => void) & {
+        cancel: () => void;
+        flush: (...args: Parameters<T>) => void;
+    };
     /**
-     * Reads a required variable from the secure internal store and throws if
-     * it cannot be resolved.
+     * ## Throttle
      *
-     * Use this method for every variable that is mandatory for application
-     * correctness. It surfaces configuration errors at startup rather than
-     * silently producing `undefined` at the point of use.
+     * Guarantees that `fn` executes no more than once per `limit` ms window,
+     * regardless of how many calls are received.
      *
-     * @param key     - Variable name to look up.
-     * @param options - Optional validation settings.
-     * @returns The stored value, guaranteed non-undefined.
-     * @throws {EnvAccessError} When the variable is missing or empty.
-     * @throws {EnvStoreError}  When the store has not been initialised.
+     * Unlike debounce, throttle executes `fn` **immediately** on the first call,
+     * then ignores subsequent calls until the window ends.
      *
-     * @example
-     * // Fail fast at boot if a critical variable is absent
-     * const databaseUrl = __sys__.__env__.getStrict("DATABASE_URL");
-     * const jwtSecret   = __sys__.__env__.getStrict("JWT_SECRET", { rejectEmpty: true });
-     * const smtpHost    = __sys__.__env__.getStrict("SMTP_HOST");
+     * Typical use cases: scroll handlers, mousemove, drag-and-drop, gamepads.
      *
-     * // Collect all required variables once at module initialisation
-     * const config = {
-     *   db:   __sys__.__env__.getStrict("DATABASE_URL"),
-     *   jwt:  __sys__.__env__.getStrict("JWT_SECRET", { rejectEmpty: true }),
-     *   smtp: __sys__.__env__.getStrict("SMTP_HOST"),
-     * };
+     * The returned version exposes a `.cancel()` method to manually reset the
+     * throttle window.
+     *
+     * @param fn    - Function to throttle.
+     * @param limit - Minimum duration between two executions (ms). @default 300
+     * @returns Throttled version of `fn` with `.cancel()` method.
+     *
+     * @example Scroll handler limited to 60fps (~16ms)
+     * ```ts
+     * const onScroll = utils.throttle(() => {
+     *   updateScrollIndicator();
+     * }, 16);
+     *
+     * window.addEventListener("scroll", onScroll);
+     * ```
      */
-    getStrict(key: string, options?: EnvGetStrictOptions): string;
+    throttle<T extends (...args: any[]) => any>(fn: T, limit?: number): ((...args: Parameters<T>) => void) & {
+        cancel: () => void;
+    };
     /**
-     * Returns `true` when the given key is present in the secure internal
-     * store, regardless of its value (including empty strings).
+     * ## High-Precision Execution Time Measurement
      *
-     * @param key - Variable name to test.
-     * @throws {EnvStoreError} When the store has not been initialised.
+     * Wraps a synchronous or asynchronous function and returns its result
+     * along with its execution time in milliseconds (microsecond precision via `performance.now()`).
      *
-     * @example
-     * if (__sys__.__env__.has("SENTRY_DSN")) {
-     *   Sentry.init({ dsn: __sys__.__env__.get("SENTRY_DSN") });
-     * }
+     * @param fn - Function to measure (sync or async).
+     * @returns An object `{ result, durationMs }`.
      *
-     * const betaEnabled = __sys__.__env__.has("ENABLE_BETA_UI");
+     * @example Measuring an API call
+     * ```ts
+     * const { result, durationMs } = await utils.measure(() =>
+     *   fetch("/api/heavy").then(r => r.json())
+     * );
+     * console.log(`Response received in ${durationMs.toFixed(2)}ms:`, result);
+     * ```
      */
-    has(key: string): boolean;
+    measure<T>(fn: () => T | Promise<T>): Promise<MeasureResult<T>>;
     /**
-     * Returns a frozen, point-in-time snapshot of stored variables.
+     * ## High-Precision Drift-Corrected Interval
      *
-     * The object is frozen at the moment of the call; subsequent `set` or
-     * `delete` calls do not affect it.
+     * Repeatedly executes `fn` with automatic compensation for accumulated
+     * clock drift. Unlike `setInterval`, this implementation adjusts each delay
+     * based on actual elapsed time.
      *
-     * Providing `options.keys` is strongly recommended in production code.
-     * Returning the full store risks inadvertently capturing secrets in log
-     * statements or JSON serialisations.
+     * The current tick count is passed as a parameter to `fn`, enabling
+     * animations or progression counting.
      *
-     * @param options - Optional filter configuration.
-     * @returns A frozen {@link EnvSnapshot}.
-     * @throws {EnvStoreError} When the store has not been initialised.
+     * Execution stops cleanly when `signal` is aborted.
      *
-     * @example
-     * // Filtered snapshot — preferred in all production code paths
-     * const dbConfig = __sys__.__env__.all({
-     *   keys: ["DATABASE_URL", "DATABASE_POOL_SIZE", "DATABASE_TIMEOUT_MS"],
-     * });
+     * @param fn     - Callback called at each tick, receiving the tick index (0-indexed).
+     * @param ms     - Target interval in milliseconds.
+     * @param signal - `AbortSignal` to stop the loop.
+     * @returns A promise that resolves when the signal is aborted.
      *
-     * // Full snapshot — use only for diagnostics / startup validation
-     * const full = __sys__.__env__.all();
-     * logger.debug("Env snapshot", { count: Object.keys(full).length });
-     */
-    all(options?: EnvAllOptions): EnvSnapshot;
-    /**
-     * Returns `true` when the execution mode is `"production"`.
+     * @example Counter update every second
+     * ```ts
+     * const controller = new AbortController();
      *
-     * @example
-     * const logger = createLogger({
-     *   level: __sys__.__env__.isProduction() ? "error" : "debug",
-     * });
-     */
-    isProduction(): boolean;
-    /**
-     * Returns `true` when the execution mode is `"development"`.
+     * utils.repeat((tick) => {
+     *   console.log(`Tick ${tick} — ${new Date().toLocaleTimeString()}`);
+     * }, 1000, controller.signal);
      *
-     * @example
-     * if (__sys__.__env__.isDevelopment()) {
-     *   app.use(requestLogger({ colorize: true }));
-     * }
+     * // Stop after 5 seconds
+     * setTimeout(() => controller.abort(), 5000);
+     * ```
      */
-    isDevelopment(): boolean;
+    repeat(fn: (tick: number) => void | Promise<void>, ms: number, signal?: AbortSignal): Promise<void>;
     /**
-     * Returns `true` when the execution mode is `"staging"`.
+     * ## Parallel Execution with Limited Concurrency
      *
-     * @example
-     * if (__sys__.__env__.isStaging()) {
-     *   payment.useSandbox();
-     * }
+     * Processes an array of values in parallel via `fn`, limiting the number
+     * of active promises simultaneously to `concurrency`. Results are returned
+     * in the same order as inputs.
+     *
+     * Ideal for scenarios where you want to avoid saturating a server or database
+     * with thousands of simultaneous requests.
+     *
+     * @param items       - Array of items to process.
+     * @param fn          - Asynchronous function applied to each element.
+     * @param concurrency - Maximum number of active parallel promises. @default 5
+     * @returns Array of results in the same order as `items`.
+     *
+     * @example Batch file import (max 3 at a time)
+     * ```ts
+     * const files = ["f1.csv", "f2.csv", "f3.csv", "f4.csv"];
+     * const results = await utils.pool(files, f => importFile(f), 3);
+     * ```
      */
-    isStaging(): boolean;
+    pool<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, concurrency?: number): Promise<R[]>;
     /**
-     * Returns `true` when the execution mode is `"test"`.
+     * ## Race with Built-in Timeout
      *
-     * @example
-     * const dbUrl = __sys__.__env__.isTest()
-     *   ? __sys__.__env__.getStrict("TEST_DATABASE_URL")
-     *   : __sys__.__env__.getStrict("DATABASE_URL");
+     * Launches multiple promises in parallel and returns the first one to resolve.
+     * If none resolve within `timeoutMs`, an error is thrown.
+     *
+     * Similar to `Promise.race`, but with an integrated temporal safety net.
+     *
+     * @param fns       - Array of functions returning promises.
+     * @param timeoutMs - Maximum delay in milliseconds. @default Infinity
+     * @returns Value of the first resolved promise.
+     * @throws `Error("Race timed out")` if timeout is reached.
      */
-    isTest(): boolean;
+    race<T>(fns: Array<() => Promise<T>>, timeoutMs?: number): Promise<T>;
     /**
-     * Returns `true` when the execution mode exactly matches `envName`
-     * (case-sensitive).
+     * ## Async Memoization with TTL
      *
-     * @param envName - Mode name to compare against.
+     * Returns a memoized version of `fn`: results are cached for `ttlMs` milliseconds.
+     * After this delay, the next call triggers a fresh execution.
      *
-     * @example
-     * if (__sys__.__env__.is("canary")) {
-     *   featureFlags.enableAll();
-     * }
+     * If multiple identical calls arrive simultaneously (while the promise is pending),
+     * they share the same promise — avoiding "thundering herd" on cold caches.
+     *
+     * @param fn    - Asynchronous function to memoize.
+     * @param ttlMs - Cache entry TTL (ms). `0` = no expiration.
+     * @param keyFn - Serialization function for arguments into cache keys.
+     *                @default `JSON.stringify`
+     * @returns Memoized version of `fn` with `.clear()` method.
      */
-    is(envName: string): boolean;
+    memoize<TArgs extends any[], TResult>(fn: (...args: TArgs) => Promise<TResult>, ttlMs?: number, keyFn?: (...args: TArgs) => string): ((...args: TArgs) => Promise<TResult>) & {
+        clear: () => void;
+    };
     /**
-     * Retrieves the OS-level username of the current process owner by invoking
-     * the XHSC native Go binary.
+     * ## Sequential Queue
      *
-     * This method is synchronous and blocks until the native call completes.
-     * Do not call it in request hot paths. Returns `""` on failure so callers
-     * can safely use the result without null checks.
+     * Guarantees that tasks are executed **one by one, in the order they were added**.
+     * Tasks submitted while another is pending are queued and executed sequentially.
      *
-     * @returns The current OS username, or `""` on failure.
+     * Unlike `pool(items, fn, 1)`, `queue` allows adding tasks dynamically over time.
      *
-     * @example
-     * const actor = __sys__.__env__.user() || "<unknown>";
-     * auditLog.write({ actor, action: "deploy" });
+     * @returns An object `{ add, size }`:
+     *   - `add(fn)` — Enqueues a task and returns a promise for its result.
+     *   - `size` — Getter for the current number of pending tasks.
+     *
+     * @example Critical Database Mutation
+     * ```ts
+     * const db = utils.queue();
+     *
+     * async function transfer(from: string, to: string, amount: number) {
+     *   return db.add(async () => {
+     *     const balance = await getBalance(from);
+     *     if (balance < amount) throw new Error("Insufficient funds");
+     *     await debit(from, amount);
+     *     await credit(to, amount);
+     *   });
+     * }
+     * ```
      */
-    user(): string;
+    queue(): {
+        add: <T>(fn: () => Promise<T>) => Promise<T>;
+        readonly size: number;
+    };
     /**
-     * Returns the internal store, throwing {@link EnvStoreError} if it has not
-     * yet been initialised.
+     * ## Once — Guaranteed Single Execution
      *
-     * SECURITY: This is the single point of store access. Every read and write
-     * method must go through here — never access `globalThis[XY_ENV_STORE_KEY]`
-     * directly outside this method.
+     * Returns a version of `fn` that executes only **once**, regardless of how
+     * many calls are made. Subsequent calls receive the cached promise or value
+     * without re-executing `fn`.
      *
-     * Eliminating the `?? process.env` fallback is intentional. A silent
-     * fallback to `process.env` during the bootstrap race window would bypass
-     * the Shield and leak values without any warning. A thrown error is
-     * immediately visible during development and integration testing.
+     * Particularly useful for expensive initializations (DB connections, config loading).
      *
-     * @internal
-     * @throws {EnvStoreError}
+     * @param fn - The function to execute exactly once.
+     * @returns A function that always returns the same resolved promise.
      */
-    private requireStoreMap;
-    private getStoreForCaller;
+    once<TArgs extends any[], TResult>(fn: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;
     /**
-     * Asserts that `key` is a valid environment variable name.
+     * ## Conditional Polling
      *
-     * @internal
-     * @throws {EnvKeyError}
+     * Repeatedly polls `fn` until `predicate` returns `true` or a signal is aborted.
+     *
+     * @param fn        - Asynchronous function returning value to test.
+     * @param predicate - Success condition for the returned value.
+     * @param interval  - Delay between attempts (ms). @default 1000
+     * @param signal    - `AbortSignal` to stop polling.
+     * @returns The value for which `predicate` returned `true`.
+     * @throws `DOMException("AbortError")` if signal is aborted before success.
      */
-    private validateKey;
+    poll<T>(fn: () => Promise<T>, predicate: (value: T) => boolean, interval?: number, signal?: AbortSignal): Promise<T>;
+}
+
+/**
+ * **ValidationUtils — XyPriss Validation Utilities**
+ */
+declare class ValidationUtils {
     /**
-     * Asserts that `value` does not contain characters that can corrupt
-     * downstream parsers, log sinks, or HTTP serialisers.
+     * **email**
      *
-     * Rejected characters:
-     * - CR (`\r`) and LF (`\n`) — break line-oriented `.env` parsers and
-     *   enable log injection attacks.
-     * - NUL (`\0`) — truncates strings in C-based runtimes and can bypass
-     *   suffix-based extension checks in some file path handling code.
+     * Performs semantic validation on an email address string.
      *
-     * @internal
-     * @throws {EnvKeyError}
+     * @param email The email string to validate.
+     * @returns `true` if valid, `false` otherwise.
      */
-    private validateValue;
+    email(email: string): boolean;
     /**
-     * **Environment Security Shield**
+     * **url**
      *
-     * Replaces the `process.env` object with a hardened Proxy that enforces
-     * the following policies on every property access:
-     *
-     * **Read trap**
-     * - Whitelisted keys (see {@link EnvApi.whitelistedFields}) and keys
-     *   matching the prefixes `XY_`, `XYPRISS_`, `ENC_`, `DOTENV_`, or `__`
-     *   pass through to the real value.
-     * - All other reads return `undefined`. A one-time per-key warning is
-     *   written to `process.stderr` (suppressed when
-     *   `XYPRISS_ENV_SHIELD=silent`).
+     * Validates a URL string using the `strulink` RFC-compliant URI parser.
      *
-     * **`ownKeys` and `has` traps**
-     * - Restrict the apparent key set to the whitelist. This prevents
-     *   third-party code from enumerating the real store through
-     *   `Object.keys(process.env)`, `JSON.stringify(process.env)`, or spread
-     *   operators — all of which bypass the `get` trap.
+     * @param url The URL string to validate.
+     * @returns `true` if valid, `false` otherwise.
+     */
+    url(url: string | URL): boolean;
+    /**
+     * **nullish**
      *
-     * The descriptor is applied with `writable: false` to prevent replacement
-     * by application code, and `configurable: true` to allow test teardown.
+     * A type guard that determines if a value is either `null` or `undefined`.
      *
-     * @internal
+     * @param value The value to check.
+     * @returns `true` if null or undefined.
      */
+    nullish(value: unknown): value is null | undefined;
+}
+
+/**
+ * **IdUtils — Identity Primitives**
+ */
+declare class IdUtils {
     /**
-     * **Environment Security Shield**
-     *
-     * Replaces the `process.env` object with a hardened Proxy that enforces
-     * the following policies on every property access:
+     * **uuid**
      *
-     * **Read trap**
-     * - Whitelisted keys (see {@link EnvApi.whitelistedFields}) and keys
-     *   matching the prefixes `XY_`, `XYPRISS_`, `ENC_`, `DOTENV_`, or `__`
-     *   pass through to the real value.
-     * - All other reads return `undefined`. A one-time per-key warning is
-     *   written to `process.stderr` (suppressed when
-     *   `XYPRISS_ENV_SHIELD=silent`).
+     * Generates a RFC-compliant UUID v4 using the `nehoid` engine.
      *
-     * **`ownKeys` and `has` traps**
-     * - Restrict the apparent key set to the whitelist. This prevents
-     *   third-party code from enumerating the real store through
-     *   `Object.keys(process.env)`, `JSON.stringify(process.env)`, or spread
-     *   operators — all of which bypass the `get` trap.
+     * @returns A random UUID string.
+     */
+    uuid(): string;
+}
+
+/**
+ * **FunctionUtils — Functional Programming Helpers**
+ */
+declare class FunctionUtils {
+    /**
+     * **memo**
      *
-     * The descriptor is applied with `writable: false` to prevent replacement
-     * by application code, and `configurable: true` to allow test teardown.
+     * Returns a memoized version of a function that caches its results based on input parameters.
      *
-     * @internal
+     * @param fn The function to memoize.
+     * @returns The memoized function.
      */
-    private applyShield;
-    private isCallerProjectCode;
+    memo<T extends (...args: any[]) => any>(fn: T): T;
+}
+
+/**
+ * **UtilsApi — XyPriss System Utility Module**
+ *
+ * A comprehensive, high-performance utility class for application development.
+ * Utilities are grouped into specialized categories for better modularity.
+ *
+ * Exposed via `__sys__.utils`.
+ *
+ * @example
+ * ```ts
+ * __sys__.utils.num.formatBytes(1048576);      // "1 MB"
+ * __sys__.utils.is.email("test@example.com");  // true
+ * __sys__.utils.id.uuid();                     // "550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
+declare class UtilsApi {
+    /** **String Utilities** (`slugify`, `truncate`, `randomString`, etc.) */
+    readonly str: StringUtils;
+    /** **Number & Math Utilities** (`clamp`, `lerp`, `formatBytes`, etc.) */
+    readonly num: NumberUtils;
+    /** **Date & Time Utilities** (`formatDuration`, `timeAgo`, etc.) */
+    readonly date: DateUtils;
+    /** **Object Utilities** (`deepClone`, `parse`, `pick`, etc.) */
+    readonly obj: ObjectUtils;
+    /** **Array Utilities** (`chunk`, `unique`, `groupBy`, etc.) */
+    readonly arr: ArrayUtils;
+    /** **Async & Control Flow Utilities** (`sleep`, `retry`, `debounce`, etc.) */
+    readonly async: AsyncUtils;
+    /** **Validation Utilities** (`email`, `url`, `nullish`) */
+    readonly is: ValidationUtils;
+    /** **Identity Utilities** (`uuid`) */
+    readonly id: IdUtils;
+    /** **Functional Utilities** (`memo`) */
+    readonly fn: FunctionUtils;
 }
 
 /**
@@ -4669,6 +6357,7 @@ declare class XyPrissFS {
     fs: FSApi;
     path: PathApi;
     os: OSApi;
+    utils: UtilsApi;
     protected _internalRoot: string;
     /**
      * **Project Root Path**
@@ -7321,6 +9010,12 @@ declare class XemsRunner {
     /**
      * Enables hardware-bound persistent storage for XEMS.
      */
+    private static runnersByPath;
+    /**
+     * Internal factory for getting or creating a runner for a specific path.
+     * This ensures only one process exists for a given file in the entire process.
+     */
+    static getInstance(pathStr: string, options?: XemsOptions): XemsRunner;
     enablePersistence(pathStr: string, secret: string, resources?: {
         cacheSize?: number;
     }): void;
@@ -8217,63 +9912,6 @@ declare class MultiServerApp implements XyPrissApp {
     getOptimizerStats(): any;
 }
 
-/**
- * Safe JSON Middleware for Express
- * Automatically handles circular references in JSON responses
- */
-
-interface SafeJsonOptions {
-    /**
-     * Enable safe JSON serialization for all responses
-     * @default true
-     */
-    enabled?: boolean;
-    /**
-     * Maximum depth for object serialization
-     * @default 10
-     */
-    maxDepth?: number;
-    /**
-     * Maximum string length before truncation
-     * @default 1000
-     */
-    truncateStrings?: number;
-    /**
-     * Include non-enumerable properties
-     * @default false
-     */
-    includeNonEnumerable?: boolean;
-    /**
-     * Log when circular references are detected
-     * @default false
-     */
-    logCircularRefs?: boolean;
-    /**
-     * Custom replacer function for additional handling
-     */
-    customReplacer?: (key: string, value: any) => any;
-}
-/**
- * Creates middleware that safely handles JSON serialization
- */
-declare function createSafeJsonMiddleware(options?: SafeJsonOptions): (req: XyPrisRequest, res: XyPrisResponse, next: NextFunction) => void;
-/**
- * Quick setup function for common use cases
- */
-declare function setupSafeJson(app: any, options?: SafeJsonOptions): void;
-/**
- * Utility function to safely stringify any object
- */
-declare function safeJsonStringify(obj: any, options?: SafeJsonOptions): string;
-/**
- * Enhanced res.json replacement that can be used manually
- */
-declare function sendSafeJson(res: XyPrisResponse, obj: any, options?: SafeJsonOptions): void;
-/**
- * Middleware specifically for debugging circular references
- */
-declare function createCircularRefDebugger(): (req: XyPrisRequest, res: XyPrisResponse, next: NextFunction) => void;
-
 /***************************************************************************
  * XyPrissJS - Fast And Secure
  *
@@ -8978,5 +10616,5 @@ declare const getMimes: (extensions?: string | string[]) => string[];
  */
 declare function Router(): XyPrissRouter;
 
-export { ConfigurationManager as CM, ConfigurationManager as Configs, FileUploadAPI as FLA, FileUploadAPI, Plugin, PluginHookIds, Router, SecurityMiddleware, Upload, XJsonResponseHandler, XyGuard, MultiServerApp as XyPMS, XyPrissRouter, XyPrissXHSC, __cfg__, __const__, __sys__, createCircularRefDebugger, createOptimalCache, createSafeJsonMiddleware, createServer, getCallerProjectRoot, getIp, getMime, getMimes, identifyProjectRoot, initializeFileUpload, mergeWithDefaults, mergeWithDefaults as mwdef, quickServer, safeJsonStringify, sendSafeJson, setupSafeJson, uploadAny, uploadArray, uploadFields, uploadSingle, xems };
+export { ConfigurationManager as CM, ConfigurationManager as Configs, FileUploadAPI as FLA, FileUploadAPI, Plugin, PluginHookIds, Router, SecurityMiddleware, Upload, XJsonResponseHandler, XyGuard, MultiServerApp as XyPMS, XyPrissRouter, XyPrissXHSC, __cfg__, __const__, __sys__, createOptimalCache, createServer, getCallerProjectRoot, getIp, getMime, getMimes, identifyProjectRoot, initializeFileUpload, mergeWithDefaults, mergeWithDefaults as mwdef, quickServer, uploadAny, uploadArray, uploadFields, uploadSingle, xems };
 export type { ArchiveOptions, BatchRenameChange, CacheConfig, FileUploadConfig as FiUpConfig, FileUploadConfig, GetIpResult, IpSource, MonitorSnapshot, MultiServerConfig, NetworkStats, NextFunction, PerformanceConfig, PluginCreator, ProcessInfo, ProcessMonitorSnapshot, XyPrisRequest as Request, RequestHandler, XyPrisResponse as Response, RoutRateLimit, RouteConfig, RouteGuard, RouteMeta, RouteOptions, ParamType as RouteParamType, SecurityConfig, ServerOptions$1 as ServerOptions, XyPrisRequest$1 as XRequest, XyPrisResponse$1 as XResponse, XemsTypes, XyPrisRequest$1 as XyPrisRequest, XyPrisResponse$1 as XyPrisResponse, XyPrissApp, XyPrissPlugin };