@cldmv/slothlet 2.11.0 → 3.0.1

package/dist/lib/errors.mjs

@@ -0,0 +1,227 @@
+/*
+	Copyright 2026 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+import { translate } from "@cldmv/slothlet/i18n";
+import { detectHint } from "@cldmv/slothlet/helpers/hint-detector";
+
+
+export class SlothletError extends Error {
+	
+	constructor(code, context = {}, originalError = null, options = {}) {
+		
+		
+		const { validationError: ctxValidation, stub: ctxStub, ...contextData } = context;
+		const { validationError: optsValidation, stub: optsStub } = options;
+		const validationError = ctxValidation ?? optsValidation;
+		const stub = ctxStub ?? optsStub;
+
+		
+		const enrichedContext = originalError ? { ...contextData, error: originalError.message } : contextData;
+
+		
+		const translatedMessage = translate(code, enrichedContext);
+
+		
+		const skipHint = stub || validationError;
+		const hintKey = originalError && !skipHint ? detectHint(originalError, code) : undefined;
+		let translatedHint = hintKey ? translate(hintKey, enrichedContext) : undefined;
+
+		
+		
+		
+		
+		
+		if (!translatedHint && validationError) {
+			const staticHintKey = `HINT_${code}`;
+			const staticHint = translate(staticHintKey, enrichedContext);
+			
+			if (staticHint && !staticHint.startsWith("Error:")) {
+				translatedHint = staticHint;
+			}
+		}
+
+		
+		const messageWithCode = `[${code}] ${translatedMessage}`;
+		super(messageWithCode);
+		this.name = "SlothletError";
+
+		
+		Object.defineProperty(this, "code", {
+			value: code,
+			enumerable: false,
+			writable: false
+		});
+
+		Object.defineProperty(this, "context", {
+			value: context,
+			enumerable: false,
+			writable: false
+		});
+
+		Object.defineProperty(this, "originalError", {
+			value: originalError,
+			enumerable: false,
+			writable: false
+		});
+
+		Object.defineProperty(this, "hint", {
+			value: translatedHint,
+			enumerable: false,
+			writable: false
+		});
+
+		Error.captureStackTrace(this, SlothletError);
+	}
+
+	
+	toString() {
+		let output = `\n[${this.code}] ${this.name}\n`;
+
+		
+		if (this.hint) {
+			output += `\n💡 ${this.hint}\n`;
+		}
+
+		
+		const criticalKeys = ["modulePath", "moduleID", "apiPath"];
+		const detailKeys = Object.keys(this.context).filter((k) => criticalKeys.includes(k));
+
+		if (detailKeys.length > 0) {
+			output += "\nDetails:\n";
+			for (const key of detailKeys) {
+				output += `  ${key}: ${this.context[key]}\n`;
+			}
+		}
+
+		return output;
+	}
+
+	
+	[Symbol.for("nodejs.util.inspect.custom")]() {
+		return this.toString() + `\n${this.stack}`;
+	}
+
+	
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			hint: this.context.hint
+		};
+	}
+}
+
+
+export class SlothletWarning {
+	
+	static captured = [];
+	static suppressConsole = false;
+
+	
+	constructor(code, context = {}) {
+		
+		const { key: msgKey, ...contextData } = context;
+		const translationKey = msgKey ?? code;
+
+		
+		const translatedMessage = translate(translationKey, contextData);
+
+		this.name = "SlothletWarning";
+		this.code = code;
+		this.message = translatedMessage;
+		this.context = context;
+
+		
+		if (!SlothletWarning.suppressConsole) {
+			console.warn(`\n⚠️  [${this.code}] ${this.name}\n${this.message}`);
+
+			
+			if (Object.keys(contextData).length > 0) {
+				console.warn("Context:", contextData);
+			}
+		} else {
+			
+			SlothletWarning.captured.push(this);
+		}
+	}
+
+	
+	toString() {
+		return `[${this.code}] ${this.name}: ${this.message}`;
+	}
+
+	
+	static clearCaptured() {
+		SlothletWarning.captured = [];
+	}
+}
+
+
+export class SlothletDebug {
+	
+	constructor(config = {}) {
+		this.config = config;
+		this.debugFlags = config.debug || {};
+	}
+
+	
+	log(code, context = {}) {
+		
+		
+		
+		
+		if (!this.debugFlags || !this.debugFlags[code]) {
+			return;
+		}
+
+		
+		const { key: msgKey, message, ...contextParams } = context;
+
+		
+		const translationKey = msgKey ?? `DEBUG_${code.toUpperCase()}`;
+		const translatedMessage = translate(translationKey, contextParams);
+		const hasTranslation = translatedMessage && !translatedMessage.startsWith("Error:");
+
+		
+		const label = `[DEBUG:${code.toUpperCase()}]`;
+
+		if (hasTranslation) {
+			console.log(`${label} ${translatedMessage}`);
+		} else if (message) {
+			
+			console.log(`${label} ${message}`);
+		} else {
+			
+			console.log(label, contextParams);
+		}
+
+		
+		if ((hasTranslation || message) && Object.keys(contextParams).length > 0) {
+			console.log(`${label} Context:`, contextParams);
+		}
+	}
+
+	
+	toString() {
+		return `[SlothletDebug] flags: ${Object.keys(this.debugFlags)
+			.filter((k) => this.debugFlags[k])
+			.join(", ")}`;
+	}
+}

package/dist/lib/factories/component-base.mjs

@@ -0,0 +1,96 @@
+/*
+	Copyright 2026 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+
+
+export class ComponentBase {
+	
+	#slothlet;
+
+	
+	constructor(slothlet) {
+		this.#slothlet = slothlet;
+	}
+
+	
+	get ____slothlet() {
+		return this.#slothlet;
+	}
+
+	
+	get slothlet() {
+		return this.#slothlet;
+	}
+
+	
+	get ____config() {
+		return this.____slothlet.config;
+	}
+
+	
+	get instanceID() {
+		return this.____slothlet.instanceID;
+	}
+
+	
+	get SlothletError() {
+		return this.____slothlet.SlothletError;
+	}
+
+	
+	get SlothletWarning() {
+		return this.____slothlet.SlothletWarning;
+	}
+
+	
+	static INTERNAL_KEYS = new Set([
+		
+		"____slothletInternal",
+		"____slothlet",
+		
+		"___getState",
+		"___setImpl",
+		"___resetLazy",
+		"___invalidate",
+		
+		"__state",
+		"__invalid",
+		"__mode",
+		"__apiPath",
+		"__slothletPath",
+		"__isCallable",
+		"__materializeOnCreate",
+		"__displayName",
+		"__type",
+		"__metadata",
+		"__filePath",
+		"__sourceFolder",
+		"__moduleID",
+		"__materialized",
+		"__inFlight",
+		"__impl",
+		
+		"_impl",
+		"_materialize",
+		
+		"slothlet",
+		"shutdown",
+		"destroy"
+	]);
+}

package/dist/lib/factories/context.mjs

@@ -0,0 +1,38 @@
+/*
+	Copyright 2026 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+import { asyncContextManager } from "@cldmv/slothlet/handlers/context-async";
+import { liveContextManager } from "@cldmv/slothlet/handlers/context-live";
+
+
+export function getContextManager(runtime = "async") {
+	return runtime === "live" ? liveContextManager : asyncContextManager;
+}
+
+
+export const contextManager = asyncContextManager;
+
+
+export const asyncRuntime = asyncContextManager;
+
+
+export const liveRuntime = liveContextManager;
+
+
+export { asyncContextManager, liveContextManager };

package/dist/lib/handlers/api-cache-manager.mjs

@@ -0,0 +1,216 @@
+/*
+	Copyright 2026 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+
+
+
+
+export class ApiCacheManager extends ComponentBase {
+	static slothletProperty = "apiCacheManager";
+
+	
+	constructor(slothlet) {
+		super(slothlet);
+
+		
+		this.caches = new Map();
+	}
+
+	
+	set(moduleID, entry) {
+		if (!moduleID || typeof moduleID !== "string") {
+			throw new this.SlothletError("INVALID_ARGUMENT", {
+				argument: "moduleID",
+				expected: "non-empty string",
+				received: typeof moduleID,
+				validationError: true
+			});
+		}
+
+		if (!entry || !entry.api) {
+			throw new this.SlothletError("INVALID_ARGUMENT", {
+				argument: "entry.api",
+				expected: "API tree object",
+				received: typeof entry?.api,
+				validationError: true
+			});
+		}
+
+		
+		if (entry.moduleID && entry.moduleID !== moduleID) {
+			throw new this.SlothletError("CACHE_MODULEID_MISMATCH", {
+				cacheKey: moduleID,
+				entryModuleID: entry.moduleID,
+				validationError: true
+			});
+		}
+
+		this.caches.set(moduleID, entry);
+
+		this.slothlet.debug("cache", {
+			key: "DEBUG_MODE_CACHE_ENTRY_STORED",
+			moduleID,
+			endpoint: entry.endpoint,
+			mode: entry.mode,
+			timestamp: entry.timestamp
+		});
+	}
+
+	
+	get(moduleID) {
+		return this.caches.get(moduleID);
+	}
+
+	
+	has(moduleID) {
+		return this.caches.has(moduleID);
+	}
+
+	
+	delete(moduleID) {
+		const deleted = this.caches.delete(moduleID);
+
+		if (deleted) {
+			this.slothlet.debug("cache", {
+				key: "DEBUG_MODE_CACHE_ENTRY_DELETED",
+				moduleID
+			});
+		}
+
+		return deleted;
+	}
+
+	
+	getAllModuleIDs() {
+		return Array.from(this.caches.keys());
+	}
+
+	
+	getCacheDiagnostics() {
+		const caches = [];
+
+		for (const [moduleID, entry] of this.caches.entries()) {
+			
+			const pathCount = this._countPaths(entry.api);
+
+			caches.push({
+				moduleID,
+				endpoint: entry.endpoint,
+				folderPath: entry.folderPath,
+				mode: entry.mode,
+				pathCount,
+				timestamp: entry.timestamp
+			});
+		}
+
+		return {
+			totalCaches: this.caches.size,
+			caches
+		};
+	}
+
+	
+	_countPaths(api, visited = new WeakSet()) {
+		if (!api || typeof api !== "object" || visited.has(api)) {
+			return 0;
+		}
+
+		visited.add(api);
+		let count = 0;
+
+		for (const [key, value] of Object.entries(api)) {
+			
+			if (key.startsWith("__") || key.startsWith("_")) {
+				continue;
+			}
+
+			count += 1;
+
+			if (value && typeof value === "object") {
+				count += this._countPaths(value, visited);
+			}
+		}
+
+		return count;
+	}
+
+	
+	clear() {
+		this.caches.clear();
+
+		this.slothlet.debug("cache", {
+			key: "DEBUG_MODE_ALL_CACHES_CLEARED"
+		});
+	}
+
+	
+	async rebuildCache(moduleID) {
+		const entry = this.get(moduleID);
+
+		if (!entry) {
+			throw new this.SlothletError("CACHE_NOT_FOUND", {
+				moduleID,
+				operation: "rebuild",
+				validationError: true
+			});
+		}
+
+		this.slothlet.debug("cache", {
+			key: "DEBUG_MODE_REBUILDING_CACHE_FROM_DISK",
+			moduleID,
+			folderPath: entry.folderPath,
+			mode: entry.mode
+		});
+
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		const freshApi = await this.slothlet.builders.builder.buildAPI({
+			dir: entry.folderPath,
+			mode: entry.mode,
+			sanitize: entry.sanitizeOptions,
+			moduleID: moduleID,
+			apiPathPrefix: entry.endpoint === "." ? "" : entry.endpoint,
+			collisionMode: entry.collisionMode,
+			collisionContext: entry.endpoint === "." ? "initial" : "addApi",
+			cacheBust: Date.now()
+		});
+
+		this.slothlet.debug("cache", {
+			key: "DEBUG_MODE_CACHE_REBUILT_SUCCESSFULLY",
+			moduleID,
+			timestamp: Date.now()
+		});
+
+		return freshApi;
+	}
+}