@cldmv/slothlet 2.11.0 → 3.0.1

package/dist/lib/helpers/class-instance-wrapper.mjs

@@ -0,0 +1,125 @@
+/*
+	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 { EventEmitter } from "node:events";
+
+
+const EXCLUDED_CONSTRUCTORS = new Set([Object, Array, Promise, Date, RegExp, Error]);
+
+
+const EXCLUDED_INSTANCEOF_CLASSES = [ArrayBuffer, Map, Set, WeakMap, WeakSet, EventEmitter];
+
+
+export function runtime_shouldWrapMethod(value, prop) {
+	return (
+		typeof value === "function" &&
+		typeof prop === "string" &&
+		prop !== "constructor" &&
+		!(prop in Object.prototype) &&
+		!prop.startsWith("__")
+	);
+}
+
+
+export function runtime_isClassInstance(val) {
+	if (
+		val == null ||
+		typeof val !== "object" ||
+		!val.constructor ||
+		typeof val.constructor !== "function" ||
+		EXCLUDED_CONSTRUCTORS.has(val.constructor)
+	) {
+		return false;
+	}
+
+	for (const cls of EXCLUDED_INSTANCEOF_CLASSES) {
+		if (typeof cls === "function" && val instanceof cls) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+
+export function runtime_wrapClassInstance(instance, contextManager, instanceID, instanceCache) {
+	if (instanceCache.has(instance)) {
+		return instanceCache.get(instance);
+	}
+
+	
+	
+	
+	
+	
+
+	
+	const methodCache = new Map();
+
+	const wrappedInstance = new Proxy(instance, {
+		get(target, prop, receiver) {
+			
+			if (methodCache.has(prop)) {
+				return methodCache.get(prop);
+			}
+
+			const value = Reflect.get(target, prop, receiver);
+
+			
+			
+			if (runtime_shouldWrapMethod(value, prop)) {
+				const runtime_contextPreservingMethod = function (...args) {
+					
+					
+					const result = contextManager.runInContext(instanceID, value, target, args);
+
+					
+					if (result != null && runtime_isClassInstance(result)) {
+						return runtime_wrapClassInstance(result, contextManager, instanceID, instanceCache);
+					}
+
+					return result;
+				};
+
+				
+				methodCache.set(prop, runtime_contextPreservingMethod);
+				return runtime_contextPreservingMethod;
+			}
+
+			
+			if (value != null && runtime_isClassInstance(value)) {
+				return runtime_wrapClassInstance(value, contextManager, instanceID, instanceCache);
+			}
+
+			return value;
+		},
+
+		set(target, prop, value, receiver) {
+			
+			if (methodCache.has(prop)) {
+				methodCache.delete(prop);
+			}
+			return Reflect.set(target, prop, value, receiver);
+		}
+	});
+
+	instanceCache.set(instance, wrappedInstance);
+	return wrappedInstance;
+}

package/dist/lib/helpers/config.mjs

@@ -0,0 +1,343 @@
+/*
+	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 Config extends ComponentBase {
+	static slothletProperty = "config";
+
+	
+	normalizeCollision(collision) {
+		const validModes = ["skip", "warn", "replace", "merge", "merge-replace", "error"];
+		const defaultMode = "merge";
+
+		
+		if (typeof collision === "string") {
+			const normalized = collision.toLowerCase();
+			const mode = validModes.includes(normalized) ? normalized : defaultMode;
+			return { initial: mode, api: mode };
+		}
+
+		
+		if (collision && typeof collision === "object") {
+			const validateMode = (m) => {
+				if (!m) return defaultMode;
+				const normalized = String(m).toLowerCase();
+				return validModes.includes(normalized) ? normalized : defaultMode;
+			};
+			return {
+				initial: validateMode(collision.initial),
+				api: validateMode(collision.api)
+			};
+		}
+
+		
+		return { initial: defaultMode, api: defaultMode };
+	}
+
+	
+	normalizeRuntime(runtime) {
+		if (!runtime || typeof runtime !== "string") {
+			return "async"; 
+		}
+
+		const normalized = runtime.toLowerCase().trim();
+
+		
+		if (normalized === "async" || normalized === "asynclocal" || normalized === "asynclocalstorage") {
+			return "async";
+		}
+
+		
+		if (normalized === "live" || normalized === "livebindings" || normalized === "experimental") {
+			return "live";
+		}
+
+		
+		return "async";
+	}
+
+	
+	normalizeMode(mode) {
+		if (!mode || typeof mode !== "string") {
+			return "eager"; 
+		}
+
+		const normalized = mode.toLowerCase().trim();
+
+		
+		if (normalized === "lazy" || normalized === "deferred" || normalized === "proxy") {
+			return "lazy";
+		}
+
+		
+		if (normalized === "eager" || normalized === "immediate" || normalized === "preload") {
+			return "eager";
+		}
+
+		
+		return "eager";
+	}
+
+	
+	normalizeMutations(mutations) {
+		const defaults = { add: true, remove: true, reload: true };
+
+		
+		if (!mutations || typeof mutations !== "object") {
+			return defaults;
+		}
+
+		
+		return {
+			add: mutations.add === false ? false : true,
+			remove: mutations.remove === false ? false : true,
+			reload: mutations.reload === false ? false : true
+		};
+	}
+
+	
+	normalizeDebug(debug) {
+		if (!debug) {
+			return {
+				builder: false,
+				api: false,
+				index: false,
+				modes: false,
+				wrapper: false,
+				ownership: false,
+				context: false,
+				initialization: false,
+				materialize: false
+			};
+		}
+
+		
+		if (debug === true) {
+			return {
+				builder: true,
+				api: true,
+				index: true,
+				modes: true,
+				wrapper: true,
+				ownership: true,
+				context: true,
+				initialization: true,
+				materialize: true
+			};
+		}
+
+		
+		if (typeof debug === "object") {
+			return {
+				builder: debug.builder || false,
+				api: debug.api || false,
+				index: debug.index || false,
+				modes: debug.modes || false,
+				wrapper: debug.wrapper || false,
+				ownership: debug.ownership || false,
+				context: debug.context || false,
+				initialization: debug.initialization || false,
+				materialize: debug.materialize || false
+			};
+		}
+
+		
+		return {
+			builder: false,
+			api: false,
+			index: false,
+			modes: false,
+			wrapper: false,
+			ownership: false,
+			context: false,
+			initialization: false,
+			materialize: false
+		};
+	}
+
+	
+	transformConfig(config = {}) {
+		
+		if (!config.dir) {
+			throw new this.SlothletError("INVALID_CONFIG_DIR_MISSING", {}, null, { validationError: true });
+		}
+
+		
+		const resolvedDir = this.slothlet.helpers.resolver.resolvePathFromCaller(config.dir);
+
+		
+		
+		let mutations = null;
+		if (config.allowMutation === false) {
+			
+			mutations = { add: false, remove: false, reload: false };
+			if (!config.silent) {
+				new this.SlothletWarning("V2_CONFIG_UNSUPPORTED", {
+					option: "allowMutation",
+					replacement: "api.mutations: { add: false, remove: false, reload: false }",
+					hint: "The allowMutation config option was part of v2. Use api.mutations for granular control in v3."
+				});
+			}
+		}
+
+		
+		
+		let collision = null;
+		if (config.collision && !config.api?.collision) {
+			collision = this.normalizeCollision(config.collision);
+			if (!config.silent) {
+				new this.SlothletWarning("V2_CONFIG_UNSUPPORTED", {
+					option: "collision",
+					replacement: "api.collision",
+					hint: "Root-level collision config was part of v2. Use api.collision in v3."
+				});
+			}
+		}
+
+		
+		const apiConfig = config.api || {};
+		const finalCollision = apiConfig.collision ? this.normalizeCollision(apiConfig.collision) : collision || this.normalizeCollision(null);
+		const finalMutations = apiConfig.mutations ? this.normalizeMutations(apiConfig.mutations) : mutations || this.normalizeMutations(null);
+
+		
+		let scopeConfig = config.scope;
+		if (scopeConfig && typeof scopeConfig === "object" && scopeConfig.merge) {
+			const validMergeStrategies = ["shallow", "deep"];
+			if (!validMergeStrategies.includes(scopeConfig.merge)) {
+				throw new this.SlothletError(
+					"INVALID_CONFIG",
+					{
+						option: "scope.merge",
+						value: scopeConfig.merge,
+						expected: validMergeStrategies.join(" or "),
+						hint: `Invalid merge strategy: "${scopeConfig.merge}". Must be "shallow" or "deep".`,
+						validationError: true
+					},
+					null,
+					{ validationError: true }
+				);
+			}
+		}
+
+		
+		let hookConfig = { enabled: false, pattern: "**", suppressErrors: false };
+		if (config.hook === true || config.hook === false) {
+			
+			hookConfig.enabled = config.hook;
+			hookConfig.pattern = config.hook ? "**" : null;
+		} else if (typeof config.hook === "string") {
+			
+			hookConfig.enabled = true;
+			hookConfig.pattern = config.hook;
+		} else if (config.hook && typeof config.hook === "object") {
+			
+			hookConfig.enabled = config.hook.enabled !== false; 
+			hookConfig.pattern = config.hook.pattern || "**";
+			hookConfig.suppressErrors = config.hook.suppressErrors || false;
+		}
+
+		
+		let trackingConfig = { materialization: false };
+		if (config.tracking === true || config.tracking === false) {
+			
+			trackingConfig.materialization = config.tracking;
+		} else if (config.tracking && typeof config.tracking === "object") {
+			
+			trackingConfig.materialization = config.tracking.materialization === true;
+		}
+
+		
+		if (config.backgroundMaterialize === true) {
+			trackingConfig.materialization = true;
+		}
+
+		
+		let i18nConfig = null;
+		if (config.i18n && typeof config.i18n === "object") {
+			i18nConfig = {
+				language: typeof config.i18n.language === "string" ? config.i18n.language : undefined
+			};
+		}
+
+		
+		return {
+			...config,
+			dir: resolvedDir,
+			mode: this.normalizeMode(config.mode),
+			runtime: this.normalizeRuntime(config.runtime),
+			apiDepth: config.apiDepth !== undefined ? config.apiDepth : Infinity,
+			reference: config.reference || null,
+			context: config.context || null,
+			i18n: i18nConfig,
+			debug: this.normalizeDebug(config.debug),
+			diagnostics: config.diagnostics === true,
+			hook: hookConfig,
+			collision: finalCollision,
+			api: {
+				collision: finalCollision,
+				mutations: finalMutations
+			},
+			scope: scopeConfig,
+			tracking: trackingConfig,
+			backgroundMaterialize: config.backgroundMaterialize === true,
+			silent: config.silent === true,
+			typescript: this.normalizeTypeScript(config.typescript)
+		};
+	}
+
+	
+	normalizeTypeScript(typescript) {
+		
+		if (!typescript) {
+			return null;
+		}
+
+		
+		if (typescript === true) {
+			return { enabled: true, mode: "fast" };
+		}
+
+		
+		if (typeof typescript === "string") {
+			const mode = typescript.toLowerCase();
+			if (mode === "fast" || mode === "strict") {
+				return { enabled: true, mode };
+			}
+			
+			return { enabled: true, mode: "fast" };
+		}
+
+		
+		if (typeof typescript === "object") {
+			const mode = typescript.mode === "strict" ? "strict" : "fast";
+			return {
+				enabled: true,
+				mode,
+				types: typescript.types || null,
+				target: typescript.target || "es2020",
+				sourcemap: typescript.sourcemap || false
+			};
+		}
+
+		
+		return null;
+	}
+}