@cldmv/slothlet 2.7.0 → 2.8.0

package/README.md

@@ -464,6 +464,7 @@ Creates and loads an API instance with the specified configuration.
 | `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                                                                                                                                                                                                                                                                         |
 | `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)                    |
+| `allowApiOverwrite` | `boolean` | `true` | Controls whether `addApi()` can overwrite existing API endpoints:<br/>• `true`: Allow overwrites (default, backwards compatible)<br/>• `false`: Prevent overwrites - logs warning and skips when attempting to overwrite existing endpoints<br/>Applies to both function and object overwrites at the final key of the API path |
 | `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**: Advanced filename-to-API transformation control. Options: `lowerFirst` (boolean), `preserveAllUpper` (boolean), `preserveAllLower` (boolean), `rules` object with `leave` (exact case-sensitive), `leaveInsensitive` (case-insensitive), `upper`/`lower` arrays. Supports exact matches, glob patterns (`*json*`, `http*`), and boundary patterns (`**url**` for surrounded matches only) |
@@ -522,10 +523,121 @@ Returns true if the API is loaded.
 
 #### `slothlet.shutdown()` ⇒ `Promise<void>`
 
-Gracefully shuts down the API and cleans up resources.
+Gracefully shuts down the API and performs comprehensive resource cleanup to prevent hanging processes.
+
+**Cleanup includes:**
+
+- Hook manager state and registered hooks
+- AsyncLocalStorage context and bindings
+- EventEmitter listeners and AsyncResource instances (including third-party libraries)
+- Instance data and runtime coordination
 
 **Returns:** `Promise<void>` - Resolves when shutdown is complete
 
+> [!IMPORTANT]  
+> **🛡️ Process Cleanup**: The shutdown method now performs comprehensive cleanup of all EventEmitter listeners created after slothlet loads, including those from third-party libraries like pg-pool. This prevents hanging AsyncResource instances that could prevent your Node.js process from exiting cleanly.
+
+#### `api.addApi(apiPath, folderPath)` ⇒ `Promise<void>` ⭐ NEW
+
+Dynamically extend your API at runtime by loading additional modules and merging them into a specified path.
+
+**Parameters:**
+
+| Param        | Type     | Description                                                         |
+| ------------ | -------- | ------------------------------------------------------------------- |
+| `apiPath`    | `string` | Dotted path where modules will be added (e.g., `"runtime.plugins"`) |
+| `folderPath` | `string` | Path to folder containing modules to load (relative or absolute)    |
+
+**Returns:** `Promise<void>` - Resolves when the API extension is complete
+
+**Features:**
+
+- ✅ **Dynamic Loading**: Add modules after initial API creation
+- ✅ **Path Creation**: Automatically creates intermediate objects for nested paths
+- ✅ **Smart Merging**: Merges into existing objects or creates new namespaces
+- ✅ **Mode Respect**: Uses same loading mode (lazy/eager) as parent API
+- ✅ **Live Binding Updates**: Automatically updates `self`, `context`, and `reference`
+- ✅ **Function Support**: Can traverse through functions (slothlet's function.property pattern)
+- ✅ **Validation**: Prevents extension through primitives, validates path format
+- ✅ **Overwrite Protection**: Optional `allowApiOverwrite` config prevents accidental endpoint overwrites
+
+**Configuration:**
+
+The `allowApiOverwrite` option controls whether `addApi` can overwrite existing endpoints:
+
+```javascript
+// Default behavior - allows overwrites (backwards compatible)
+const api = await slothlet({ 
+    dir: "./api",
+    allowApiOverwrite: true // default
+});
+await api.addApi("tools", "./new-tools"); // Overwrites existing api.tools
+
+// Protected mode - prevents overwrites
+const api = await slothlet({ 
+    dir: "./api",
+    allowApiOverwrite: false // protection enabled
+});
+await api.addApi("tools", "./new-tools"); // Logs warning and skips
+// Console: "[slothlet] Skipping addApi: API path "tools" final key "tools" already exists..."
+```
+
+**Usage Examples:**
+
+```javascript
+const api = await slothlet({ dir: "./api" });
+
+// Add modules to nested path
+await api.addApi("runtime.plugins", "./plugins");
+api.runtime.plugins.myPlugin(); // New modules accessible
+
+// Add to root level
+await api.addApi("utilities", "./utils");
+api.utilities.helperFunc(); // Root-level addition
+
+// Deep nesting (creates intermediate objects)
+await api.addApi("services.external.github", "./integrations/github");
+api.services.external.github.getUser(); // Deep path created
+
+// Merge into existing namespace
+await api.addApi("math", "./advanced-math"); // Merges with existing api.math
+api.math.add(2, 3); // Original functions preserved
+api.math.advancedCalc(); // New functions added
+```
+
+**Path Validation:**
+
+```javascript
+// ❌ Invalid paths throw errors
+await api.addApi("", "./modules"); // Empty string
+await api.addApi(".path", "./modules"); // Leading dot
+await api.addApi("path.", "./modules"); // Trailing dot
+await api.addApi("path..name", "./modules"); // Consecutive dots
+
+// ✅ Valid paths
+await api.addApi("simple", "./modules"); // Single segment
+await api.addApi("nested.path", "./modules"); // Dotted path
+await api.addApi("very.deep.nested", "./modules"); // Multi-level
+```
+
+**Type Safety:**
+
+```javascript
+// ✅ Can extend through objects and functions
+api.logger = { info: () => {} };
+await api.addApi("logger.plugins", "./logger-plugins"); // Works - object
+
+api.handler = () => "handler";
+await api.addApi("handler.middleware", "./middleware"); // Works - function
+
+// ❌ Cannot extend through primitives
+api.config.timeout = 5000;
+await api.addApi("config.timeout.advanced", "./modules"); // Throws error
+```
+
+> [!WARNING]  
+> **⚠️ Concurrency Limitation:** The `addApi` method is **not thread-safe**. Concurrent calls to `addApi` with overlapping paths may result in race conditions and inconsistent API state. Ensure calls are properly sequenced using `await` or other synchronization mechanisms. Do not call `addApi` from multiple threads/workers simultaneously.
+
 > [!NOTE]  
 > **📚 For detailed API documentation with comprehensive parameter descriptions, method signatures, and examples, see [docs/API.md](https://github.com/CLDMV/slothlet/blob/HEAD/docs/API.md)**
 
@@ -649,6 +761,7 @@ console.log("TCP server started with context preservation");
 - ✅ **Nested Events**: Works with any depth of EventEmitter nesting (server → socket → custom emitters)
 - ✅ **Universal Support**: All EventEmitter methods (`on`, `once`, `addListener`) are automatically context-aware
 - ✅ **Production Ready**: Uses Node.js AsyncResource patterns for reliable context propagation
+- ✅ **Clean Shutdown**: Automatically cleans up all AsyncResource instances during shutdown to prevent hanging processes
 - ✅ **Zero Overhead**: Only wraps listeners when context is active, minimal performance impact
 
 > [!TIP]  

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

@@ -26,6 +26,17 @@ import { AsyncLocalStorage } from "node:async_hooks";
 const defaultALS = new AsyncLocalStorage();
 
 
+let originalMethods = null;
+
+
+const globalResourceSet = new Set();
+
+
+
+const globalListenerTracker = new WeakMap(); 
+const allPatchedListeners = new Set(); 
+
+
 export function enableAlsForEventEmitters(als = defaultALS) {
 	
 	const kPatched = Symbol.for("slothlet.als.patched");
@@ -52,6 +63,9 @@ export function enableAlsForEventEmitters(als = defaultALS) {
 		const resource = new AsyncResource("slothlet-als-listener");
 
 		
+		globalResourceSet.add(resource);
+
+		
 		const runtime_wrappedListener = function (...args) {
 			return resource.runInAsyncScope(
 				() => {
@@ -62,6 +76,9 @@ export function enableAlsForEventEmitters(als = defaultALS) {
 			);
 		};
 
+		
+		runtime_wrappedListener._slothletResource = resource;
+
 		return runtime_wrappedListener;
 	}
 
@@ -81,6 +98,22 @@ export function enableAlsForEventEmitters(als = defaultALS) {
 		proto[addFnName] = function (event, listener) {
 			const map = runtime_ensureMap(this);
 			const wrapped = runtime_wrapListener(listener);
+
+			
+			
+			if (!globalListenerTracker.has(this)) {
+				globalListenerTracker.set(this, new Set());
+			}
+			const listenerInfo = {
+				emitter: this,
+				event,
+				originalListener: listener,
+				wrappedListener: wrapped,
+				addMethod: addFnName
+			};
+			globalListenerTracker.get(this).add(listenerInfo);
+			allPatchedListeners.add(listenerInfo);
+
 			if (wrapped !== listener) map.set(listener, wrapped);
 			return orig.call(this, event, wrapped);
 		};
@@ -99,6 +132,30 @@ export function enableAlsForEventEmitters(als = defaultALS) {
 		const runtime_removeWrapper = function (event, listener) {
 			const map = runtime_ensureMap(this);
 			const wrapped = map.get(listener) || listener;
+
+			
+			if (globalListenerTracker.has(this)) {
+				const emitterListeners = globalListenerTracker.get(this);
+				for (const info of emitterListeners) {
+					if (info.originalListener === listener || info.wrappedListener === wrapped) {
+						emitterListeners.delete(info);
+						allPatchedListeners.delete(info);
+						break;
+					}
+				}
+			}
+
+			
+			if (wrapped && wrapped._slothletResource) {
+				const resource = wrapped._slothletResource;
+				globalResourceSet.delete(resource);
+				try {
+					resource.emitDestroy();
+				} catch (err) {
+					
+				}
+			}
+
 			map.delete(listener);
 			return method.call(this, event, wrapped);
 		};
@@ -117,4 +174,84 @@ export function enableAlsForEventEmitters(als = defaultALS) {
 		if (this[kMap]) this[kMap] = new WeakMap();
 		return res;
 	};
+
+	
+	if (!originalMethods) {
+		originalMethods = {
+			on: origOn,
+			once: origOnce,
+			addListener: origAdd,
+			prependListener: origPre,
+			prependOnceListener: origPreO,
+			off: origOff,
+			removeListener: origRem,
+			removeAllListeners: origRemoveAll
+		};
+	}
+}
+
+
+
+export function cleanupAllSlothletListeners() {
+	let cleanedCount = 0;
+	let errorCount = 0;
+
+	
+	for (const listenerInfo of allPatchedListeners) {
+		try {
+			const { emitter, event, wrappedListener } = listenerInfo;
+			if (emitter && typeof emitter.removeListener === "function") {
+				emitter.removeListener(event, wrappedListener);
+				cleanedCount++;
+			}
+		} catch (err) {
+			errorCount++;
+			
+		}
+	}
+
+	
+	allPatchedListeners.clear();
+	
+
+	if (process.env.NODE_ENV === "development" || process.env.SLOTHLET_DEBUG) {
+		console.log(`[slothlet] Cleaned up ${cleanedCount} listeners (${errorCount} errors)`);
+	}
+}
+
+export function disableAlsForEventEmitters() {
+	const kPatched = Symbol.for("slothlet.als.patched");
+
+	if (!EventEmitter.prototype[kPatched] || !originalMethods) return;
+
+	
+	cleanupAllSlothletListeners();
+
+	
+	for (const resource of globalResourceSet) {
+		try {
+			resource.emitDestroy();
+		} catch (err) {
+			
+			console.warn("[slothlet] AsyncResource cleanup warning:", err.message);
+		}
+	}
+	globalResourceSet.clear();
+
+	
+	const proto = EventEmitter.prototype;
+	proto.on = originalMethods.on;
+	proto.once = originalMethods.once;
+	proto.addListener = originalMethods.addListener;
+	if (originalMethods.prependListener) proto.prependListener = originalMethods.prependListener;
+	if (originalMethods.prependOnceListener) proto.prependOnceListener = originalMethods.prependOnceListener;
+	if (originalMethods.off) proto.off = originalMethods.off;
+	proto.removeListener = originalMethods.removeListener;
+	proto.removeAllListeners = originalMethods.removeAllListeners;
+
+	
+	delete EventEmitter.prototype[kPatched];
+
+	
+	originalMethods = null;
 }

package/dist/lib/helpers/hooks.mjs

@@ -53,6 +53,14 @@ export class HookManager {
 	}
 
 	
+	cleanup() {
+		this.hooks.clear();
+		this.reportedErrors = new WeakSet();
+		this.registrationOrder = 0;
+		this.enabled = false;
+	}
+
+	
 	off(nameOrPattern) {
 		
 		if (this.hooks.has(nameOrPattern)) {

package/dist/slothlet.mjs

@@ -31,6 +31,7 @@ import {
 	buildCategoryDecisions
 } 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";
 
 
@@ -139,7 +140,7 @@ const slothletObject = {
 	reference: {},
 	mode: "singleton",
 	loaded: false,
-	config: { lazy: false, apiDepth: Infinity, debug: DEBUG, dir: null, sanitize: null },
+	config: { lazy: false, apiDepth: Infinity, debug: DEBUG, dir: null, sanitize: null, allowApiOverwrite: true },
 	_dispose: null,
 	_boundAPIShutdown: null,
 	instanceId: null, 
@@ -993,9 +994,12 @@ const slothletObject = {
 		
 		
 		
+
+		
+		const instance = this;
 		this.safeDefine(boundApi, "describe", function (showAll = false) {
 			
-			if (this.config && this.config.lazy) {
+			if (instance.config && instance.config.lazy) {
 				if (!showAll) {
 					return Reflect.ownKeys(boundApi);
 				}
@@ -1051,17 +1055,36 @@ const slothletObject = {
 		} else {
 			this._boundAPIShutdown = null;
 		}
+
+		
+		
+		
+		const hasUserDefinedShutdown = this._boundAPIShutdown !== null;
+
 		const shutdownDesc = Object.getOwnPropertyDescriptor(boundApi, "shutdown");
 		if (!shutdownDesc || shutdownDesc.configurable) {
 			Object.defineProperty(boundApi, "shutdown", {
 				value: this.shutdown.bind(this),
 				writable: true,
 				configurable: true,
-				enumerable: true
+				enumerable: hasUserDefinedShutdown 
 			});
 		} else if (this.config && this.config.debug) {
 			console.warn("Could not redefine boundApi.shutdown: not configurable");
 		}
+
+		
+		const addApiDesc = Object.getOwnPropertyDescriptor(boundApi, "addApi");
+		if (!addApiDesc || addApiDesc.configurable) {
+			Object.defineProperty(boundApi, "addApi", {
+				value: this.addApi.bind(this),
+				writable: true,
+				configurable: true,
+				enumerable: false 
+			});
+		} else if (this.config && this.config.debug) {
+			console.warn("Could not redefine boundApi.addApi: not configurable");
+		}
 		
 
 		
@@ -1073,21 +1096,21 @@ const slothletObject = {
 	},
 
 	
-	safeDefine(obj, key, value) {
+	safeDefine(obj, key, value, enumerable = false) {
 		const desc = Object.getOwnPropertyDescriptor(obj, key);
 		if (!desc) {
 			Object.defineProperty(obj, key, {
 				value,
 				writable: true,
 				configurable: true,
-				enumerable: true
+				enumerable
 			});
 		} else if (desc.configurable) {
 			Object.defineProperty(obj, key, {
 				value,
 				writable: true,
 				configurable: true,
-				enumerable: true
+				enumerable
 			});
 		} else if (this.config && this.config.debug) {
 			console.warn(`Could not redefine boundApi.${key}: not configurable`);
@@ -1110,6 +1133,220 @@ const slothletObject = {
 	},
 
 	
+	async addApi(apiPath, folderPath) {
+		if (!this.loaded) {
+			throw new Error("[slothlet] Cannot add API: API not loaded. Call create() or load() first.");
+		}
+
+		
+		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.");
+		}
+
+		
+		let resolvedFolderPath = folderPath;
+		if (!path.isAbsolute(folderPath)) {
+			resolvedFolderPath = resolvePathFromCaller(folderPath);
+		}
+
+		
+		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}`);
+		}
+
+		if (this.config.debug) {
+			console.log(`[DEBUG] addApi: Loading modules from ${resolvedFolderPath} to path: ${normalizedApiPath}`);
+		}
+
+		
+		let newModules;
+		if (this.config.lazy) {
+			
+			newModules = await this.modes.lazy.create.call(this, resolvedFolderPath, this.config.apiDepth || Infinity, 0);
+		} 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.`
+					);
+				}
+				
+			} else {
+				currentBoundTarget[key] = {};
+			}
+
+			
+			currentTarget = currentTarget[key];
+			currentBoundTarget = currentBoundTarget[key];
+		}
+
+		
+		const finalKey = this._toapiPathKey(pathParts[pathParts.length - 1]);
+
+		
+		if (typeof newModules === "function") {
+			
+			
+			if (Object.prototype.hasOwnProperty.call(currentTarget, finalKey)) {
+				const existing = currentTarget[finalKey];
+
+				
+				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 (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 (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; 
+					}
+				}
+
+				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.`
+					);
+				}
+			}
+
+			
+			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.`
+			);
+		} else {
+			
+			
+			currentTarget[finalKey] = newModules;
+			currentBoundTarget[finalKey] = newModules;
+		}
+
+		
+		this.updateBindings(this.context, this.reference, this.boundapi);
+
+		if (this.config.debug) {
+			console.log(`[DEBUG] addApi: Successfully added modules at ${normalizedApiPath}`);
+		}
+	},
+
+	
 	async shutdown() {
 		
 		
@@ -1152,12 +1389,30 @@ const slothletObject = {
 				this._boundAPIShutdown = null;
 
 				
+				if (this.hookManager) {
+					this.hookManager.cleanup();
+					this.hookManager = null;
+				}
+
+				
 
 				
 				if (this.instanceId) {
 					await cleanupInstance(this.instanceId);
 				}
 
+				
+				
+				try {
+					
+					cleanupAllSlothletListeners();
+					
+					disableAlsForEventEmitters();
+				} catch (cleanupError) {
+					
+					console.warn("[slothlet] Warning: EventEmitter cleanup failed:", cleanupError.message);
+				}
+
 				if (apiError || internalError) throw apiError || internalError;
 			}
 		} finally {
@@ -1197,6 +1452,18 @@ export function mutateLiveBindingFunction(target, source) {
 			}
 		}
 		
+		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;
 		}
@@ -1211,3 +1478,5 @@ export default slothlet;
 
 
 
+
+

package/index.cjs

@@ -30,9 +30,10 @@
  * @param {string} [options.mode="singleton"] - Execution mode (singleton, vm, worker, fork)
  * @param {string} [options.api_mode="auto"] - API structure mode (auto, function, object)
  * @param {string} [options.runtime] - Runtime type ("async", "asynclocalstorage", "live", "livebindings", "experimental")
+ * @param {boolean} [options.allowApiOverwrite=true] - Allow addApi to overwrite existing API endpoints
  * @param {object} [options.context={}] - Context data for live bindings
  * @param {object} [options.reference={}] - Reference objects to merge into API root
- * @returns {Promise<function|object>} The bound API object with live-binding context
+ * @returns {Promise<import("./src/slothlet.mjs").SlothletAPI>} The bound API object with management methods
  *
  * @example // CJS usage
  * const slothlet = require("@cldmv/slothlet");

package/index.mjs

@@ -55,9 +55,10 @@ function normalizeRuntimeType(runtime) {
  * @param {number} [options.apiDepth=Infinity] - Maximum directory depth to scan
  * @param {boolean} [options.debug=false] - Enable debug logging
  * @param {string} [options.api_mode="auto"] - API structure mode (auto, function, object)
+ * @param {boolean} [options.allowApiOverwrite=true] - Allow addApi to overwrite existing API endpoints
  * @param {object} [options.context={}] - Context data for live bindings
  * @param {object} [options.reference={}] - Reference objects to merge into API root
- * @returns {Promise<function|object>} The bound API object with live-binding context
+ * @returns {Promise<import("./src/slothlet.mjs").SlothletAPI>} The bound API object with management methods
  *
  * @example // ESM
  * import slothlet from "@cldmv/slothlet";

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "@cldmv/slothlet",
-	"version": "2.7.0",
+	"version": "2.8.0",
 	"moduleVersions": {
-		"lazy": "1.3.0",
-		"eager": "1.3.0"
+		"lazy": "1.3.1",
+		"eager": "1.3.1"
 	},
 	"description": "Slothlet: Modular API Loader for Node.js. Lazy mode dynamically loads API modules and submodules only when accessed, supporting both lazy and eager loading.",
 	"main": "./index.cjs",

package/types/dist/lib/helpers/als-eventemitter.d.mts

@@ -19,5 +19,38 @@
  * enableAlsForEventEmitters(als);
  */
 export function enableAlsForEventEmitters(als?: AsyncLocalStorage<any>): void;
+/**
+ * Disable AsyncLocalStorage context propagation for EventEmitter instances.
+ *
+ * @function disableAlsForEventEmitters
+ * @package
+ *
+ * @description
+ * Restores original EventEmitter methods, removing the AsyncLocalStorage
+ * context propagation. This should be called during cleanup to prevent
+ * hanging AsyncResource instances that can keep the event loop alive.
+ *
+ * @example
+ * // Disable ALS patching during shutdown
+ * disableAlsForEventEmitters();
+ */
+/**
+ * Clean up ALL listeners that went through slothlet's EventEmitter patching.
+ *
+ * @function cleanupAllSlothletListeners
+ * @package
+ *
+ * @description
+ * Removes all event listeners that were registered through slothlet's patched
+ * EventEmitter methods. This includes listeners from third-party libraries
+ * that got wrapped with AsyncResource instances. This nuclear cleanup option
+ * should be called during shutdown to prevent hanging listeners.
+ *
+ * @example
+ * // Clean up all patched listeners during shutdown
+ * cleanupAllSlothletListeners();
+ */
+export function cleanupAllSlothletListeners(): void;
+export function disableAlsForEventEmitters(): void;
 import { AsyncLocalStorage } from "node:async_hooks";
 //# sourceMappingURL=als-eventemitter.d.mts.map

package/types/dist/lib/helpers/als-eventemitter.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"als-eventemitter.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/als-eventemitter.mjs"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8EAqJC;kCA9KiC,kBAAkB"}
+{"version":3,"file":"als-eventemitter.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/als-eventemitter.mjs"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8EAiNC;AAED;;;;;;;;;;;;;;GAcG;AACH;;;;;;;;;;;;;;;GAeG;AACH,oDAyBC;AAED,mDAmCC;kCApViC,kBAAkB"}

package/types/dist/lib/helpers/hooks.d.mts

@@ -55,6 +55,18 @@ export class HookManager {
         priority?: number;
         pattern?: string;
     }): string;
+    /**
+     * Clean up all hooks and resources
+     * @public
+     * @description
+     * Clears all registered hooks and resets internal state.
+     * Should be called during shutdown to prevent memory leaks.
+     *
+     * @example
+     * // Clean up during shutdown
+     * manager.cleanup();
+     */
+    public cleanup(): void;
     /**
      * @function off
      * @public

package/types/dist/lib/helpers/hooks.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/hooks.mjs"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;GAaG;AACH;IACC;;;;;;OAMG;IACH,sBALW,OAAO,mBACP,MAAM,YAEd;QAA0B,cAAc,GAAhC,OAAO;KACjB,EAQA;IANA,iBAAsB;IACtB,uBAAoC;IACpC,wBAAqD;IACrD,qBAAsB;IACtB,0BAA0B;IAC1B,gCAAmC;IAGpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAnBW,MAAM,QACN,MAAM,+BAOd;QAAyB,QAAQ,GAAzB,MAAM;QACW,OAAO,GAAxB,MAAM;KACd,GAAU,MAAM,CA0BlB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,0BAdW,MAAM,GACJ,OAAO,CA6BnB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,oBAdW,MAAM,GACJ,IAAI,CA0BhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAfW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CA4BzB;IAED;;;;;;;;;;;;OAYG;IACH,wBAVW,MAAM,GACJ,IAAI,CAchB;IAED;;;;;;;;;;;OAWG;IACH,kBATa,IAAI,CAWhB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,2BAkCC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,0BAwBC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,2BAqBC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,0BAyBC;IAED;;;;;;;;;;;;;;OAcG;IACH,0BAkBC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,wBAmBC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,sBA4CC;IAED;;;;;;;;;;;;;OAaG;IACH,2BAuBC;IAED;;;;;;;;;;;;;OAaG;IACH,wBAiBC;IAED;;;;;;;;;;;;;;OAcG;IACH,sBAOC;CACD"}
+{"version":3,"file":"hooks.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/hooks.mjs"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;GAaG;AACH;IACC;;;;;;OAMG;IACH,sBALW,OAAO,mBACP,MAAM,YAEd;QAA0B,cAAc,GAAhC,OAAO;KACjB,EAQA;IANA,iBAAsB;IACtB,uBAAoC;IACpC,wBAAqD;IACrD,qBAAsB;IACtB,0BAA0B;IAC1B,gCAAmC;IAGpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAnBW,MAAM,QACN,MAAM,+BAOd;QAAyB,QAAQ,GAAzB,MAAM;QACW,OAAO,GAAxB,MAAM;KACd,GAAU,MAAM,CA0BlB;IAED;;;;;;;;;;OAUG;IACH,uBAKC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,0BAdW,MAAM,GACJ,OAAO,CA6BnB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,oBAdW,MAAM,GACJ,IAAI,CA0BhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAfW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CA4BzB;IAED;;;;;;;;;;;;OAYG;IACH,wBAVW,MAAM,GACJ,IAAI,CAchB;IAED;;;;;;;;;;;OAWG;IACH,kBATa,IAAI,CAWhB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,2BAkCC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,0BAwBC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,2BAqBC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,0BAyBC;IAED;;;;;;;;;;;;;;OAcG;IACH,0BAkBC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,wBAmBC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,sBA4CC;IAED;;;;;;;;;;;;;OAaG;IACH,2BAuBC;IAED;;;;;;;;;;;;;OAaG;IACH,wBAiBC;IAED;;;;;;;;;;;;;;OAcG;IACH,sBAOC;CACD"}

package/types/dist/slothlet.d.mts

@@ -92,6 +92,13 @@ export type SlothletOptions = {
      * - `"object"`: Force API to be plain object with method properties
      */
     api_mode?: string;
+    /**
+     * - Controls whether addApi can overwrite existing API endpoints:
+     * - `true`: Allow overwrites (default, backwards compatible)
+     * - `false`: Prevent overwrites, log warning and skip when attempting to overwrite existing endpoints
+     * - Applies to both function and object overwrites at the final key of the API path
+     */
+    allowApiOverwrite?: boolean;
     /**
      * - Context data object injected into live-binding `context` reference.
      * - Available to all loaded modules via `import { context } from "@cldmv/slothlet/runtime"`. Useful for request data,
@@ -121,14 +128,28 @@ export type SlothletOptions = {
         };
     };
 };
+export type SlothletAPI = {
+    /**
+     * - Shuts down the API instance and cleans up all resources
+     */
+    shutdown: () => Promise<void>;
+    /**
+     * - Dynamically adds API modules from a folder to a specified API path
+     */
+    addApi: (apiPath: string, folderPath: string) => Promise<void>;
+    /**
+     * - Returns metadata about the current API instance configuration. In lazy mode with showAll=false, returns an array of property keys. In lazy mode with showAll=true, returns a Promise resolving to an object. In eager mode, returns a plain object.
+     */
+    describe: (showAll?: boolean) => ((string | symbol)[] | object | Promise<object>);
+};
 /**
  * Creates a slothlet API instance with the specified configuration.
  * This is the main entry point that can be called directly as a function.
  * @async
  * @alias module:@cldmv/slothlet
  * @param {SlothletOptions} [options={}] - Configuration options for creating the API
- * @returns {Promise<function|object>} The bound API object or function
+ * @returns {Promise<SlothletAPI>} The bound API object or function with management methods
  * @public
  */
-export function slothlet(options?: SlothletOptions): Promise<Function | object>;
+export function slothlet(options?: SlothletOptions): Promise<SlothletAPI>;
 //# sourceMappingURL=slothlet.d.mts.map

package/types/dist/slothlet.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AA+hDA;;;;;;;;;GASG;AACH,kDARW,WAAS,MAAM,UACf,WAAS,MAAM,QAwCzB;AAp5CD;;;;;;;GAOG;AACH,mBAJU,MAAM,CAIO;AAEvB;;;;;GAKG;AACH,sBAJU,MAAM,CAIU;AAE1B;;;;;GAKG;AACH,wBAJU,MAAM,CAIY;;;;;;;;;UAu4Cd,MAAM;;;;;;WAIN,OAAO;;;;;;;;WAGP,MAAM;;;;;;;;aAKN,MAAM;;;;;;;cAKN,MAAM;;;;;;;eAIN,MAAM;;;;;;;;YAIN,OAAO;;;;;;;eAKP,MAAM;;;;;;cAIN,MAAM;;;;;;gBAGN,MAAM;;;;;;eAMjB;QAA8B,UAAU,GAA7B,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACW,KAAK,GAClC;YAAqC,KAAK,GAA/B,MAAM,EAAE;YACkB,gBAAgB,GAA1C,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;SACrB;KAAA;;AAx7CD;;;;;;;;GAQG;AACH,mCAJW,eAAe,GACb,OAAO,CAAC,WAAS,MAAM,CAAC,CAiCpC"}
+{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AA80DA;;;;;;;;;GASG;AACH,kDARW,WAAS,MAAM,UACf,WAAS,MAAM,QAoDzB;AA9sDD;;;;;;;GAOG;AACH,mBAJU,MAAM,CAIO;AAEvB;;;;;GAKG;AACH,sBAJU,MAAM,CAIU;AAE1B;;;;;GAKG;AACH,wBAJU,MAAM,CAIY;;;;;;;;;UAisDd,MAAM;;;;;;WAIN,OAAO;;;;;;;;WAGP,MAAM;;;;;;;;aAKN,MAAM;;;;;;;cAKN,MAAM;;;;;;;eAIN,MAAM;;;;;;;;YAIN,OAAO;;;;;;;eAKP,MAAM;;;;;;;wBAIN,OAAO;;;;;;cAIP,MAAM;;;;;;gBAGN,MAAM;;;;;;eAMjB;QAA8B,UAAU,GAA7B,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACW,KAAK,GAClC;YAAqC,KAAK,GAA/B,MAAM,EAAE;YACkB,gBAAgB,GAA1C,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;SACrB;KAAA;;;;;;cAIa,MAAM,OAAO,CAAC,IAAI,CAAC;;;;YACnB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC;;;;cACtD,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,GAAC,MAAM,GAAC,OAAO,CAAC,MAAM,CAAC,CAAC;;AA5vD/E;;;;;;;;GAQG;AACH,mCAJW,eAAe,GACb,OAAO,CAAC,WAAW,CAAC,CAiChC"}