@cldmv/slothlet 2.4.3 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/slothlet",
-	"version": "2.4.3",
+	"version": "2.5.0",
 	"moduleVersions": {
 		"lazy": "1.3.0",
 		"eager": "1.3.0"
@@ -53,6 +53,7 @@
 	},
 	"types": "./types/index.d.mts",
 	"scripts": {
+		"precommit": "node tools/precommit-validation.mjs",
 		"publish:manual": "npm publish --access public",
 		"test": "node tests/test-conditional.mjs",
 		"test:pre-build": "node tests/test-conditional.mjs",

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

@@ -0,0 +1,446 @@
+/**
+ * Analyzes a module and returns processing decisions that both eager and lazy modes can use.
+ * This centralizes the module loading logic from _loadSingleModule while allowing each mode
+ * to handle the results according to their strategy (immediate materialization vs proxy creation).
+ * @function analyzeModule
+ * @internal
+ * @package
+ * @param {string} modulePath - Absolute path to the module file
+ * @param {object} options - Analysis options
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @param {object} [options.instance] - Slothlet instance for accessing config and methods
+ * @returns {Promise<{
+ *   rawModule: object,
+ *   processedModule: object,
+ *   isFunction: boolean,
+ *   hasDefault: boolean,
+ *   isCjs: boolean,
+ *   exports: Array<[string, any]>,
+ *   defaultExportType: 'function'|'object'|null,
+ *   shouldWrapAsCallable: boolean,
+ *   namedExports: object,
+ *   metadata: object
+ * }>} Module analysis results
+ * @example
+ * // Analyze a module file
+ * const analysis = await analyzeModule("./api/math.mjs", { instance });
+ * // Eager mode: use analysis.processedModule directly
+ * // Lazy mode: create proxy based on analysis.isFunction, analysis.exports, etc.
+ */
+export function analyzeModule(modulePath: string, options?: {
+    debug?: boolean;
+    instance?: object;
+}): Promise<{
+    rawModule: object;
+    processedModule: object;
+    isFunction: boolean;
+    hasDefault: boolean;
+    isCjs: boolean;
+    exports: Array<[string, any]>;
+    defaultExportType: "function" | "object" | null;
+    shouldWrapAsCallable: boolean;
+    namedExports: object;
+    metadata: object;
+}>;
+/**
+ * Processes module analysis results into a final module object using slothlet's established patterns.
+ * This centralizes the processing logic while allowing both modes to apply the results differently.
+ * @function processModuleFromAnalysis
+ * @internal
+ * @package
+ * @param {object} analysis - Results from analyzeModule
+ * @param {object} options - Processing options
+ * @param {object} [options.instance] - Slothlet instance for accessing _toapiPathKey method
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {object} Processed module ready for API integration
+ * @example
+ * // Process analyzed module
+ * const analysis = await analyzeModule(modulePath, { instance });
+ * const processed = processModuleFromAnalysis(analysis, { instance });
+ * // Both modes can use 'processed' but integrate it differently
+ */
+export function processModuleFromAnalysis(analysis: object, options?: {
+    instance?: object;
+    debug?: boolean;
+}): object;
+/**
+ * Analyzes a directory and returns structural decisions that both eager and lazy modes can use.
+ * This provides the decision-making logic for directory handling without implementing the actual
+ * loading strategy (allowing lazy mode to create proxies while eager mode materializes).
+ * @function analyzeDirectoryStructure
+ * @internal
+ * @package
+ * @param {string} categoryPath - Absolute path to the directory
+ * @param {object} options - Analysis options
+ * @param {object} options.instance - Slothlet instance for accessing config and methods
+ * @param {number} [options.currentDepth=0] - Current traversal depth
+ * @param {number} [options.maxDepth=Infinity] - Maximum traversal depth
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {Promise<{
+ *   isSingleFile: boolean,
+ *   shouldAutoFlatten: boolean,
+ *   categoryName: string,
+ *   moduleFiles: Array<import('fs').Dirent>,
+ *   subDirs: Array<import('fs').Dirent>,
+ *   multiDefaultAnalysis: object,
+ *   processingStrategy: 'single-file'|'multi-file'|'empty',
+ *   flatteningHints: object
+ * }>} Directory structure analysis
+ * @example
+ * // Analyze directory structure
+ * const analysis = await analyzeDirectoryStructure(categoryPath, { instance });
+ * if (analysis.isSingleFile) {
+ *   // Both modes: handle as single file (but differently)
+ * } else {
+ *   // Both modes: handle as multi-file (but differently)
+ * }
+ */
+export function analyzeDirectoryStructure(categoryPath: string, options?: {
+    instance: object;
+    currentDepth?: number;
+    maxDepth?: number;
+    debug?: boolean;
+}): Promise<{
+    isSingleFile: boolean;
+    shouldAutoFlatten: boolean;
+    categoryName: string;
+    moduleFiles: Array<import("fs").Dirent>;
+    subDirs: Array<import("fs").Dirent>;
+    multiDefaultAnalysis: object;
+    processingStrategy: "single-file" | "multi-file" | "empty";
+    flatteningHints: object;
+}>;
+/**
+ * Returns category building decisions and processed modules that both eager and lazy modes can use.
+ * This provides all the structural information needed to build a category but lets each mode
+ * implement the actual building strategy (materialization vs proxy creation).
+ * @function getCategoryBuildingDecisions
+ * @internal
+ * @package
+ * @param {string} categoryPath - Absolute path to the directory
+ * @param {object} options - Building options
+ * @param {object} options.instance - Slothlet instance for accessing config and methods
+ * @param {number} [options.currentDepth=0] - Current traversal depth
+ * @param {number} [options.maxDepth=Infinity] - Maximum traversal depth
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {Promise<{
+ *   processingStrategy: 'single-file'|'multi-file'|'empty',
+ *   categoryName: string,
+ *   shouldFlattenSingle: boolean,
+ *   processedModules: Array<{file: import('fs').Dirent, moduleName: string, processedModule: any, flattening: object}>,
+ *   subDirectories: Array<{dirEntry: import('fs').Dirent, apiPathKey: string}>,
+ *   multiDefaultAnalysis: object,
+ *   flatteningDecisions: object,
+ *   upwardFlatteningCandidate: {shouldFlatten: boolean, apiPathKey: string}
+ * }>} Complete category building information
+ * @example
+ * // Get category building decisions
+ * const decisions = await getCategoryBuildingDecisions(categoryPath, { instance });
+ * if (decisions.processingStrategy === "single-file") {
+ *   // Both modes: handle single file differently
+ *   // Eager: return decisions.processedModules[0].processedModule
+ *   // Lazy: create proxy based on decisions.processedModules[0].flattening
+ * }
+ */
+export function getCategoryBuildingDecisions(categoryPath: string, options?: {
+    instance: object;
+    currentDepth?: number;
+    maxDepth?: number;
+    debug?: boolean;
+}): Promise<{
+    processingStrategy: "single-file" | "multi-file" | "empty";
+    categoryName: string;
+    shouldFlattenSingle: boolean;
+    processedModules: Array<{
+        file: import("fs").Dirent;
+        moduleName: string;
+        processedModule: any;
+        flattening: object;
+    }>;
+    subDirectories: Array<{
+        dirEntry: import("fs").Dirent;
+        apiPathKey: string;
+    }>;
+    multiDefaultAnalysis: object;
+    flatteningDecisions: object;
+    upwardFlatteningCandidate: {
+        shouldFlatten: boolean;
+        apiPathKey: string;
+    };
+}>;
+/**
+ * Auto-flattening decision logic that determines whether a module should be flattened
+ * based on filename matching, export patterns, and context.
+ * @function getFlatteningDecision
+ * @internal
+ * @package
+ * @param {object} options - Flattening analysis options
+ * @param {object} options.mod - The loaded module object
+ * @param {string} options.fileName - Original filename (without extension)
+ * @param {string} options.apiPathKey - Sanitized API key for the module
+ * @param {boolean} options.hasMultipleDefaultExports - Whether multiple default exports exist in the container
+ * @param {boolean} options.isSelfReferential - Whether this is a self-referential export
+ * @param {boolean} [options.moduleHasDefault] - Whether this specific module has a default export
+ * @param {string} [options.categoryName] - Container/category name for context
+ * @param {number} [options.totalModules=1] - Total number of modules in container
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {{
+ *   shouldFlatten: boolean,
+ *   flattenToRoot: boolean,
+ *   flattenToCategory: boolean,
+ *   preserveAsNamespace: boolean,
+ *   useAutoFlattening: boolean,
+ *   reason: string
+ * }} Flattening decision result
+ *
+ * @description
+ * Determines flattening behavior based on slothlet's established rules:
+ *
+ * 1. Self-referential exports: Never flatten (preserve as namespace)
+ * 2. Multi-default context: Flatten modules WITHOUT defaults, preserve WITH defaults
+ * 3. Single named export matching filename: Auto-flatten to use export directly
+ * 4. Filename matches container: Flatten contents to container level
+ * 5. Traditional context: Preserve as namespace unless auto-flattening applies
+ *
+ * @example
+ * // Internal usage - single named export matching filename
+ * const decision = getFlatteningDecision({
+ *   mod: { math: { add: fn, multiply: fn } },
+ *   fileName: "math", apiPathKey: "math",
+ *   hasMultipleDefaultExports: false, isSelfReferential: false
+ * });
+ * // Returns: { shouldFlatten: true, useAutoFlattening: true, reason: "auto-flatten single named export" }
+ */
+export function getFlatteningDecision(options: {
+    mod: object;
+    fileName: string;
+    apiPathKey: string;
+    hasMultipleDefaultExports: boolean;
+    isSelfReferential: boolean;
+    moduleHasDefault?: boolean;
+    categoryName?: string;
+    totalModules?: number;
+    debug?: boolean;
+}): {
+    shouldFlatten: boolean;
+    flattenToRoot: boolean;
+    flattenToCategory: boolean;
+    preserveAsNamespace: boolean;
+    useAutoFlattening: boolean;
+    reason: string;
+};
+/**
+ * Processes a single module and applies it to the target API object based on flattening decisions.
+ * @function processModuleForAPI
+ * @internal
+ * @package
+ * @param {object} options - Module processing options
+ * @param {object} options.mod - The loaded module object
+ * @param {string} options.fileName - Original filename (without extension)
+ * @param {string} options.apiPathKey - Sanitized API key for the module
+ * @param {boolean} options.hasMultipleDefaultExports - Whether multiple default exports exist
+ * @param {boolean} options.isSelfReferential - Whether this is a self-referential export
+ * @param {object} options.api - Target API object to modify (could be root api or categoryModules)
+ * @param {function} [options.getRootDefault] - Function to get current root default function
+ * @param {function} [options.setRootDefault] - Function to set the root default function
+ * @param {object} [options.context] - Processing context
+ * @param {boolean} [options.context.debug=false] - Enable debug logging
+ * @param {string} [options.context.mode="unknown"] - Processing mode (root, subfolder, eager, lazy)
+ * @param {string} [options.context.categoryName] - Container/category name
+ * @param {number} [options.context.totalModules=1] - Total modules in container
+ * @returns {{
+ *   processed: boolean,
+ *   rootDefaultSet: boolean,
+ *   flattened: boolean,
+ *   namespaced: boolean,
+ *   apiAssignments: Record<string, any>
+ * }} Processing result
+ *
+ * @description
+ * Unified module processing logic that handles:
+ * 1. Function default exports (multi-default, self-referential, traditional root contributor)
+ * 2. Object/named exports with flattening decisions
+ * 3. Export merging and namespace assignments
+ * 4. Function name preference logic
+ * 5. Root default function management
+ *
+ * @example
+ * // Internal usage for root-level processing
+ * const result = processModuleForAPI({
+ *   mod, fileName, apiPathKey, hasMultipleDefaultExports, isSelfReferential, api,
+ *   getRootDefault: () => rootDefaultFunction,
+ *   setRootDefault: (fn) => { rootDefaultFunction = fn; },
+ *   context: { debug: true, mode: "root", totalModules: 3 }
+ * });
+ */
+export function processModuleForAPI(options: {
+    mod: object;
+    fileName: string;
+    apiPathKey: string;
+    hasMultipleDefaultExports: boolean;
+    isSelfReferential: boolean;
+    api: object;
+    getRootDefault?: Function;
+    setRootDefault?: Function;
+    context?: {
+        debug?: boolean;
+        mode?: string;
+        categoryName?: string;
+        totalModules?: number;
+    };
+}): {
+    processed: boolean;
+    rootDefaultSet: boolean;
+    flattened: boolean;
+    namespaced: boolean;
+    apiAssignments: Record<string, any>;
+};
+/**
+ * Handles function name preference logic for better API naming.
+ * @function applyFunctionNamePreference
+ * @internal
+ * @package
+ * @param {object} options - Name preference options
+ * @param {object} options.mod - The loaded module object
+ * @param {string} options.fileName - Original filename (without extension)
+ * @param {string} options.apiPathKey - Sanitized API key
+ * @param {object} options.categoryModules - Target category modules object
+ * @param {function} options.toapiPathKey - Function to sanitize names to API keys
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {{hasPreferredName: boolean, preferredKey: string}} Name preference result
+ *
+ * @description
+ * Implements slothlet's function name preference logic where the original function name
+ * is preferred over the sanitized filename when they represent the same semantic meaning
+ * but have different capitalization (e.g., autoIP vs autoIp, parseJSON vs parseJson).
+ *
+ * @example
+ * // Internal usage in _buildCategory
+ * const preference = applyFunctionNamePreference({
+ *   mod: { autoIP: function autoIP() {} },
+ *   fileName: "auto-ip", apiPathKey: "autoIp",
+ *   categoryModules, toapiPathKey: this._toapiPathKey, debug: true
+ * });
+ * // Returns: { hasPreferredName: true, preferredKey: "autoIP" }
+ */
+export function applyFunctionNamePreference(options: {
+    mod: object;
+    fileName: string;
+    apiPathKey: string;
+    categoryModules: object;
+    toapiPathKey: Function;
+    debug?: boolean;
+}): {
+    hasPreferredName: boolean;
+    preferredKey: string;
+};
+/**
+ * Comprehensive category/directory building function that replaces _buildCategory.
+ * Handles complete directory structure processing with all flattening rules.
+ * @function buildCategoryStructure
+ * @internal
+ * @package
+ * @async
+ * @param {string} categoryPath - Absolute path to the category directory
+ * @param {object} options - Building options
+ * @param {number} [options.currentDepth=0] - Current recursion depth
+ * @param {number} [options.maxDepth=Infinity] - Maximum recursion depth
+ * @param {string} [options.mode="eager"] - Loading mode ("eager" or "lazy")
+ * @param {function} [options.subdirHandler] - Custom subdirectory handler for lazy mode
+ * @param {object} options.instance - Slothlet instance for access to helper methods
+ * @returns {Promise<object>} Complete category API structure
+ *
+ * @description
+ * Complete directory structure building pipeline that handles:
+ * - Single-file vs multi-file directory processing
+ * - Auto-flattening decisions for single files matching directory names
+ * - Multi-default export detection and processing
+ * - Self-referential export handling
+ * - Recursive subdirectory traversal with depth control
+ * - Function name preference over sanitized names
+ * - All established slothlet flattening rules and conventions
+ *
+ * @example
+ * // Internal usage - build complete category structure
+ * const categoryApi = await buildCategoryStructure("/path/to/category", {
+ *   currentDepth: 0, maxDepth: 3, mode: "eager", instance: slothletInstance
+ * });
+ */
+export function buildCategoryStructure(categoryPath: string, options?: {
+    currentDepth?: number;
+    maxDepth?: number;
+    mode?: string;
+    subdirHandler?: Function;
+    instance: object;
+}): Promise<object>;
+/**
+ * Comprehensive root API building function that replaces eager/lazy create methods.
+ * Handles complete root-level API construction with mode-specific optimizations.
+ * @function buildRootAPI
+ * @internal
+ * @package
+ * @async
+ * @param {string} dir - Root directory path to build API from
+ * @param {object} options - Building options
+ * @param {boolean} [options.lazy=false] - Whether to use lazy loading mode
+ * @param {number} [options.maxDepth=Infinity] - Maximum recursion depth
+ * @param {object} options.instance - Slothlet instance for access to helper methods
+ * @returns {Promise<object|function>} Complete root API (object or function with properties)
+ *
+ * @description
+ * Complete root API building pipeline that handles:
+ * - Root-level module processing with multi-default detection
+ * - Root contributor pattern (default function becomes callable API)
+ * - Named export merging and flattening decisions
+ * - Recursive directory structure building via buildCategoryStructure
+ * - Mode-specific optimizations (eager vs lazy)
+ * - All established slothlet API construction patterns
+ *
+ * @example
+ * // Internal usage - build complete root API
+ * const rootApi = await buildRootAPI("/path/to/api", {
+ *   lazy: false, maxDepth: 3, instance: slothletInstance
+ * });
+ */
+export function buildRootAPI(dir: string, options?: {
+    lazy?: boolean;
+    maxDepth?: number;
+    instance: object;
+}): Promise<object | Function>;
+/**
+ * Centralized category building decisions - contains ALL logic for directory/category processing.
+ * This function analyzes a directory and returns decisions about how to structure the API,
+ * but doesn't actually build the API (allowing eager/lazy modes to implement differently).
+ *
+ * @function buildCategoryDecisions
+ * @param {string} categoryPath - Path to the category directory
+ * @param {object} options - Configuration options
+ * @param {number} [options.currentDepth=0] - Current nesting depth
+ * @param {number} [options.maxDepth=Infinity] - Maximum nesting depth
+ * @param {string} [options.mode="eager"] - Loading mode ("eager" or "lazy")
+ * @param {Function} [options.subdirHandler] - Handler for subdirectories (lazy mode)
+ * @param {object} options.instance - Slothlet instance with _toapiPathKey, _shouldIncludeFile, config
+ * @returns {Promise<object>} Category building decisions and data
+ *
+ * @example // ESM usage
+ * import { buildCategoryDecisions } from "@cldmv/slothlet/helpers/api_builder";
+ * const decisions = await buildCategoryDecisions("/path/to/category", {
+ *   currentDepth: 1,
+ *   instance: slothletInstance
+ * });
+ *
+ * @example // CJS usage
+ * const { buildCategoryDecisions } = require("@cldmv/slothlet/helpers/api_builder");
+ * const decisions = await buildCategoryDecisions("/path/to/category", {
+ *   currentDepth: 1,
+ *   instance: slothletInstance
+ * });
+ */
+export function buildCategoryDecisions(categoryPath: string, options?: {
+    currentDepth?: number;
+    maxDepth?: number;
+    mode?: string;
+    subdirHandler?: Function;
+    instance: object;
+}): Promise<object>;
+//# sourceMappingURL=api_builder.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api_builder.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/api_builder.mjs"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,85 @@
+/**
+ * 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 {boolean} [debug=false] - Enable debug logging
+ * @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, config.debug);
+ * if (analysis.hasMultipleDefaultExports) {
+ *   // Handle multi-default context
+ * }
+ */
+export function multidefault_analyzeModules(moduleFiles: Array<{
+    name: string;
+}>, baseDir: string, debug?: boolean): 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

@@ -0,0 +1 @@
+{"version":3,"file":"multidefault.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/multidefault.mjs"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,yDAhBW,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,WACrB,MAAM,UACN,OAAO,GACL,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,CAsFJ;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

@@ -41,7 +41,6 @@
  * @alias module:@cldmv/slothlet.modes.eager.create
  * @memberof module:@cldmv/slothlet.modes.eager
  * @param {string} dir - Directory to load
- * @param {boolean} [rootLevel=true] - Is this the root level?
  * @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
@@ -53,14 +52,14 @@
  *
  * @example
  * // Internal usage - called by slothlet core
- * const api = await create('./api_test', true, 3, 0);
+ * 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', true);
+ * 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, rootLevel?: boolean, maxDepth?: number, currentDepth?: number): Promise<object>;
+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 +1 @@
-{"version":3,"file":"slothlet_eager.d.mts","sourceRoot":"","sources":["../../../../dist/lib/modes/slothlet_eager.mjs"],"names":[],"mappings":"AA2IA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAsDH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,4BAtBW,MAAM,cACN,OAAO,aACP,MAAM,iBACN,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAqM3B"}
+{"version":3,"file":"slothlet_eager.d.mts","sourceRoot":"","sources":["../../../../dist/lib/modes/slothlet_eager.mjs"],"names":[],"mappings":"AA0IA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAsDH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4BArBW,MAAM,aACN,MAAM,iBACN,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CA8G3B"}

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

@@ -6,7 +6,6 @@
  * @alias module:@cldmv/slothlet.modes.lazy.create
  * @memberof module:@cldmv/slothlet.modes.lazy
  * @param {string} dir - Root directory
- * @param {boolean} [rootLevel=true] - Root level flag
  * @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)
@@ -19,14 +18,14 @@
  *
  * @example
  * // Internal usage - called by slothlet core
- * const api = await create('./api_test', true, 3, 0);
+ * 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', true);
+ * 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, rootLevel?: boolean, maxDepth?: number, currentDepth?: number): Promise<Function | object>;
+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 +1 @@
-{"version":3,"file":"slothlet_lazy.d.mts","sourceRoot":"","sources":["../../../../dist/lib/modes/slothlet_lazy.mjs"],"names":[],"mappings":"AA6JA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,4BAvBW,MAAM,cACN,OAAO,aACP,MAAM,iBACN,MAAM,GACJ,OAAO,CAAC,WAAS,MAAM,CAAC,CAqMpC"}
+{"version":3,"file":"slothlet_lazy.d.mts","sourceRoot":"","sources":["../../../../dist/lib/modes/slothlet_lazy.mjs"],"names":[],"mappings":"AA+JA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,4BAtBW,MAAM,aACN,MAAM,iBACN,MAAM,GACJ,OAAO,CAAC,WAAS,MAAM,CAAC,CAqJpC"}

package/types/dist/slothlet.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AA4+CA;;;;;;;;;GASG;AACH,kDARW,WAAS,MAAM,UACf,WAAS,MAAM,QAwCzB;AAv4CD;;;;;;;GAOG;AACH,mBAJU,MAAM,CAIO;AAEvB;;;;;GAKG;AACH,sBAJU,MAAM,CAIU;AAE1B;;;;;GAKG;AACH,wBAJU,MAAM,CAIY;;;;;;;;;UA03Cd,MAAM;;;;;;WAIN,OAAO;;;;;;;eAGP,MAAM;;;;;;;;YAIN,OAAO;;;;;;;;WAKP,MAAM;;;;;;;eAKN,MAAM;;;;;;cAIN,MAAM;;;;;;gBAGN,MAAM;;;;;;eAMjB;QAA8B,UAAU,GAA7B,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACW,KAAK,GAClC;YAAqC,KAAK,GAA/B,MAAM,EAAE;YACkB,gBAAgB,GAA1C,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;SACrB;KAAA;;AAl6CD;;;;;;;;GAQG;AACH,mCAJW,eAAe,GACb,OAAO,CAAC,WAAS,MAAM,CAAC,CAiCpC"}
+{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AAyzCA;;;;;;;;;GASG;AACH,kDARW,WAAS,MAAM,UACf,WAAS,MAAM,QAwCzB;AA9sCD;;;;;;;GAOG;AACH,mBAJU,MAAM,CAIO;AAEvB;;;;;GAKG;AACH,sBAJU,MAAM,CAIU;AAE1B;;;;;GAKG;AACH,wBAJU,MAAM,CAIY;;;;;;;;;UAisCd,MAAM;;;;;;WAIN,OAAO;;;;;;;eAGP,MAAM;;;;;;;;YAIN,OAAO;;;;;;;;WAKP,MAAM;;;;;;;eAKN,MAAM;;;;;;cAIN,MAAM;;;;;;gBAGN,MAAM;;;;;;eAMjB;QAA8B,UAAU,GAA7B,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACW,KAAK,GAClC;YAAqC,KAAK,GAA/B,MAAM,EAAE;YACkB,gBAAgB,GAA1C,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;SACrB;KAAA;;AAzuCD;;;;;;;;GAQG;AACH,mCAJW,eAAe,GACb,OAAO,CAAC,WAAS,MAAM,CAAC,CAiCpC"}