@cldmv/slothlet-types 3.15.3 → 3.16.1

package/lib/helpers/platform.d.mts

@@ -1,11 +1,110 @@
-export let AsyncLocalStorage: null;
-export let AsyncResource: null;
-export let EventEmitter: null;
-export let createRequire: null;
-export let fs: null;
-export let fsp: null;
+/**
+ *	@Project: @cldmv/slothlet
+ *	@Filename: /src/lib/helpers/platform.mjs
+ *	@Date: 2026-05-29 22:02:43 -07:00 (1780117363)
+ *	@Author: Nate Corcoran <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-06-03 21:17:59 -07:00 (1780546679)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+/**
+ * @fileoverview Single source of truth for Node.js-vs-browser host differences.
+ * @module @cldmv/slothlet/helpers/platform
+ * @internal
+ *
+ * @description
+ * Slothlet runs in two hosts: Node.js (full filesystem access) and browser /
+ * Electron-renderer "browser mode" (no `node:*` builtins, manifest-based loading).
+ * Rather than scatter `typeof process` checks and gated `await import("node:*")`
+ * blocks across a dozen modules (#123), every host difference is decided ONCE here
+ * and the rest of the codebase imports the resolved builtins (or browser shims)
+ * plus `isNode` via plain static imports — no `node:*` specifier ever enters the
+ * static-import graph a browser must parse.
+ *
+ * The builtins are pulled in through a single top-level-await `import()` block
+ * guarded by `isNode`. In a browser the same exports resolve to `null` (for the
+ * Node-only ones, whose every call site is `isNode`-guarded) or to a minimal shim
+ * (`util`, which is consumed in both hosts for `inspect` / `types.isProxy`).
+ *
+ * Anything that genuinely cannot run outside Node and is never reachable from a
+ * browser module graph (TypeScript compilation, type generation, manifest
+ * generation) keeps its own direct `node:*` imports — routing those through here
+ * would only drag build-time-only builtins (`crypto`, `os`) into the shared hub.
+ *
+ * ## Browser-only branches & coverage (policy)
+ * The browser arms here — and in the modules that import `isNode` (the `else`/`: null` shims, the
+ * i18n browser paths, the live-mode null-ALS arm) — are UNREACHABLE under the Node coverage run:
+ * `process.versions.node` is always truthy there, even in the `platform:"browser"` node-side suites.
+ *
+ * They are now genuinely covered+counted by a **vitest browser-mode** run (real headless Chromium,
+ * Playwright provider — `.configs/vitest.browser.config.mjs`, `tests/browser/*.browser.test.mjs`).
+ * Because that run uses the SAME `@vitest/coverage-v8` provider over vite-transformed source as the
+ * node run, the two `coverage-final.json` maps align and merge cleanly
+ * (`tools/coverage/merge-browser-coverage.mjs`, wired as `npm run coverage:all`). An earlier merge was
+ * rejected, but that was of the raw-source Playwright *smoke* (`npm run test:browser`), whose importmap
+ * serves raw `src/` — those maps don't align with node's. The vitest-browser run does, which is what
+ * makes the merge correct. Only arms unreachable in BOTH hosts (e.g. an exotic non-Node host with no
+ * `process`/`navigator`) keep a precise v8 ignore-next comment. The smoke remains as a raw-importmap
+ * load check (the path a real consumer uses), not the coverage justification.
+ */
 export const isNode: boolean;
-export function loadJson(ref: any): any;
-export let path: null;
-export let url: null;
-export let util: null;
+/**
+ * Resolved Node.js builtins (Node host) or browser shims / `null` (browser host).
+ *
+ * Each is initialized to `null` and reassigned to the real builtin inside the `isNode`
+ * block below; in a browser the Node-only ones stay `null` (every call site is
+ * `isNode`-guarded) and `util` becomes a minimal shim. Annotated `any` (not bare `null`,
+ * which would make a TS consumer treat them as non-callable, nor the precise
+ * `typeof import("node:*")` shape, which would force `@types/node` onto every consumer —
+ * including browser ones — and break the no-extra-types export contract). `any` keeps them
+ * usable from TS while the polymorphic real-module / shim / `null` behavior is documented here.
+ * @private
+ */
+/** @type {any} */
+export let fs: any;
+/** @type {any} */
+export let fsp: any;
+/** @type {any} */
+export let path: any;
+/** @type {any} */
+export let url: any;
+/** @type {any} */
+export let util: any;
+/** @type {any} */
+export let EventEmitter: any;
+/** @type {any} */
+export let AsyncLocalStorage: any;
+/** @type {any} */
+export let AsyncResource: any;
+/** @type {any} */
+export let createRequire: any;
+/**
+ * Load and parse JSON, branching on host — this is the single place that knows how each
+ * environment reads JSON.
+ *
+ * @description
+ * - **Node**: synchronous `fs.readFileSync` + parse. Returns the parsed object directly (or
+ *   `null` on a read/parse failure). `ref` is a filesystem path or `file:` URL.
+ * - **Browser**: asynchronous dynamic `import(ref, { with: { type: "json" } })`. Returns a
+ *   `Promise<object|null>` — a miss resolves to `null` (callers keep their bundled default;
+ *   a failed import also surfaces a console error, which is harmless). `ref` is a module
+ *   specifier resolvable via the page's importmap (e.g. `@cldmv/slothlet/i18n/language/es-mx.json`).
+ *
+ * The return type is therefore polymorphic by host: `object|null` in Node, `Promise<object|null>`
+ * in a browser. Callers that already branch on `isNode` consume the matching form directly;
+ * `await loadJson(...)` is safe in both (awaiting a non-promise is a no-op).
+ *
+ * @param {string} ref - Filesystem path / `file:` URL (Node) or importmap specifier (browser).
+ * @returns {object|null|Promise<object|null>} Parsed JSON (Node, sync) or a promise of it (browser).
+ * @internal
+ *
+ * @example
+ * // Node (sync):
+ * const pkg = loadJson(new URL("../../package.json", import.meta.url));
+ * // Browser (async):
+ * const es = await loadJson("@cldmv/slothlet/i18n/language/es-mx.json");
+ */
+export function loadJson(ref: string): object | null | Promise<object | null>;

package/lib/helpers/resolve-from-caller.d.mts

@@ -1,8 +1,32 @@
+/**
+ * Path resolver component
+ * @class Resolver
+ * @extends ComponentBase
+ * @package
+ */
 export class Resolver extends ComponentBase {
     static slothletProperty: string;
-    getStack(skipFn: any): string | undefined;
-    toFsPath(v: any): any;
-    resolvePathFromCaller(rel: any): any;
+    /**
+     * Get V8 stack trace as CallSite array.
+     * @param {Function} [skipFn] - Optional function to skip from stack trace
+     * @returns {Array} Array of CallSite objects
+     * @public
+     */
+    public getStack(skipFn?: Function): any[];
+    /**
+     * Convert file:// URL to filesystem path or return as-is.
+     * @param {any} v - Value to convert
+     * @returns {string|null} Filesystem path or null
+     * @public
+     */
+    public toFsPath(v: any): string | null;
+    /**
+     * Resolve relative path from caller's context.
+     * @param {string} rel - Relative path to resolve
+     * @returns {string} Absolute filesystem path
+     * @public
+     */
+    public resolvePathFromCaller(rel: string): string;
     #private;
 }
 import { ComponentBase } from "#factories/component-base";

package/lib/helpers/sanitize.d.mts

@@ -1,9 +1,97 @@
+/**
+ * Standalone sanitizePropertyName function for backward compatibility
+ * @param {string} input - Input string to sanitize
+ * @param {object} options - Sanitization options
+ * @returns {string} Sanitized property name
+ * @public
+ */
+export function sanitizePropertyName(input: string, options?: object): string;
+/**
+ * Advanced filename sanitization with rule-based transformation
+ * @extends ComponentBase
+ * @public
+ */
 export class Sanitize extends ComponentBase {
     static slothletProperty: string;
-    sanitizePropertyName(input: any, options?: {}): string;
-    getModuleId(filePath: any, baseDir: any): any;
-    shouldPreserveFunctionCase(name: any): boolean;
+    /**
+     * Advanced sanitization function with configurable rule-based transformation
+     *
+     * @description
+     * Converts arbitrary strings (filenames, path segments) into valid JavaScript identifiers
+     * suitable for dot-notation property access. Supports sophisticated rule-based transformation
+     * with glob patterns, case preservation, and intelligent segment handling.
+     *
+     * @param {string} input - String to sanitize
+     * @param {Object} [options={}] - Sanitization configuration
+     * @param {boolean} [options.lowerFirst=true] - Lowercase first character of first segment
+     * @param {boolean} [options.preserveAllUpper=false] - Preserve all-uppercase identifiers
+     * @param {boolean} [options.preserveAllLower=false] - Preserve all-lowercase identifiers
+     * @param {Object} [options.rules={}] - Transformation rules
+     * @param {string[]} [options.rules.leave=[]] - Preserve exactly (case-sensitive, supports globs)
+     * @param {string[]} [options.rules.leaveInsensitive=[]] - Preserve exactly (case-insensitive, supports globs)
+     * @param {string[]} [options.rules.upper=[]] - Force UPPERCASE (supports globs and **STRING**)
+     * @param {string[]} [options.rules.lower=[]] - Force lowercase (supports globs and **STRING**)
+     * @returns {string} Valid JavaScript identifier
+     * @public
+     *
+     * @example
+     * // Basic usage
+     * sanitizePropertyName("auto-ip"); // "autoIp"
+     * sanitizePropertyName("root-math"); // "rootMath"
+     *
+     * @example
+     * // Rule-based transformation
+     * sanitizePropertyName("auto-ip", {
+     *   rules: { upper: ["*-ip"] }
+     * }); // "autoIP"
+     *
+     * @example
+     * // Boundary-requiring patterns
+     * sanitizePropertyName("parseJsonData", {
+     *   rules: { upper: ["**json**"] }
+     * }); // "parseJSONData"
+     *
+     * @example
+     * // Case preservation
+     * sanitizePropertyName("COMMON_APPS", {
+     *   preserveAllUpper: true
+     * }); // "COMMON_APPS"
+     *
+     * @example
+     * // Multiple rules
+     * sanitizePropertyName("get-api-status", {
+     *   rules: {
+     *     upper: ["*-api-*", "http"],
+     *     lower: ["xml"]
+     *   }
+     * }); // "getAPIStatus"
+     */
+    public sanitizePropertyName(input: string, options?: {
+        lowerFirst?: boolean | undefined;
+        preserveAllUpper?: boolean | undefined;
+        preserveAllLower?: boolean | undefined;
+        rules?: {
+            leave?: string[] | undefined;
+            leaveInsensitive?: string[] | undefined;
+            upper?: string[] | undefined;
+            lower?: string[] | undefined;
+        } | undefined;
+    }): string;
+    /**
+     * Get module ID from file path
+     * @param {string} filePath - Full file path
+     * @param {string} baseDir - Base directory
+     * @returns {string} Module ID
+     * @public
+     */
+    public getModuleId(filePath: string, baseDir: string): string;
+    /**
+     * Check if filename represents a special function name that should preserve case
+     * @param {string} name - Name to check
+     * @returns {boolean} True if special case should be preserved
+     * @public
+     */
+    public shouldPreserveFunctionCase(name: string): boolean;
     #private;
 }
-export function sanitizePropertyName(input: any, options?: {}): string;
 import { ComponentBase } from "#factories/component-base";

package/lib/helpers/scheduler-context.d.mts

@@ -1,2 +1,22 @@
-export function disableSchedulerPatching(): void;
+/**
+ * Pin deferred callbacks to the module that schedules them.
+ *
+ * Called once globally when the first instance is created; later calls are ignored, matching how
+ * EventEmitter patching behaves. Costs nothing when no runtime registered a pinning strategy — the
+ * wrapper hands the callback straight through.
+ *
+ * @returns {void}
+ * @public
+ */
 export function enableSchedulerPatching(): void;
+/**
+ * Restore the original scheduler entry points.
+ *
+ * Restores an entry point only when the wrapper installed here is still the one in place. Anything
+ * that replaced a scheduler afterwards — a test runner's fake timers being the usual case — owns that
+ * slot and its own restore, and writing over it would strand the process on a stale function.
+ *
+ * @returns {void}
+ * @public
+ */
+export function disableSchedulerPatching(): void;

package/lib/helpers/utilities.d.mts

@@ -1,8 +1,56 @@
+/**
+ * General utility functions
+ * @class Utilities
+ * @extends ComponentBase
+ * @package
+ */
 export class Utilities extends ComponentBase {
     static slothletProperty: string;
-    isPlainObject(obj: any): boolean;
-    deepMerge(target: any, source: any): any;
-    deepClone(obj: any): any;
-    generateId(): string;
+    /**
+     * Check if value is a plain object
+     * @param {*} obj - Value to check
+     * @returns {boolean} True if plain object
+     * @public
+     */
+    public isPlainObject(obj: any): boolean;
+    /**
+     * Deep merge two plain objects recursively.
+     *
+     * Differences from a simple spread:
+     * - Recursively merges nested plain objects rather than replacing them.
+     * - Uses `hasOwnProperty` to skip prototype-chain keys (no prototype pollution).
+     * - Non-plain values (arrays, class instances, primitives) are always copied by
+     *   value from `source`, never merged.
+     * - When `source[key]` is a plain object but `target[key]` is not (or absent),
+     *   the merge starts from `{}` so the returned sub-tree is always a fresh copy.
+     * - If either top-level argument is not a plain object, returns `source` as-is.
+     *
+     * @param {unknown} target - Base object (not mutated).
+     * @param {unknown} source - Source object whose keys are merged in.
+     * @returns {unknown} New merged object, or `source` as-is if either argument is not a plain object.
+     * @public
+     */
+    public deepMerge(target: unknown, source: unknown): unknown;
+    /**
+     * Deep clone a value, handling Proxy objects and functions that `structuredClone`
+     * cannot serialise.
+     *
+     * Strategy:
+     * 1. Try `structuredClone` — fast and spec-correct for plain data.
+     * 2. Fall back to a manual recursive copy for Proxies, callables, and other
+     *    non-serialisable objects; errors on individual property clones are swallowed
+     *    and the original reference is retained for that key.
+     *
+     * @param {unknown} obj - Value to clone.
+     * @returns {unknown} Deep clone of `obj`.
+     * @public
+     */
+    public deepClone(obj: unknown): unknown;
+    /**
+     * Generate unique ID
+     * @returns {string} Unique identifier
+     * @public
+     */
+    public generateId(): string;
 }
 import { ComponentBase } from "#factories/component-base";

package/lib/i18n/translations.d.mts

@@ -1,6 +1,51 @@
+/**
+ * Set current language (synchronous)
+ * Merges requested language translations over default English translations
+ * @param {string} lang - Language code
+ * @public
+ */
+export function setLanguage(lang: string): void;
+/**
+ * Set the current language asynchronously — the browser-capable path.
+ *
+ * @description
+ * Mirrors {@link setLanguage}, but awaits the locale load so it works in a browser, where locales
+ * arrive via dynamic `import(…, { with: { type: "json" } })` rather than the filesystem. In Node it
+ * awaits the same synchronous read (the await is a no-op). A failed load warns and keeps the bundled
+ * English default. Use this when you need to *await* a locale switch (e.g. in an Electron renderer).
+ * @param {string} lang - Language code (e.g. "es-mx").
+ * @returns {Promise<void>}
+ * @public
+ */
+export function setLanguageAsync(lang: string): Promise<void>;
+/**
+ * Get current language
+ * @returns {string} Language code
+ * @public
+ */
 export function getLanguage(): string;
-export function initI18n(options?: {}): void;
-export function setLanguage(lang: any): void;
-export function setLanguageAsync(lang: any): Promise<void>;
-export function t(errorCode: any, params?: {}): any;
-export function translate(errorCode: any, params?: {}): any;
+/**
+ * Translate error message with interpolation
+ * @param {string} errorCode - Error code
+ * @param {Object} params - Parameters for interpolation
+ * @returns {string} Translated message
+ * @public
+ */
+export function translate(errorCode: string, params?: Object): string;
+/**
+ * Initialize i18n system (synchronous)
+ * @param {Object} options - Options
+ * @param {string} [options.language] - Language code (auto-detect if not provided)
+ * @public
+ */
+export function initI18n(options?: {
+    language?: string | undefined;
+}): void;
+/**
+ * Translate error message with interpolation
+ * @param {string} errorCode - Error code
+ * @param {Object} params - Parameters for interpolation
+ * @returns {string} Translated message
+ * @public
+ */
+export function t(errorCode: string, params?: Object): string;

package/lib/modes/eager.d.mts

@@ -1,17 +1,55 @@
+/**
+ * Eager mode component - builds APIs by loading all modules immediately.
+ * @class EagerMode
+ * @extends ComponentBase
+ * @package
+ */
 export class EagerMode extends ComponentBase {
     static slothletProperty: string;
-    buildAPI({ dir, apiPathPrefix, collisionContext, moduleID, apiDepth, cacheBust, fileFilter, hidden, scanHiddenFolders, preloadedStructure, rootUnwrap }: {
-        dir: any;
+    /**
+     * Create EagerMode instance.
+     * @param {object} slothlet - Slothlet orchestrator instance.
+     * @package
+     */
+    constructor(slothlet: object);
+    /**
+     * Build API in eager mode (load all modules immediately).
+     * @param {Object} options - Build options
+     * @param {string} options.dir - Directory path to load from
+     * @param {string} [options.apiPathPrefix=""] - Prefix for API paths
+     * @param {string} [options.collisionContext="initial"] - Collision context
+     * @param {string|null} [options.collisionMode=null] - Per-call collision mode override (e.g. from `api.add()`'s `forceOverwrite`) — see `lazy.mjs`'s identical parameter
+     * @param {string} [options.moduleID] - Module ID
+     * @param {number} [options.apiDepth=DEFAULT_API_DEPTH] - Maximum directory depth ({@link DEFAULT_API_DEPTH})
+     * @param {string|null} [options.cacheBust=null] - Cache-busting value
+     * @param {Function|null} [options.fileFilter=null] - Optional filter (fileName) => boolean
+     * @param {string|string[]|null} [options.hidden=null] - Glob(s) hiding files/folders, matched against each entry's path relative to the API root
+     * @param {boolean} [options.scanHiddenFolders=false] - Deprecated: restore the pre-v3.11 scanning of `.`/`__`-prefixed folders
+     * @param {Object|null} [options.preloadedStructure=null] - Pre-built `{ files, directories }` structure
+     *   to use instead of scanning `dir` (synthetic / in-memory build, #117). Each synthetic file entry
+     *   carries its exports directly so no module is loaded from disk.
+     * @param {boolean} [options.rootUnwrap=false] - The mount exposes the single root entry's exports
+     *   directly at the mount path (a single-file or synthetic `api.add()`), so that entry creates no api
+     *   level and must contribute no path segment either.
+     * @returns {Promise<Object>} Built API object
+     * @public
+     *
+     * @example
+     * const api = await slothlet.modes.eager.buildAPI({ dir: "./api", moduleID: "base" });
+     */
+    public buildAPI({ dir, apiPathPrefix, collisionContext, collisionMode, moduleID, apiDepth, cacheBust, fileFilter, hidden, scanHiddenFolders, preloadedStructure, rootUnwrap }: {
+        dir: string;
         apiPathPrefix?: string | undefined;
         collisionContext?: string | undefined;
-        moduleID: any;
+        collisionMode?: string | null | undefined;
+        moduleID?: string | undefined;
         apiDepth?: number | undefined;
-        cacheBust?: null | undefined;
-        fileFilter?: null | undefined;
-        hidden?: null | undefined;
+        cacheBust?: string | null | undefined;
+        fileFilter?: Function | null | undefined;
+        hidden?: string | string[] | null | undefined;
         scanHiddenFolders?: boolean | undefined;
-        preloadedStructure?: null | undefined;
+        preloadedStructure?: Object | null | undefined;
         rootUnwrap?: boolean | undefined;
-    }): Promise<any>;
+    }): Promise<Object>;
 }
 import { ComponentBase } from "#factories/component-base";

package/lib/modes/lazy.d.mts

@@ -1,19 +1,66 @@
+/**
+ * Lazy mode component - builds APIs with deferred (on-demand) loading.
+ * @class LazyMode
+ * @extends ComponentBase
+ * @package
+ */
 export class LazyMode extends ComponentBase {
     static slothletProperty: string;
-    createNamedMaterializeFunc(apiPath: any, handler: any): (...args: any[]) => Promise<any>;
-    buildAPI({ dir, apiPathPrefix, collisionContext, collisionMode, moduleID, apiDepth, cacheBust, fileFilter, hidden, scanHiddenFolders, preloadedStructure, rootUnwrap }: {
-        dir: any;
+    /**
+     * Create LazyMode instance.
+     * @param {object} slothlet - Slothlet orchestrator instance.
+     * @package
+     */
+    constructor(slothlet: object);
+    /**
+     * Create a named async materialization function for lazy subdirectories.
+     * @param {string} apiPath - API path to derive the function name from.
+     * @param {Function} handler - Async handler that performs materialization.
+     * @returns {Function} Named async materialization function.
+     * @public
+     *
+     * @example
+     * const fn = lazyMode.createNamedMaterializeFunc('api.math', async () => ({ add: (a,b) => a+b }));
+     */
+    public createNamedMaterializeFunc(apiPath: string, handler: Function): Function;
+    /**
+     * Build API in lazy mode (proxy-based deferred loading).
+     * @param {Object} options - Build options
+     * @param {string} options.dir - Directory to build from
+     * @param {string} [options.apiPathPrefix=""] - Prefix for API paths
+     * @param {string} [options.collisionContext="initial"] - Collision context
+     * @param {string|null} [options.collisionMode=null] - Collision mode override from api.add()
+     * @param {string} [options.moduleID] - Module ID
+     * @param {number} [options.apiDepth=DEFAULT_API_DEPTH] - Maximum directory depth ({@link DEFAULT_API_DEPTH})
+     * @param {string|null} [options.cacheBust=null] - Cache-busting value
+     * @param {Function|null} [options.fileFilter=null] - Optional filter (fileName) => boolean
+     * @param {string|string[]|null} [options.hidden=null] - Glob(s) hiding files/folders, matched against each entry's path relative to the API root
+     * @param {boolean} [options.scanHiddenFolders=false] - Deprecated: restore the pre-v3.11 scanning of `.`/`__`-prefixed folders
+     * @param {Object|null} [options.preloadedStructure=null] - Pre-built `{ files, directories }` structure
+     *   to use instead of scanning `dir` (synthetic / in-memory build, #117). Each synthetic file entry
+     *   carries its exports directly so no module is loaded from disk.
+     * @param {boolean} [options.rootUnwrap=false] - The mount exposes the single root entry's exports
+     *   directly at the mount path (a single-file or synthetic `api.add()`), so that entry creates no api
+     *   level and must contribute no path segment either.
+     * @returns {Promise<Object>} Built API object with lazy proxies
+     * @public
+     *
+     * @example
+     * const api = await slothlet.modes.lazy.buildAPI({ dir: "./api", moduleID: "base" });
+     */
+    public buildAPI({ dir, apiPathPrefix, collisionContext, collisionMode, moduleID, apiDepth, cacheBust, fileFilter, hidden, scanHiddenFolders, preloadedStructure, rootUnwrap }: {
+        dir: string;
         apiPathPrefix?: string | undefined;
         collisionContext?: string | undefined;
-        collisionMode?: null | undefined;
-        moduleID: any;
+        collisionMode?: string | null | undefined;
+        moduleID?: string | undefined;
         apiDepth?: number | undefined;
-        cacheBust?: null | undefined;
-        fileFilter?: null | undefined;
-        hidden?: null | undefined;
+        cacheBust?: string | null | undefined;
+        fileFilter?: Function | null | undefined;
+        hidden?: string | string[] | null | undefined;
         scanHiddenFolders?: boolean | undefined;
-        preloadedStructure?: null | undefined;
+        preloadedStructure?: Object | null | undefined;
         rootUnwrap?: boolean | undefined;
-    }): Promise<any>;
+    }): Promise<Object>;
 }
 import { ComponentBase } from "#factories/component-base";