@cldmv/slothlet 2.7.0 → 2.7.1

package/README.md

@@ -522,10 +522,19 @@ 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.
+
 > [!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 +658,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";
 
 
@@ -1152,12 +1153,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 {

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "@cldmv/slothlet",
-	"version": "2.7.0",
+	"version": "2.7.1",
 	"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.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":"AAkjDA;;;;;;;;;GASG;AACH,kDARW,WAAS,MAAM,UACf,WAAS,MAAM,QAwCzB;AAt6CD;;;;;;;GAOG;AACH,mBAJU,MAAM,CAIO;AAEvB;;;;;GAKG;AACH,sBAJU,MAAM,CAIU;AAE1B;;;;;GAKG;AACH,wBAJU,MAAM,CAIY;;;;;;;;;UAy5Cd,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;;AA18CD;;;;;;;;GAQG;AACH,mCAJW,eAAe,GACb,OAAO,CAAC,WAAS,MAAM,CAAC,CAiCpC"}