@cldmv/slothlet-types 3.15.3 → 3.16.0

package/lib/factories/component-base.d.mts

@@ -1,12 +1,175 @@
+/**
+ * Base class for Slothlet component classes.
+ * @class ComponentBase
+ * @package
+ *
+ * @description
+ * Provides common Slothlet property access for handlers, builders, and processors.
+ * All component classes should extend this to gain consistent access to the Slothlet
+ * instance's configuration, API references, and error classes. Components are instantiated
+ * with a reference to the Slothlet class itself, making them modular extensions.
+ *
+ * @example
+ * class ApiManager extends ComponentBase {
+ *   constructor(slothlet) {
+ *     super(slothlet);
+ *     this.state = { addHistory: [] };
+ *   }
+ *
+ *   someMethod() {
+ *     if (this.debug?.api) {
+ *       console.log(`Slothlet: ${this.instanceID}`);
+ *     }
+ *     throw new this.SlothletError("INVALID_CONFIG", { reason: "bad input" });
+ *   }
+ * }
+ */
 export class ComponentBase {
+    /**
+     * Complete set of property names reserved by the slothlet framework.
+     *
+     * @description
+     * These keys are either private wrapper internals, read-only info props exposed
+     * through the proxy, write-blocked lifecycle keys, or builtin namespace keys
+     * injected at the API root level. Used by all components to distinguish framework
+     * internals from user-defined properties when:
+     *   - Collecting user-set custom properties for preservation across reload
+     *     (`_collectCustomProperties` in api-manager.mjs)
+     *   - Extracting child keys for impl reconstruction (`_extractFullImpl`)
+     *   - Determining whether a set(trap) write should be silently absorbed (`setTrap`)
+     *   - Filtering what getTrap exposes externally on wrapper proxies
+     *
+     * Note: `_materialize` is included here (skip for collection/extraction) but
+     * setTrap exempts it since the framework needs to write it directly.
+     *
+     * @type {Set<string>}
+     * @static
+     */
     static INTERNAL_KEYS: Set<string>;
-    constructor(slothlet: any);
-    get ____slothlet(): any;
-    get slothlet(): any;
-    get ____config(): any;
-    get instanceID(): any;
-    get SlothletError(): any;
-    get SlothletWarning(): any;
-    emitImplDiagnostic(level: any, data: any): Promise<void>;
+    /**
+     * Create a component base instance.
+     * @param {object} slothlet - Slothlet class instance.
+     * @package
+     *
+     * @description
+     * Stores the Slothlet reference for access via getters. The Slothlet class itself
+     * is passed (not a separate "instance" object), making components modular extensions
+     * of Slothlet.
+     *
+     * @example
+     * super(slothlet);
+     */
+    constructor(slothlet: object);
+    /**
+     * Get Slothlet instance via the canonical internal accessor name.
+     * @returns {object} Slothlet instance.
+     * @package
+     *
+     * @description
+     * Prototype getter — NOT an own property — so the JS Proxy invariant for
+     * non-configurable own properties never applies. UnifiedWrapper's getTrap blocks
+     * this name via the underscore-filter before it can reach the getter.
+     *
+     * @example
+     * const s = this.____slothlet;
+     */
+    get ____slothlet(): object;
+    /**
+     * Get Slothlet instance (internal access).
+     * @returns {object} Slothlet instance.
+     * @package
+     *
+     * @description
+     * Provides direct access to the Slothlet instance for legacy code compatibility.
+     * Prefer using specific getters (config, helpers, handlers) when possible.
+     *
+     * @example
+     * this.slothlet.debug("api", { action: "assigned" });
+     */
+    get slothlet(): object;
+    /**
+     * Get Slothlet configuration.
+     * @returns {object} Slothlet configuration object.
+     * @package
+     *
+     * @description
+     * Provides access to the Slothlet config for collision modes, debug settings, etc.
+     * Named with ____ prefix to avoid shadowing user API names like 'config'.
+     *
+     * @example
+     * const collisionMode = this.____config.collision.api;
+     */
+    get ____config(): object;
+    /**
+     * Get Slothlet instance ID.
+     * @returns {string} Slothlet instance identifier.
+     * @package
+     */
+    get instanceID(): string;
+    /**
+     * Get SlothletError class.
+     * @returns {Function} SlothletError constructor.
+     * @package
+     *
+     * @description
+     * Provides access to SlothletError without importing in every file.
+     * Components can throw errors via `new this.SlothletError(...)`.
+     *
+     * @example
+     * throw new this.SlothletError("INVALID_CONFIG", { reason: "missing dir" });
+     */
+    get SlothletError(): Function;
+    /**
+     * Get SlothletWarning class.
+     * @returns {Function} SlothletWarning constructor.
+     * @package
+     *
+     * @description
+     * Provides access to SlothletWarning without importing in every file.
+     * Components can issue warnings via `new this.SlothletWarning(...)`.
+     *
+     * @example
+     * new this.SlothletWarning("WARNING_DEPRECATED", { feature: "oldApi" });
+     */
+    get SlothletWarning(): Function;
+    /**
+     * Emit a non-throwing diagnostic lifecycle event (`impl:warning` or `impl:error`).
+     * @param {"warning"|"error"} level - Diagnostic level → `impl:warning` or `impl:error`.
+     * @param {object} data - Diagnostic payload.
+     * @param {string} data.code - i18n code (e.g. "WARN_SYNTHETIC_ROOT_COLLISION") used to translate `message`.
+     * @param {object} data.context - Structured context object passed to the diagnostic (also the i18n interpolation params).
+     * @param {string} [data.apiPath] - API path where the mutation was attempted ("" / "(root)" for root).
+     * @param {string} [data.source] - Command family that produced the diagnostic (addApi | reload | buildAPI | module-mount).
+     * @param {string} [data.moduleID] - Module identifier, when one is in scope.
+     * @param {Error} [data.error] - The originating Error / SlothletError (impl:error only).
+     * @returns {Promise<void>} Resolves once all subscribers (including async ones) have run.
+     * @package
+     *
+     * @description
+     * Fires an additive lifecycle event for a diagnostic the framework handled WITHOUT throwing —
+     * a warning, or a runtime error a command caught and continued past. Observers registered via
+     * `api.slothlet.lifecycle.on("impl:warning"|"impl:error", fn)` — or the construction-time
+     * `lifecycle` config option — receive these regardless of the `silent` config: `silent`
+     * suppresses console output only, never events. The human-readable `message` is translated
+     * from `code` + `context` here so subscribers get a ready-to-display string even when the
+     * corresponding SlothletWarning/SlothletError was never constructed (e.g. under `silent`).
+     *
+     * Emission stays per-site: each diagnostic location calls this explicitly, mirroring how each
+     * site constructs its own `this.SlothletWarning`. The SlothletError / SlothletWarning classes
+     * remain context-free (no slothlet reference) and are never coupled to the lifecycle emitter.
+     *
+     * @example
+     * await this.emitImplDiagnostic("warning", {
+     *   apiPath: "", code: "WARN_SYNTHETIC_ROOT_EMPTY", context: { apiPath: "(root)" }, source: "addApi"
+     * });
+     */
+    emitImplDiagnostic(level: "warning" | "error", data: {
+        code: string;
+        context: object;
+        apiPath?: string | undefined;
+        source?: string | undefined;
+        moduleID?: string | undefined;
+        error?: Error | undefined;
+    }): Promise<void>;
     #private;
 }

package/lib/factories/context.d.mts

@@ -1,7 +1,25 @@
-import { asyncContextManager } from "#handlers/context-async";
-export const asyncRuntime: import("#handlers/context-async").AsyncContextManager;
+/**
+ * Get context manager for specified runtime type
+ * @param {string} runtime - Runtime type ("async" or "live")
+ * @returns {Object} Context manager instance
+ * @public
+ */
+export function getContextManager(runtime?: string): Object;
+/**
+ * Default context manager (async)
+ * @public
+ */
 export const contextManager: import("#handlers/context-async").AsyncContextManager;
-export function getContextManager(runtime?: string): import("#handlers/context-async").AsyncContextManager | import("#handlers/context-live").LiveContextManager;
-import { liveContextManager } from "#handlers/context-live";
+/**
+ * Async runtime for runtime exports
+ * @public
+ */
+export const asyncRuntime: import("#handlers/context-async").AsyncContextManager;
+/**
+ * Live runtime for runtime exports
+ * @public
+ */
 export const liveRuntime: import("#handlers/context-live").LiveContextManager;
+import { asyncContextManager } from "#handlers/context-async";
+import { liveContextManager } from "#handlers/context-live";
 export { asyncContextManager, liveContextManager };

package/lib/handlers/api-cache-manager.d.mts

@@ -1,24 +1,213 @@
+/**
+ * Cache entry structure for API tree storage and rebuild parameters.
+ * @typedef {Object} CacheEntry
+ * @property {string} endpoint - API path endpoint (e.g., ".", "plugins")
+ * @property {string} moduleID - Module identifier
+ * @property {Object} api - Complete buildAPI result tree (primary storage)
+ * @property {string} folderPath - Source folder path
+ * @property {string} mode - Loading mode: 'lazy' or 'eager'
+ * @property {Object} sanitizeOptions - Sanitization configuration
+ * @property {string} collisionMode - Collision handling mode
+ * @property {Object} config - Config snapshot at add time
+ * @property {number} timestamp - Cache creation time (Unix ms)
+ */
+/**
+ * Manages API caches - complete buildAPI results per moduleID
+ * @class ApiCacheManager
+ * @extends ComponentBase
+ * @public
+ *
+ * @description
+ * Stores complete API trees for each moduleID with all rebuild parameters.
+ * The cache is the PRIMARY storage - live API references cached trees.
+ * Enables hot reload by rebuilding caches from disk and updating live references.
+ *
+ * @example
+ * const cacheManager = new ApiCacheManager(slothlet);
+ * cacheManager.set("module_abc", { api: tree, folderPath: "./plugins", ... });
+ */
 export class ApiCacheManager extends ComponentBase {
     static slothletProperty: string;
-    caches: Map<any, any>;
-    set(moduleID: any, entry: any): void;
-    get(moduleID: any): any;
-    has(moduleID: any): boolean;
-    delete(moduleID: any): boolean;
-    getAllModuleIDs(): any[];
-    getCacheDiagnostics(): {
-        totalCaches: number;
-        caches: {
-            moduleID: any;
-            endpoint: any;
-            folderPath: any;
-            mode: any;
-            pathCount: number;
-            timestamp: any;
-        }[];
-    };
-    _countPaths(api: any, visited?: WeakSet<object>): number;
-    clear(): void;
-    rebuildCache(moduleID: any): Promise<any>;
+    /**
+     * Create ApiCacheManager instance
+     * @param {object} slothlet - Slothlet instance
+     * @public
+     */
+    constructor(slothlet: object);
+    /**
+     * Cache storage - moduleID → CacheEntry
+     * @type {Map<string, CacheEntry>}
+     * @private
+     */
+    private caches;
+    /**
+     * Store cache entry for moduleID
+     * @param {string} moduleID - Module identifier
+     * @param {CacheEntry} entry - Cache entry with api tree and rebuild parameters
+     * @returns {void}
+     * @public
+     *
+     * @description
+     * Stores complete buildAPI result. The cached API tree becomes the source of truth.
+     * Existing references should point to entry.api, not copy it.
+     *
+     * @example
+     * cache.set("base_abc123", {
+     *   endpoint: ".",
+     *   moduleID: "base_abc123",
+     *   api: apiTree,
+     *   folderPath: this.____config.dir,
+     *   mode: "lazy",
+     *   sanitizeOptions: {},
+     *   collisionMode: "merge",
+     *   config: {...this.____config},
+     *   timestamp: Date.now()
+     * });
+     */
+    public set(moduleID: string, entry: CacheEntry): void;
+    /**
+     * Get cache entry by moduleID
+     * @param {string} moduleID - Module identifier
+     * @returns {CacheEntry|undefined} Cache entry or undefined if not found
+     * @public
+     *
+     * @example
+     * const cache = cacheManager.get("base_abc123");
+     * if (cache) {
+     *   const api = cache.api; // Get API tree from cache
+     * }
+     */
+    public get(moduleID: string): CacheEntry | undefined;
+    /**
+     * Check if cache exists for moduleID
+     * @param {string} moduleID - Module identifier
+     * @returns {boolean} True if cache exists
+     * @public
+     *
+     * @example
+     * if (cacheManager.has("base_abc123")) {
+     *   // Cache exists
+     * }
+     */
+    public has(moduleID: string): boolean;
+    /**
+     * Delete cache entry by moduleID
+     * @param {string} moduleID - Module identifier
+     * @returns {boolean} True if cache was deleted
+     * @public
+     *
+     * @description
+     * Removes cache entry. Should be called when module is removed via api.remove(moduleID).
+     *
+     * @example
+     * cacheManager.delete("plugins_abc123");
+     */
+    public delete(moduleID: string): boolean;
+    /**
+     * Get all moduleIDs in cache
+     * @returns {string[]} Array of moduleIDs
+     * @public
+     *
+     * @example
+     * const moduleIDs = cacheManager.getAllModuleIDs();
+     * // ["base_abc123", "plugins_xyz789", ...]
+     */
+    public getAllModuleIDs(): string[];
+    /**
+     * Get cache diagnostics
+     * @returns {object} Diagnostic information
+     * @public
+     *
+     * @description
+     * Returns diagnostic data about cached modules. Available under api.slothlet.diag.caches
+     * when config.debug.diagnostics is enabled.
+     *
+     * @example
+     * const diag = cacheManager.getCacheDiagnostics();
+     * // {
+     * //   totalCaches: 3,
+     * //   caches: [
+     * //     { moduleID: "base_abc123", endpoint: ".", pathCount: 42, timestamp: ... },
+     * //     ...
+     * //   ]
+     * // }
+     */
+    public getCacheDiagnostics(): object;
+    /**
+     * Count API paths in a tree
+     * @param {object} api - API tree
+     * @param {WeakSet} [visited] - Visited objects (prevent circular refs)
+     * @returns {number} Number of paths
+     * @private
+     */
+    private _countPaths;
+    /**
+     * Clear all caches
+     * @returns {void}
+     * @public
+     *
+     * @description
+     * Removes all cache entries. Used during shutdown or full reload.
+     *
+     * @example
+     * cacheManager.clear();
+     */
+    public clear(): void;
+    /**
+     * Rebuild cache from disk by calling buildAPI with stored parameters
+     * @param {string} moduleID - Module identifier to rebuild
+     * @returns {Promise<object>} Fresh API tree from buildAPI
+     * @public
+     *
+     * @description
+     * Reloads module source files and rebuilds API tree. Does NOT update cache -
+     * caller must call set() with fresh tree. Returns the new API tree.
+     *
+     * @example
+     * const freshApi = await cacheManager.rebuildCache("plugins_abc123");
+     * cacheManager.set("plugins_abc123", { ...existingEntry, api: freshApi, timestamp: Date.now() });
+     */
+    public rebuildCache(moduleID: string): Promise<object>;
 }
+/**
+ * Cache entry structure for API tree storage and rebuild parameters.
+ */
+export type CacheEntry = {
+    /**
+     * - API path endpoint (e.g., ".", "plugins")
+     */
+    endpoint: string;
+    /**
+     * - Module identifier
+     */
+    moduleID: string;
+    /**
+     * - Complete buildAPI result tree (primary storage)
+     */
+    api: Object;
+    /**
+     * - Source folder path
+     */
+    folderPath: string;
+    /**
+     * - Loading mode: 'lazy' or 'eager'
+     */
+    mode: string;
+    /**
+     * - Sanitization configuration
+     */
+    sanitizeOptions: Object;
+    /**
+     * - Collision handling mode
+     */
+    collisionMode: string;
+    /**
+     * - Config snapshot at add time
+     */
+    config: Object;
+    /**
+     * - Cache creation time (Unix ms)
+     */
+    timestamp: number;
+};
 import { ComponentBase } from "#factories/component-base";