@cldmv/slothlet 2.11.0 → 3.0.1

package/dist/lib/handlers/metadata.mjs

@@ -0,0 +1,500 @@
+/*
+	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";
+import { resolveWrapper } from "@cldmv/slothlet/handlers/unified-wrapper";
+import { verifyToken } from "@cldmv/slothlet/handlers/lifecycle-token";
+
+
+export class Metadata extends ComponentBase {
+	static slothletProperty = "metadata";
+
+	
+	#secureMetadata = new WeakMap(); 
+
+	
+	#userMetadataStore = new Map(); 
+	#globalUserMetadata = {}; 
+
+	_instanceId = null;
+
+	
+	constructor(slothlet) {
+		super(slothlet);
+		this._instanceId = `metadata_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+	}
+
+	
+	#deepFreeze(obj) {
+		
+		if (Object.isFrozen(obj)) return obj;
+
+		
+		Object.freeze(obj);
+
+		
+		Object.getOwnPropertyNames(obj).forEach((prop) => {
+			if (obj[prop] !== null && typeof obj[prop] === "object") {
+				this.#deepFreeze(obj[prop]);
+			}
+		});
+
+		return obj;
+	}
+
+	
+	tagSystemMetadata(target, systemData, token) {
+		
+		
+		
+		
+		if (!verifyToken(this.slothlet, token)) {
+			throw new this.SlothletError("METADATA_LIFECYCLE_BYPASS", {}, null, { validationError: true });
+		}
+
+		if (!target) return;
+
+		
+		if (typeof target !== "object" && typeof target !== "function") {
+			return;
+		}
+
+		
+		let fullModuleID = systemData.moduleID;
+		if (systemData.apiPath && systemData.moduleID) {
+			const apiPathSlashes = systemData.apiPath.replace(/\./g, "/");
+			fullModuleID = `${systemData.moduleID}:${apiPathSlashes}`;
+		}
+
+		
+		let sourceFolder = systemData.sourceFolder;
+		if (!sourceFolder && systemData.filePath) {
+			
+			const pathModule = this.slothlet.helpers.resolver.path;
+			sourceFolder = pathModule.dirname(systemData.filePath);
+		}
+
+		
+		const frozenSystem = Object.freeze({
+			filePath: systemData.filePath,
+			sourceFolder: sourceFolder,
+			apiPath: systemData.apiPath,
+			moduleID: fullModuleID,
+			taggedAt: Date.now()
+		});
+
+		this.#secureMetadata.set(target, frozenSystem);
+	}
+
+	
+	getSystemMetadata(target) {
+		if (!target) return null;
+
+		
+		const actualTarget = resolveWrapper(target) ?? target;
+
+		
+		const systemData = this.#secureMetadata.get(actualTarget.____slothletInternal?.impl || actualTarget);
+		return systemData || null;
+	}
+
+	
+	getMetadata(target) {
+		if (!target) return {};
+
+		
+		const actualTarget = resolveWrapper(target) ?? target;
+
+		
+		
+		const systemData = this.#secureMetadata.get(actualTarget) || this.#secureMetadata.get(actualTarget.____slothletInternal?.impl) || {};
+
+		
+		
+		
+		const moduleID = systemData.moduleID || systemData.moduleID;
+		const apiPath = systemData.apiPath;
+
+		
+		
+		
+		
+		
+		
+		const collectMetadataFromParents = (path) => {
+			const parts = path.split(".");
+			const collected = {};
+
+			
+			for (let i = 1; i <= parts.length; i++) {
+				const parentPath = parts.slice(0, i).join(".");
+				const parentMeta = this.#userMetadataStore.get(parentPath);
+				if (parentMeta?.metadata) {
+					Object.assign(collected, parentMeta.metadata);
+				}
+			}
+
+			return collected;
+		};
+
+		const userMetadataByModule = moduleID ? this.#userMetadataStore.get(moduleID) : null;
+		const userMetadataByPath = apiPath ? collectMetadataFromParents(apiPath) : {};
+
+		
+		const userData = {
+			...userMetadataByPath,
+			...(userMetadataByModule?.metadata || {})
+		};
+
+		
+		const combined = {
+			...this.#globalUserMetadata,
+			...userData,
+			...systemData 
+		};
+
+		
+		if (combined.metadata && typeof combined.metadata === "object") {
+			const { metadata, ...rest } = combined;
+			return this.#deepFreeze({
+				...rest,
+				...metadata
+			});
+		}
+
+		return this.#deepFreeze(combined);
+	}
+
+	
+	setGlobalMetadata(key, value) {
+		this.#globalUserMetadata[key] = value;
+	}
+
+	
+	setUserMetadata(target, key, value) {
+		if (typeof target !== "function" && typeof target !== "object") {
+			throw new this.SlothletError("INVALID_METADATA_TARGET", {
+				target: typeof target,
+				expected: "function or object"
+			});
+		}
+
+		
+		const actualTarget = resolveWrapper(target) ?? target;
+
+		
+		
+		
+		const systemData = this.#secureMetadata.get(actualTarget) || this.#secureMetadata.get(actualTarget.____slothletInternal?.impl) || {};
+		const moduleID = systemData.moduleID;
+
+		if (!moduleID) {
+			throw new this.SlothletError("METADATA_NO_MODULE_ID", {}, null, { validationError: true });
+		}
+
+		
+		let entry = this.#userMetadataStore.get(moduleID);
+		if (!entry) {
+			entry = { metadata: {}, apiPaths: new Set() };
+			this.#userMetadataStore.set(moduleID, entry);
+		}
+
+		
+		entry.metadata[key] = value;
+
+		
+		
+		
+		const apiPath = systemData.apiPath;
+		if (apiPath) {
+			let pathEntry = this.#userMetadataStore.get(apiPath);
+			if (!pathEntry) {
+				pathEntry = { metadata: {}, apiPaths: new Set() };
+				this.#userMetadataStore.set(apiPath, pathEntry);
+			}
+			pathEntry.metadata[key] = value;
+			pathEntry.apiPaths.add(apiPath);
+		}
+	}
+
+	
+	removeUserMetadata(target, key) {
+		if (typeof target !== "function" && typeof target !== "object") {
+			throw new this.SlothletError("INVALID_METADATA_TARGET", {
+				target: typeof target,
+				expected: "function or object"
+			});
+		}
+
+		
+		const actualTarget = resolveWrapper(target) ?? target;
+
+		
+		const systemData = this.#secureMetadata.get(actualTarget) || this.#secureMetadata.get(actualTarget.____slothletInternal?.impl) || {};
+		const moduleID = systemData.moduleID;
+		const apiPath = systemData.apiPath;
+
+		if (!moduleID) return;
+
+		
+		const applyRemoval = (storeKey) => {
+			const storeEntry = this.#userMetadataStore.get(storeKey);
+			if (!storeEntry) return;
+
+			if (key === undefined) {
+				this.#userMetadataStore.delete(storeKey);
+			} else if (Array.isArray(key)) {
+				for (const k of key) {
+					if (typeof k !== "string") {
+						throw new this.SlothletError("INVALID_METADATA_KEY", {
+							key: k,
+							type: typeof k,
+							expected: "string"
+						});
+					}
+					delete storeEntry.metadata[k];
+				}
+			} else if (typeof key === "object" && key !== null) {
+				for (const [metadataKey, nestedKeys] of Object.entries(key)) {
+					if (!Array.isArray(nestedKeys)) {
+						throw new this.SlothletError("INVALID_METADATA_KEY", {
+							key: metadataKey,
+							type: typeof nestedKeys,
+							expected: "array"
+						});
+					}
+					const metadataValue = storeEntry.metadata[metadataKey];
+					if (metadataValue && typeof metadataValue === "object") {
+						for (const nestedKey of nestedKeys) {
+							if (typeof nestedKey !== "string") {
+								throw new this.SlothletError("INVALID_METADATA_KEY", {
+									key: nestedKey,
+									type: typeof nestedKey,
+									expected: "string"
+								});
+							}
+							delete metadataValue[nestedKey];
+						}
+					}
+				}
+			} else if (typeof key === "string") {
+				delete storeEntry.metadata[key];
+			} else {
+				throw new this.SlothletError("INVALID_METADATA_KEY", {
+					key: key,
+					type: typeof key,
+					expected: "string, string[], or object"
+				});
+			}
+		};
+
+		
+		
+		applyRemoval(moduleID);
+		if (apiPath && apiPath !== moduleID) {
+			applyRemoval(apiPath);
+		}
+	}
+
+	
+	registerUserMetadata(identifier, metadata) {
+		if (!identifier || typeof identifier !== "string") {
+			throw new this.SlothletError(
+				"INVALID_ARGUMENT",
+				{
+					argument: "identifier",
+					expected: "non-empty string",
+					received: typeof identifier
+				},
+				null,
+				{ validationError: true }
+			);
+		}
+
+		let entry = this.#userMetadataStore.get(identifier);
+		if (!entry) {
+			entry = { metadata: {}, apiPaths: new Set() };
+			this.#userMetadataStore.set(identifier, entry);
+		}
+		
+		entry.metadata = { ...entry.metadata, ...metadata };
+		
+		entry.apiPaths.add(identifier);
+	}
+
+	
+	removeUserMetadataByApiPath(apiPath) {
+		if (!apiPath) return;
+		this.#userMetadataStore.delete(apiPath);
+	}
+
+	
+	setPathMetadata(apiPath, keyOrObj, value) {
+		if (typeof apiPath !== "string" || !apiPath) {
+			throw new this.SlothletError(
+				"INVALID_ARGUMENT",
+				{ argument: "apiPath", expected: "non-empty string", received: typeof apiPath },
+				null,
+				{ validationError: true }
+			);
+		}
+
+		const metadataObj = typeof keyOrObj === "string" ? { [keyOrObj]: value } : keyOrObj;
+
+		if (!metadataObj || typeof metadataObj !== "object" || Array.isArray(metadataObj)) {
+			throw new this.SlothletError(
+				"INVALID_ARGUMENT",
+				{ argument: "keyOrObj", expected: "string key or plain object", received: typeof keyOrObj },
+				null,
+				{ validationError: true }
+			);
+		}
+
+		this.registerUserMetadata(apiPath, metadataObj);
+	}
+
+	
+	removePathMetadata(apiPath, key) {
+		if (!apiPath || typeof apiPath !== "string") return;
+
+		const entry = this.#userMetadataStore.get(apiPath);
+		if (!entry) return;
+
+		if (key === undefined) {
+			this.#userMetadataStore.delete(apiPath);
+		} else if (Array.isArray(key)) {
+			for (const k of key) {
+				if (typeof k !== "string") {
+					throw new this.SlothletError("INVALID_METADATA_KEY", {
+						key: k,
+						type: typeof k,
+						expected: "string"
+					});
+				}
+				delete entry.metadata[k];
+			}
+		} else if (typeof key === "string") {
+			delete entry.metadata[key];
+		} else {
+			throw new this.SlothletError("INVALID_METADATA_KEY", {
+				key,
+				type: typeof key,
+				expected: "string or string[]"
+			});
+		}
+	}
+
+	
+	exportUserState() {
+		const storeCopy = new Map();
+		for (const [key, entry] of this.#userMetadataStore) {
+			storeCopy.set(key, {
+				metadata: { ...entry.metadata },
+				apiPaths: new Set(entry.apiPaths)
+			});
+		}
+		return {
+			globalMetadata: { ...this.#globalUserMetadata },
+			userMetadataStore: storeCopy
+		};
+	}
+
+	
+	importUserState(state) {
+		if (!state) return;
+
+		
+		if (state.globalMetadata) {
+			for (const [k, v] of Object.entries(state.globalMetadata)) {
+				if (!(k in this.#globalUserMetadata)) {
+					this.#globalUserMetadata[k] = v;
+				}
+			}
+		}
+
+		
+		if (state.userMetadataStore) {
+			for (const [key, savedEntry] of state.userMetadataStore) {
+				const existing = this.#userMetadataStore.get(key);
+				if (!existing) {
+					
+					this.#userMetadataStore.set(key, {
+						metadata: { ...savedEntry.metadata },
+						apiPaths: new Set(savedEntry.apiPaths)
+					});
+				} else {
+					
+					existing.metadata = { ...savedEntry.metadata, ...existing.metadata };
+					for (const p of savedEntry.apiPaths) existing.apiPaths.add(p);
+				}
+			}
+		}
+	}
+
+	
+	async get(path) {
+		if (typeof path !== "string") {
+			throw new this.SlothletError("INVALID_ARGUMENT", {
+				argument: "path",
+				expected: "string",
+				received: typeof path
+			});
+		}
+
+		const apiRoot = this.slothlet.api;
+		if (!apiRoot) return null;
+
+		const parts = path.split(".");
+		let target = apiRoot;
+
+		for (const part of parts) {
+			if (!target || (typeof target !== "object" && typeof target !== "function")) {
+				return null;
+			}
+			target = target[part];
+		}
+
+		if (target && typeof target._materialize === "function") {
+			await target._materialize();
+		}
+
+		if (typeof target === "function" || (target && resolveWrapper(target)?.____slothletInternal?.impl)) {
+			return this.getMetadata(target);
+		}
+
+		return null;
+	}
+
+	
+	self() {
+		const ctx = this.slothlet.contextManager?.tryGetContext();
+		if (!ctx || !ctx.currentWrapper) {
+			throw new this.SlothletError("RUNTIME_NO_ACTIVE_CONTEXT", {}, null, { validationError: true });
+		}
+		return this.getMetadata(ctx.currentWrapper);
+	}
+
+	
+	caller() {
+		const ctx = this.slothlet.contextManager?.tryGetContext();
+		if (!ctx || !ctx.callerWrapper) return null;
+		return this.getMetadata(ctx.callerWrapper);
+	}
+}