@cldmv/slothlet 3.1.0 → 3.2.0

package/dist/lib/handlers/version-manager.mjs

@@ -0,0 +1,773 @@
+/*
+	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 { inspect } from "node:util";
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+
+
+
+
+function stripPrefix(tag) {
+	
+	return tag.replace(/^[^0-9]+/, "");
+}
+
+
+function stripSuffix(s) {
+	
+	return s.replace(/[-+].*$/, "");
+}
+
+
+function normaliseVersionTag(tag) {
+	const bare = stripSuffix(stripPrefix(tag));
+	const parts = bare.split(".").map((p) => {
+		const n = parseInt(p, 10);
+		
+		
+		return isNaN(n) ? 0 : n;
+	});
+	
+	
+	return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+}
+
+
+function compareTuples(a, b) {
+	for (let i = 0; i < 3; i++) {
+		if (a[i] !== b[i]) return b[i] - a[i];
+	}
+	
+	
+	
+	
+	
+	return 0;
+}
+
+
+
+const FORCE_VERSION_SYMBOL = Symbol.for("slothlet.versioning.force");
+
+
+
+
+export class VersionManager extends ComponentBase {
+	static slothletProperty = "versionManager";
+
+	
+	#registry = new Map();
+
+	
+	#versionMetadataByModule = new Map();
+
+	
+	#moduleToVersionKey = new Map();
+
+	
+	#dispatchers = new Map();
+
+	
+
+	
+	registerVersion(logicalPath, versionTag, moduleID, versionMeta, isDefault) {
+		if (!this.#registry.has(logicalPath)) {
+			this.#registry.set(logicalPath, { versions: new Map() });
+		}
+
+		const entry = this.#registry.get(logicalPath);
+
+		
+		if (entry.versions.has(versionTag)) {
+			throw new this.SlothletError("VERSION_REGISTER_DUPLICATE", {
+				version: versionTag,
+				apiPath: logicalPath
+			});
+		}
+
+		
+		const versionEntry = {
+			moduleID,
+			versionTag,
+			versionedPath: `${versionTag}.${logicalPath}`,
+			
+			
+			
+			versionedParts: [versionTag, ...logicalPath.split(".")],
+			
+			
+			isDefault: isDefault ?? false,
+			
+			versionMeta: versionMeta ?? {},
+			registeredAt: Date.now()
+		};
+
+		entry.versions.set(versionTag, versionEntry);
+		this.#moduleToVersionKey.set(moduleID, { logicalPath, versionTag });
+
+		
+		this.#versionMetadataByModule.set(moduleID, {
+			
+			
+			...(versionMeta ?? {}), 
+			version: versionTag, 
+			logicalPath 
+		});
+
+		this.slothlet.debug("versioning", {
+			key: "DEBUG_VERSION_REGISTERED",
+			version: versionTag,
+			logicalPath,
+			moduleID
+		});
+
+		
+		this.updateDispatcher(logicalPath);
+	}
+
+	
+	unregisterVersion(logicalPath, versionTag) {
+		const entry = this.#registry.get(logicalPath);
+		
+		
+		
+		if (!entry) return false;
+
+		const versionEntry = entry.versions.get(versionTag);
+		
+		
+		if (!versionEntry) return false;
+
+		
+		this.#moduleToVersionKey.delete(versionEntry.moduleID);
+		this.#versionMetadataByModule.delete(versionEntry.moduleID);
+		entry.versions.delete(versionTag);
+
+		this.slothlet.debug("versioning", {
+			key: "DEBUG_VERSION_UNREGISTERED",
+			version: versionTag,
+			logicalPath
+		});
+
+		if (entry.versions.size === 0) {
+			
+			this.#registry.delete(logicalPath);
+			this.teardownDispatcher(logicalPath);
+		} else {
+			
+			this.updateDispatcher(logicalPath);
+		}
+
+		return true;
+	}
+
+	
+	getVersionKeyForModule(moduleID) {
+		return this.#moduleToVersionKey.get(moduleID);
+	}
+
+	
+	hasDispatcher(logicalPath) {
+		return this.#dispatchers.has(logicalPath);
+	}
+
+	
+	getVersionMetadata(moduleID) {
+		return this.#versionMetadataByModule.get(moduleID);
+	}
+
+	
+	getVersionMetadataByPath(logicalPath, versionTag) {
+		const entry = this.#registry.get(logicalPath);
+		if (!entry) return undefined;
+		const ve = entry.versions.get(versionTag);
+		if (!ve) return undefined;
+		return this.#versionMetadataByModule.get(ve.moduleID);
+	}
+
+	
+	setVersionMetadataByPath(logicalPath, versionTag, patch) {
+		const entry = this.#registry.get(logicalPath);
+		if (!entry || !entry.versions.has(versionTag)) {
+			throw new this.SlothletError("VERSION_NOT_FOUND", {
+				version: versionTag,
+				apiPath: logicalPath
+			});
+		}
+		const ve = entry.versions.get(versionTag);
+		const existing = this.#versionMetadataByModule.get(ve.moduleID) ?? {};
+		
+		this.#versionMetadataByModule.set(ve.moduleID, {
+			...existing,
+			...(patch && typeof patch === "object" ? patch : {}),
+			version: ve.versionTag,
+			logicalPath
+		});
+	}
+
+	
+	list(logicalPath) {
+		const entry = this.#registry.get(logicalPath);
+		if (!entry) return undefined;
+
+		const versions = {};
+		for (const [tag, ve] of entry.versions) {
+			versions[tag] = { ...ve };
+		}
+		return { versions, default: this.getDefaultVersion(logicalPath) };
+	}
+
+	
+	setDefault(logicalPath, versionTag) {
+		const entry = this.#registry.get(logicalPath);
+		if (!entry) {
+			throw new this.SlothletError("VERSION_NOT_FOUND", {
+				version: versionTag,
+				apiPath: logicalPath
+			});
+		}
+		if (!entry.versions.has(versionTag)) {
+			throw new this.SlothletError("VERSION_NOT_FOUND", {
+				version: versionTag,
+				apiPath: logicalPath
+			});
+		}
+		
+		for (const ve of entry.versions.values()) {
+			ve.isDefault = false;
+		}
+		entry.versions.get(versionTag).isDefault = true;
+	}
+
+	
+
+	
+	getDefaultVersion(logicalPath) {
+		const entry = this.#registry.get(logicalPath);
+		
+		
+		
+		if (!entry || entry.versions.size === 0) return null;
+
+		
+		for (const [tag, ve] of entry.versions) {
+			if (ve.isDefault) return tag;
+		}
+
+		
+		const tags = Array.from(entry.versions.keys());
+		if (tags.length === 1) return tags[0];
+
+		
+		const sorted = tags
+			.map((tag) => ({ tag, tuple: normaliseVersionTag(tag) }))
+			.sort((a, b) => {
+				const cmp = compareTuples(a.tuple, b.tuple);
+				if (cmp !== 0) return cmp;
+				
+				
+				
+				const aSuffix = a.tag.match(/[-+]/) ? 1 : 0;
+				
+				const bSuffix = b.tag.match(/[-+]/) ? 1 : 0;
+				return aSuffix - bSuffix;
+			});
+
+		return sorted[0].tag;
+	}
+
+	
+
+	
+	resolveForPath(logicalPath, allVersions, caller) {
+		const discriminator = this.slothlet.config?.versionDispatcher ?? "version";
+
+		let resolvedTag = null;
+
+		if (typeof discriminator === "string") {
+			
+			resolvedTag = caller.versionMetadata?.[discriminator] ?? null;
+		}
+		
+		
+		
+		if (typeof discriminator === "function") {
+			try {
+				resolvedTag = discriminator(allVersions, caller);
+			} catch {
+				resolvedTag = null;
+			}
+		}
+
+		if (resolvedTag == null) return null;
+
+		
+		const entry = this.#registry.get(logicalPath);
+		if (!entry || !entry.versions.has(resolvedTag)) {
+			this.slothlet.debug("versioning", {
+				key: "DEBUG_VERSION_RESOLVED",
+				version: null,
+				apiPath: logicalPath,
+				
+				
+				callerModule: caller?.metadata?.moduleID ?? null
+			});
+			return null;
+		}
+
+		this.slothlet.debug("versioning", {
+			key: "DEBUG_VERSION_RESOLVED",
+			version: resolvedTag,
+			apiPath: logicalPath,
+			
+			
+			callerModule: caller?.metadata?.moduleID ?? null
+		});
+
+		return resolvedTag;
+	}
+
+	
+
+	
+	buildAllVersionsArg(logicalPath) {
+		const entry = this.#registry.get(logicalPath);
+		
+		
+		
+		if (!entry) return {};
+
+		const defaultTag = this.getDefaultVersion(logicalPath);
+		const result = {};
+
+		for (const [tag, ve] of entry.versions) {
+			
+			
+			
+			const mountedWrapper = this.#walkApiPath(ve.versionedParts);
+			
+			
+			const regularMetadata = this.slothlet.handlers.metadata?.getMetadata?.(mountedWrapper) ?? {};
+			
+			const versionMetadata = this.#versionMetadataByModule.get(ve.moduleID) ?? {};
+
+			result[tag] = {
+				version: tag,
+				default: tag === defaultTag,
+				metadata: regularMetadata,
+				versionMetadata
+			};
+		}
+
+		return result;
+	}
+
+	
+	buildCallerArg(callerWrapper) {
+		
+		
+		const callerModuleID = callerWrapper?.____slothletInternal?.moduleID ?? callerWrapper?.__moduleID;
+		const callerVersionEntry = callerModuleID ? this.#findVersionEntryForModule(callerModuleID) : null;
+		
+		
+		const regularMetadata = this.slothlet.handlers.metadata?.getMetadata?.(callerWrapper) ?? {};
+
+		if (!callerVersionEntry) {
+			return {
+				version: null,
+				default: null,
+				metadata: regularMetadata,
+				versionMetadata: null
+			};
+		}
+
+		const defaultTag = this.getDefaultVersion(callerVersionEntry.logicalPath);
+		
+		
+		const versionMetadata = this.#versionMetadataByModule.get(callerModuleID) ?? {};
+
+		return {
+			version: callerVersionEntry.versionTag,
+			default: callerVersionEntry.versionTag === defaultTag,
+			metadata: regularMetadata,
+			versionMetadata
+		};
+	}
+
+	
+	#findVersionEntryForModule(moduleID) {
+		const key = this.#moduleToVersionKey.get(moduleID);
+		
+		
+		if (!key) return null;
+		const entry = this.#registry.get(key.logicalPath);
+		
+		
+		
+		if (!entry) return null;
+		
+		
+		return entry.versions.get(key.versionTag) ?? null;
+	}
+
+	
+	#walkApiPath(apiPath) {
+		
+		
+		if (!apiPath) return undefined;
+		let node = this.slothlet.api;
+		
+		
+		const segments = Array.isArray(apiPath) ? apiPath : apiPath.split(".");
+		for (const segment of segments) {
+			
+			
+			if (node == null) return undefined;
+			node = node[segment];
+		}
+		return node;
+	}
+
+	
+
+	
+	createDispatcher(logicalPath) {
+		const manager = this;
+		const target = { __isVersionDispatcher: true, __logicalPath: logicalPath };
+		const displayName = logicalPath.split(".").pop();
+
+		
+		const resolveVersion = () => {
+			
+			
+			
+			const ctx = manager.slothlet.contextManager?.tryGetContext?.();
+			const forcedVersion = ctx?.context?.[FORCE_VERSION_SYMBOL];
+			if (forcedVersion) {
+				const entry = manager.#registry.get(logicalPath);
+				if (entry?.versions.has(forcedVersion)) return forcedVersion;
+			}
+
+			
+			
+			const callerWrapper = ctx?.currentWrapper ?? null;
+			const allVersions = manager.buildAllVersionsArg(logicalPath);
+			const caller = manager.buildCallerArg(callerWrapper);
+
+			
+			let tag = manager.resolveForPath(logicalPath, allVersions, caller);
+
+			if (tag == null) {
+				
+				tag = manager.getDefaultVersion(logicalPath);
+				
+				
+				
+				if (tag != null) {
+					manager.slothlet.debug("versioning", {
+						key: "DEBUG_VERSION_DEFAULT_USED",
+						apiPath: logicalPath,
+						version: tag
+					});
+				}
+			}
+
+			return tag;
+		};
+
+		
+		const resolveVersionedWrapper = () => {
+			const versionTag = resolveVersion();
+			
+			
+			
+			if (!versionTag) return null;
+			
+			
+			return manager.#walkApiPath([versionTag, ...logicalPath.split(".")]);
+		};
+
+		const handlers = {
+			
+			get(t, prop) {
+				
+				if (typeof prop === "string") {
+					if (prop === "____slothletInternal" || prop === "_impl" || prop === "__impl" || prop === "__state" || prop === "__invalid") {
+						return undefined;
+					}
+				}
+
+				
+				if (prop === "__isVersionDispatcher") return true;
+				
+				
+				if (prop === "__mode") return "eager";
+				if (prop === "__apiPath") return logicalPath;
+				
+				
+				if (prop === "__slothletPath") return logicalPath;
+				if (prop === "__isCallable") return false;
+				
+				
+				
+				
+				if (prop === "__materializeOnCreate") return false;
+				if (prop === "__materialized") return true;
+				if (prop === "__inFlight") return false;
+				if (prop === "__displayName") return displayName;
+				if (prop === "__moduleID") return `versionDispatcher:${logicalPath}`;
+				if (prop === "_materialize") return () => {};
+				if (prop === "length") return 0;
+				if (prop === "name") return displayName;
+				
+
+				
+				
+				
+				if (prop === "then") return undefined;
+
+				
+				
+				
+				if (prop === "constructor") return Object.prototype.constructor;
+
+				
+				if (prop === Symbol.toStringTag) {
+					const vw = resolveVersionedWrapper();
+					
+					
+					if (!vw) return "Object";
+					return vw[Symbol.toStringTag];
+				}
+
+				
+				
+				
+				
+				
+				if (typeof prop === "symbol" && prop.toString() === "Symbol(nodejs.util.inspect.custom)") {
+					return () => {
+						const vw = resolveVersionedWrapper();
+						if (vw) {
+							try {
+								return inspect(vw);
+							} catch {
+								
+								void 0; 
+							}
+						}
+						
+						const entry = manager.#registry.get(logicalPath);
+						const versions = entry ? Array.from(entry.versions.keys()) : [];
+						return { __versionDispatcher: logicalPath, versions };
+					};
+				}
+				
+
+				
+				if (prop === "toString") return () => `[VersionDispatcher: ${logicalPath}]`;
+
+				
+				if (prop === "valueOf") return () => dispatcherProxy;
+
+				
+				if (prop === "toJSON") return () => undefined;
+
+				
+				if (typeof prop === "symbol") return undefined;
+
+				
+				if (prop === "__metadata" || prop === "__filePath" || prop === "__sourceFolder" || prop === "__type") {
+					const vw = resolveVersionedWrapper();
+					
+					
+					
+					if (!vw) return undefined;
+					return vw[prop];
+				}
+
+				
+				
+				const versionTag = resolveVersion();
+				
+				
+				
+				if (!versionTag) {
+					throw new manager.SlothletError("VERSION_NO_DEFAULT", {
+						apiPath: logicalPath
+					});
+				}
+
+				
+				const versionedWrapper = manager.#walkApiPath([versionTag, ...logicalPath.split(".")]);
+				
+				
+				
+				if (!versionedWrapper) return undefined;
+
+				return versionedWrapper[prop];
+			},
+
+			
+			
+			apply() {
+				throw new manager.SlothletError("VERSION_DISPATCH_NOT_CALLABLE", {
+					apiPath: logicalPath
+				});
+			},
+
+			
+			has(t, key) {
+				
+				
+				
+				if (Reflect.has(t, key)) return true;
+				const entry = manager.#registry.get(logicalPath);
+				
+				
+				if (!entry) return false;
+				for (const ve of entry.versions.values()) {
+					const vw = manager.#walkApiPath(ve.versionedParts);
+					
+					
+					
+					
+					
+					if (vw && key in vw) return true;
+				}
+				return false;
+			},
+
+			
+			ownKeys(t) {
+				const keySet = new Set(Reflect.ownKeys(t));
+				const entry = manager.#registry.get(logicalPath);
+				
+				
+				if (entry) {
+					for (const ve of entry.versions.values()) {
+						const vw = manager.#walkApiPath(ve.versionedParts);
+						
+						
+						if (vw) {
+							for (const k of Reflect.ownKeys(Object(vw))) {
+								keySet.add(k);
+							}
+						}
+					}
+				}
+				return Array.from(keySet);
+			},
+
+			
+			getOwnPropertyDescriptor(t, prop) {
+				
+				const targetDesc = Reflect.getOwnPropertyDescriptor(t, prop);
+				if (targetDesc) return { configurable: true, enumerable: true, writable: false, value: t[prop] };
+
+				
+				
+				
+				return { configurable: true, enumerable: true, writable: false, value: undefined };
+			}
+		};
+
+		let dispatcherProxy;
+		dispatcherProxy = new Proxy(target, handlers);
+		return dispatcherProxy;
+	}
+
+	
+	updateDispatcher(logicalPath) {
+		
+		
+		if (this.#dispatchers.has(logicalPath)) {
+			return;
+		}
+
+		const dispatcher = this.createDispatcher(logicalPath);
+		this.#dispatchers.set(logicalPath, dispatcher);
+
+		const parts = logicalPath.split(".");
+		const mountOptions = {
+			collisionMode: "replace",
+			moduleID: `versionDispatcher:${logicalPath}`,
+			allowOverwrite: true,
+			mutateExisting: false
+		};
+
+		
+		
+		
+		if (this.slothlet.api) {
+			this.slothlet.handlers.apiManager.setValueAtPath(this.slothlet.api, parts, dispatcher, mountOptions);
+		}
+		
+		
+		if (this.slothlet.boundApi) {
+			this.slothlet.handlers.apiManager.setValueAtPath(this.slothlet.boundApi, parts, dispatcher, mountOptions);
+		}
+	}
+
+	
+	teardownDispatcher(logicalPath) {
+		this.#dispatchers.delete(logicalPath);
+
+		const parts = logicalPath.split(".");
+		
+		
+		
+		if (this.slothlet.api) {
+			this.slothlet.handlers.apiManager.deletePath(this.slothlet.api, parts).catch(() => {});
+		}
+		if (this.slothlet.boundApi) {
+			this.slothlet.handlers.apiManager.deletePath(this.slothlet.boundApi, parts).catch(() => {});
+		}
+		
+	}
+
+	
+
+	
+	onVersionedModuleReload(moduleID) {
+		const key = this.#moduleToVersionKey.get(moduleID);
+		if (!key) return;
+
+		const { logicalPath } = key;
+
+		
+		this.updateDispatcher(logicalPath);
+
+		this.slothlet.debug("versioning", {
+			key: "DEBUG_VERSION_REGISTERED",
+			version: key.versionTag,
+			logicalPath,
+			moduleID
+		});
+	}
+
+	
+	shutdown() {
+		this.#registry.clear();
+		this.#versionMetadataByModule.clear();
+		this.#moduleToVersionKey.clear();
+		this.#dispatchers.clear();
+	}
+}