@cldmv/slothlet 2.6.3 → 2.7.0

package/README.md

@@ -74,6 +74,15 @@ v2.0 represents a ground-up rewrite with enterprise-grade features:
 - **AsyncResource Integration**: Production-ready context management following Node.js best practices
 - **Zero Configuration**: Works automatically with TCP servers, HTTP servers, and any EventEmitter-based patterns
 
+### 🎣 **Hook System (v2.6.4)** ⭐ NEW
+
+- **3-Hook Types**: `before` (modify args or cancel), `after` (transform results), `always` (observe final result)
+- **Cross-Mode Compatibility**: Works seamlessly across all 4 combinations (eager/lazy × async/live)
+- **Pattern Matching**: Target specific functions or use wildcards (`math.*`, `*.add`, `**`)
+- **Priority Control**: Order hook execution with numeric priorities
+- **Runtime Control**: Enable/disable hooks at runtime, globally or by pattern
+- **Short-Circuit Support**: Cancel execution and return custom values from `before` hooks
+
 ---
 
 ## 🚀 Key Features
@@ -712,6 +721,488 @@ console.log("Processing completed with context preservation");
 > [!TIP]  
 > **Universal Class Support**: Any class instance returned from your API functions automatically maintains slothlet context. This includes database models, service classes, utility classes, and any other object-oriented patterns in your codebase.
 
+### Hook System
+
+Slothlet provides a powerful hook system for intercepting, modifying, and observing API function calls. Hooks work seamlessly across all loading modes (eager/lazy) and runtime types (async/live).
+
+#### Hook Configuration
+
+Hooks can be configured when creating a slothlet instance:
+
+```javascript
+// Enable hooks (simple boolean)
+const api = await slothlet({
+	dir: "./api",
+	hooks: true // Enable all hooks with default pattern "**"
+});
+
+// Enable with custom pattern
+const api = await slothlet({
+	dir: "./api",
+	hooks: "database.*" // Only enable for database functions
+});
+
+// Full configuration object
+const api = await slothlet({
+	dir: "./api",
+	hooks: {
+		enabled: true,
+		pattern: "**", // Default pattern for filtering
+		suppressErrors: false // Control error throwing behavior
+	}
+});
+```
+
+**Configuration Options:**
+
+- **`enabled`** (boolean): Enable or disable hook execution
+- **`pattern`** (string): Default pattern for filtering which functions hooks apply to
+- **`suppressErrors`** (boolean): Control error throwing behavior
+  - `false` (default): Errors are sent to error hooks, THEN thrown (normal behavior)
+  - `true`: Errors are sent to error hooks, BUT NOT thrown (returns `undefined`)
+
+**Error Suppression Behavior:**
+
+Error hooks **ALWAYS receive errors** regardless of this setting. The `suppressErrors` option only controls whether errors are thrown after error hooks execute.
+
+> [!IMPORTANT]  
+> **Hooks Must Be Enabled**: Error hooks (and all hooks) only execute when `hooks.enabled: true`. If hooks are disabled, errors are thrown normally without any hook execution.
+
+When `suppressErrors: true`, errors are caught and sent to error hooks, but not thrown:
+
+```javascript
+const api = await slothlet({
+	dir: "./api",
+	hooks: {
+		enabled: true,
+		pattern: "**",
+		suppressErrors: true // Suppress all errors
+	}
+});
+
+// Register error hook to monitor failures
+api.hooks.on(
+	"error-monitor",
+	"error",
+	({ path, error, source }) => {
+		console.error(`Error in ${path}:`, error.message);
+		// Log to monitoring service without crashing
+	},
+	{ pattern: "**" }
+);
+
+// Function errors won't crash the application
+const result = await api.riskyOperation();
+if (result === undefined) {
+	// Function failed but didn't throw
+	console.log("Operation failed gracefully");
+}
+```
+
+**Error Flow:**
+
+1. Error occurs (in before hook, function, or after hook)
+2. Error hooks execute and receive the error
+3. **If `suppressErrors: false`** → Error is thrown (crashes if uncaught)
+4. **If `suppressErrors: true`** → Error is NOT thrown, function returns `undefined`
+
+**What Gets Suppressed (when `suppressErrors: true`):**
+
+- ✅ Before hook errors → Sent to error hooks, NOT thrown
+- ✅ Function execution errors → Sent to error hooks, NOT thrown
+- ✅ After hook errors → Sent to error hooks, NOT thrown
+- ✅ Always hook errors → Sent to error hooks, never thrown (regardless of setting)
+
+> [!TIP]  
+> **Use Case**: Enable `suppressErrors: true` for resilient systems where you want to monitor failures without crashing. Perfect for background workers, batch processors, or systems with comprehensive error monitoring.
+
+> [!CAUTION]  
+> **Critical Operations**: For validation or authorization hooks where errors MUST stop execution, use `suppressErrors: false` (default) to ensure errors propagate normally.
+
+#### Hook Types
+
+**Four hook types with distinct responsibilities:**
+
+- **`before`**: Intercept before function execution
+  - Modify arguments passed to functions
+  - Cancel execution and return custom values (short-circuit)
+  - Execute validation or logging before function runs
+- **`after`**: Transform results after successful execution
+  - Transform function return values
+  - Only runs if function executes (skipped on short-circuit)
+  - Chain multiple transformations in priority order
+- **`always`**: Observe final result with full execution context
+  - Always executes after function completes
+  - Runs even when `before` hooks cancel execution or errors occur
+  - Receives complete context: `{ path, result, hasError, errors }`
+  - Cannot modify result (read-only observation)
+  - Perfect for unified logging of both success and error scenarios
+- **`error`**: Monitor and handle errors
+  - Receives detailed error context with source tracking
+  - Error source types: 'before', 'function', 'after', 'always', 'unknown'
+  - Includes error type, hook ID, hook tag, timestamp, and stack trace
+  - Perfect for error monitoring, logging, and alerting
+
+#### Basic Usage
+
+```javascript
+import slothlet from "@cldmv/slothlet";
+
+const api = await slothlet({
+	dir: "./api",
+	hooks: true // Enable hooks
+});
+
+// Before hook: Modify arguments
+api.hooks.on(
+	"validate-input",
+	"before",
+	({ path, args }) => {
+		console.log(`Calling ${path} with args:`, args);
+		// Return modified args or original
+		return [args[0] * 2, args[1] * 2];
+	},
+	{ pattern: "math.add", priority: 100 }
+);
+
+// After hook: Transform result
+api.hooks.on(
+	"format-output",
+	"after",
+	({ path, result }) => {
+		console.log(`${path} returned:`, result);
+		// Return transformed result
+		return result * 10;
+	},
+	{ pattern: "math.*", priority: 100 }
+);
+
+// Always hook: Observe final result with error context
+api.hooks.on(
+	"log-execution",
+	"always",
+	({ path, result, hasError, errors }) => {
+		if (hasError) {
+			console.log(`${path} failed with ${errors.length} error(s):`, errors);
+		} else {
+			console.log(`${path} succeeded with result:`, result);
+		}
+		// Return value ignored - read-only observer
+	},
+	{ pattern: "**" } // All functions
+);
+
+// Call function - hooks execute automatically
+const result = await api.math.add(2, 3);
+// Logs: "Calling math.add with args: [2, 3]"
+// Logs: "math.add returned: 10" (4+6)
+// Logs: "Final result for math.add: 100" (10*10)
+// result === 100
+```
+
+#### Short-Circuit Execution
+
+`before` hooks can cancel function execution and return custom values:
+
+```javascript
+// Caching hook example
+const cache = new Map();
+
+api.hooks.on(
+	"cache-check",
+	"before",
+	({ path, args }) => {
+		const key = JSON.stringify({ path, args });
+		if (cache.has(key)) {
+			console.log(`Cache hit for ${path}`);
+			return cache.get(key); // Short-circuit: return cached value
+		}
+		// Return undefined to continue to function
+	},
+	{ pattern: "**", priority: 1000 } // High priority
+);
+
+api.hooks.on(
+	"cache-store",
+	"after",
+	({ path, args, result }) => {
+		const key = JSON.stringify({ path, args });
+		cache.set(key, result);
+		return result; // Pass through
+	},
+	{ pattern: "**", priority: 100 }
+);
+
+// First call - executes function and caches
+await api.math.add(2, 3); // Computes and stores
+
+// Second call - returns cached value (function not executed)
+await api.math.add(2, 3); // Cache hit! No computation
+```
+
+#### Pattern Matching
+
+Hooks support flexible pattern matching:
+
+```javascript
+// Exact match
+api.hooks.on("hook1", "before", handler, { pattern: "math.add" });
+
+// Wildcard: all functions in namespace
+api.hooks.on("hook2", "before", handler, { pattern: "math.*" });
+
+// Wildcard: specific function in all namespaces
+api.hooks.on("hook3", "before", handler, { pattern: "*.add" });
+
+// Global: all functions
+api.hooks.on("hook4", "before", handler, { pattern: "**" });
+```
+
+#### Priority and Chaining
+
+Multiple hooks execute in priority order (highest first):
+
+```javascript
+// High priority - runs first
+api.hooks.on(
+	"validate",
+	"before",
+	({ args }) => {
+		if (args[0] < 0) throw new Error("Negative numbers not allowed");
+		return args;
+	},
+	{ pattern: "math.*", priority: 1000 }
+);
+
+// Medium priority - runs second
+api.hooks.on("double", "before", ({ args }) => [args[0] * 2, args[1] * 2], { pattern: "math.*", priority: 500 });
+
+// Low priority - runs last
+api.hooks.on(
+	"log",
+	"before",
+	({ path, args }) => {
+		console.log(`Final args for ${path}:`, args);
+		return args;
+	},
+	{ pattern: "math.*", priority: 100 }
+);
+```
+
+#### Runtime Control
+
+Enable and disable hooks at runtime:
+
+```javascript
+const api = await slothlet({ dir: "./api", hooks: true });
+
+// Add hooks
+api.hooks.on("test", "before", handler, { pattern: "math.*" });
+
+// Disable all hooks
+api.hooks.disable();
+await api.math.add(2, 3); // No hooks execute
+
+// Re-enable all hooks
+api.hooks.enable();
+await api.math.add(2, 3); // Hooks execute
+
+// Enable specific pattern only
+api.hooks.disable();
+api.hooks.enable("math.*"); // Only math.* pattern enabled
+await api.math.add(2, 3); // math.* hooks execute
+await api.other.func(); // No hooks execute
+```
+
+#### Hook Management
+
+```javascript
+// List registered hooks
+const beforeHooks = api.hooks.list("before");
+const afterHooks = api.hooks.list("after");
+const allHooks = api.hooks.list(); // All types
+
+// Remove specific hook by ID
+const id = api.hooks.on("temp", "before", handler, { pattern: "math.*" });
+api.hooks.off(id);
+
+// Remove all hooks matching pattern
+api.hooks.off("math.*");
+
+// Clear all hooks of a type
+api.hooks.clear("before"); // Remove all before hooks
+api.hooks.clear(); // Remove all hooks
+```
+
+#### Error Handling
+
+Hooks have a special `error` type for observing function errors with detailed source tracking:
+
+```javascript
+api.hooks.on(
+	"error-logger",
+	"error",
+	({ path, error, source }) => {
+		console.error(`Error in ${path}:`, error.message);
+		console.error(`Source: ${source.type}`); // 'before', 'after', 'always', 'function', 'unknown'
+
+		if (source.type === "function") {
+			console.error("Error occurred in function execution");
+		} else if (["before", "after", "always"].includes(source.type)) {
+			console.error(`Error occurred in ${source.type} hook:`);
+			console.error(`  Hook ID: ${source.hookId}`);
+			console.error(`  Hook Tag: ${source.hookTag}`);
+		}
+
+		console.error(`Timestamp: ${source.timestamp}`);
+		console.error(`Stack trace:\n${source.stack}`);
+
+		// Log to monitoring service with full context
+		// Error is re-thrown after all error hooks execute
+	},
+	{ pattern: "**" }
+);
+
+try {
+	await api.validateData({ invalid: true });
+} catch (error) {
+	// Error hooks executed before this catch block
+	console.log("Caught error:", error);
+}
+```
+
+##### Error Source Tracking
+
+Error hooks receive detailed context about where errors originated:
+
+**Source Types:**
+
+- `"function"`: Error occurred during function execution
+- `"before"`: Error occurred in a before hook
+- `"after"`: Error occurred in an after hook
+- `"always"`: Error occurred in an always hook
+- `"unknown"`: Error source could not be determined
+
+**Source Metadata:**
+
+- `source.type`: Error source type (see above)
+- `source.hookId`: Hook identifier (for hook errors)
+- `source.hookTag`: Hook tag/name (for hook errors)
+- `source.timestamp`: ISO timestamp when error occurred
+- `source.stack`: Full stack trace
+
+**Example: Comprehensive Error Monitoring**
+
+```javascript
+const errorStats = {
+	function: 0,
+	before: 0,
+	after: 0,
+	always: 0,
+	byHook: {}
+};
+
+api.hooks.on(
+	"error-analytics",
+	"error",
+	({ path, error, source }) => {
+		// Track error source statistics
+		errorStats[source.type]++;
+
+		if (source.hookId) {
+			if (!errorStats.byHook[source.hookTag]) {
+				errorStats.byHook[source.hookTag] = 0;
+			}
+			errorStats.byHook[source.hookTag]++;
+		}
+
+		// Log detailed error info
+		console.error(`[${source.timestamp}] Error in ${path}:`);
+		console.error(`  Type: ${source.type}`);
+		console.error(`  Message: ${error.message}`);
+
+		if (source.type === "function") {
+			// Function-level error - might be a bug in implementation
+			console.error("  Action: Review function implementation");
+		} else {
+			// Hook-level error - might be a bug in hook logic
+			console.error(`  Action: Review ${source.hookTag} hook (${source.type})`);
+		}
+
+		// Send to monitoring service
+		sendToMonitoring({
+			timestamp: source.timestamp,
+			path,
+			errorType: source.type,
+			hookId: source.hookId,
+			hookTag: source.hookTag,
+			message: error.message,
+			stack: source.stack
+		});
+	},
+	{ pattern: "**" }
+);
+
+// Later: Analyze error patterns
+console.log("Error Statistics:", errorStats);
+// {
+//   function: 5,
+//   before: 2,
+//   after: 1,
+//   always: 0,
+//   byHook: {
+//     "validate-input": 2,
+//     "format-output": 1
+//   }
+// }
+```
+
+**Important Notes:**
+
+- Errors from `before` and `after` hooks are re-thrown after error hooks execute
+- Errors from `always` hooks are caught and logged but do NOT crash execution
+- Error hooks themselves do not receive errors from other error hooks (no recursion)
+- The `_hookSourceReported` flag prevents double-reporting of errors
+
+#### Cross-Mode Compatibility
+
+Hooks work identically across all configurations:
+
+```javascript
+// Eager + AsyncLocalStorage
+const api1 = await slothlet({ dir: "./api", lazy: false, runtime: "async", hooks: true });
+
+// Eager + Live Bindings
+const api2 = await slothlet({ dir: "./api", lazy: false, runtime: "live", hooks: true });
+
+// Lazy + AsyncLocalStorage
+const api3 = await slothlet({ dir: "./api", lazy: true, runtime: "async", hooks: true });
+
+// Lazy + Live Bindings
+const api4 = await slothlet({ dir: "./api", lazy: true, runtime: "live", hooks: true });
+
+// Same hook code works with all configurations
+[api1, api2, api3, api4].forEach((api) => {
+	api.hooks.on(
+		"universal",
+		"before",
+		({ args }) => {
+			return [args[0] * 10, args[1] * 10];
+		},
+		{ pattern: "math.add" }
+	);
+});
+```
+
+**Key Benefits:**
+
+- ✅ **Universal**: Works across all 4 mode/runtime combinations
+- ✅ **Flexible**: Pattern matching with wildcards and priorities
+- ✅ **Powerful**: Modify args, transform results, observe execution
+- ✅ **Composable**: Chain multiple hooks with priority control
+- ✅ **Dynamic**: Enable/disable at runtime globally or by pattern
+- ✅ **Observable**: Separate hook types for different responsibilities
+
 ### API Mode Configuration
 
 The `api_mode` option controls how slothlet handles root-level default function exports: