@cldmv/slothlet 2.8.0 → 2.10.0

package/dist/slothlet.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.
@@ -19,20 +19,23 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import { types as utilTypes } from "node:util";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { resolvePathFromCaller } from "@cldmv/slothlet/helpers/resolve-from-caller";
-import { sanitizePathName } from "@cldmv/slothlet/helpers/sanitize";
 import {
 	analyzeModule,
 	processModuleFromAnalysis,
-	getCategoryBuildingDecisions,
-	buildCategoryDecisions
+	buildCategoryStructure,
+	toapiPathKey,
+	shouldIncludeFile,
+	safeDefine,
+	deepMerge,
+	mutateLiveBindingFunction,
+	addApiFromFolder
 } from "@cldmv/slothlet/helpers/api_builder";
-import { updateInstanceData, cleanupInstance } from "./lib/helpers/instance-manager.mjs";
-import { disableAlsForEventEmitters, cleanupAllSlothletListeners } from "./lib/helpers/als-eventemitter.mjs";
-import { HookManager } from "./lib/helpers/hooks.mjs";
+import { updateInstanceData, cleanupInstance } from "@cldmv/slothlet/helpers/instance-manager";
+import { disableAlsForEventEmitters, cleanupAllSlothletListeners } from "@cldmv/slothlet/helpers/als-eventemitter";
+import { HookManager } from "@cldmv/slothlet/helpers/hooks";
 
 
 
@@ -72,6 +75,11 @@ let DEBUG = process.argv.includes("--slothletdebug")
 		: false;
 
 
+if (DEBUG && !process.env.SLOTHLET_DEBUG) {
+	process.env.SLOTHLET_DEBUG = "1";
+}
+
+
 export const self = {};
 
 
@@ -177,31 +185,18 @@ const slothletObject = {
 		if (!this.modes) {
 			this.modes = {};
 			const modesDir = path.join(__dirname, "lib", "modes");
-			
-			
+
 			const dirents = await fs.readdir(modesDir, { withFileTypes: true });
 			const modeFiles = dirents.filter((d) => d.isFile()).map((d) => path.join(modesDir, d.name));
-			
-			
 
 			for (const file of modeFiles) {
-				
-				
 				const modePath = file;
 
-				
-				
-				
-				
-
 				const modeName = path.parse(file).name.replace(/^slothlet_/, "");
 				if (!modeName || modeName.includes(" ")) continue;
 				try {
 					
 					const modeUrl = pathToFileURL(modePath).href;
-					
-					
-					
 
 					const imported = await import(modeUrl);
 					if (imported && typeof imported === "object") {
@@ -213,10 +208,6 @@ const slothletObject = {
 			}
 		}
 
-		
-		
-		
-
 		this.mode = executionEngine;
 		this.api_mode = api_mode;
 		let api;
@@ -224,7 +215,7 @@ const slothletObject = {
 		if (executionEngine === "singleton") {
 			
 			
-			const { context = null, reference = null, sanitize = null, hooks = false, engine, mode, ...loadConfig } = options;
+			const { context = null, reference = null, sanitize = null, hooks = false, scope, engine, mode, ...loadConfig } = options;
 			this.context = context;
 			this.reference = reference;
 
@@ -252,6 +243,20 @@ const slothletObject = {
 			this.hookManager = new HookManager(hooksEnabled, hooksPattern, { suppressErrors: hooksSuppressErrors });
 
 			
+			if (scope && typeof scope === "object") {
+				const mergeStrategy = scope.merge || "shallow";
+				if (mergeStrategy !== "shallow" && mergeStrategy !== "deep") {
+					throw new TypeError(`Invalid scope.merge value: "${mergeStrategy}". Must be "shallow" or "deep".`);
+				}
+				this.config.scope = { merge: mergeStrategy };
+			} else if (scope === false) {
+				this.config.scope = { enabled: false };
+			} else {
+				
+				this.config.scope = { merge: "shallow" };
+			}
+
+			
 			if (sanitize !== null) {
 				this.config.sanitize = sanitize;
 			}
@@ -278,9 +283,6 @@ const slothletObject = {
 			await this.load(loadConfig, { context, reference });
 
 			
-
-			
-			
 			return this.boundapi;
 		} else {
 			const { createEngine } = await import("./lib/engine/slothlet_engine.mjs");
@@ -318,17 +320,10 @@ const slothletObject = {
 			}
 		}
 
-		
-		
 		let apiDir = this.config.dir || "api";
 		
 		if (apiDir && !path.isAbsolute(apiDir)) {
-			
 			apiDir = resolvePathFromCaller(apiDir);
-			
-			
-			
-			
 		}
 
 		if (this.loaded) return this.api;
@@ -381,70 +376,22 @@ const slothletObject = {
 			}
 		}
 
-		
-
 		const l_ctxRef = { ...{ context: null, reference: null }, ...ctxRef };
 
-		
-		
-		
 		const _boundapi = this.createBoundApi(l_ctxRef.reference);
 
 		mutateLiveBindingFunction(this.boundapi, _boundapi);
 
 		this.updateBindings(this.context, this.reference, this.boundapi);
-		
-		
-		
-		
-		
-		
-		
-		
-		this.loaded = true;
-
-		
-		
-
-		
-
-		
-		
-		
-		
-		
 
-		
-		
-
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-		
+		this.loaded = true;
 
 		return this.boundapi;
 	},
 
 	
 	_toapiPathKey(name) {
-		return sanitizePathName(name, this.config.sanitize || {});
-		
+		return toapiPathKey(name, this.config.sanitize || {});
 	},
 
 	
@@ -452,288 +399,13 @@ const slothletObject = {
 		const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler } = options;
 
 		
-		const decisions = await buildCategoryDecisions(categoryPath, {
+		return buildCategoryStructure(categoryPath, {
 			currentDepth,
 			maxDepth,
 			mode,
 			subdirHandler,
 			instance: this
 		});
-
-		
-		if (decisions.type === "single-file") {
-			const { singleFile } = decisions;
-			const { mod, moduleName } = singleFile;
-
-			
-			if (decisions.shouldFlatten) {
-				switch (decisions.flattenType) {
-					case "function-folder-match":
-					case "default-function":
-						try {
-							Object.defineProperty(mod, "name", { value: decisions.preferredName, configurable: true });
-						} catch {
-							
-						}
-						return mod;
-
-					case "default-export-flatten":
-						
-						return mod;
-
-					case "object-auto-flatten":
-						
-						return mod[decisions.preferredName];
-
-					case "parent-level-flatten": {
-						
-						const exportValue = mod[Object.keys(mod).filter((k) => k !== "default")[0]];
-						return { [decisions.preferredName]: exportValue };
-					}
-
-					case "filename-folder-match-flatten":
-						
-						return mod;
-				}
-			}
-
-			
-			if (decisions.preferredName && decisions.preferredName !== moduleName) {
-				return { [decisions.preferredName]: mod };
-			}
-
-			
-			return { [moduleName]: mod };
-		}
-
-		
-		const categoryModules = {};
-		const { categoryName, processedModules, subdirectoryDecisions } = decisions;
-
-		
-		for (const moduleDecision of processedModules) {
-			const { moduleName, mod, type, apiPathKey, shouldFlatten, flattenType, specialHandling, processedExports } = moduleDecision;
-			
-			if (specialHandling === "category-merge") {
-				
-				if (
-					Object.prototype.hasOwnProperty.call(mod, categoryName) &&
-					typeof mod[categoryName] === "object" &&
-					mod[categoryName] !== null
-				) {
-					Object.assign(categoryModules, mod[categoryName]);
-					for (const [key, value] of Object.entries(mod)) {
-						if (key !== categoryName) categoryModules[this._toapiPathKey(key)] = value;
-					}
-				} else {
-					Object.assign(categoryModules, mod);
-				}
-			} else if (type === "function") {
-				
-				if (specialHandling === "multi-default-filename") {
-					try {
-						Object.defineProperty(mod, "name", { value: moduleName, configurable: true });
-					} catch {
-						
-					}
-					categoryModules[moduleName] = mod;
-				} else if (specialHandling === "prefer-function-name") {
-					categoryModules[apiPathKey] = mod;
-				} else {
-					
-					categoryModules[apiPathKey] = mod;
-				}
-			} else if (type === "self-referential") {
-				
-				categoryModules[moduleName] = mod[moduleName] || mod;
-			} else if (type === "object") {
-				
-				if (specialHandling === "preferred-export-names") {
-					Object.assign(categoryModules, processedExports);
-				} else if (shouldFlatten) {
-					switch (flattenType) {
-						case "single-default-object": {
-							
-							
-							let flattened;
-
-							
-							const defaultExport = mod.default;
-							const hasNamedExports = Object.keys(mod).some((k) => k !== "default");
-
-							if (hasNamedExports && defaultExport && typeof defaultExport === "object") {
-								
-								const isProxy = utilTypes?.isProxy?.(defaultExport) ?? false;
-
-								if (isProxy) {
-									
-									flattened = defaultExport;
-									let assignmentFailed = false;
-									
-									const failedMap = new Map();
-
-									
-									for (const [key, value] of Object.entries(mod)) {
-										if (key !== "default") {
-											try {
-												flattened[key] = value;
-											} catch (e) {
-												
-												assignmentFailed = true;
-												failedMap.set(key, value);
-												if (this.config?.debug) {
-													console.warn(
-														`Could not assign '${key}' to proxy object in module '${moduleName}' at '${categoryPath}':`,
-														e.message
-													);
-												}
-											}
-										}
-									}
-
-									
-									if (assignmentFailed) {
-										
-										
-										
-										
-										
-										
-										
-										
-										const originalProxy = flattened;
-										flattened = new Proxy(originalProxy, {
-											get(target, prop, receiver) {
-												
-												if (failedMap.has(prop)) return failedMap.get(prop);
-
-												
-												return Reflect.get(target, prop, receiver);
-											},
-											has(target, prop) {
-												
-												if (failedMap.has(prop)) return true;
-												return Reflect.has(target, prop);
-											},
-											ownKeys(target) {
-												const originalKeys = Reflect.ownKeys(target);
-												const failedKeys = Array.from(failedMap.keys());
-												return [...new Set([...originalKeys, ...failedKeys])];
-											},
-											getOwnPropertyDescriptor(target, prop) {
-												if (failedMap.has(prop)) {
-													return { configurable: true, enumerable: true, value: failedMap.get(prop) };
-												}
-												return Reflect.getOwnPropertyDescriptor(target, prop);
-											}
-										});
-									}
-								} else {
-									
-									flattened = { ...defaultExport };
-									for (const [key, value] of Object.entries(mod)) {
-										if (key !== "default") {
-											flattened[key] = value;
-										}
-									}
-								}
-							} else {
-								
-								flattened = defaultExport;
-							}
-
-							categoryModules[apiPathKey] = flattened;
-							break;
-						}
-						case "multi-default-no-default": {
-							
-							const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-							for (const key of moduleKeys) {
-								categoryModules[key] = mod[key];
-							}
-							break;
-						}
-						case "single-named-export-match":
-							
-							categoryModules[apiPathKey] = mod[apiPathKey];
-							break;
-						case "category-name-match-flatten": {
-							
-							const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
-							for (const key of moduleKeys) {
-								categoryModules[key] = mod[key];
-							}
-							break;
-						}
-					}
-				} else {
-					
-					categoryModules[apiPathKey] = mod;
-				}
-			}
-		}
-
-		
-		for (const subDirDecision of subdirectoryDecisions) {
-			if (subDirDecision.shouldRecurse) {
-				const { name, path: subDirPath, apiPathKey } = subDirDecision;
-				let subModule;
-
-				if (mode === "lazy" && typeof subdirHandler === "function") {
-					subModule = subdirHandler({
-						subDirEntry: { name },
-						subDirPath,
-						key: apiPathKey,
-						categoryModules,
-						currentDepth,
-						maxDepth
-					});
-				} else {
-					subModule = await this._buildCategory(subDirPath, {
-						currentDepth: currentDepth + 1,
-						maxDepth,
-						mode: "eager"
-					});
-				}
-
-				
-				
-				if (
-					typeof subModule === "function" &&
-					subModule.name &&
-					subModule.name.toLowerCase() === apiPathKey.toLowerCase() &&
-					subModule.name !== apiPathKey
-				) {
-					
-					categoryModules[subModule.name] = subModule;
-				} else {
-					categoryModules[apiPathKey] = subModule;
-				}
-			}
-		}
-
-		
-		const keys = Object.keys(categoryModules);
-		if (keys.length === 1) {
-			const singleKey = keys[0];
-			if (singleKey === categoryName) {
-				const single = categoryModules[singleKey];
-				if (typeof single === "function") {
-					if (single.name !== categoryName) {
-						try {
-							Object.defineProperty(single, "name", { value: categoryName, configurable: true });
-						} catch {
-							
-						}
-					}
-					return single;
-				} else if (single && typeof single === "object" && !Array.isArray(single)) {
-					return single;
-				}
-			}
-		}
-
-		return categoryModules;
 	},
 
 	
@@ -763,117 +435,8 @@ const slothletObject = {
 	},
 
 	
-	async _buildCategoryEnhanced(categoryPath, options = {}) {
-		const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler } = options;
-
-		
-		const decisions = await getCategoryBuildingDecisions(categoryPath, {
-			instance: this,
-			currentDepth,
-			maxDepth,
-			debug: this.config.debug
-		});
-
-		const { processingStrategy, categoryName, processedModules, subDirectories } = decisions;
-
-		
-		if (processingStrategy === "single-file" && processedModules.length === 1) {
-			const { processedModule, flattening } = processedModules[0];
-
-			if (flattening.shouldFlatten) {
-				
-				if (typeof processedModule === "function") {
-					try {
-						Object.defineProperty(processedModule, "name", { value: flattening.apiPathKey, configurable: true });
-					} catch {
-						
-					}
-				}
-				return processedModule;
-			}
-
-			
-			return { [flattening.apiPathKey]: processedModule };
-		}
-
-		
-		const categoryModules = {};
-
-		for (const { processedModule, flattening } of processedModules) {
-			categoryModules[flattening.apiPathKey] = processedModule;
-		}
-
-		
-		for (const { dirEntry: subDirEntry, apiPathKey: key } of subDirectories) {
-			const subDirPath = path.join(categoryPath, subDirEntry.name);
-			let subModule;
-
-			if (mode === "lazy" && typeof subdirHandler === "function") {
-				subModule = subdirHandler({
-					subDirEntry,
-					subDirPath,
-					key,
-					categoryModules,
-					currentDepth,
-					maxDepth
-				});
-			} else {
-				
-				subModule = await this._buildCategoryEnhanced(subDirPath, {
-					currentDepth: currentDepth + 1,
-					maxDepth,
-					mode: "eager"
-				});
-			}
-
-			
-			if (
-				typeof subModule === "function" &&
-				subModule.name &&
-				subModule.name.toLowerCase() === key.toLowerCase() &&
-				subModule.name !== key
-			) {
-				categoryModules[subModule.name] = subModule;
-			} else {
-				categoryModules[key] = subModule;
-			}
-		}
-
-		
-		const keys = Object.keys(categoryModules);
-		if (keys.length === 1) {
-			const singleKey = keys[0];
-			if (singleKey === categoryName) {
-				const single = categoryModules[singleKey];
-				if (typeof single === "function") {
-					if (single.name !== categoryName) {
-						try {
-							Object.defineProperty(single, "name", { value: categoryName, configurable: true });
-						} catch {
-							
-						}
-					}
-					return single;
-				} else if (single && typeof single === "object" && !Array.isArray(single)) {
-					return single;
-				}
-			}
-		}
-
-		return categoryModules;
-	},
-
-	
 	_shouldIncludeFile(entry) {
-		
-		if (!entry.isFile()) return false;
-		
-		if (!(entry.name.endsWith(".mjs") || entry.name.endsWith(".cjs") || entry.name.endsWith(".js"))) return false;
-		
-		if (entry.name.startsWith(".")) return false;
-		
-		if (entry.name.startsWith("__slothlet_")) return false;
-		return true;
+		return shouldIncludeFile(entry);
 	},
 
 	
@@ -956,11 +519,7 @@ const slothletObject = {
 	createBoundApi(ref = null) {
 		if (!this.api) throw new Error("BindleApi modules not loaded. Call load() first.");
 
-		
-		
-
 		let boundApi;
-		
 
 		boundApi = this.api;
 
@@ -978,24 +537,6 @@ const slothletObject = {
 		}
 
 		
-		
-		
-		
-		
-		
-		
-		
-		
-		
-
-		
-		
-
-		
-		
-		
-
-		
 		const instance = this;
 		this.safeDefine(boundApi, "describe", function (showAll = false) {
 			
@@ -1085,6 +626,43 @@ const slothletObject = {
 		} else if (this.config && this.config.debug) {
 			console.warn("Could not redefine boundApi.addApi: not configurable");
 		}
+
+		
+		const runDesc = Object.getOwnPropertyDescriptor(boundApi, "run");
+		if (!runDesc || runDesc.configurable) {
+			Object.defineProperty(boundApi, "run", {
+				value: this.run.bind(this),
+				writable: true,
+				configurable: true,
+				enumerable: false
+			});
+		} else if (this.config && this.config.debug) {
+			console.warn("Could not redefine boundApi.run: not configurable");
+		}
+
+		
+		const instanceIdDesc = Object.getOwnPropertyDescriptor(boundApi, "instanceId");
+		if (!instanceIdDesc || instanceIdDesc.configurable) {
+			Object.defineProperty(boundApi, "instanceId", {
+				value: this.instanceId,
+				writable: false,
+				configurable: true,
+				enumerable: false
+			});
+		}
+
+		
+		const scopeDesc = Object.getOwnPropertyDescriptor(boundApi, "scope");
+		if (!scopeDesc || scopeDesc.configurable) {
+			Object.defineProperty(boundApi, "scope", {
+				value: this.scope.bind(this),
+				writable: true,
+				configurable: true,
+				enumerable: false
+			});
+		} else if (this.config && this.config.debug) {
+			console.warn("Could not redefine boundApi.scope: not configurable");
+		}
 		
 
 		
@@ -1097,24 +675,7 @@ const slothletObject = {
 
 	
 	safeDefine(obj, key, value, enumerable = false) {
-		const desc = Object.getOwnPropertyDescriptor(obj, key);
-		if (!desc) {
-			Object.defineProperty(obj, key, {
-				value,
-				writable: true,
-				configurable: true,
-				enumerable
-			});
-		} else if (desc.configurable) {
-			Object.defineProperty(obj, key, {
-				value,
-				writable: true,
-				configurable: true,
-				enumerable
-			});
-		} else if (this.config && this.config.debug) {
-			console.warn(`Could not redefine boundApi.${key}: not configurable`);
-		}
+		return safeDefine(obj, key, value, enumerable, this.config);
 	},
 
 	
@@ -1133,220 +694,121 @@ const slothletObject = {
 	},
 
 	
-	async addApi(apiPath, folderPath) {
-		if (!this.loaded) {
-			throw new Error("[slothlet] Cannot add API: API not loaded. Call create() or load() first.");
-		}
+	async addApi(apiPath, folderPath, metadata = {}) {
+		return addApiFromFolder({ apiPath, folderPath, instance: this, metadata });
+	},
 
-		
-		if (typeof apiPath !== "string") {
-			throw new TypeError("[slothlet] addApi: 'apiPath' must be a string.");
-		}
-		const normalizedApiPath = apiPath.trim();
-		if (normalizedApiPath === "") {
-			throw new TypeError("[slothlet] addApi: 'apiPath' must be a non-empty, non-whitespace string.");
-		}
-		const pathParts = normalizedApiPath.split(".");
-		if (pathParts.some((part) => part === "")) {
-			throw new Error(`[slothlet] addApi: 'apiPath' must not contain empty segments. Received: "${normalizedApiPath}"`);
-		}
+	
 
-		
-		if (typeof folderPath !== "string") {
-			throw new TypeError("[slothlet] addApi: 'folderPath' must be a string.");
+	
+	run(contextData, callback, ...args) {
+		if (this.config.scope?.enabled === false) {
+			throw new Error("Per-request context (scope) is disabled for this instance.");
 		}
 
-		
-		let resolvedFolderPath = folderPath;
-		if (!path.isAbsolute(folderPath)) {
-			resolvedFolderPath = resolvePathFromCaller(folderPath);
+		if (typeof callback !== "function") {
+			throw new TypeError("Callback must be a function.");
 		}
 
-		
-		let stats;
-		try {
-			stats = await fs.stat(resolvedFolderPath);
-		} catch (error) {
-			throw new Error(`[slothlet] addApi: Cannot access folder: ${resolvedFolderPath} - ${error.message}`);
-		}
-		if (!stats.isDirectory()) {
-			throw new Error(`[slothlet] addApi: Path is not a directory: ${resolvedFolderPath}`);
-		}
+		const runtimeType = this.config.runtime || "async";
+		let requestALS;
+		if (runtimeType === "async") {
+			return import("@cldmv/slothlet/runtime/async").then((asyncRuntime) => {
+				requestALS = asyncRuntime.requestALS;
+				const parentContext = requestALS.getStore() || {};
 
-		if (this.config.debug) {
-			console.log(`[DEBUG] addApi: Loading modules from ${resolvedFolderPath} to path: ${normalizedApiPath}`);
-		}
+				let mergedContext;
+				if (this.config.scope?.merge === "deep") {
+					const instanceContext = this.context || {};
+					let temp = this._deepMerge({}, instanceContext);
+					temp = this._deepMerge(temp, parentContext);
+					mergedContext = this._deepMerge(temp, contextData);
+				} else {
+					mergedContext = { ...parentContext, ...contextData };
+				}
 
-		
-		let newModules;
-		if (this.config.lazy) {
-			
-			newModules = await this.modes.lazy.create.call(this, resolvedFolderPath, this.config.apiDepth || Infinity, 0);
+				return requestALS.run(mergedContext, () => callback(...args));
+			});
 		} else {
-			
-			newModules = await this.modes.eager.create.call(this, resolvedFolderPath, this.config.apiDepth || Infinity, 0);
-		}
-
-		if (this.config.debug) {
-			if (newModules && typeof newModules === "object") {
-				console.log(`[DEBUG] addApi: Loaded modules:`, Object.keys(newModules));
-			} else {
-				console.log(
-					`[DEBUG] addApi: Loaded modules (non-object):`,
-					typeof newModules === "function" ? `[Function: ${newModules.name || "anonymous"}]` : newModules
-				);
-			}
-		}
-
-		
-		let currentTarget = this.api;
-		let currentBoundTarget = this.boundapi;
-
-		for (let i = 0; i < pathParts.length - 1; i++) {
-			const part = pathParts[i];
-			const key = this._toapiPathKey(part);
-
-			
-			
-			
-			if (Object.prototype.hasOwnProperty.call(currentTarget, key)) {
-				const existing = currentTarget[key];
-				if (existing === null || (typeof existing !== "object" && typeof existing !== "function")) {
-					throw new Error(
-						`[slothlet] Cannot extend API path "${normalizedApiPath}" through segment "${part}": ` +
-							`existing value is type "${typeof existing}", cannot add properties.`
-					);
-				}
-				
-				
-			} else {
-				currentTarget[key] = {};
-			}
-			if (Object.prototype.hasOwnProperty.call(currentBoundTarget, key)) {
-				const existingBound = currentBoundTarget[key];
-				if (existingBound === null || (typeof existingBound !== "object" && typeof existingBound !== "function")) {
-					throw new Error(
-						`[slothlet] Cannot extend bound API path "${normalizedApiPath}" through segment "${part}": ` +
-							`existing value is type "${typeof existingBound}", cannot add properties.`
-					);
+			return import("@cldmv/slothlet/runtime/live").then((liveRuntime) => {
+				requestALS = liveRuntime.requestALS;
+				const parentContext = requestALS.getStore() || {};
+
+				let mergedContext;
+				if (this.config.scope?.merge === "deep") {
+					const instanceContext = this.context || {};
+					let temp = this._deepMerge({}, instanceContext);
+					temp = this._deepMerge(temp, parentContext);
+					mergedContext = this._deepMerge(temp, contextData);
+				} else {
+					mergedContext = { ...parentContext, ...contextData };
 				}
-				
-			} else {
-				currentBoundTarget[key] = {};
-			}
 
-			
-			currentTarget = currentTarget[key];
-			currentBoundTarget = currentBoundTarget[key];
+				return requestALS.run(mergedContext, () => callback(...args));
+			});
 		}
+	},
 
-		
-		const finalKey = this._toapiPathKey(pathParts[pathParts.length - 1]);
-
-		
-		if (typeof newModules === "function") {
-			
-			
-			if (Object.prototype.hasOwnProperty.call(currentTarget, finalKey)) {
-				const existing = currentTarget[finalKey];
+	
+	scope({ context, fn, args }) {
+		if (this.config.scope?.enabled === false) {
+			throw new Error("Per-request context (scope) is disabled for this instance.");
+		}
 
-				
-				if (this.config.allowApiOverwrite === false) {
-					console.warn(
-						`[slothlet] Skipping addApi: API path "${normalizedApiPath}" final key "${finalKey}" ` +
-							`already exists (type: "${typeof existing}"). Set allowApiOverwrite: true to allow overwrites.`
-					);
-					return; 
-				}
+		if (!context || typeof context !== "object") {
+			throw new TypeError("context must be an object.");
+		}
 
-				
-				if (existing !== null && typeof existing !== "function") {
-					console.warn(
-						`[slothlet] Overwriting existing non-function value at API path "${normalizedApiPath}" ` +
-							`final key "${finalKey}" with a function. Previous type: "${typeof existing}".`
-					);
-				} else if (typeof existing === "function") {
-					
-					console.warn(
-						`[slothlet] Overwriting existing function at API path "${normalizedApiPath}" ` + `final key "${finalKey}" with a new function.`
-					);
-				}
-			}
-			currentTarget[finalKey] = newModules;
-			currentBoundTarget[finalKey] = newModules;
-		} else if (typeof newModules === "object" && newModules !== null) {
-			
-			if (Object.prototype.hasOwnProperty.call(currentTarget, finalKey)) {
-				const existing = currentTarget[finalKey];
+		if (typeof fn !== "function") {
+			throw new TypeError("fn must be a function.");
+		}
 
-				
-				if (this.config.allowApiOverwrite === false && existing !== undefined && existing !== null) {
-					
-					const hasContent = typeof existing === "object" ? Object.keys(existing).length > 0 : true;
-					if (hasContent) {
-						console.warn(
-							`[slothlet] Skipping addApi merge: API path "${normalizedApiPath}" final key "${finalKey}" ` +
-								`already exists with content (type: "${typeof existing}"). Set allowApiOverwrite: true to allow merging.`
-						);
-						return; 
-					}
-				}
+		const runtimeType = this.config.runtime || "async";
+		let requestALS;
+		if (runtimeType === "async") {
+			return import("./lib/runtime/runtime-asynclocalstorage.mjs").then((asyncRuntime) => {
+				requestALS = asyncRuntime.requestALS;
+				const parentContext = requestALS.getStore() || {};
 
-				if (existing !== null && typeof existing !== "object" && typeof existing !== "function") {
-					throw new Error(
-						`[slothlet] Cannot merge API at "${normalizedApiPath}": ` +
-							`existing value at final key "${finalKey}" is type "${typeof existing}", cannot merge into primitives.`
-					);
-				}
-			}
-			if (Object.prototype.hasOwnProperty.call(currentBoundTarget, finalKey)) {
-				const existingBound = currentBoundTarget[finalKey];
-				if (existingBound !== null && typeof existingBound !== "object" && typeof existingBound !== "function") {
-					throw new Error(
-						`[slothlet] Cannot merge bound API at "${normalizedApiPath}": ` +
-							`existing value at final key "${finalKey}" is type "${typeof existingBound}", cannot merge into primitives.`
-					);
+				let mergedContext;
+				if (this.config.scope?.merge === "deep") {
+					const instanceContext = this.context || {};
+					let temp = this._deepMerge({}, instanceContext);
+					temp = this._deepMerge(temp, parentContext);
+					mergedContext = this._deepMerge(temp, context);
+				} else {
+					mergedContext = { ...parentContext, ...context };
 				}
-			}
 
-			
-			if (!currentTarget[finalKey]) {
-				currentTarget[finalKey] = {};
-			}
-			if (!currentBoundTarget[finalKey]) {
-				currentBoundTarget[finalKey] = {};
-			}
-
-			
-			
-			
-			
-			
-			Object.assign(currentTarget[finalKey], newModules);
-			Object.assign(currentBoundTarget[finalKey], newModules);
-		} else if (newModules === null || newModules === undefined) {
-			
-			const receivedType = newModules === null ? "null" : "undefined";
-			console.warn(
-				`[slothlet] addApi: No modules loaded from folder at API path "${normalizedApiPath}". ` +
-					`Loaded modules resulted in ${receivedType}. Check that the folder contains valid module files.`
-			);
+				const argsArray = args || [];
+				return requestALS.run(mergedContext, () => fn(...argsArray));
+			});
 		} else {
-			
-			
-			currentTarget[finalKey] = newModules;
-			currentBoundTarget[finalKey] = newModules;
-		}
-
-		
-		this.updateBindings(this.context, this.reference, this.boundapi);
+			return import("./lib/runtime/runtime-livebindings.mjs").then((liveRuntime) => {
+				requestALS = liveRuntime.requestALS;
+				const parentContext = requestALS.getStore() || {};
+
+				let mergedContext;
+				if (this.config.scope?.merge === "deep") {
+					const instanceContext = this.context || {};
+					let temp = this._deepMerge({}, instanceContext);
+					temp = this._deepMerge(temp, parentContext);
+					mergedContext = this._deepMerge(temp, context);
+				} else {
+					mergedContext = { ...parentContext, ...context };
+				}
 
-		if (this.config.debug) {
-			console.log(`[DEBUG] addApi: Successfully added modules at ${normalizedApiPath}`);
+				const argsArray = args || [];
+				return requestALS.run(mergedContext, () => fn(...argsArray));
+			});
 		}
 	},
 
 	
+	_deepMerge(target, source) {
+		return deepMerge(target, source);
+	},
+
 	async shutdown() {
 		
 		
@@ -1423,52 +885,6 @@ const slothletObject = {
 };
 
 
-export function mutateLiveBindingFunction(target, source) {
-	if (typeof source === "function") {
-		target._impl = (...args) => source(...args);
-		
-		for (const key of Object.keys(target)) {
-			if (key !== "_impl" && key !== "__ctx") delete target[key];
-		}
-		
-		for (const key of Object.getOwnPropertyNames(source)) {
-			if (key !== "length" && key !== "name" && key !== "prototype" && key !== "_impl" && key !== "__ctx") {
-				try {
-					target[key] = source[key];
-				} catch {
-					
-				}
-			}
-		}
-	} else if (typeof source === "object" && source !== null) {
-		
-		for (const key of Object.keys(target)) {
-			if (key !== "_impl" && key !== "__ctx") delete target[key];
-		}
-		
-		for (const [key, value] of Object.entries(source)) {
-			if (key !== "__ctx") {
-				target[key] = value;
-			}
-		}
-		
-		const managementMethods = ["shutdown", "addApi", "describe"];
-		for (const method of managementMethods) {
-			const desc = Object.getOwnPropertyDescriptor(source, method);
-			if (desc) {
-				try {
-					Object.defineProperty(target, method, desc);
-				} catch {
-					
-				}
-			}
-		}
-		
-		if (typeof source._impl === "function") {
-			target._impl = source._impl;
-		}
-	}
-}
 
 export { slothlet };
 export default slothlet;