@cldmv/slothlet 2.11.0 → 3.0.1

package/dist/lib/builders/api-assignment.mjs

@@ -0,0 +1,605 @@
+/*
+	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";
+
+
+export class ApiAssignment extends ComponentBase {
+	static slothletProperty = "apiAssignment";
+
+	
+	constructor(slothlet) {
+		super(slothlet);
+	}
+
+	
+	isWrapperProxy(value) {
+		return !!(value && resolveWrapper(value));
+	}
+
+	
+	assignToApiPath(targetApi, key, value, options = {}) {
+		const valueIsWrapper = this.isWrapperProxy(value);
+		
+		
+		const valueId = valueIsWrapper ? (resolveWrapper(value)?.____slothletInternal?.id ?? "no-id") : "not-wrapper";
+		this.slothlet.debug("api", {
+			key: "DEBUG_MODE_ASSIGN_TO_API",
+			propKey: key,
+			valueId,
+			typeOf: typeof value
+		});
+
+		const {
+			allowOverwrite = false,
+			mutateExisting = false,
+			useCollisionDetection = false,
+			config = null,
+			collisionContext = "initial",
+			syncWrapper = null,
+			collisionMode = "merge", 
+			moduleID = null
+		} = options;
+
+		
+		const existing = targetApi[key];
+
+		
+		if (existing !== undefined && this.isWrapperProxy(existing) && this.isWrapperProxy(value)) {
+			if (mutateExisting && syncWrapper) {
+				syncWrapper(existing, value, config, collisionMode, moduleID);
+				return true;
+			}
+			
+		}
+
+		
+		this.slothlet.debug("api", {
+			key: "DEBUG_MODE_COLLISION_CHECK",
+			propKey: key,
+			useCollisionDetection,
+			hasConfig: !!config,
+			hasExisting: existing !== undefined,
+			existingType: typeof existing
+		});
+		if (useCollisionDetection && config && existing !== undefined) {
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_COLLISION_DETECT",
+				propKey: key,
+				context: collisionContext,
+				existingType: typeof existing,
+				valueType: typeof value
+			});
+			
+			const collisionMode = config.collision?.[collisionContext] || "merge";
+
+			if (collisionMode === "error") {
+				
+				
+				const SlothletError = this.slothlet?.SlothletError || Error;
+				throw new SlothletError("COLLISION_ERROR", {
+					key: String(key),
+					collisionMode,
+					collisionContext
+				});
+			}
+
+			if (collisionMode === "skip") {
+				
+				return false;
+			}
+
+			
+			let effectiveMode = collisionMode;
+			if (collisionMode === "warn") {
+				new this.slothlet.SlothletWarning("WARNING_COLLISION_FILE_FOLDER_MERGE", {
+					key: String(key)
+				});
+				
+				effectiveMode = "merge";
+			}
+
+			
+			
+			const existingIsWrapper = this.isWrapperProxy(existing);
+			const valueIsWrapper = this.isWrapperProxy(value);
+
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_COLLISION_WRAPPER_DETECTION",
+				propKey: key,
+				existingIsWrapper,
+				valueIsWrapper,
+				hasExistingWrapper: resolveWrapper(existing) ? "yes" : "no",
+				hasValueWrapper: resolveWrapper(value) ? "yes" : "no"
+			});
+
+			if (existingIsWrapper && valueIsWrapper) {
+				const existingWrapper = resolveWrapper(existing);
+				const valueWrapper = resolveWrapper(value);
+				const existingIsLazyUnmaterialized =
+					existingWrapper.____slothletInternal.mode === "lazy" && !existingWrapper.____slothletInternal.state.materialized;
+				const valueIsLazyUnmaterialized =
+					valueWrapper.____slothletInternal.mode === "lazy" && !valueWrapper.____slothletInternal.state.materialized;
+
+				this.slothlet.debug("api", {
+					key: "DEBUG_MODE_COLLISION_LAZY_DETECTION",
+					propKey: key,
+					effectiveMode,
+					existingLazy: existingIsLazyUnmaterialized,
+					valueLazy: valueIsLazyUnmaterialized
+				});
+
+				
+				
+				
+				if (existingIsLazyUnmaterialized) {
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_COLLISION_SET_MODE_EXISTING_WRAPPER",
+						effectiveMode,
+						apiPath: existingWrapper.____slothletInternal.apiPath
+					});
+					existingWrapper.____slothletInternal.state.collisionMode = effectiveMode;
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_COLLISION_VERIFIED_EXISTING_WRAPPER_MODE",
+						collisionMode: existingWrapper.____slothletInternal.state.collisionMode
+					});
+				}
+				if (valueIsLazyUnmaterialized) {
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_COLLISION_SET_MODE_VALUE_WRAPPER",
+						effectiveMode,
+						apiPath: valueWrapper.____slothletInternal.apiPath
+					});
+					valueWrapper.____slothletInternal.state.collisionMode = effectiveMode;
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_COLLISION_VERIFIED_VALUE_WRAPPER_MODE",
+						collisionMode: valueWrapper.____slothletInternal.state.collisionMode
+					});
+
+					
+					
+					if (effectiveMode === "replace") {
+						this.slothlet.debug("api", {
+							key: "DEBUG_MODE_COLLISION_REPLACE_MATERIALIZE",
+							apiPath: valueWrapper.____slothletInternal.apiPath
+						});
+						valueWrapper._materialize(); 
+					}
+				}
+			}
+
+			
+			if (effectiveMode === "replace") {
+				
+				
+				
+				if (existingIsWrapper && valueIsWrapper) {
+					const existingWrapper = resolveWrapper(existing);
+					const valueWrapper = resolveWrapper(value);
+					
+					
+					
+					
+					const existingIsLazyUnmaterialized =
+						existingWrapper.____slothletInternal.mode === "lazy" && !existingWrapper.____slothletInternal.state.materialized;
+					const valueIsLazyUnmaterialized =
+						valueWrapper.____slothletInternal.mode === "lazy" && !valueWrapper.____slothletInternal.state.materialized;
+
+					
+					if (valueIsLazyUnmaterialized && !existingIsLazyUnmaterialized) {
+						this.slothlet.debug("api", {
+							key: "DEBUG_MODE_COLLISION_REPLACE_NO_COPY"
+						});
+						this.slothlet.debug("api", {
+							key: "DEBUG_MODE_COLLISION_REPLACE_BEFORE",
+							propKey: key,
+							currentWrapperId: resolveWrapper(existing)?.____slothletInternal.id
+						});
+						this.slothlet.debug("api", {
+							key: "DEBUG_MODE_COLLISION_ASSIGN_REPLACING_WITH_LAZY",
+							propKey: key,
+							collisionMode: valueWrapper.____slothletInternal.state.collisionMode
+						});
+						targetApi[key] = value;
+						this.slothlet.debug("api", {
+							key: "DEBUG_MODE_COLLISION_REPLACE_AFTER",
+							propKey: key,
+							newWrapperId: resolveWrapper(targetApi[key])?.____slothletInternal.id
+						});
+						this.slothlet.debug("api", {
+							key: "DEBUG_MODE_COLLISION_REPLACE_VERIFY",
+							expectedId: valueWrapper.____slothletInternal.id,
+							actualId: resolveWrapper(targetApi[key])?.____slothletInternal.id
+						});
+						return true; 
+					}
+					
+				}
+				
+				targetApi[key] = value;
+				return true;
+			}
+
+			
+			
+			
+			if (effectiveMode === "merge" || effectiveMode === "merge-replace") {
+				const isMergeReplace = effectiveMode === "merge-replace";
+				
+
+				if (existingIsWrapper && valueIsWrapper) {
+					
+					const existingWrapper = resolveWrapper(existing);
+					const valueWrapper = resolveWrapper(value);
+
+					
+					
+					const existingIsLazyUnmaterialized =
+						existingWrapper.____slothletInternal.mode === "lazy" && !existingWrapper.____slothletInternal.state.materialized;
+					const valueIsLazyUnmaterialized =
+						valueWrapper.____slothletInternal.mode === "lazy" && !valueWrapper.____slothletInternal.state.materialized;
+
+					if (existingIsLazyUnmaterialized && !valueIsLazyUnmaterialized) {
+						
+						
+
+						
+						const valueMetadata = this.slothlet.handlers?.metadata?.getMetadata(value);
+						const valueFilePath = valueMetadata?.filePath;
+
+						
+						
+						
+						
+						
+						if (!existingWrapper.____slothletInternal.childFilePathsPreMaterialize) {
+							existingWrapper.____slothletInternal.childFilePathsPreMaterialize = {};
+						}
+
+						const valueChildKeys = Object.keys(valueWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
+						for (const key of valueChildKeys) {
+							
+							Object.defineProperty(existingWrapper, key, {
+								configurable: true
+							});
+							
+							if (valueFilePath) {
+								existingWrapper.____slothletInternal.childFilePathsPreMaterialize[key] = valueFilePath;
+							}
+						}
+
+						return true; 
+					} else if (valueIsLazyUnmaterialized && !existingIsLazyUnmaterialized) {
+						
+						
+						
+						
+						
+						
+
+						
+						
+						if (!isMergeReplace) {
+							
+							
+
+							
+							const existingMetadata = this.slothlet.handlers?.metadata?.getMetadata(existing);
+							const existingFilePath = existingMetadata?.filePath;
+
+							
+							if (!valueWrapper.____slothletInternal.childFilePathsPreMaterialize) {
+								valueWrapper.____slothletInternal.childFilePathsPreMaterialize = {};
+							}
+
+							const existingChildKeys = Object.keys(existingWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
+							
+							
+							
+							this.slothlet.debug("api", {
+								key: "DEBUG_MODE_COLLISION_COPY_CHILD_KEYS",
+								existingChildKeys: existingChildKeys.join(","),
+								fromApiPath: existingWrapper.____slothletInternal.apiPath,
+								toApiPath: valueWrapper.____slothletInternal.apiPath,
+								valueWrapperId: valueWrapper.____slothletInternal.id || "no-id"
+							});
+
+							
+							if (!valueWrapper.____slothletInternal.collisionMergedKeys) {
+								valueWrapper.____slothletInternal.collisionMergedKeys = new Set();
+							}
+
+							for (const key of existingChildKeys) {
+								const child = existingWrapper[key];
+								this.slothlet.debug("api", {
+									key: "DEBUG_MODE_COLLISION_COPY_INDIVIDUAL_KEY",
+									propKey: key,
+									childName: child?.name,
+									typeOf: typeof child,
+									valueWrapperId: valueWrapper.____slothletInternal.id || "no-id"
+								});
+								Object.defineProperty(valueWrapper, key, {
+									value: child,
+									writable: false,
+									enumerable: true,
+									configurable: true
+								});
+								
+								valueWrapper.____slothletInternal.collisionMergedKeys.add(key);
+								
+								if (existingFilePath) {
+									valueWrapper.____slothletInternal.childFilePathsPreMaterialize[key] = existingFilePath;
+								}
+							}
+
+							
+							
+							
+							
+							this.slothlet.debug("api", {
+								key: "DEBUG_MODE_COLLISION_TRIGGER_EARLY_MAT",
+								apiPath: valueWrapper.____slothletInternal.apiPath
+							});
+							valueWrapper.____slothletInternal.needsImmediateChildAdoption = true;
+							if (
+								valueWrapper.____slothletInternal.materializeFunc &&
+								!valueWrapper.____slothletInternal.state?.materialized &&
+								!valueWrapper.____slothletInternal.state?.inFlight
+							) {
+								valueWrapper._materialize().catch((err) => {
+									new this.slothlet.SlothletWarning(
+										"WARNING_COLLISION_TRIGGER_MATERIALIZE_ERROR",
+										{
+											apiPath: valueWrapper.____slothletInternal.apiPath
+										},
+										err
+									);
+								});
+							}
+							
+						} else {
+							
+							
+							
+							
+							valueWrapper._mergeAfterMaterialize = {
+								existingWrapper,
+								isMergeReplace: true
+							};
+						}
+
+						
+						this.slothlet.debug("api", {
+							key: "DEBUG_MODE_COLLISION_ASSIGN_REPLACING_WITH_LAZY",
+							propKey: key,
+							collisionMode: valueWrapper.____slothletInternal.state.collisionMode
+						});
+						targetApi[key] = value;
+						return true; 
+					}
+
+					
+					
+					const existingChildCount = Object.keys(existingWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__")).length;
+					const valueChildCount = Object.keys(valueWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__")).length;
+					if (existingWrapper.____slothletInternal.impl && existingChildCount === 0) {
+						existingWrapper.___adoptImplChildren();
+					}
+					if (valueWrapper.____slothletInternal.impl && valueChildCount === 0) {
+						valueWrapper.___adoptImplChildren();
+					}
+
+					
+					
+					
+					
+					
+					
+					const valueChildKeys2 = Object.keys(valueWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
+					for (const key of valueChildKeys2) {
+						const child = valueWrapper[key];
+						const isInternal = typeof key === "string" && (key.startsWith("_") || key.startsWith("__"));
+						
+						const keyExists = !isInternal && Object.prototype.hasOwnProperty.call(existingWrapper, key);
+
+						if (!keyExists) {
+							Object.defineProperty(existingWrapper, key, {
+								value: child,
+								writable: false,
+								enumerable: true,
+								configurable: true
+							});
+						} else if (isMergeReplace) {
+							const descriptor = Object.getOwnPropertyDescriptor(existingWrapper, key);
+							
+							
+							
+							
+							if (descriptor?.configurable) {
+								delete existingWrapper[key];
+							}
+							Object.defineProperty(existingWrapper, key, {
+								value: child,
+								writable: false,
+								enumerable: true,
+								configurable: true
+							});
+						} else {
+							
+							
+							
+							const existingChild = existingWrapper[key];
+							const existingChildWrapper = resolveWrapper(existingChild);
+							const newChildWrapper = resolveWrapper(child);
+							
+							
+							if (existingChildWrapper && newChildWrapper) {
+								
+								const newChildChildCount = Object.keys(newChildWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__")).length;
+								if (newChildWrapper.____slothletInternal.impl && newChildChildCount === 0) {
+									newChildWrapper.___adoptImplChildren();
+								}
+								const newChildKeys = Object.keys(newChildWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
+								const ____existingChildKeys = Object.keys(existingChildWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
+								for (const childKey of newChildKeys) {
+									const childKeyExists = Object.prototype.hasOwnProperty.call(existingChildWrapper, childKey);
+									
+									
+									if (!childKeyExists) {
+										Object.defineProperty(existingChildWrapper, childKey, {
+											value: newChildWrapper[childKey],
+											writable: false,
+											enumerable: true,
+											configurable: true
+										});
+									}
+								}
+							}
+						}
+					}
+					
+					if (
+						valueWrapper.____slothletInternal.mode === "lazy" &&
+						!valueWrapper.____slothletInternal.state.materialized &&
+						valueWrapper.____slothletInternal.materializeFunc
+					) {
+						
+						
+						return false; 
+					}
+
+					return true;
+				} else if (existingIsWrapper && !valueIsWrapper) {
+					
+					const existingWrapper = resolveWrapper(existing);
+					const existingImpl = existingWrapper.__impl;
+					
+					
+					const mergedImpl = { ...(existingImpl || {}), ...value };
+					existingWrapper.___setImpl(mergedImpl);
+					return true;
+				} else if (!existingIsWrapper && valueIsWrapper) {
+					
+					
+				} else {
+					
+					
+					
+					if (typeof existing === "object" && existing !== null && typeof value === "object" && value !== null) {
+						Object.assign(existing, value);
+						return true;
+					}
+				}
+				
+			}
+
+			
+		}
+
+		
+		if (existing !== undefined && !allowOverwrite && !mutateExisting && !useCollisionDetection) {
+			return false; 
+		}
+
+		
+		targetApi[key] = value;
+		return true;
+	}
+
+	
+	async mergeApiObjects(targetApi, sourceApi, options = {}) {
+		const config = options.config;
+		if (config?.debug?.api) {
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_MERGE_API_OBJECTS_ENTRY",
+				targetApiType: typeof targetApi,
+				sourceApiType: typeof sourceApi
+			});
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_MERGE_API_OBJECTS_SOURCE_KEYS",
+				sourceApiKeys: sourceApi ? Object.keys(sourceApi) : []
+			});
+		}
+
+		
+		if (!sourceApi || (typeof sourceApi !== "object" && typeof sourceApi !== "function")) {
+			if (config?.debug?.api) {
+				this.slothlet.debug("api", {
+					key: "DEBUG_MODE_MERGE_API_OBJECTS_EXIT_INVALID_SOURCE"
+				});
+			}
+			return;
+		}
+
+		const { removeMissing = false, moduleID = null, ...assignOptions } = options;
+
+		
+		const sourceKeys = new Set(Object.keys(sourceApi));
+		for (const key of sourceKeys) {
+			const sourceValue = sourceApi[key];
+			const targetValue = targetApi[key];
+
+			if (config?.debug?.api) {
+				this.slothlet.debug("api", {
+					key: "DEBUG_MODE_MERGE_API_OBJECTS_PROCESSING_KEY",
+					propKey: key,
+					targetValueType: typeof targetValue,
+					sourceValueType: typeof sourceValue
+				});
+			}
+
+			
+			if (
+				targetValue &&
+				typeof targetValue === "object" &&
+				!this.isWrapperProxy(targetValue) &&
+				sourceValue &&
+				typeof sourceValue === "object" &&
+				!this.isWrapperProxy(sourceValue)
+			) {
+				if (config?.debug?.api) {
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_MERGE_API_OBJECTS_RECURSING",
+						propKey: key
+					});
+				}
+				await this.mergeApiObjects(targetValue, sourceValue, options);
+			} else {
+				
+				if (config?.debug?.api) {
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_MERGE_API_OBJECTS_CALLING_ASSIGN",
+						propKey: key
+					});
+				}
+				this.assignToApiPath(targetApi, key, sourceValue, { ...assignOptions, moduleID });
+			}
+		}
+
+		
+		if (removeMissing) {
+			for (const key of Object.keys(targetApi)) {
+				if (!sourceKeys.has(key)) {
+					delete targetApi[key];
+				}
+			}
+		}
+	}
+}