@cldmv/slothlet 2.4.3 → 2.5.0

package/dist/slothlet.mjs

@@ -23,6 +23,12 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { resolvePathFromCaller } from "@cldmv/slothlet/helpers/resolve-from-caller";
 import { sanitizePathName } from "@cldmv/slothlet/helpers/sanitize";
+import {
+	processModuleForAPI,
+	analyzeModule,
+	processModuleFromAnalysis,
+	getCategoryBuildingDecisions
+} from "@cldmv/slothlet/helpers/api_builder";
 
 
 
@@ -239,9 +245,9 @@ const slothletObject = {
 
 		if (this.loaded) return this.api;
 		if (this.config.lazy) {
-			this.api = await this.modes.lazy.create.call(this, apiDir, true, this.config.apiDepth || Infinity, 0);
+			this.api = await this.modes.lazy.create.call(this, apiDir, this.config.apiDepth || Infinity, 0);
 		} else {
-			this.api = await this.modes.eager.create.call(this, apiDir, true, this.config.apiDepth || Infinity, 0);
+			this.api = await this.modes.eager.create.call(this, apiDir, this.config.apiDepth || Infinity, 0);
 		}
 		if (this.config.debug) console.log(this.api);
 
@@ -327,7 +333,7 @@ const slothletObject = {
 	},
 
 	
-	_toApiKey(name) {
+	_toapiPathKey(name) {
 		return sanitizePathName(name, this.config.sanitize || {});
 		
 	},
@@ -337,165 +343,74 @@ const slothletObject = {
 		const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler } = options;
 
 		
-		if (this.config.debug) {
-			console.log(`[DEBUG] _buildCategory called with path: ${categoryPath}, mode: ${mode}`);
-		}
-
-		const files = await fs.readdir(categoryPath, { withFileTypes: true });
-		const moduleFiles = files.filter((f) => this._shouldIncludeFile(f));
-		const categoryName = this._toApiKey(path.basename(categoryPath));
-		const subDirs = files.filter((e) => e.isDirectory() && !e.name.startsWith("."));
+		const { buildCategoryDecisions } = await import("@cldmv/slothlet/helpers/api_builder");
+		const decisions = await buildCategoryDecisions(categoryPath, {
+			currentDepth,
+			maxDepth,
+			mode,
+			subdirHandler,
+			instance: this
+		});
 
 		
-		if (moduleFiles.length === 1 && subDirs.length === 0) {
-			const moduleExt = path.extname(moduleFiles[0].name);
-			const moduleName = this._toApiKey(path.basename(moduleFiles[0].name, moduleExt));
-			const mod = await this._loadSingleModule(path.join(categoryPath, moduleFiles[0].name));
+		if (decisions.type === "single-file") {
+			const { singleFile } = decisions;
+			const { mod, moduleName } = singleFile;
 
 			
-			const functionNameMatchesFolder = typeof mod === "function" && mod.name && mod.name.toLowerCase() === categoryName.toLowerCase();
+			if (decisions.shouldFlatten) {
+				switch (decisions.flattenType) {
+					case "function-folder-match":
+					case "default-function":
+						try {
+							Object.defineProperty(mod, "name", { value: decisions.preferredName, configurable: true });
+						} catch {
+							
+						}
+						return mod;
 
-			
-			const functionNameMatchesFilename =
-				typeof mod === "function" &&
-				mod.name &&
-				this._toApiKey(mod.name).toLowerCase() === this._toApiKey(moduleName).toLowerCase() &&
-				mod.name !== this._toApiKey(moduleName);
+					case "default-export-flatten":
+						
+						return mod;
 
-			
-			
-			
-			
-			
-			
-			
+					case "object-auto-flatten":
+						
+						return mod[decisions.preferredName];
 
-			
-			if (moduleName === categoryName && typeof mod === "function") {
-				try {
-					Object.defineProperty(mod, "name", { value: categoryName, configurable: true });
-				} catch {
-					
-				}
-				return mod;
-			}
+					case "parent-level-flatten": {
+						
+						const exportValue = mod[Object.keys(mod).filter((k) => k !== "default")[0]];
+						return { [decisions.preferredName]: exportValue };
+					}
 
-			
-			if (functionNameMatchesFolder) {
-				try {
-					
-					Object.defineProperty(mod, "name", { value: mod.name, configurable: true });
-				} catch {
-					
+					case "filename-folder-match-flatten":
+						
+						return mod;
 				}
-				return mod;
 			}
 
 			
-			if (functionNameMatchesFilename) {
-				
-				
-				
-				return { [mod.name]: mod };
+			if (decisions.preferredName && decisions.preferredName !== moduleName) {
+				return { [decisions.preferredName]: mod };
 			}
 
 			
-			
-			if (
-				typeof mod === "function" &&
-				(!mod.name || mod.name === "default" || mod.__slothletDefault === true) 
-			) {
-				try {
-					Object.defineProperty(mod, "name", { value: categoryName, configurable: true });
-				} catch {
-					
-				}
-				return mod;
-			}
-			if (moduleName === categoryName && mod && typeof mod === "object" && !mod.default) {
-				return { ...mod };
+			if (this.config.debug && moduleName === "nest") {
+				console.log(`[DEBUG] Single-file default case for nest: moduleName="${moduleName}" mod keys=[${Object.keys(mod)}]`);
 			}
 			return { [moduleName]: mod };
 		}
 
 		
 		const categoryModules = {};
+		const { categoryName, processedModules, subdirectoryDecisions } = decisions;
 
 		
-		const defaultExportFiles = [];
-		const selfReferentialFiles = new Set(); 
-		const rawModuleCache = new Map(); 
-
-		
-		for (const file of moduleFiles) {
-			const moduleExt = path.extname(file.name);
-			const moduleName = this._toApiKey(path.basename(file.name, moduleExt));
-			const moduleFilePath = path.resolve(categoryPath, file.name);
-
-			
-			const rawMod = await import(`file://${moduleFilePath.replace(/\\/g, "/")}`);
-			rawModuleCache.set(file.name, rawMod);
-
-			
-			if (rawMod && "default" in rawMod) {
-				
-				const isSelfReferential = Object.entries(rawMod).some(([key, value]) => key !== "default" && value === rawMod.default);
-
-				if (this.config.debug) {
-					console.log(`[DEBUG] _buildCategory: Checking ${file.name} in ${categoryPath}`);
-					console.log(`[DEBUG]   - moduleName: ${moduleName}`);
-					console.log(`[DEBUG]   - has default: ${rawMod && "default" in rawMod}`);
-					console.log(`[DEBUG]   - isSelfReferential: ${isSelfReferential}`);
-				}
-
-				if (!isSelfReferential) {
-					
-					const processedMod = await this._loadSingleModule(path.join(categoryPath, file.name));
-					defaultExportFiles.push({ file, moduleName, mod: processedMod });
-					if (this.config.debug) {
-						console.log(`[DEBUG] Found default export in ${file.name} (non-self-referential)`);
-					}
-				} else {
-					selfReferentialFiles.add(moduleName); 
-					if (this.config.debug) {
-						console.log(`[DEBUG] Skipped ${file.name} - self-referential default export`);
-					}
-				}
-			}
-		}
-
-		const hasMultipleDefaultExports = defaultExportFiles.length > 1;
-
-		if (this.config.debug) {
-			console.log(`[DEBUG] selfReferentialFiles Set:`, Array.from(selfReferentialFiles));
-			console.log(`[DEBUG] hasMultipleDefaultExports:`, hasMultipleDefaultExports);
-		}
-
-		for (const file of moduleFiles) {
-			const moduleExt = path.extname(file.name);
-			const moduleName = this._toApiKey(path.basename(file.name, moduleExt));
-
-			
-			if (this.config.debug && moduleName === "config") {
-				console.log("[DEBUG] Processing config file:", file.name, "moduleName:", moduleName);
-				console.log("[DEBUG] selfReferentialFiles has config?", selfReferentialFiles.has(moduleName));
-			}
-
+		for (const moduleDecision of processedModules) {
+			const { moduleName, mod, type, apiPathKey, shouldFlatten, flattenType, specialHandling, processedExports } = moduleDecision;
 			
-			let mod = null;
-			const existingDefault = defaultExportFiles.find(def => def.moduleName === moduleName);
-			if (existingDefault) {
-				mod = existingDefault.mod; 
-			} else {
+			if (specialHandling === "category-merge") {
 				
-				mod = await this._loadSingleModule(path.join(categoryPath, file.name));
-			}
-
-			if (this.config.debug && moduleName === "config") {
-				console.log("[DEBUG] Config mod type:", typeof mod);
-				console.log("[DEBUG] Config mod keys:", Object.keys(mod));
-			}
-			if (moduleName === categoryName && mod && typeof mod === "object") {
 				if (
 					Object.prototype.hasOwnProperty.call(mod, categoryName) &&
 					typeof mod[categoryName] === "object" &&
@@ -503,139 +418,86 @@ const slothletObject = {
 				) {
 					Object.assign(categoryModules, mod[categoryName]);
 					for (const [key, value] of Object.entries(mod)) {
-						if (key !== categoryName) categoryModules[this._toApiKey(key)] = value;
+						if (key !== categoryName) categoryModules[this._toapiPathKey(key)] = value;
 					}
 				} else {
 					Object.assign(categoryModules, mod);
 				}
-			} else if (typeof mod === "function") {
+			} else if (type === "function") {
 				
-				const isSelfReferential = selfReferentialFiles.has(moduleName);
-
-				
-				let apiKey;
-				if (hasMultipleDefaultExports && mod.__slothletDefault === true && !isSelfReferential) {
-					
-					apiKey = moduleName;
+				if (specialHandling === "multi-default-filename") {
 					try {
 						Object.defineProperty(mod, "name", { value: moduleName, configurable: true });
 					} catch {
 						
 					}
-					if (this.config.debug) {
-						console.log(`[DEBUG] Multi-default detected: using filename '${moduleName}' for default export`);
-					}
-				} else if (selfReferentialFiles.has(moduleName)) {
-					
-					if (this.config.debug) {
-						console.log(`[DEBUG] Self-referential default export: treating ${moduleName} as namespace`);
-					}
-					
-					categoryModules[moduleName] = mod[moduleName] || mod;
-					continue; 
+					categoryModules[moduleName] = mod;
+				} else if (specialHandling === "prefer-function-name") {
+					categoryModules[apiPathKey] = mod;
 				} else {
 					
-					const fnName = mod.name && mod.name !== "default" ? mod.name : moduleName;
-					try {
-						Object.defineProperty(mod, "name", { value: fnName, configurable: true });
-					} catch {
-						
-					}
-
-					
-					
-					if (fnName && fnName.toLowerCase() === moduleName.toLowerCase() && fnName !== moduleName) {
-						
-						apiKey = fnName;
-						if (this.config.debug) {
-							console.log(`[DEBUG] Using function name '${fnName}' instead of module name '${moduleName}'`);
-						}
-					} else {
-						
-						apiKey = this._toApiKey(fnName);
-						if (this.config.debug) {
-							console.log(`[DEBUG] Using sanitized key '${apiKey}' for function '${fnName}' (module: '${moduleName}')`);
-						}
-					}
+					categoryModules[apiPathKey] = mod;
 				}
-
-				categoryModules[apiKey] = mod;
-			} else {
-				
-				let hasPreferredName = false;
-				const modWithPreferredNames = {};
-
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
+			} else if (type === "self-referential") {
 				
+				categoryModules[moduleName] = mod[moduleName] || mod;
+			} else if (type === "object") {
 				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-				
-
-				for (const [exportName, exportValue] of Object.entries(mod)) {
-					if (
-						typeof exportValue === "function" &&
-						exportValue.name &&
-						this._toApiKey(exportValue.name).toLowerCase() === this._toApiKey(moduleName).toLowerCase() &&
-						exportValue.name !== this._toApiKey(moduleName)
-					) {
-						
-						modWithPreferredNames[exportValue.name] = exportValue;
-						hasPreferredName = true;
-						if (this.config.debug) {
-							console.log("[DEBUG] Using preferred name:", exportValue.name, "instead of:", this._toApiKey(moduleName));
+				if (specialHandling === "preferred-export-names") {
+					Object.assign(categoryModules, processedExports);
+				} else if (shouldFlatten) {
+					switch (flattenType) {
+						case "single-default-object": {
+							
+							const flattened = { ...mod.default };
+							
+							for (const [key, value] of Object.entries(mod)) {
+								if (key !== "default") {
+									flattened[key] = value;
+								}
+							}
+							categoryModules[apiPathKey] = flattened;
+							break;
+						}
+						case "multi-default-no-default": {
+							
+							const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+							for (const key of moduleKeys) {
+								categoryModules[key] = mod[key];
+							}
+							break;
+						}
+						case "single-named-export-match":
+							
+							categoryModules[apiPathKey] = mod[apiPathKey];
+							break;
+						case "category-name-match-flatten": {
+							
+							const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+							for (const key of moduleKeys) {
+								categoryModules[key] = mod[key];
+							}
+							break;
 						}
-					} else {
-						modWithPreferredNames[this._toApiKey(exportName)] = exportValue;
-					}
-				}
-
-				if (hasPreferredName) {
-					Object.assign(categoryModules, modWithPreferredNames);
-					
-				} else if (selfReferentialFiles.has(moduleName)) {
-					
-					if (this.config.debug) {
-						console.log(`[DEBUG] Self-referential object: treating ${moduleName} as namespace`);
 					}
-					categoryModules[moduleName] = mod[moduleName] || mod;
 				} else {
-					categoryModules[this._toApiKey(moduleName)] = mod;
-					
-					
 					
+					categoryModules[apiPathKey] = mod;
 				}
 			}
 		}
 
 		
-		for (const subDirEntry of subDirs) {
-			if (currentDepth < maxDepth) {
-				const key = this._toApiKey(subDirEntry.name);
-				const subDirPath = path.join(categoryPath, subDirEntry.name);
+		for (const subDirDecision of subdirectoryDecisions) {
+			if (subDirDecision.shouldRecurse) {
+				const { name, path: subDirPath, apiPathKey } = subDirDecision;
 				let subModule;
 
 				if (mode === "lazy" && typeof subdirHandler === "function") {
 					subModule = subdirHandler({
-						subDirEntry,
+						subDirEntry: { name },
 						subDirPath,
-						key,
+						key: apiPathKey,
 						categoryModules,
 						currentDepth,
 						maxDepth
@@ -653,13 +515,13 @@ const slothletObject = {
 				if (
 					typeof subModule === "function" &&
 					subModule.name &&
-					subModule.name.toLowerCase() === key.toLowerCase() &&
-					subModule.name !== key
+					subModule.name.toLowerCase() === apiPathKey.toLowerCase() &&
+					subModule.name !== apiPathKey
 				) {
 					
 					categoryModules[subModule.name] = subModule;
 				} else {
-					categoryModules[key] = subModule;
+					categoryModules[apiPathKey] = subModule;
 				}
 			}
 		}
@@ -694,164 +556,117 @@ const slothletObject = {
 	},
 
 	
-	async _loadSingleModule(modulePath, rootLevel = false) {
-		const moduleUrl = pathToFileURL(modulePath).href;
-
+	async _loadSingleModule(modulePath) {
 		
-		const module = await import(moduleUrl);
+		const analysis = await analyzeModule(modulePath, {
+			debug: this.config.debug,
+			instance: this
+		});
+		return processModuleFromAnalysis(analysis, {
+			debug: this.config.debug,
+			instance: this
+		});
+	},
 
-		
-		
+	
+	async _buildCategoryEnhanced(categoryPath, options = {}) {
+		const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler } = options;
 
 		
+		const decisions = await getCategoryBuildingDecisions(categoryPath, {
+			instance: this,
+			currentDepth,
+			maxDepth,
+			debug: this.config.debug
+		});
+
+		const { processingStrategy, categoryName, processedModules, subDirectories } = decisions;
 
-		if (this.config.debug) console.log("module: ", module);
 		
-		if (typeof module.default === "function") {
-			let fn;
-			if (rootLevel) {
-				fn = module;
-			} else {
-				fn = module.default;
-				
-				try {
-					Object.defineProperty(fn, "__slothletDefault", { value: true, enumerable: false });
-				} catch {
-					
-				}
+		if (processingStrategy === "single-file" && processedModules.length === 1) {
+			const { processedModule, flattening } = processedModules[0];
 
+			if (flattening.shouldFlatten) {
 				
-				
-				
-				
-				
-
-				for (const [exportName, exportValue] of Object.entries(module)) {
-					if (exportName !== "default") {
-						
-						
-						
-						
-						
-						fn[this._toApiKey(exportName)] = exportValue;
+				if (typeof processedModule === "function") {
+					try {
+						Object.defineProperty(processedModule, "name", { value: flattening.apiPathKey, configurable: true });
+					} catch {
 						
 					}
 				}
-				if (this.config.debug) console.log("fn: ", fn);
+				return processedModule;
 			}
-			return fn;
+
+			
+			return { [flattening.apiPathKey]: processedModule };
 		}
 
-		const moduleExports = Object.entries(module);
 		
-		if (!moduleExports.length) {
-			throw new Error(
-				`slothlet: No exports found in module '${modulePath}'. The file is empty or does not export any function/object/variable.`
-			);
-		}
-		if (this.config.debug) console.log("moduleExports: ", moduleExports);
-
-		
-		const defaultExportObj =
-			typeof module.default === "object" && module.default !== null
-				? module.default
-				: typeof moduleExports[0][1] === "object" && typeof moduleExports[0][1].default === "function" && moduleExports[0][1] !== null
-					? moduleExports[0][1]
-					: null;
-		let objectName = null;
-		if (typeof module.default === "function" && module.default.name) {
-			objectName = module.default.name;
-		} else if (moduleExports[0] && moduleExports[0][0] !== "default") {
-			objectName = moduleExports[0][0];
+		const categoryModules = {};
+
+		for (const { processedModule, flattening } of processedModules) {
+			categoryModules[flattening.apiPathKey] = processedModule;
 		}
-		
-		
 
-		if (this.config.debug) console.log("defaultExportObj: ", defaultExportObj);
-		if (this.config.debug) console.log("objectName: ", objectName);
+		
+		for (const { dirEntry: subDirEntry, apiPathKey: key } of subDirectories) {
+			const subDirPath = path.join(categoryPath, subDirEntry.name);
+			let subModule;
 
-		if (defaultExportObj && typeof defaultExportObj.default === "function") {
-			if (this.config.debug) console.log("DEFAULT FUNCTION FOUND FOR: ", module);
-			
-			const callableApi = {
-				[objectName]: function (...args) {
-					return defaultExportObj.default.apply(defaultExportObj, args);
-				}
-			}[objectName];
-			for (const [methodName, method] of Object.entries(defaultExportObj)) {
-				if (methodName === "default") continue;
-				callableApi[methodName] = method;
+			if (mode === "lazy" && typeof subdirHandler === "function") {
+				subModule = subdirHandler({
+					subDirEntry,
+					subDirPath,
+					key,
+					categoryModules,
+					currentDepth,
+					maxDepth
+				});
+			} else {
+				
+				subModule = await this._buildCategoryEnhanced(subDirPath, {
+					currentDepth: currentDepth + 1,
+					maxDepth,
+					mode: "eager"
+				});
 			}
-			
-			
-			
-			
-			
-			if (this.config.debug) console.log("callableApi", callableApi);
-			return callableApi;
-		} else if (defaultExportObj) {
-			if (this.config.debug) console.log("DEFAULT FOUND FOR: ", module);
 
-			const obj = { ...defaultExportObj };
-
-			
-			
-			
-			
-			
 			
-			
-			
-			
-			
-
-			for (const [exportName, exportValue] of Object.entries(module)) {
-				if (exportName !== "default" && exportValue !== obj) {
-					
-					
-					
-					
-					
-					obj[this._toApiKey(exportName)] = exportValue;
-				}
+			if (
+				typeof subModule === "function" &&
+				subModule.name &&
+				subModule.name.toLowerCase() === key.toLowerCase() &&
+				subModule.name !== key
+			) {
+				categoryModules[subModule.name] = subModule;
+			} else {
+				categoryModules[key] = subModule;
 			}
-
-			return obj;
 		}
-		
-		const namedExports = Object.entries(module).filter(([k]) => k !== "default");
-		if (this.config.debug) console.log("namedExports: ", namedExports);
-		if (namedExports.length === 1 && !module.default) {
-			if (typeof namedExports[0][1] === "object") {
-				
-				if (this.config.debug) console.log("namedExports[0][1] === object: ", namedExports[0][1]);
-				const obj = { ...namedExports[0][1] };
-
-				
-				
-				
-				
-				
-				
-				
-				
 
-				return obj;
-			}
-			if (typeof namedExports[0][1] === "function") {
-				if (this.config.debug) console.log("namedExports[0][1] === function: ", namedExports[0][1]);
-				
-				
-				return namedExports[0][1];
+		
+		const keys = Object.keys(categoryModules);
+		if (keys.length === 1) {
+			const singleKey = keys[0];
+			if (singleKey === categoryName) {
+				const single = categoryModules[singleKey];
+				if (typeof single === "function") {
+					if (single.name !== categoryName) {
+						try {
+							Object.defineProperty(single, "name", { value: categoryName, configurable: true });
+						} catch {
+							
+						}
+					}
+					return single;
+				} else if (single && typeof single === "object" && !Array.isArray(single)) {
+					return single;
+				}
 			}
 		}
-		const apiExport = {};
-		for (const [exportName, exportValue] of namedExports) {
-			
-			
-			apiExport[this._toApiKey(exportName)] = exportValue;
-		}
-		return apiExport;
+
+		return categoryModules;
 	},