@cldmv/slothlet 2.11.0 → 3.0.1

package/types/dist/lib/builders/builder.d.mts

@@ -0,0 +1,60 @@
+/**
+ * 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;
+    /**
+     * Build API from directory or file.
+     * @param {Object} options - Build options
+     * @param {string} options.dir - Directory or file to build from
+     * @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 {Function|null} [options.fileFilter=null] - Optional filter function (fileName) => boolean to load specific files only
+     * @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;
+        mode?: string;
+        ownership?: any;
+        contextManager?: any;
+        instanceID?: string;
+        config?: any;
+        apiPathPrefix?: string;
+        collisionContext?: string;
+        fileFilter?: Function | null;
+    }): Promise<any>;
+}
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=builder.d.mts.map

package/types/dist/lib/builders/builder.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.mts","sourceRoot":"","sources":["../../../../dist/lib/builders/builder.mjs"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;GAaG;AACH;IACC,gCAAoC;IAiBpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,yBA3BG;QAAwB,GAAG,EAAnB,MAAM;QACW,IAAI,GAArB,MAAM;QACW,SAAS;QACT,cAAc;QACd,UAAU,GAA3B,MAAM;QACW,MAAM;QACN,aAAa,GAA9B,MAAM;QACW,gBAAgB,GAAjC,MAAM;QACkB,UAAU,GAAlC,WAAS,IAAI;KACrB,GAAU,OAAO,KAAQ,CA+E3B;CACD;8BA9H6B,0CAA0C"}

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

@@ -0,0 +1,32 @@
+/**
+ * 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?: any, sourceFolder?: any, cacheBust?: any, collisionModeOverride?: any): Promise<any>;
+    /**
+     * Create lazy wrapper for subdirectory (lazy mode only)
+     * @param {Object} dir - Directory structure
+     * @param {string} apiPath - Current API path
+     * @param {Object} config - Configuration
+     * @returns {Proxy} Lazy unified wrapper
+     * @public
+     */
+    public createLazySubdirectoryWrapper(dir: any, apiPath: string, moduleID?: any, sourceFolder?: any, cacheBust?: any, fileFolderCollisionImpl?: any, collisionMode?: 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: any, rootFunction: Function | null, mode: string): Promise<any | Function>;
+}
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=modes-processor.d.mts.map

package/types/dist/lib/builders/modes-processor.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modes-processor.d.mts","sourceRoot":"","sources":["../../../../dist/lib/builders/modes-processor.mjs"],"names":[],"mappings":"AA8BA;;;;;;GAMG;AACH;IACC,gCAA2C;IAS3C,6RA+3CC;IACD;;;;;;;OAOG;IACH,wDALW,MAAM,gIA6WhB;IACD;;;;;;;;OAQG;IACH,oDANW,WAAS,IAAI,QAEb,MAAM,GACJ,OAAO,CAAC,cAAe,CAAC,CAoBpC;CACD;8BAjyD6B,0CAA0C"}

package/types/dist/lib/errors.d.mts

@@ -0,0 +1,118 @@
+/**
+ * Custom error class for Slothlet-specific errors with context and i18n
+ * @public
+ */
+export class SlothletError extends Error {
+    /**
+     * 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 {Error} [originalError] - The original error that caused this SlothletError
+     * @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
+     */
+    constructor(code: string, context?: {
+        validationError?: boolean;
+        stub?: boolean;
+    }, originalError?: Error, options?: {
+        validationError?: boolean;
+        stub?: boolean;
+    });
+    /**
+     * Prevent JSON serialization of context (cleaner error display)
+     * @returns {Object} Simplified error object
+     */
+    toJSON(): any;
+}
+/**
+ * Warning class for non-fatal issues with i18n support
+ * @public
+ */
+export class SlothletWarning {
+    static captured: any[];
+    static suppressConsole: boolean;
+    /**
+     * 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;
+    });
+    name: string;
+    code: string;
+    message: string;
+    context: {
+        key?: string;
+    };
+    /**
+     * 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?: any);
+    config: any;
+    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;
+        message?: string;
+    }): void;
+    /**
+     * Custom string representation
+     * @returns {string} Debug info
+     */
+    toString(): string;
+}
+//# sourceMappingURL=errors.d.mts.map

package/types/dist/lib/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","sourceRoot":"","sources":["../../../dist/lib/errors.mjs"],"names":[],"mappings":"AAqBA;;;GAGG;AACH;IACC;;;;;;;;;;;OAWG;IACH,kBAVW,MAAM,YAEd;QAA0B,eAAe,GAAjC,OAAO;QACW,IAAI,GAAtB,OAAO;KACf,kBAAQ,KAAK,YAEb;QAA0B,eAAe,GAAjC,OAAO;QACW,IAAI,GAAtB,OAAO;KACf,EAkEF;IAoCD;;;OAGG;IACH,cAOC;CACD;AAED;;;GAGG;AACH;IAEC,uBAAqB;IACrB,gCAA+B;IA8C/B;;;OAGG;IACH,oCAEC;IAlDD;;;;;;;;OAQG;IACH,kBAPW,MAAM,YAEd;QAAyB,GAAG,GAApB,MAAM;KAGd,EA2BF;IAjBA,aAA6B;IAC7B,aAAgB;IAChB,gBAAgC;IAChC;cAhBU,MAAM;MAgBM;IAgBvB;;;OAGG;IACH,YAFa,MAAM,CAIlB;CASD;AAED;;;GAGG;AACH;IACC;;;;OAIG;IACH,0BAGC;IAFA,YAAoB;IACpB,gBAAoC;IAGrC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,iBA1BW,MAAM,YAEd;QAAyB,GAAG,GAApB,MAAM;QAIW,OAAO,GAAxB,MAAM;KAEd,QAoDF;IAED;;;OAGG;IACH,YAFa,MAAM,CAMlB;CACD"}

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

@@ -0,0 +1,182 @@
+/**
+ *	@Project: @cldmv/slothlet
+ *	@Filename: /src/lib/factories/component-base.mjs
+ *	@Date: 2026-01-24 09:30:16 -08:00 (1737735016)
+ *	@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-03-01 20:21:36 -08:00 (1772425296)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
+/**
+ * @fileoverview Base class for Slothlet component classes providing common Slothlet access.
+ * @module @cldmv/slothlet/factories/component-base
+ * @internal
+ * @package
+ *
+ * @description
+ * Provides common getters for all Slothlet component classes (handlers, builders, processors).
+ * All components extend this class to access the Slothlet instance's configuration and API
+ * references without passing them through function parameters. Components become modular
+ * extensions of the Slothlet class itself.
+ *
+ * @example
+ * // ESM
+ * import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+ * class MyHandler extends ComponentBase {
+ *   doSomething() {
+ *     if (this.debug?.api) {
+ *       console.log("Debug mode enabled");
+ *     }
+ *     throw new this.SlothletError("ERROR_CODE", { details: "info" });
+ *   }
+ * }
+ *
+ * @example
+ * // CJS
+ * const { ComponentBase } = require("@cldmv/slothlet/factories/component-base");
+ * class MyHandler extends ComponentBase {
+ *   doSomething() {
+ *     return this.____config.mode;
+ *   }
+ * }
+ */
+/**
+ * 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>;
+    /**
+     * 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;
+    #private;
+}
+//# sourceMappingURL=component-base.d.mts.map

package/types/dist/lib/factories/component-base.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-base.d.mts","sourceRoot":"","sources":["../../../../dist/lib/factories/component-base.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAuHC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,sBAHU,GAAG,CAAC,MAAM,CAAC,CAoClB;IAhKH;;;;;;;;;;;;OAYG;IACH,sBAXW,MAAM,EAahB;IAED;;;;;;;;;;;;OAYG;IACH,oBAXa,MAAM,CAalB;IAED;;;;;;;;;;;OAWG;IACH,gBAVa,MAAM,CAYlB;IAED;;;;;;;;;;;OAWG;IACH,kBAVa,MAAM,CAYlB;IAED;;;;OAIG;IACH,kBAHa,MAAM,CAKlB;IAED;;;;;;;;;;;OAWG;IACH,8BAEC;IAED;;;;;;;;;;;OAWG;IACH,gCAEC;;CAwDD"}

package/types/dist/lib/factories/context.d.mts

@@ -0,0 +1,26 @@
+/**
+ * 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): any;
+/**
+ * Default context manager (async)
+ * @public
+ */
+export const contextManager: import("@cldmv/slothlet/handlers/context-async").AsyncContextManager;
+/**
+ * Async runtime for runtime exports
+ * @public
+ */
+export const asyncRuntime: import("@cldmv/slothlet/handlers/context-async").AsyncContextManager;
+/**
+ * Live runtime for runtime exports
+ * @public
+ */
+export const liveRuntime: import("@cldmv/slothlet/handlers/context-live").LiveContextManager;
+import { asyncContextManager } from "@cldmv/slothlet/handlers/context-async";
+import { liveContextManager } from "@cldmv/slothlet/handlers/context-live";
+export { asyncContextManager, liveContextManager };
+//# sourceMappingURL=context.d.mts.map

package/types/dist/lib/factories/context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.mts","sourceRoot":"","sources":["../../../../dist/lib/factories/context.mjs"],"names":[],"mappings":"AAqBA;;;;;GAKG;AACH,4CAJW,MAAM,OAMhB;AAED;;;GAGG;AACH,kGAAkD;AAElD;;;GAGG;AACH,gGAAgD;AAEhD;;;GAGG;AACH,6FAA8C;oCA7BV,wCAAwC;mCACzC,uCAAuC"}

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

@@ -0,0 +1,208 @@
+/**
+ * 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;
+    /**
+     * 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: any;
+    /**
+     * - Source folder path
+     */
+    folderPath: string;
+    /**
+     * - Loading mode: 'lazy' or 'eager'
+     */
+    mode: string;
+    /**
+     * - Sanitization configuration
+     */
+    sanitizeOptions: any;
+    /**
+     * - Collision handling mode
+     */
+    collisionMode: string;
+    /**
+     * - Config snapshot at add time
+     */
+    config: any;
+    /**
+     * - Cache creation time (Unix ms)
+     */
+    timestamp: number;
+};
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=api-cache-manager.d.mts.map

package/types/dist/lib/handlers/api-cache-manager.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-cache-manager.d.mts","sourceRoot":"","sources":["../../../../dist/lib/handlers/api-cache-manager.mjs"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;GAcG;AACH;IACC,gCAA4C;IAU3C;;;;OAIG;IACH,eAAuB;IAGxB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,qBAtBW,MAAM,SACN,UAAU,GACR,IAAI,CAyDhB;IAED;;;;;;;;;;;OAWG;IACH,qBAVW,MAAM,GACJ,UAAU,GAAC,SAAS,CAWhC;IAED;;;;;;;;;;OAUG;IACH,qBATW,MAAM,GACJ,OAAO,CAUnB;IAED;;;;;;;;;;;OAWG;IACH,wBAVW,MAAM,GACJ,OAAO,CAoBnB;IAED;;;;;;;;OAQG;IACH,0BAPa,MAAM,EAAE,CASpB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,8BAjBa,MAAM,CAsClB;IAED;;;;;;OAMG;IACH,oBAsBC;IAED;;;;;;;;;;OAUG;IACH,gBATa,IAAI,CAehB;IAED;;;;;;;;;;;;;OAaG;IACH,8BAZW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CA8D3B;CACD;;;;;;;;cA/Ua,MAAM;;;;cACN,MAAM;;;;;;;;gBAEN,MAAM;;;;UACN,MAAM;;;;;;;;mBAEN,MAAM;;;;;;;;eAEN,MAAM;;8BAbU,0CAA0C"}