@noego/ioc 0.0.8 → 0.0.10

package/readme.md

@@ -4,9 +4,8 @@ A lightweight, flexible Inversion of Control (IoC) container for Node.js and Typ
 
 ## Features
 
- **Dual Module Support**: Compatible with CommonJS and ES Modules
- **TypeScript & Typings**: Built in TypeScript with bundled declaration files
-
+- **Dual Module Support**: Compatible with CommonJS and ES Modules
+- **TypeScript & Typings**: Built in TypeScript with bundled declaration files
 - **Multiple Lifetime Scopes**: Support for Singleton, Transient, and Scoped dependencies
 - **Class & Function Registration**: Register both classes and functions as dependencies
 - **Parameter Injection**: Inject parameter values at resolution time
@@ -14,6 +13,8 @@ A lightweight, flexible Inversion of Control (IoC) container for Node.js and Typ
 - **Decorator Support**: Use @Component and @Inject decorators for clean, declarative DI
 - **TypeScript Support**: Built with full TypeScript support for type safety
 - **Async Resolution**: Support for asynchronous dependency resolution
+- **Method Call Tracing**: Automatic tracing of method calls with performance metrics and dependency hierarchies
+- **Trace Analytics**: Export and analyze traces, track statistics, and monitor dependency interactions
 - **Lightweight**: Small footprint with minimal external dependencies
 
 ## Installation
@@ -413,6 +414,124 @@ childContainer.registerClass(Database, { /* different configuration */ });
 // Child container uses the new registration
 ```
 
+### Method Call Tracing and Monitoring
+
+The container supports automatic tracing of method calls on resolved instances. This is useful for debugging, monitoring, and understanding dependency interactions in your application.
+
+#### Enabling Tracing
+
+```typescript
+const container = createContainer();
+
+// Enable tracing
+container.setTracingEnabled(true);
+
+// Optional: Set trace retention (default is 5 minutes)
+container.setTraceRetentionMinutes(10);
+
+// Register your classes
+container.registerClass(DatabaseService);
+container.registerClass(UserService);
+
+// When instances are resolved, method calls are automatically traced
+const service = await container.get(UserService);
+service.getUsers(); // This call will be traced
+```
+
+#### Retrieving Traces
+
+```typescript
+// Get recent traces within retention window
+const traces = await container.getTraces();
+console.log(traces);
+
+// Get all traces ever recorded
+const allTraces = await container.getAllTraces();
+
+// Get trace statistics
+const stats = await container.getTraceStatistics();
+console.log(`Total method calls traced: ${stats.totalTraces}`);
+console.log(`Total proxies created: ${stats.totalProxies}`);
+```
+
+#### How Tracing Works
+
+When tracing is enabled:
+
+1. **Automatic Wrapping**: Each resolved instance is wrapped in a JavaScript Proxy that intercepts method calls
+2. **Call Recording**: Every method call is recorded with:
+   - Method name and parameters
+   - Return value or error (if thrown)
+   - Execution duration in milliseconds
+   - Parent-child dependency relationships
+3. **Zero Overhead When Disabled**: When tracing is disabled, instances are not wrapped and there's no performance impact
+4. **Database Storage**: Traces are stored in-memory using sql.js (pure JavaScript SQLite)
+5. **Automatic Cleanup**: Old traces are automatically cleaned up based on retention settings
+
+#### Trace Statistics
+
+The trace statistics provide insights into your application's dependency interactions:
+
+```typescript
+const stats = await container.getTraceStatistics();
+
+// Example output:
+// {
+//   totalTraces: 42,                    // Total method calls recorded
+//   totalProxies: 5,                    // Total unique instances traced
+//   proxiesByClass: {
+//     UserService: 1,
+//     DatabaseService: 1,
+//     UserRepository: 1
+//   },
+//   methodCallsByProxy: {
+//     1: 12,  // Proxy 1 had 12 method calls
+//     2: 8,   // Proxy 2 had 8 method calls
+//     // ...
+//   }
+// }
+```
+
+#### Exporting and Analyzing Traces
+
+```typescript
+// Export traces to JSON for analysis
+const exported = await TraceLoggerModule.exportTracesToJson();
+// or use container method
+await container.exportTraces('./traces.json');
+
+// Clear traces
+await container.clearTraces();
+```
+
+#### Tracing with Dependency Hierarchies
+
+When an instance depends on other instances, the tracing system records the parent-child relationships:
+
+```typescript
+@Component()
+class Database {
+  query() { return 'data'; }
+}
+
+@Component()
+class UserService {
+  constructor(private db: Database) {}
+  getUsers() { return this.db.query(); }
+}
+
+const container = createContainer();
+container.setTracingEnabled(true);
+container.registerClass(Database);
+container.registerClass(UserService);
+
+const service = await container.get(UserService);
+await service.getUsers();
+
+// Traces will show the call hierarchy:
+// UserService.getUsers() -> Database.query()
+```
+
 ## API Reference
 
 ### Container
@@ -423,6 +542,14 @@ childContainer.registerClass(Database, { /* different configuration */ });
 - `instance<T>(classDefinition, params?)`: Resolve a class instance
 - `get<T>(label, params?)`: Resolve a dependency by key
 - `extend()`: Create a child container
+- `setTracingEnabled(enabled: boolean)`: Enable/disable method call tracing
+- `isTracingEnabled(): boolean`: Check if tracing is enabled
+- `setTraceRetentionMinutes(minutes: number)`: Set trace retention window
+- `getTraces(retentionMinutes?: number): Promise<TraceRecord[]>`: Get recent traces
+- `getAllTraces(): Promise<TraceRecord[]>`: Get all recorded traces
+- `clearTraces(): Promise<void>`: Clear all traces
+- `exportTraces(filepath: string): Promise<void>`: Export traces to JSON file
+- `getTraceStatistics(): Promise<TraceStatistics>`: Get trace statistics
 
 ### Decorators