@cldmv/slothlet 2.6.1 → 2.7.0

package/README.md

@@ -40,7 +40,7 @@ The name might suggest we're taking it easy, but don't be fooled. **Slothlet del
 v2.0 represents a ground-up rewrite with enterprise-grade features:
 
 - **Universal Module Support**: Load both ESM (`.mjs`) and CommonJS (`.cjs`) files seamlessly
-- **AsyncLocalStorage Integration**: Advanced context isolation and live-binding system
+- **Dual Runtime System**: Choose AsyncLocalStorage or live-bindings for context isolation
 - **4.3x Faster Startup**: Lazy mode achieves 564.17μs vs 2.45ms in eager mode
 - **Copy-Left Materialization**: Once loaded, modules stay materialized for optimal performance
 - **Zero Dependencies**: Pure Node.js implementation with no external dependencies
@@ -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
@@ -113,14 +122,14 @@ v2.0 represents a ground-up rewrite with enterprise-grade features:
 ### 🔗 **Advanced Binding System**
 
 - **Live Bindings**: Dynamic context and reference binding for runtime API mutation
-- **AsyncLocalStorage**: Per-instance context isolation with seamless integration
+- **Context Isolation**: Dual runtime options for per-instance context isolation with seamless integration
 - **Copy-Left Preservation**: Materialized functions stay materialized, preserving performance gains
 - **Bubble-Up Updates**: Parent API synchronization ensures consistency across the API tree
 - **Mixed Module Support**: Seamlessly blend ESM and CommonJS modules in the same API
 
 ### 🛠 **Developer Experience**
 
-- **Standard Error Handling**: Clear JavaScript errors with plans for enhanced descriptive errors in v2.1.0
+- **Enhanced Error Handling**: Clear JavaScript errors with module suggestions and descriptive errors (planned for v3.0.0)
 - **TypeScript-Friendly**: Comprehensive JSDoc annotations for excellent editor support with auto-generated declarations
 - **Configurable Debug**: Detailed logging for development and troubleshooting via CLI flags or environment variables
 - **Multiple Instances**: Parameter-based isolation for complex applications with instance ID management
@@ -132,7 +141,7 @@ v2.0 represents a ground-up rewrite with enterprise-grade features:
 - **Universal Loading**: CommonJS and ESM files work together seamlessly
 - **Zero Dependencies**: Lightweight footprint with no external dependencies
 - **Cross-Platform**: Works seamlessly across all Node.js environments
-- **Extensible**: Modular architecture designed for future plugin system (in development)
+- **Extensible**: Modular architecture with flexible API composition patterns
 
 ---
 
@@ -140,11 +149,16 @@ v2.0 represents a ground-up rewrite with enterprise-grade features:
 
 ### Requirements
 
-- **Node.js v16.4.0 or higher** (for stable AsyncLocalStorage support)
-- **ESM support** (ES modules with `import`/`export`)
+- **Node.js v12.20.0 or higher** (for ESM support with `import`/`export`)
+- **Node.js v16.4.0 or higher** (recommended for AsyncLocalStorage runtime - `runtime: "async"`)
 
 > [!IMPORTANT]  
-> **v2.x Breaking Change**: Slothlet v2.x requires AsyncLocalStorage for its comprehensive live-binding system, which was stabilized in Node.js v16.4.0+ (June 2021). If you need older Node.js versions, please use slothlet v1.x (which requires Node.js v12.20.0+ (November 2020) for ESM support, dynamic imports, and query string imports). Note that v1.x live-binding worked in ESM (including multiple APIs via query strings) but was not available for multiple API instances in CommonJS.
+> **v2.x Runtime Options**: Slothlet v2.x supports two runtime systems:
+>
+> - **AsyncLocalStorage Runtime** (`runtime: "async"`) - Default, requires Node.js v16.4.0+ for context isolation
+> - **Live Bindings Runtime** (`runtime: "live"`) - Advanced system, works on Node.js v12.20.0+ without AsyncLocalStorage
+>
+> Both runtimes provide full live-binding capabilities with `self`, `context`, and `reference` support across ESM and CommonJS modules. Use `runtime: "live"` for older Node.js versions or advanced binding scenarios.
 
 ### Install
 
@@ -194,6 +208,28 @@ const result = api.math.multiply(4, 5); // 20
 const mixedResult = await api.interop.processData({ data: "test" }); // CJS+ESM interop
 ```
 
+### Runtime Selection
+
+```javascript
+// AsyncLocalStorage runtime (default) - requires Node.js v16.4.0+
+const apiAsync = await slothlet({
+	dir: "./api",
+	runtime: "async", // or "asynclocalstorage"
+	context: { user: "alice" }
+});
+
+// Live bindings runtime - works on Node.js v12.20.0+
+const apiLive = await slothlet({
+	dir: "./api",
+	runtime: "live", // or "livebindings"
+	context: { user: "bob" }
+});
+
+// Both provide identical live-binding capabilities
+import { self, context, reference } from "@cldmv/slothlet/runtime";
+// context.user is available in your modules regardless of runtime choice
+```
+
 ### Lazy Loading Mode
 
 ```javascript
@@ -260,7 +296,7 @@ const api = await slothlet({
 
 ### Sanitize Options Examples
 
-Transform module filenames into clean, professional API property names:
+Transform module filenames into clean, professional API property names with sophisticated control:
 
 ```javascript
 // Without sanitize options (default behavior)
@@ -272,23 +308,96 @@ const api = await slothlet({ dir: "./api" });
 const api = await slothlet({
 	dir: "./api",
 	sanitize: {
-		lowerFirst: false,
+		lowerFirst: false, // Keep first character casing
+		preserveAllUpper: true, // Preserve identifiers like "COMMON_APPS"
+		preserveAllLower: false, // Transform identifiers like "common_apps"
 		rules: {
-			leave: ["parseJSON"], // Exact match preservation
-			upper: ["**url**", "ip", "http*"], // Boundary + glob patterns
-			leaveInsensitive: ["*xml*"] // Case-insensitive globs
+			leave: ["parseJSON"], // Exact match preservation (case-sensitive)
+			leaveInsensitive: ["*xml*"], // Case-insensitive preservation
+			upper: ["**url**", "ip", "http*"], // Force uppercase transformations
+			lower: ["id", "*id"] // Force lowercase transformations
 		}
 	}
 });
 // Result: api.buildURLWithParams, api.parseJSON, api.autoIP
 ```
 
+**Comprehensive Sanitize Configuration:**
+
+```javascript
+const api = await slothlet({
+	dir: "./api",
+	sanitize: {
+		// Basic Options
+		lowerFirst: true, // Default: lowercase first character for camelCase
+		preserveAllUpper: true, // Keep "COMMON_APPS" unchanged
+		preserveAllLower: false, // Transform "common_apps" → "commonApps"
+
+		rules: {
+			// Preserve exact matches (case-sensitive)
+			leave: ["parseJSON", "autoIP", "getHTTPStatus"],
+
+			// Preserve patterns (case-insensitive)
+			leaveInsensitive: ["*xml*", "*html*"],
+
+			// Force uppercase transformations
+			upper: [
+				"api", // Exact: "api" → "API"
+				"http*", // Glob: "httpGet" → "HTTPGet"
+				"**url**", // Boundary: "buildUrlPath" → "buildURLPath"
+				"**json**" // Boundary: "parseJsonData" → "parseJSONData"
+			],
+
+			// Force lowercase transformations
+			lower: [
+				"id", // Exact: "ID" → "id"
+				"*id", // Glob: "userId" → "userid"
+				"uuid*" // Glob: "UUIDGenerator" → "uuidGenerator"
+			]
+		}
+	}
+});
+```
+
 **Sanitize Pattern Types:**
 
 - **Exact Match**: `"parseJSON"` - Matches exact string only
-- **Glob Patterns**: `"*json*"`, `"auto*"`, `"http*"` - Wildcard matching
-- **Boundary Patterns**: `"**url**"` - Only matches when surrounded by word boundaries
-- **Case Control**: `leaveInsensitive` for case-insensitive matching
+- **Glob Patterns**:
+  - `"*json*"` - Matches anywhere in string (`parseJsonData`)
+  - `"auto*"` - Matches at start (`autoGenerateId`)
+  - `"*id"` - Matches at end (`userId`)
+- **Boundary Patterns**:
+  - `"**url**"` - Only matches when surrounded by characters (`buildUrlPath` ✓, `url` ✗)
+  - `"**json**"` - Matches `parseJsonData` but not standalone `json`
+- **Case Control**:
+  - `leave` - Case-sensitive exact preservation
+  - `leaveInsensitive` - Case-insensitive preservation
+  - `preserveAllUpper`/`preserveAllLower` - Automatic case detection
+
+**Advanced Pattern Examples:**
+
+```javascript
+// File transformations with patterns:
+sanitizePathName("build-url-with-params", {
+	rules: { upper: ["**url**"] }
+}); // → "buildURLWithParams"
+
+sanitizePathName("parse-json-data", {
+	rules: { upper: ["**json**"] }
+}); // → "parseJSONData"
+
+sanitizePathName("get-http-status", {
+	rules: { upper: ["http*"] }
+}); // → "getHTTPStatus"
+
+sanitizePathName("validate-user-id", {
+	rules: { lower: ["*id"] }
+}); // → "validateUserid"
+
+sanitizePathName("XML_PARSER", {
+	preserveAllUpper: true
+}); // → "XML_PARSER" (preserved)
+```
 
 ### Multiple Instances
 
@@ -323,7 +432,7 @@ console.log(api2.context.tenant); // "bob"
 ```
 
 > [!NOTE]  
-> **v2.x Simplification**: Unlike v1.x which required query string parameters or `withInstanceId()` methods, v2.x automatically creates isolated instances with each `slothlet()` call, leveraging AsyncLocalStorage for complete context separation.
+> **v2.x Simplification**: Unlike v1.x which required query string parameters or `withInstanceId()` methods, v2.x automatically creates isolated instances with each `slothlet()` call, using your chosen runtime system (`async` or `live`) for complete context separation.
 
 ---
 
@@ -345,20 +454,21 @@ Creates and loads an API instance with the specified configuration.
 
 **Options:**
 
-| 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`       | **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                                                                                                                                                                                                                                                      |
-| `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+)
+| 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`       | **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"`                                                                                                                                                                                                                                                                                                                   |
+| `runtime`   | `string`  | `"async"`     | Runtime binding system: `"async"` for AsyncLocalStorage-based context isolation (default, requires Node.js v16.4.0+), `"live"` for advanced live-binding system (works on Node.js v12.20.0+). Both provide full live-binding capabilities.                                                                                                                                                            |
+| `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)                    |
+| `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) |
+
+#### ✨ Current Option Format
 
 The option structure has been improved for better clarity:
 
@@ -611,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:
@@ -839,16 +1431,16 @@ flowchart TD
     HASDEFAULT -->|Yes| NAMESPACE
 
     HASDEFAULT -->|No| NAMEDONLY{Only Named Exports?}
-    NAMEDONLY -->|Yes| FLATTEN[Flatten All Named Exports<br/>api.connect(), api.disconnect()]
+    NAMEDONLY -->|Yes| FLATTEN["Flatten All Named Exports<br/>api.connect, api.disconnect"]
 
     NAMEDONLY -->|No| SINGLENAMED{Single Named Export<br/>Matching Filename?}
     SINGLENAMED -->|Yes| FLATTENSINGLE[Flatten Single Export<br/>api.math]
     SINGLENAMED -->|No| NAMESPACE
 
-    style FLATTEN fill:#e1f5fe
-    style FLATTENSINGLE fill:#e8f5e8
-    style NAMESPACE fill:#fff3e0
-    style PRESERVE fill:#fce4ec
+    style FLATTEN fill:#e1f5fe,stroke:#0277bd,stroke-width:2px,color:#000
+    style FLATTENSINGLE fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000
+    style NAMESPACE fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
+    style PRESERVE fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#000
 ```
 
 ### 🚀 Benefits of Smart Flattening
@@ -1049,7 +1641,7 @@ const syncResult = await api.string.format("Hello"); // Originally sync, but nee
 ## 🛡 Error Handling
 
 > [!NOTE]  
-> **Current Error Behavior**: Slothlet currently uses standard JavaScript error handling. Enhanced error handling with module suggestions is planned for v2.1.0 but not yet implemented.
+> **Current Error Behavior**: Slothlet currently uses standard JavaScript error handling. Enhanced error handling with module suggestions is planned for v3.0.0 but not yet implemented.
 
 **Current behavior:**
 
@@ -1062,7 +1654,7 @@ try {
 }
 ```
 
-**Planned Enhanced Error Features (v2.1.0):**
+**Planned Enhanced Error Features (v3.0.0):**
 
 > [!TIP]  
 > **Coming Soon**: Enhanced error handling with descriptive messages and module suggestions:
@@ -1123,7 +1715,7 @@ try {
 2. **Configuration**: New options (`api_mode`, `context`, `reference`)
 3. **Function names**: Enhanced preservation of original capitalization
 4. **Module structure**: Mixed ESM/CJS support
-5. **Live bindings**: New runtime system with AsyncLocalStorage
+5. **Live bindings**: Dual runtime system with AsyncLocalStorage and live-bindings options
 
 ### Migration Steps
 
@@ -1234,7 +1826,7 @@ Apache-2.0 © Shinrai / CLDMV
 
 Slothlet v2.0 represents a complete architectural rewrite with enterprise-grade features and performance. Special thanks to all contributors who made this comprehensive enhancement possible.
 
-**🎉 Welcome to the future of module loading with Slothlet v2.0!**
+**🎉 Welcome to the future of module loading with Slothlet!**
 
 > _Where sophisticated architecture meets blazing performance - slothlet is anything but slow._