@cldmv/slothlet 2.10.0 → 3.0.0

package/types/dist/lib/helpers/metadata-api.d.mts

@@ -1,132 +0,0 @@
-export namespace metadataAPI {
-    /**
-     * Get metadata of the function that called the current function.
-     *
-     * @function caller
-     * @memberof metadataAPI
-     * @returns {object|null} Caller's metadata object or null if not found
-     * @public
-     *
-     * @description
-     * Uses stack trace analysis to identify the calling function and retrieve
-     * its attached metadata. Useful for implementing access control where a
-     * function needs to verify the identity/permissions of its caller.
-     *
-     * Stack trace structure:
-     * - Line 0: Error
-     * - Line 1: metadataAPI.caller (this function)
-     * - Line 2: Current function (the one checking)
-     * - Line 3: The caller we want to identify
-     *
-     * @example
-     * // In a secure function
-     * import { metadataAPI } from "@cldmv/slothlet/runtime";
-     *
-     * export function getSecrets() {
-     *     const caller = metadataAPI.caller();
-     *
-     *     if (!caller?.trusted) {
-     *         throw new Error("Access denied: untrusted caller");
-     *     }
-     *
-     *     if (!caller.permissions?.includes("read_secrets")) {
-     *         throw new Error("Access denied: insufficient permissions");
-     *     }
-     *
-     *     return { apiKey: "secret123", token: "xyz" };
-     * }
-     *
-     * @example
-     * // With custom metadata tags
-     * const caller = metadataAPI.caller();
-     * console.log("Caller source:", caller?.sourceFolder);
-     * console.log("Caller version:", caller?.version);
-     * console.log("Caller author:", caller?.author);
-     */
-    function caller(): object | null;
-    /**
-     * Get metadata of the current function.
-     *
-     * @function self
-     * @memberof metadataAPI
-     * @returns {object|null} Current function's metadata or null if not found
-     * @public
-     *
-     * @description
-     * Retrieves metadata attached to the currently executing function. Useful
-     * for functions that need to inspect their own metadata (e.g., for logging,
-     * conditional behavior based on load source).
-     *
-     * Stack trace structure:
-     * - Line 0: Error
-     * - Line 1: metadataAPI.self (this function)
-     * - Line 2: Current function (the one we want to identify)
-     *
-     * @example
-     * // Function checking its own metadata
-     * import { metadataAPI } from "@cldmv/slothlet/runtime";
-     *
-     * export function smartFunction() {
-     *     const meta = metadataAPI.self();
-     *
-     *     if (meta?.environment === "development") {
-     *         console.log("Running in development mode");
-     *     }
-     *
-     *     if (meta?.version) {
-     *         console.log(`Function version: ${meta.version}`);
-     *     }
-     *
-     *     return "result";
-     * }
-     */
-    function self(): object | null;
-    /**
-     * Get metadata of any function by API path.
-     *
-     * @function get
-     * @memberof metadataAPI
-     * @param {string} path - Dot-notation API path (e.g., "math.add", "plugins.helper")
-     * @param {object} [apiRoot] - Optional API root object (uses runtime.self if not provided)
-     * @returns {object|null} Function's metadata or null if not found
-     * @public
-     *
-     * @description
-     * Retrieves metadata for any function in the API tree by its path. Useful
-     * for checking metadata of functions you have references to, or for
-     * administrative/introspection purposes.
-     *
-     * @example
-     * // Check metadata of a specific function
-     * import { metadataAPI } from "@cldmv/slothlet/runtime";
-     *
-     * export function checkPermissions() {
-     *     const pluginMeta = metadataAPI.get("plugins.userPlugin");
-     *
-     *     if (!pluginMeta) {
-     *         throw new Error("Plugin not found or has no metadata");
-     *     }
-     *
-     *     if (pluginMeta.trusted) {
-     *         console.log("Plugin is trusted");
-     *     } else {
-     *         console.log("Plugin is untrusted");
-     *     }
-     * }
-     *
-     * @example
-     * // Iterate and check all plugins
-     * const pluginPaths = ["plugins.auth", "plugins.logger", "plugins.cache"];
-     * for (const path of pluginPaths) {
-     *     const meta = metadataAPI.get(path);
-     *     console.log(`${path}: ${meta?.version || "unknown"}`);
-     * }
-     *
-     * @example
-     * // From outside slothlet context, pass API root explicitly
-     * const api = await slothlet({ dir: "./modules" });
-     * const meta = await metadataAPI.get("plugins.helper", api);
-     */
-    function get(path: string, apiRoot?: object): object | null;
-}
-//# sourceMappingURL=metadata-api.d.mts.map

package/types/dist/lib/helpers/metadata-api.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"metadata-api.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/metadata-api.mjs"],"names":[],"mappings":";IAmNC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,mBAvCa,MAAM,GAAC,IAAI,CAgEvB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,iBA/Ba,MAAM,GAAC,IAAI,CAsDvB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,mBAzCW,MAAM,YACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAsDvB"}

package/types/dist/lib/helpers/multidefault.d.mts

@@ -1,90 +0,0 @@
-/**
- * Analyzes module files to detect multi-default and self-referential patterns.
- * @internal
- * @private
- * @param {Array<{name: string}>} moduleFiles - Array of module file objects with name property
- * @param {string} baseDir - Base directory path containing the modules
- * @param {object} [options={}] - Configuration options
- * @param {boolean} [options.debug=false] - Enable debug logging
- * @param {object|null} [options.instance=null] - Slothlet instance for cache isolation
- * @returns {Promise<{
- *   totalDefaultExports: number,
- *   hasMultipleDefaultExports: boolean,
- *   selfReferentialFiles: Set<string>,
- *   rawModuleCache: Map<string, object>,
- *   defaultExportFiles: Array<{fileName: string, rawModule: object}>
- * }>} Analysis results
- * @example // Internal usage in slothlet modes
- * const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, { debug: config.debug, instance });
- * if (analysis.hasMultipleDefaultExports) {
- *   // Handle multi-default context
- * }
- */
-export function multidefault_analyzeModules(moduleFiles: Array<{
-    name: string;
-}>, baseDir: string, options?: {
-    debug?: boolean;
-    instance?: object | null;
-}): Promise<{
-    totalDefaultExports: number;
-    hasMultipleDefaultExports: boolean;
-    selfReferentialFiles: Set<string>;
-    rawModuleCache: Map<string, object>;
-    defaultExportFiles: Array<{
-        fileName: string;
-        rawModule: object;
-    }>;
-}>;
-/**
- * Checks if a raw module's default export is self-referential (points to a named export).
- * @internal
- * @private
- * @param {object} rawModule - Raw module object to check
- * @returns {boolean} True if default export points to a named export
- * @example // Internal usage
- * const isSelfRef = multidefault_isSelfReferential(rawModule);
- */
-export function multidefault_isSelfReferential(rawModule: object): boolean;
-/**
- * Determines auto-flattening behavior based on multi-default context and module structure.
- * @internal
- * @private
- * @param {object} options - Configuration options
- * @param {boolean} options.hasMultipleDefaultExports - Whether multiple default exports exist
- * @param {boolean} options.moduleHasDefault - Whether current module has default export
- * @param {boolean} options.isSelfReferential - Whether current module is self-referential
- * @param {Array<string>} options.moduleKeys - Named export keys from the module
- * @param {string} options.apiPathKey - API key for the module
- * @param {number} options.totalModuleCount - Total number of modules in directory
- * @param {boolean} [options.debug=false] - Enable debug logging
- * @returns {{
- *   shouldFlatten: boolean,
- *   flattenToRoot: boolean,
- *   preserveAsNamespace: boolean,
- *   reason: string
- * }} Flattening decision and reasoning
- * @example // Internal usage in processing logic
- * const decision = multidefault_getFlatteningDecision({
- *   hasMultipleDefaultExports: true,
- *   moduleHasDefault: false,
- *   isSelfReferential: false,
- *   moduleKeys: ["add", "subtract"],
- *   apiPathKey: "math",
- *   totalModuleCount: 3
- * });
- */
-export function multidefault_getFlatteningDecision(options: {
-    hasMultipleDefaultExports: boolean;
-    moduleHasDefault: boolean;
-    isSelfReferential: boolean;
-    moduleKeys: Array<string>;
-    apiPathKey: string;
-    totalModuleCount: number;
-    debug?: boolean;
-}): {
-    shouldFlatten: boolean;
-    flattenToRoot: boolean;
-    preserveAsNamespace: boolean;
-    reason: string;
-};
-//# sourceMappingURL=multidefault.d.mts.map

package/types/dist/lib/helpers/multidefault.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"multidefault.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/multidefault.mjs"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yDAlBW,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,WACrB,MAAM,YAEd;IAA0B,KAAK,GAAvB,OAAO;IACe,QAAQ,GAA9B,MAAM,GAAC,IAAI;CACnB,GAAU,OAAO,CAAC;IAChB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yBAAyB,EAAE,OAAO,CAAC;IACnC,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,kBAAkB,EAAE,KAAK,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CACjE,CAAC,CAuGJ;AAED;;;;;;;;GAQG;AACH,0DALW,MAAM,GACJ,OAAO,CAWnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4DAvBG;IAAyB,yBAAyB,EAA1C,OAAO;IACU,gBAAgB,EAAjC,OAAO;IACU,iBAAiB,EAAlC,OAAO;IACgB,UAAU,EAAjC,KAAK,CAAC,MAAM,CAAC;IACG,UAAU,EAA1B,MAAM;IACU,gBAAgB,EAAhC,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU;IACR,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAA;CACf,CA4FH"}

package/types/dist/lib/modes/slothlet_eager.d.mts

@@ -1,65 +0,0 @@
-/**
- * @function eager_wrapWithRunCtx
- * @internal
- * @package
- * @alias module:@cldmv/slothlet.modes.eager.eager_wrapWithRunCtx
- * @memberof module:@cldmv/slothlet.modes.eager
- * @param {*} obj - The object/function to wrap
- * @param {object} instance - The slothlet instance that will have boundapi.__ctx attached
- * @returns {*} The wrapped object/function
- *
- * @description
- * Recursively wraps all functions in an object with runWithCtx for eager mode.
- * This makes eager mode use the same call stack optimization as lazy mode.
- *
- * @example
- * // Wrapping a function
- * const wrappedFn = eager_wrapWithRunCtx(originalFunction, instance);
- *
- * @example
- * // Wrapping an object with nested functions
- * const wrappedObj = eager_wrapWithRunCtx({ method: fn }, instance);
- *
- * @example
- * // Wrapping a function
- * const wrappedFn = eager_wrapWithRunCtx(originalFunction, instance);
- *
- * @example
- * // Wrapping an object with nested functions
- * const wrappedObj = eager_wrapWithRunCtx({ method: fn }, instance);
- * const wrappedFn = eager_wrapWithRunCtx(originalFunction, instance);
- *
- * @example
- * // Wrapping an object with nested functions
- * const wrappedObj = eager_wrapWithRunCtx({ method: fn }, instance);
- */
-/**
- * @function create
- * @internal
- * @package
- * @async
- * @alias module:@cldmv/slothlet.modes.eager.create
- * @memberof module:@cldmv/slothlet.modes.eager
- * @param {string} dir - Directory to load
- * @param {number} [maxDepth=Infinity] - Maximum depth to traverse
- * @param {number} [currentDepth=0] - Current traversal depth
- * @returns {Promise<object>} Complete API object with all modules loaded
- * @throws {Error} When module loading or directory traversal fails
- *
- * @description
- * Creates the eager API for slothlet (mode: eager).
- * Immediately loads all modules and constructs the complete API structure.
- *
- * @example
- * // Internal usage - called by slothlet core
- * const api = await create('./api_test', 3, 0);
- * // Returns: { math: { add: [Function], multiply: [Function] }, ... }
- *
- * @example
- * // Root-level processing with function exports
- * const api = await create('./api_test');
- * // If root has default function: api becomes that function with properties
- * // Otherwise: api is object with module properties
- */
-export function create(dir: string, maxDepth?: number, currentDepth?: number): Promise<object>;
-//# sourceMappingURL=slothlet_eager.d.mts.map

package/types/dist/lib/modes/slothlet_eager.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"slothlet_eager.d.mts","sourceRoot":"","sources":["../../../../dist/lib/modes/slothlet_eager.mjs"],"names":[],"mappings":"AA4IA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAsDH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4BArBW,MAAM,aACN,MAAM,iBACN,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAgH3B"}

package/types/dist/lib/modes/slothlet_lazy.d.mts

@@ -1,31 +0,0 @@
-/**
- * @function create
- * @internal
- * @package
- * @async
- * @alias module:@cldmv/slothlet.modes.lazy.create
- * @memberof module:@cldmv/slothlet.modes.lazy
- * @param {string} dir - Root directory
- * @param {number} [maxDepth=Infinity] - Maximum depth to traverse
- * @param {number} [currentDepth=0] - Current depth (for internal recursion only)
- * @returns {Promise<function|object>} Root API object or function (if default export)
- * @throws {Error} When module loading or directory traversal fails
- *
- * @description
- * Creates a lazy API structure. Root-level files are loaded immediately (mirrors eager).
- * Directories become lazy proxies. Nested directories remain lazy after materialization
- * via _buildCategory recursion with subdirHandler.
- *
- * @example
- * // Internal usage - called by slothlet core
- * const api = await create('./api_test', 3, 0);
- * // Returns: { math: [Function: lazyFolder_math], ... } (lazy proxies)
- *
- * @example
- * // Root-level processing with function exports
- * const api = await create('./api_test');
- * // If root has default function: api becomes that function with properties
- * // Otherwise: api is object with lazy proxy properties
- */
-export function create(dir: string, maxDepth?: number, currentDepth?: number): Promise<Function | object>;
-//# sourceMappingURL=slothlet_lazy.d.mts.map

package/types/dist/lib/modes/slothlet_lazy.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"slothlet_lazy.d.mts","sourceRoot":"","sources":["../../../../dist/lib/modes/slothlet_lazy.mjs"],"names":[],"mappings":"AAgKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,4BAtBW,MAAM,aACN,MAAM,iBACN,MAAM,GACJ,OAAO,CAAC,WAAS,MAAM,CAAC,CAkKpC"}