@cldmv/slothlet 2.5.5 → 2.6.0

package/README.md

@@ -104,6 +104,12 @@ v2.0 represents a ground-up rewrite with enterprise-grade features:
 > [!TIP]  
 > **📁 For comprehensive examples of API flattening, naming conventions, and function preservation patterns, see the test modules in [api_tests/](https://github.com/CLDMV/slothlet/blob/HEAD/api_tests) and their documentation in [docs/api_tests/](https://github.com/CLDMV/slothlet/blob/HEAD/docs/api_tests)**
 
+> [!NOTE]  
+> **🔍 For detailed technical documentation on API transformation rules:**
+>
+> - **[API-RULES.md](https://github.com/CLDMV/slothlet/blob/HEAD/API-RULES.md)** - Verified API transformation rules with examples and test cases
+> - **[API-RULES-CONDITIONS.md](https://github.com/CLDMV/slothlet/blob/HEAD/API-RULES-CONDITIONS.md)** - Complete technical reference of all conditional logic that controls API generation
+
 ### 🔗 **Advanced Binding System**
 
 - **Live Bindings**: Dynamic context and reference binding for runtime API mutation
@@ -193,9 +199,16 @@ const mixedResult = await api.interop.processData({ data: "test" }); // CJS+ESM
 ```javascript
 import slothlet from "@cldmv/slothlet";
 
-// Lazy mode with copy-left materialization (opt-in)
+// Lazy mode with copy-left materialization
 const api = await slothlet({
-	lazy: true,
+	mode: "lazy", // New preferred syntax
+	dir: "./api",
+	apiDepth: 3
+});
+
+// Or use legacy syntax (still supported)
+const apiLegacy = await slothlet({
+	lazy: true, // Legacy syntax
 	dir: "./api",
 	apiDepth: 3
 });
@@ -214,7 +227,8 @@ import slothlet from "@cldmv/slothlet";
 
 const api = await slothlet({
 	dir: "./api",
-	lazy: false, // Loading strategy
+	mode: "eager", // New: Loading strategy (lazy/eager)
+	engine: "singleton", // New: Execution environment
 	api_mode: "auto", // API structure behavior
 	apiDepth: Infinity, // Directory traversal depth
 	debug: false, // Enable verbose logging
@@ -334,15 +348,50 @@ Creates and loads an API instance with the specified configuration.
 | Option      | Type      | Default       | Description                                                                                                                                                                                                                                                                                                                                                                        |
 | ----------- | --------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `dir`       | `string`  | `"api"`       | Directory to load API modules from. Can be absolute or relative path. If relative, resolved from process.cwd().                                                                                                                                                                                                                                                                    |
-| `lazy`      | `boolean` | `false`       | Loading strategy - `true` for lazy loading (on-demand), `false` for eager loading (immediate)                                                                                                                                                                                                                                                                                      |
+| `lazy`      | `boolean` | `false`       | **Legacy** loading strategy - `true` for lazy loading (on-demand), `false` for eager loading (immediate). Use `mode` option instead.                                                                                                                                                                                                                                               |
+| `mode`      | `string`  | -             | **New** loading mode - `"lazy"` for on-demand loading, `"eager"` for immediate loading. Takes precedence over `lazy` option. Also supports execution modes for backward compatibility.                                                                                                                                                                                             |
+| `engine`    | `string`  | `"singleton"` | **New** execution environment mode - `"singleton"`, `"vm"`, `"worker"`, or `"fork"`                                                                                                                                                                                                                                                                                                |
 | `apiDepth`  | `number`  | `Infinity`    | Directory traversal depth control - `0` for root only, `Infinity` for all levels                                                                                                                                                                                                                                                                                                   |
 | `debug`     | `boolean` | `false`       | Enable verbose logging. Can also be set via `--slothletdebug` command line flag or `SLOTHLET_DEBUG=true` environment variable                                                                                                                                                                                                                                                      |
-| `mode`      | `string`  | `"singleton"` | Execution environment mode - `"singleton"`, `"vm"`, `"worker"`, or `"fork"`                                                                                                                                                                                                                                                                                                        |
 | `api_mode`  | `string`  | `"auto"`      | API structure behavior when root-level default functions exist:<br/>• `"auto"`: Automatically detects if root has default function export and creates callable API<br/>• `"function"`: Forces API to be callable (use when you have root-level default function exports)<br/>• `"object"`: Forces API to be object-only (use when you want object interface regardless of exports) |
 | `context`   | `object`  | `{}`          | Context data object injected into live-binding `context` reference. Available to all loaded modules via `import { context } from "@cldmv/slothlet/runtime"`                                                                                                                                                                                                                        |
 | `reference` | `object`  | `{}`          | Reference object merged into the API root level. Properties not conflicting with loaded modules are added directly to the API                                                                                                                                                                                                                                                      |
 | `sanitize`  | `object`  | `{}`          | **🔧 NEW**: Control how filenames become API property names. Supports exact matches, glob patterns (`*json*`), and boundary patterns (`**url**`). Configure `lowerFirst` and `rules` for `leave`, `leaveInsensitive`, `upper`, and `lower` transformations                                                                                                                         |
 
+#### ✨ New Option Format (v2.6.0+)
+
+The option structure has been improved for better clarity:
+
+```javascript
+// ✅ New recommended syntax
+const api = await slothlet({
+	mode: "lazy", // Loading strategy: "lazy" | "eager"
+	engine: "singleton", // Execution environment: "singleton" | "vm" | "worker" | "fork"
+	dir: "./api"
+});
+
+// ✅ Legacy syntax (still fully supported)
+const api = await slothlet({
+	lazy: true, // Boolean loading strategy
+	mode: "singleton", // Execution environment (legacy placement)
+	dir: "./api"
+});
+
+// ✅ Mixed usage (mode takes precedence)
+const api = await slothlet({
+	lazy: false, // Will be overridden
+	mode: "lazy", // Takes precedence - results in lazy loading
+	engine: "singleton"
+});
+```
+
+**Benefits of the new syntax:**
+
+- **Clearer separation**: `mode` for loading strategy, `engine` for execution environment
+- **Better discoverability**: String values are more self-documenting than boolean flags
+- **Future-proof**: Easier to extend with additional loading strategies
+- **Backward compatible**: All existing code continues to work unchanged
+
 #### `slothlet.getApi()` ⇒ `object`
 
 Returns the raw API object (Proxy or plain object).
@@ -1157,6 +1206,11 @@ Key highlights:
 - **[Security Policy](https://github.com/CLDMV/slothlet/blob/HEAD/SECURITY.md)** - Security guidelines and reporting
 - **[Test Documentation](https://github.com/CLDMV/slothlet/blob/HEAD/api_tests)** - Comprehensive test module examples
 
+### 🔧 Technical Documentation
+
+- **[API Rules](https://github.com/CLDMV/slothlet/blob/HEAD/API-RULES.md)** - Systematically verified API transformation rules with real examples and test cases
+- **[API Rules Conditions](https://github.com/CLDMV/slothlet/blob/HEAD/API-RULES-CONDITIONS.md)** - Complete technical reference of all 26 conditional statements that control API generation
+
 ---
 
 ## 🔗 Links

package/dist/lib/helpers/als-eventemitter.mjs

@@ -20,10 +20,13 @@
 
 import { AsyncResource } from "node:async_hooks";
 import { EventEmitter } from "node:events";
-import { sharedALS } from "../runtime/runtime.mjs";
+import { AsyncLocalStorage } from "node:async_hooks";
 
 
-export function enableAlsForEventEmitters(als = sharedALS) {
+const defaultALS = new AsyncLocalStorage();
+
+
+export function enableAlsForEventEmitters(als = defaultALS) {
 	
 	const kPatched = Symbol.for("slothlet.als.patched");
 
@@ -115,5 +118,3 @@ export function enableAlsForEventEmitters(als = sharedALS) {
 		return res;
 	};
 }
-
-

package/dist/lib/helpers/api_builder.mjs

@@ -22,6 +22,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { types as utilTypes } from "node:util";
 import { pathToFileURL } from "node:url";
+import { multidefault_analyzeModules } from "@cldmv/slothlet/helpers/multidefault";
+import { setActiveInstance } from "@cldmv/slothlet/helpers/instance-manager";
 
 
 
@@ -48,10 +50,29 @@ function isLikelySerializable(val) {
 
 
 export async function analyzeModule(modulePath, options = {}) {
-	const { debug = false } = options;
+	const { debug = false, instance = null } = options;
 
 	const moduleUrl = pathToFileURL(modulePath).href;
-	const rawModule = await import(moduleUrl);
+
+	
+	let importUrl = moduleUrl;
+	if (instance && instance.instanceId) {
+		const runtimeType = instance.config?.runtime || "async";
+
+		
+		if (runtimeType === "live") {
+			const separator = moduleUrl.includes("?") ? "&" : "?";
+			importUrl = `${moduleUrl}${separator}slothlet_instance=${instance.instanceId}`;
+			importUrl = `${importUrl}&slothlet_runtime=${runtimeType}`;
+
+			
+			setActiveInstance(instance.instanceId);
+		}
+		
+		
+	}
+
+	const rawModule = await import(importUrl);
 
 	
 	let processedModule = rawModule;
@@ -361,8 +382,7 @@ export async function analyzeDirectoryStructure(categoryPath, options = {}) {
 	
 	let multiDefaultAnalysis = null;
 	if (processingStrategy === "multi-file") {
-		const { multidefault_analyzeModules } = await import("@cldmv/slothlet/helpers/multidefault");
-		multiDefaultAnalysis = await multidefault_analyzeModules(moduleFiles, categoryPath, debug);
+		multiDefaultAnalysis = await multidefault_analyzeModules(moduleFiles, categoryPath, { debug, instance });
 	}
 
 	
@@ -949,8 +969,7 @@ export async function buildCategoryStructure(categoryPath, options = {}) {
 	const categoryModules = {};
 
 	
-	const { multidefault_analyzeModules } = await import("@cldmv/slothlet/helpers/multidefault");
-	const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, debug);
+	const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, { debug, instance });
 	const { totalDefaultExports, hasMultipleDefaultExports, selfReferentialFiles, defaultExportFiles: analysisDefaults } = analysis;
 
 	
@@ -1090,8 +1109,7 @@ export async function buildRootAPI(dir, options = {}) {
 
 	if (moduleFiles.length > 0) {
 		
-		const { multidefault_analyzeModules } = await import("@cldmv/slothlet/helpers/multidefault");
-		const analysis = await multidefault_analyzeModules(moduleFiles, dir, debug);
+		const analysis = await multidefault_analyzeModules(moduleFiles, dir, { debug, instance });
 		const { hasMultipleDefaultExports, selfReferentialFiles } = analysis;
 
 		
@@ -1193,9 +1211,6 @@ export async function buildCategoryDecisions(categoryPath, options = {}) {
 		console.log(`[DEBUG] buildCategoryDecisions called with path: ${categoryPath}, mode: ${mode}`);
 	}
 
-	const fs = await import("fs/promises");
-	const path = await import("path");
-
 	const files = await fs.readdir(categoryPath, { withFileTypes: true });
 	const moduleFiles = files.filter((f) => instance._shouldIncludeFile(f));
 	const categoryName = instance._toapiPathKey(path.basename(categoryPath));
@@ -1390,8 +1405,7 @@ export async function buildCategoryDecisions(categoryPath, options = {}) {
 	}
 
 	
-	const { multidefault_analyzeModules } = await import("@cldmv/slothlet/helpers/multidefault");
-	const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, debug);
+	const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, { debug, instance });
 
 	decisions.multifileAnalysis = analysis;
 

package/dist/lib/helpers/auto-wrap.mjs

@@ -22,13 +22,15 @@
 export async function autoWrapEventEmitters(nodeModule) {
 	
 	try {
-		const { self } = await import("@cldmv/slothlet/runtime");
+		
+		
+		const { self } = await import("@cldmv/slothlet/runtime/async");
 		if (!self?.__ctx) {
 			
 			return nodeModule;
 		}
 
-		const { makeWrapper } = await import("../runtime/runtime.mjs");
+		const { makeWrapper } = await import("@cldmv/slothlet/runtime/async");
 		const wrapper = makeWrapper(self.__ctx);
 
 		

package/dist/lib/helpers/instance-manager.mjs

@@ -0,0 +1,111 @@
+/*
+	Copyright 2025 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.
+*/
+
+
+
+
+const instanceRegistry = new Map();
+
+
+let currentActiveInstanceId = null;
+
+
+export function getInstanceData(instanceId) {
+	return instanceRegistry.get(instanceId) || null;
+}
+
+
+export function updateInstanceData(instanceId, key, value) {
+	
+	
+	
+	
+	
+
+	let instanceData = instanceRegistry.get(instanceId);
+	if (!instanceData) {
+		instanceData = {
+			self: null,
+			context: {},
+			reference: {}
+		};
+		instanceRegistry.set(instanceId, instanceData);
+	}
+	instanceData[key] = value;
+
+	
+}
+
+
+export async function cleanupInstance(instanceId) {
+	
+	instanceRegistry.delete(instanceId);
+
+	if (currentActiveInstanceId === instanceId) {
+		currentActiveInstanceId = null;
+	}
+}
+
+
+export function setActiveInstance(instanceId) {
+	currentActiveInstanceId = instanceId;
+	
+}
+
+
+export function getCurrentActiveInstanceId() {
+	return currentActiveInstanceId;
+}
+
+
+export function detectCurrentInstanceId() {
+	
+	
+	
+	
+	
+	
+
+	
+	if (currentActiveInstanceId && instanceRegistry.has(currentActiveInstanceId)) {
+		return currentActiveInstanceId;
+	}
+
+	
+	const stack = new Error().stack;
+	if (stack) {
+		
+		const matches = stack.match(/slothlet_instance=([^&\s):]+)/g);
+
+		if (matches && matches.length > 0) {
+			
+			const instanceParam = matches[0];
+			const instanceId = instanceParam.replace(/slothlet_instance=([^&\s):]+).*/, "$1");
+
+			if (instanceRegistry.has(instanceId)) {
+				return instanceId;
+			}
+		}
+	}
+
+	
+	return null;
+}
+
+
+export function getAllInstanceIds() {
+	return Array.from(instanceRegistry.keys());
+}

package/dist/lib/helpers/multidefault.mjs

@@ -16,10 +16,13 @@
 
 
 
+
+
 import path from "path";
 
 
-async function multidefault_analyzeModules(moduleFiles, baseDir, debug = false) {
+async function multidefault_analyzeModules(moduleFiles, baseDir, options = {}) {
+	const { debug = false, instance = null } = options;
 	const selfReferentialFiles = new Set();
 	const rawModuleCache = new Map();
 	const defaultExportFiles = [];
@@ -36,7 +39,14 @@ async function multidefault_analyzeModules(moduleFiles, baseDir, debug = false)
 		const moduleFilePath = path.resolve(baseDir, file.name);
 
 		
-		const rawImport = await import(`file://${moduleFilePath.replace(/\\/g, "/")}`);
+		let importUrl = `file://${moduleFilePath.replace(/\\/g, "/")}`;
+		if (instance && instance.instanceId) {
+			const separator = importUrl.includes("?") ? "&" : "?";
+			importUrl = `${importUrl}${separator}slothlet_instance=${instance.instanceId}`;
+		}
+
+		
+		const rawImport = await import(importUrl);
 
 		
 		const isCjsFile = moduleExt === ".cjs";

package/dist/lib/modes/slothlet_eager.mjs

@@ -38,7 +38,7 @@ export async function create(dir, maxDepth = Infinity, currentDepth = 0) {
 	const moduleFiles = entries.filter((e) => this._shouldIncludeFile(e));
 	const defaultExportFiles = [];
 	
-	const analysis = await multidefault_analyzeModules(moduleFiles, dir, this.config.debug);
+	const analysis = await multidefault_analyzeModules(moduleFiles, dir, { debug: this.config.debug, instance: this });
 
 	const { totalDefaultExports, hasMultipleDefaultExports, selfReferentialFiles, defaultExportFiles: analysisDefaults } = analysis;
 

package/dist/lib/modes/slothlet_lazy.mjs

@@ -21,13 +21,17 @@ import fs from "node:fs/promises";
 import { readdirSync } from "node:fs";
 import path from "node:path";
 import { types as utilTypes } from "node:util";
-import { runWithCtx } from "@cldmv/slothlet/runtime";
 import { processModuleForAPI } from "@cldmv/slothlet/helpers/api_builder";
 import { multidefault_analyzeModules } from "@cldmv/slothlet/helpers/multidefault";
 
 
 export async function create(dir, maxDepth = Infinity, currentDepth = 0) {
 	const instance = this; 
+
+	
+	const runtimePath = instance.config.runtime === "live" ? "@cldmv/slothlet/runtime/live" : "@cldmv/slothlet/runtime/async";
+	const { runWithCtx } = await import(runtimePath);
+
 	const entries = await fs.readdir(dir, { withFileTypes: true });
 	let api = {};
 	let rootDefaultFn = null;
@@ -38,7 +42,7 @@ export async function create(dir, maxDepth = Infinity, currentDepth = 0) {
 	const defaultExportFiles = [];
 
 	
-	const analysis = await multidefault_analyzeModules(moduleFiles, dir, instance.config.debug);
+	const analysis = await multidefault_analyzeModules(moduleFiles, dir, { debug: instance.config.debug, instance });
 
 	const { totalDefaultExports, hasMultipleDefaultExports, selfReferentialFiles, defaultExportFiles: analysisDefaults } = analysis;
 
@@ -156,7 +160,8 @@ export async function create(dir, maxDepth = Infinity, currentDepth = 0) {
 				instance,
 				depth,
 				maxDepth,
-				pathParts: [key]
+				pathParts: [key],
+				runWithCtx
 			});
 			parent[key] = proxy;
 		}
@@ -223,7 +228,7 @@ function replacePlaceholder(parent, key, placeholder, value, instance, depth) {
 }
 
 
-function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth, pathParts }) {
+function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth, pathParts, runWithCtx }) {
 	let materialized = null;
 	let inFlight = null;
 
@@ -246,7 +251,8 @@ function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth,
 						instance,
 						depth: cd + 1,
 						maxDepth: md,
-						pathParts: [...pathParts, nestedKey]
+						pathParts: [...pathParts, nestedKey],
+						runWithCtx
 					})
 			});
 			materialized = value;
@@ -374,6 +380,43 @@ function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth,
 						return new Proxy(
 							 function lazy_deepPropertyAccessor() {},
 							{
+								get(target, nextProp) {
+									if (nextProp === "name") return `lazy_${prop}_${subProp}`;
+									if (nextProp === "length") return 0;
+									
+									return new Proxy(function lazy_deeperPropertyAccessor() {}, {
+										apply(target, thisArg, args) {
+											if (materialized) {
+												const value = materialized[prop];
+												const subValue = value ? value[subProp] : undefined;
+												if (subValue && typeof subValue[nextProp] === "function") {
+													const ctx = instance.boundapi?.__ctx;
+													if (ctx) {
+														return runWithCtx(ctx, subValue[nextProp], thisArg, args);
+													} else {
+														return subValue[nextProp].apply(thisArg, args);
+													}
+												}
+												return subValue ? subValue[nextProp] : undefined;
+											}
+
+											if (!inFlight) inFlight = _materialize();
+											return inFlight.then(function lazy_handleDeeperResolvedValue(resolved) {
+												const value = resolved ? resolved[prop] : undefined;
+												const subValue = value ? value[subProp] : undefined;
+												if (subValue && typeof subValue[nextProp] === "function") {
+													const ctx = instance.boundapi?.__ctx;
+													if (ctx) {
+														return runWithCtx(ctx, subValue[nextProp], thisArg, args);
+													} else {
+														return subValue[nextProp].apply(thisArg, args);
+													}
+												}
+												return subValue ? subValue[nextProp] : undefined;
+											});
+										}
+									});
+								},
 								apply(target, thisArg, args) {
 									
 									if (materialized) {