@cldmv/slothlet-types 3.15.3 → 3.16.0

package/lib/builders/api-assignment.d.mts

@@ -1,8 +1,129 @@
+/**
+ * Manages unified API assignment logic
+ * @class ApiAssignment
+ * @extends ComponentBase
+ * @package
+ *
+ * @description
+ * Class-based utility for assigning values to API paths with collision detection,
+ * wrapper sync, and merge operations. Extends ComponentBase for Slothlet property access.
+ *
+ * @example
+ * const assignment = new ApiAssignment(slothlet);
+ * assignment.assignToApiPath(api, "math", mathWrapper, {});
+ */
 export class ApiAssignment extends ComponentBase {
     static slothletProperty: string;
-    isWrapperProxy(value: any): boolean;
-    mergeOffSlotCollisionFolder(keptWrapper: any): void;
-    assignToApiPath(targetApi: any, key: any, value: any, options?: {}): boolean;
-    mergeApiObjects(targetApi: any, sourceApi: any, options?: {}): Promise<void>;
+    /**
+     * Create an ApiAssignment instance.
+     * @param {object} slothlet - Slothlet class instance.
+     * @package
+     *
+     * @description
+     * Creates ApiAssignment with ComponentBase support for config access.
+     */
+    constructor(slothlet: object);
+    /**
+     * Check if a value is a UnifiedWrapper proxy
+     * @param {unknown} value - Value to check
+     * @returns {boolean} True if value is a wrapper proxy
+     * @private
+     */
+    private isWrapperProxy;
+    /**
+     * Merge a callable-vs-callable collision's off-slot folder into the callable that kept the slot.
+     *
+     * Under the documented `merge` row the first-loaded callable holds the slot, so the folder
+     * composes off-slot; its members still belong on the surface — everything the survivor does not
+     * already define (first loaded wins conflicts). Idempotent: the handle is cleared on the first
+     * run, so a later settle pass over the same wrapper is a no-op.
+     *
+     * @param {object} keptWrapper - The surviving callable's wrapper (holds the off-slot handle).
+     * @returns {void}
+     * @package
+     */
+    mergeOffSlotCollisionFolder(keptWrapper: object): void;
+    /**
+     * Assign a value to an API object at a given property key.
+     * Handles wrapper sync, collision detection, and proper proxy preservation.
+     *
+     * @param {Object} targetApi - Target object to assign to (may be a UnifiedWrapper proxy)
+     * @param {string|symbol} key - Property name to assign
+     * @param {unknown} value - Value to assign (may be UnifiedWrapper proxy, raw value, etc.)
+     * @param {Object} options - Assignment options
+     * @param {boolean} [options.allowOverwrite=false] - Allow overwriting existing non-wrapper values
+     * @param {boolean} [options.mutateExisting=false] - Sync existing wrappers instead of replacing
+     * @param {boolean} [options.useCollisionDetection=false] - Enable collision detection using config.collision mode
+     * @param {Object} [options.config] - Slothlet config (uses config.collision.initial or config.collision.api)
+     * @param {string} [options.collisionContext="initial"] - Collision context: "initial" or "api"
+     * @param {Function} [options.syncWrapper] - Function to sync two wrapper proxies
+     * @param {string} [options.collisionMode="merge"] - Mode used by the mutateExisting/hot-reload path (Case 1) when syncing two existing wrappers
+     * @param {string|null} [options.collisionModeOverride=null] - Per-call override (e.g. `api.add()`'s `forceOverwrite`) for the collision-detection branch (Case 2); takes precedence over `config.collision[collisionContext]`
+     * @param {string|null} [options.moduleID=null] - Module id to associate with this assignment, forwarded to `syncWrapper`
+     * @returns {Promise<boolean>} True if assignment succeeded, false if blocked by collision or other constraint
+     *
+     * @description
+     * This function encapsulates all assignment patterns from processFiles:
+     * - Direct assignment when no collision
+     * - Wrapper sync when both existing and new are wrappers
+     * - Collision detection using config.collision[context] mode (merge/replace/error/skip/warn)
+     * - Proper handling of UnifiedWrapper proxies (preserves them, doesn't unwrap)
+     *
+     * Async (#369) because Case 1 awaits `syncWrapper` — itself async since it force-materializes
+     * both sides of a collision (#364). Every caller must await this call: a caller that captures
+     * the return value in an `if (assigned)`/truthy check and does NOT await first sees a Promise
+     * object, which is always truthy regardless of what it resolves to.
+     *
+     * @example
+     * // Direct assignment
+     * await assignment.assignToApiPath(api, "math", mathWrapper, {});
+     *
+     * @example
+     * // Sync existing wrapper with new data
+     * await assignment.assignToApiPath(api, "config", newConfigWrapper, { mutateExisting: true, syncWrapper });
+     *
+     * @example
+     * // With collision detection
+     * await assignment.assignToApiPath(api.math, "add", addFunction, {
+     *     useCollisionDetection: true,
+     *     config,
+     *     collisionContext: "initial"
+     * });
+     */
+    assignToApiPath(targetApi: Object, key: string | symbol, value: unknown, options?: {
+        allowOverwrite?: boolean | undefined;
+        mutateExisting?: boolean | undefined;
+        useCollisionDetection?: boolean | undefined;
+        config?: Object | undefined;
+        collisionContext?: string | undefined;
+        syncWrapper?: Function | undefined;
+        collisionMode?: string | undefined;
+        collisionModeOverride?: string | null | undefined;
+        moduleID?: string | null | undefined;
+    }): Promise<boolean>;
+    /**
+     * Recursively merge a source object into a target object using assignToApiPath logic.
+     *
+     * @param {Object} targetApi - Target object
+     * @param {Object} sourceApi - Source object to merge from
+     * @param {Object} options - Assignment options (passed to assignToApiPath)
+     * @param {boolean} [options.removeMissing=false] - Remove keys from target that don't exist in source
+     * @returns {Promise<void>}
+     *
+     * @description
+     * Recursively walks the source object and assigns each value to the target using
+     * assignToApiPath. This provides consistent merge behavior for both initial build
+     * and hot reload operations.
+     *
+     * @example
+     * await assignment.mergeApiObjects(api.config, newConfigApi, {
+     *     mutateExisting: true,
+     *     syncWrapper,
+     *     removeMissing: false
+     * });
+     */
+    mergeApiObjects(targetApi: Object, sourceApi: Object, options?: {
+        removeMissing?: boolean | undefined;
+    }): Promise<void>;
 }
 import { ComponentBase } from "#factories/component-base";

package/lib/builders/api_builder.d.mts

@@ -1,11 +1,108 @@
+/**
+ * Builds final API with built-in methods attached
+ * @class ApiBuilder
+ * @extends ComponentBase
+ * @package
+ *
+ * @description
+ * Class-based builder for final API construction with built-in namespace attachment.
+ * Extends ComponentBase for common Slothlet property access.
+ *
+ * @example
+ * const builder = new ApiBuilder(slothlet);
+ * const api = await builder.buildFinalAPI(userApi);
+ */
 export class ApiBuilder extends ComponentBase {
     static slothletProperty: string;
-    buildFinalAPI(userApi: any): Promise<any>;
-    createSlothletNamespace(userApi: any): Promise<any>;
-    createShutdownFunction(): () => Promise<any>;
-    createRunFunction(): (contextData: any, callback: any, ...args: any[]) => Promise<any>;
-    createScopeFunction(): (options: any) => Promise<any>;
-    createDestroyFunction(api: any): () => Promise<void>;
-    attachBuiltins(userApi: any, builtins: any): void;
+    /**
+     * Create an ApiBuilder instance.
+     * @param {object} slothlet - Slothlet class instance.
+     * @package
+     *
+     * @description
+     * Creates ApiBuilder with ComponentBase support for config, debug, instanceID access.
+     */
+    constructor(slothlet: object);
+    /**
+     * Build final API with built-in methods attached
+     * @param {Object} userApi - User API object from mode builder
+     * @returns {Promise<Object>} Final API with built-ins attached
+     * @public
+     */
+    public buildFinalAPI(userApi: Object): Promise<Object>;
+    /**
+     * @param {object} userApi - User API object (for diagnostics).
+     * @returns {Promise<object>} Slothlet namespace object.
+     * @private
+     *
+     * @description
+     * Builds the slothlet namespace with version metadata, API controls, and lifecycle
+     * helpers for the current instance.
+     *
+     * @example
+     * const namespace = await this.createSlothletNamespace(api);
+     */
+    private createSlothletNamespace;
+    /**
+     * Create root-level shutdown function (convenience)
+     * @returns {Function} Shutdown function that dynamically calls user hooks
+     * @private
+     */
+    private createShutdownFunction;
+    /**
+     * Create root-level run function (per-request context isolation)
+     * @returns {Function} Run function that executes callbacks with isolated context
+     * @private
+     */
+    private createRunFunction;
+    /**
+     * Create root-level scope function (structured per-request context with options)
+     * @returns {Function} Scope function that executes functions with isolated context
+     * @private
+     */
+    private createScopeFunction;
+    /**
+     * Create root-level destroy function (permanent destruction)
+     * @param {Object} api - Full API object
+     * @returns {Function} Destroy function that dynamically calls user hooks
+     * @private
+     */
+    private createDestroyFunction;
+    /**
+     * Attach built-in methods to user API
+     * @param {Object} userApi - User API object
+     * @param {Object} builtins - Built-in methods to attach
+     * @private
+     */
+    private attachBuiltins;
 }
+/**
+ * i18n translation helpers exposed on every Slothlet namespace.
+ */
+export type I18nNamespace = {
+    /**
+     * - Set the active locale (e.g. "en-us"). Synchronous; in a browser, non-default locales load in the background.
+     */
+    setLanguage: Function;
+    /**
+     * - Set the active locale and await its load. Browser-capable (resolves once the locale module is fetched).
+     */
+    setLanguageAsync: Function;
+    /**
+     * - Return the current active locale string.
+     */
+    getLanguage: Function;
+    /**
+     * - Translate an error code with optional params.
+     */
+    translate: Function;
+    /**
+     * - Alias for translate.
+     */
+    t: Function;
+    /**
+     * - Initialise the i18n system with options.
+     */
+    initI18n: Function;
+};
 import { ComponentBase } from "#factories/component-base";

package/lib/builders/builder.d.mts

@@ -1,5 +1,86 @@
+/**
+ * API builder class for orchestrating mode-based API construction.
+ * @class Builder
+ * @extends ComponentBase
+ * @package
+ *
+ * @description
+ * Orchestrates API building by delegating to mode-specific builders (eager/lazy).
+ * Extends ComponentBase for access to Slothlet configuration and error classes.
+ *
+ * @example
+ * const builder = new Builder(slothlet);
+ * const api = await builder.buildAPI({ dir: "./api" });
+ */
 export class Builder extends ComponentBase {
     static slothletProperty: string;
-    buildAPI(options: any): Promise<any>;
+    /**
+     * Create Builder instance.
+     * @param {object} slothlet - Slothlet orchestrator instance.
+     * @package
+     *
+     * @description
+     * Stores Slothlet reference for accessing configuration and components.
+     *
+     * @example
+     * const builder = new Builder(slothlet);
+     */
+    constructor(slothlet: object);
+    /**
+     * Build API from directory or file.
+     * @param {Object} options - Build options
+     * @param {string} [options.dir] - Directory or file to build from. Required unless `syntheticExports` is set (synthetic / in-memory leaf, #117).
+     * @param {string} [options.mode="eager"] - Loading mode (eager or lazy)
+     * @param {Object} [options.ownership] - Ownership manager (uses slothlet's if not provided)
+     * @param {Object} [options.contextManager] - Context manager (uses slothlet's if not provided)
+     * @param {string} [options.instanceID] - Instance ID (uses slothlet's if not provided)
+     * @param {Object} [options.config] - Configuration (uses slothlet's if not provided)
+     * @param {string} [options.apiPathPrefix=""] - Prefix for API paths (for api.add support)
+     * @param {string} [options.collisionContext="initial"] - Collision context
+     * @param {string} [options.moduleID] - Stable module identifier (cache key; enables later reload/remove)
+     * @param {string|null} [options.cacheBust=null] - Cache-busting value forwarded to the loader/mode
+     * @param {string|null} [options.collisionMode=null] - Per-call collision mode override (lazy builds)
+     * @param {Function|null} [options.fileFilter=null] - Optional filter function (fileName) => boolean to load specific files only
+     * @param {Object|null} [options.syntheticExports=null] - Inline `{ default?, ...named }` exports to build
+     *   from instead of scanning `dir` (synthetic / in-memory leaf, #117). When set, `dir` is not required.
+     * @param {string} [options.syntheticName="synthetic"] - Intermediate key name for the synthetic build.
+     * @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>} Raw API object (unwrapped)
+     * @public
+     *
+     * @description
+     * Validates inputs and delegates to mode-specific builder (buildEagerAPI or buildLazyAPI).
+     * When fileFilter is provided, only files matching the filter are loaded.
+     *
+     * @example
+     * const api = await builder.buildAPI({ dir: "./api_tests/api_test", mode: "eager" });
+     *
+     * @example
+     * // Load specific file only
+     * const api = await builder.buildAPI({
+     *   dir: "./api_tests/api_test",
+     *   mode: "eager",
+     *   fileFilter: (fileName) => fileName === "math.mjs"
+     * });
+     */
+    public buildAPI(options: {
+        dir?: string | undefined;
+        mode?: string | undefined;
+        ownership?: Object | undefined;
+        contextManager?: Object | undefined;
+        instanceID?: string | undefined;
+        config?: Object | undefined;
+        apiPathPrefix?: string | undefined;
+        collisionContext?: string | undefined;
+        moduleID?: string | undefined;
+        cacheBust?: string | null | undefined;
+        collisionMode?: string | null | undefined;
+        fileFilter?: Function | null | undefined;
+        syntheticExports?: Object | null | undefined;
+        syntheticName?: string | undefined;
+        rootUnwrap?: boolean | undefined;
+    }): Promise<Object>;
 }
 import { ComponentBase } from "#factories/component-base";

package/lib/builders/modes-processor.d.mts

@@ -1,7 +1,70 @@
+/**
+ * ModesProcessor - Handles mode-specific file and directory processing.
+ *
+ * @class
+ * @extends ComponentBase
+ * @package
+ */
 export class ModesProcessor extends ComponentBase {
     static slothletProperty: string;
-    processFiles(api: any, files: any, directory: any, currentDepth: any, mode: any, isRoot: any, recursive: any, populateDirectly?: boolean, apiPathPrefix?: string, collisionContext?: string, moduleID?: null, sourceFolder?: null, cacheBust?: null, collisionModeOverride?: null, rootUnwrap?: boolean): Promise<any>;
-    createLazySubdirectoryWrapper(dir: any, apiPath: any, moduleID?: null, sourceFolder?: null, cacheBust?: null, fileFolderCollisionImpl?: null, collisionMode?: string): any;
-    applyRootContributor(api: any, rootFunction: any, mode: any): Promise<any>;
+    /**
+     * Creates a new ModesProcessor instance.
+     *
+     * @param {Object} slothlet - Parent slothlet instance
+     */
+    constructor(slothlet: Object);
+    /**
+     * Recursively walk a directory's scanned files/subdirectories and compose them onto `api`.
+     * @param {Object} api - Root api object being built.
+     * @param {Array<Object>} files - This directory's own files (from the loader's scan structure).
+     * @param {{name: string, path?: string, children: {files: Array, directories: Array}}} directory - This directory's own scan node.
+     * @param {number} currentDepth - Recursion depth, for `apiDepth` enforcement.
+     * @param {string} mode - `"eager"` or `"lazy"`.
+     * @param {boolean} isRoot - Whether this call is the top-level (mount root) invocation.
+     * @param {boolean} recursive - Whether to descend into subdirectories at all.
+     * @param {boolean} [populateDirectly=false] - Pour this directory's contents directly into `api` (no nested namespace level) — used for transparent-folder and lazy-materialization callers.
+     * @param {string} [apiPathPrefix=""] - Dotted api path prefix this directory's own entries are built under.
+     * @param {string} [collisionContext="initial"] - `"initial"` or `"api"` — which `config.collision` policy governs this build.
+     * @param {string|null} [moduleID=null] - Module id every leaf produced by this call is attributed to.
+     * @param {string|null} [sourceFolder=null] - Filesystem path this directory was scanned from, for metadata.
+     * @param {string|null} [cacheBust=null] - Cache-busting value forwarded to dynamic imports.
+     * @param {string|null} [collisionModeOverride=null] - Per-call override (e.g. `api.add()`'s `forceOverwrite`) that takes precedence over `collisionContext`'s config default for every leaf this call (and its own recursive calls) produces.
+     * @param {boolean} [rootUnwrap=false] - The mount exposes its single root entry's exports directly at the mount path (a single-file or synthetic `api.add()`), so that entry creates no api level.
+     * @returns {Promise<Function|null>} The root-level default-export contributor function, if one was found at this call's own top level; otherwise `null`.
+     * @package
+     */
+    processFiles(api: Object, files: Array<Object>, directory: {
+        name: string;
+        path?: string;
+        children: {
+            files: any[];
+            directories: any[];
+        };
+    }, currentDepth: number, mode: string, isRoot: boolean, recursive: boolean, populateDirectly?: boolean, apiPathPrefix?: string, collisionContext?: string, moduleID?: string | null, sourceFolder?: string | null, cacheBust?: string | null, collisionModeOverride?: string | null, rootUnwrap?: boolean): Promise<Function | null>;
+    /**
+     * Create lazy wrapper for subdirectory (lazy mode only)
+     * @param {Object} dir - Directory structure to materialize on first access.
+     * @param {string} apiPath - Current (already composed) API path for this subdirectory.
+     * @param {string} [moduleID] - Owning module id, threaded into the loader and ownership registration.
+     * @param {string} [sourceFolder] - Parent's source folder path; this subdirectory's own source folder is derived from it.
+     * @param {*} [cacheBust] - Cache-busting token passed through to `loadModule`.
+     * @param {Object} [fileFolderCollisionImpl] - Pre-existing implementation properties from a file/folder name collision, merged onto the materialized result so they survive lazy materialization.
+     * @param {string} [collisionMode] - Effective (override-or-config-resolved) collision mode to apply within this subdirectory.
+     * @param {string} [collisionContext] - Collision context ("initial" | "api") this subdirectory was mounted under, threaded to ownership/ collision-detection calls.
+     * @returns {Proxy} Lazy unified wrapper
+     * @public
+     */
+    public createLazySubdirectoryWrapper(dir: Object, apiPath: string, moduleID?: string, sourceFolder?: string, cacheBust?: any, fileFolderCollisionImpl?: Object, collisionMode?: string, collisionContext?: string): ProxyConstructor;
+    /**
+     * Apply root contributor pattern - merge API into root function
+     * @param {Object} api - API object with properties
+     * @param {Function|null} rootFunction - Root contributor function
+     * @param {Object} config - Configuration
+     * @param {string} mode - Mode name for debug messages
+     * @returns {Promise<Object|Function>} Final API (function if root contributor, object otherwise)
+     * @public
+     */
+    public applyRootContributor(api: Object, rootFunction: Function | null, mode: string): Promise<Object | Function>;
+    #private;
 }
 import { ComponentBase } from "#factories/component-base";

package/lib/errors.d.mts

@@ -1,28 +1,123 @@
-export class SlothletDebug {
-    constructor(config?: {});
-    config: {};
-    debugFlags: any;
-    log(code: any, context?: {}): void;
-    toString(): string;
-}
+/**
+ * Custom error class for Slothlet-specific errors with context and i18n
+ * @public
+ */
 export class SlothletError extends Error {
-    static #describeThrown(thrown: any): string;
+    /**
+     * Create a new SlothletError with automatic translation and hint detection
+     * @param {string} code - Error code identifier
+     * @param {Object} context - Additional context about the error
+     * @param {boolean} [context.validationError] - Mark as validation error (no originalError needed)
+     * @param {boolean} [context.stub] - Mark as stub error (not-yet-implemented feature)
+     * @param {unknown} [originalError] - What was originally thrown. Not necessarily an `Error`:
+     *   application code may throw a structured payload, a string, or any other value, and all of
+     *   them are rendered into the message and chained via `cause`. Only `null`/`undefined` mean
+     *   "no original".
+     * @param {Object} [options] - Additional options (alternative to embedding flags in context)
+     * @param {boolean} [options.validationError] - Mark as validation error (no originalError needed)
+     * @param {boolean} [options.stub] - Mark as stub error (not-yet-implemented feature)
+     * @public
+     */
+    /**
+     * Renders a thrown value for message interpolation.
+     *
+     * @param {unknown} thrown - Whatever the guarded code threw.
+     * @returns {string} A human-readable rendering: an Error's message, a string as itself, and
+     *   any other value JSON-serialized (falling back to String() for unserializable values).
+     */
+    static #describeThrown(thrown: unknown): string;
     constructor(code: any, context?: {}, originalError?: null, options?: {});
-    toJSON(): {
-        name: string;
-        code: any;
-        message: string;
-        hint: any;
-    };
+    /**
+     * Prevent JSON serialization of context (cleaner error display)
+     * @returns {Object} Simplified error object
+     */
+    toJSON(): Object;
 }
+/**
+ * Warning class for non-fatal issues with i18n support
+ * @public
+ */
 export class SlothletWarning {
     static captured: any[];
     static suppressConsole: boolean;
-    static clearCaptured(): void;
-    constructor(code: any, context?: {});
+    /**
+     * Clear captured warnings (for testing)
+     * @public
+     */
+    public static clearCaptured(): void;
+    /**
+     * Create and emit a warning with automatic translation
+     * @param {string} code - Warning code identifier
+     * @param {Object} context - Additional context about the warning
+     * @param {string} [context.key] - Optional translation key override. When provided, this key
+     *   is used for translation instead of `code`. All other context properties are used as
+     *   interpolation params. Allows sub-key variants without changing the warning code.
+     * @public
+     */
+    constructor(code: string, context?: {
+        key?: string | undefined;
+    });
     name: string;
-    code: any;
-    message: any;
-    context: {};
+    code: string;
+    /** @type {string} */
+    message: string;
+    context: {
+        key?: string | undefined;
+    };
+    /**
+     * Custom string representation
+     * @returns {string} Formatted warning string
+     */
+    toString(): string;
+}
+/**
+ * Debug utility class for centralized conditional console output with i18n
+ * @public
+ */
+export class SlothletDebug {
+    /**
+     * Create a debug logger instance bound to a config
+     * @param {Object} config - Configuration object (typically slothlet.config)
+     * @public
+     */
+    constructor(config?: Object);
+    config: Object;
+    debugFlags: any;
+    /**
+     * Log a debug message if the code's debug flag is enabled
+     * @param {string} code - Debug code/category (e.g., "modes", "wrapper", "api")
+     * @param {Object} context - Contextual information to display
+     * @param {string} [context.key] - Translation key for the message (e.g. "DEBUG_MODE_FLATTENING").
+     *   When provided, translates via i18n using the remaining context properties as interpolation
+     *   params - no `await t()` needed at the call site. Falls back to `DEBUG_{CODE}` category key
+     *   if omitted, then to `context.message` for backwards compatibility.
+     * @param {string} [context.message] - Raw message string (backwards-compat fallback).
+     *   Prefer `context.key` for new call sites so messages are translatable.
+     * @public
+     *
+     * @description
+     * Centralized debug logging that respects debug configuration flags.
+     * Only outputs when the specified code matches a truthy debug flag.
+     * Translates messages using i18n system with the following key resolution order:
+     * 1. `context.key` - explicit per-message translation key (preferred)
+     * 2. `DEBUG_{CODE}` - category-level key (e.g. DEBUG_MODES)
+     * 3. `context.message` - raw string fallback for backwards compatibility
+     *
+     * @example
+     * // Preferred: pass translation key directly - no await needed
+     * this.debug("modes", { key: "DEBUG_MODE_FLATTENING", mode, categoryName });
+     *
+     * @example
+     * // Legacy: raw message string (still works, but not translatable)
+     * this.debug("wrapper", { message: "Category reuse - using existing wrapper", apiPath });
+     */
+    public log(code: string, context?: {
+        key?: string | undefined;
+        message?: string | undefined;
+    }): void;
+    /**
+     * Custom string representation
+     * @returns {string} Debug info
+     */
     toString(): string;
 }