nest-live-flow 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nest Live Flow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# Nest Live Flow
+
+A powerful NestJS library for real-time application architecture visualization and flow tracing with Total.js Flow integration. Monitor your application's dependency graph, trace execution flows, and visualize your architecture in real-time.
+
+## Features
+
+- 🔍 **Automatic Architecture Discovery**: Automatically scans and maps your NestJS application's modules, controllers, and services
+- 📊 **Real-time Flow Tracing**: Traces method calls and data flow through your application using OpenTelemetry
+- 🎨 **Visual Architecture Dashboard**: Integrates with Total.js Flow for beautiful architecture visualization
+- 🚀 **Zero Configuration**: Works out of the box with minimal setup
+- 🔧 **Flexible Integration**: Supports both decorator-based and programmatic tracing
+- 📈 **Performance Monitoring**: Track execution times and identify bottlenecks
+
+## Installation
+
+```bash
+npm install nest-live-flow
+```
+
+## Quick Start
+
+### 1. Initialize in main.ts
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { initFlow } from 'nest-live-flow';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  // Initialize flow tracing before creating the app
+  initFlow('http://localhost:8000'); // Your Total.js Flow URL
+  
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+### 2. Import the Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { NestLiveFlowModule } from 'nest-live-flow';
+
+@Module({
+  imports: [
+    NestLiveFlowModule, // Add this to your root module
+    // ... your other modules
+  ],
+})
+export class AppModule {}
+```
+
+### 3. Use Flow Tracing (Optional)
+
+#### Decorator-based Tracing
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { FlowTrace } from 'nest-live-flow';
+
+@Injectable()
+export class UserService {
+  @FlowTrace('Get User by ID')
+  async getUserById(id: string) {
+    // Your service logic
+    return { id, name: 'John Doe' };
+  }
+
+  @FlowTrace('Create New User')
+  async createUser(userData: any) {
+    // Your service logic
+    return { id: '123', ...userData };
+  }
+}
+```
+
+#### Programmatic Tracing
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { flowTrace } from 'nest-live-flow';
+
+@Injectable()
+export class ProductService {
+  async getProducts() {
+    return flowTrace('Fetch All Products', async () => {
+      // Your service logic
+      return await this.database.findAll();
+    });
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+TOTALJS_FLOW_URL=http://localhost:8000
+```
+
+### Advanced Configuration
+
+```typescript
+import { initFlow } from 'nest-live-flow';
+
+// Initialize with custom options
+initFlow('http://localhost:8000', {
+  serviceName: 'my-nestjs-app',
+  enableConsoleLogging: true,
+  batchTimeout: 2000,
+});
+```
+
+## Architecture Visualization
+
+Once configured, your application architecture will be automatically:
+
+1. **Scanned**: All modules, controllers, and services are discovered
+2. **Mapped**: Dependencies and relationships are identified
+3. **Visualized**: Real-time architecture graph in Total.js Flow
+4. **Traced**: Method calls and data flow are tracked and displayed
+
+## API Reference
+
+### Core Functions
+
+#### `initFlow(totalJsUrl: string)`
+Initializes the flow tracing system. Must be called before `NestFactory.create()`.
+
+#### `flowTrace<T>(name: string, fn: () => T | Promise<T>): Promise<T>`
+Programmatically traces a function execution.
+
+### Decorators
+
+#### `@FlowTrace(name?: string)`
+Decorator for automatic method tracing.
+
+### Modules
+
+#### `NestLiveFlowModule`
+The main module to import in your application.
+
+### Services
+
+#### `FlowScannerService`
+Service that handles architecture discovery and scanning.
+
+#### `ServiceInstrumentor`
+Service for manual instrumentation of existing services.
+
+## Integration with Total.js Flow
+
+This library is designed to work with [Total.js Flow](https://www.totaljs.com/flow/). 
+
+### Setting up Total.js Flow
+
+1. Install Total.js Flow:
+```bash
+npm install -g @totaljs/flow
+```
+
+2. Start Total.js Flow:
+```bash
+flow
+```
+
+3. Access the dashboard at `http://localhost:8000`
+
+## Examples
+
+### Basic NestJS Application
+
+```typescript
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { initFlow } from 'nest-live-flow';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  initFlow('http://localhost:8000');
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+bootstrap();
+
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { NestLiveFlowModule } from 'nest-live-flow';
+import { UsersModule } from './users/users.module';
+
+@Module({
+  imports: [
+    NestLiveFlowModule,
+    UsersModule,
+  ],
+})
+export class AppModule {}
+
+// users/users.service.ts
+import { Injectable } from '@nestjs/common';
+import { FlowTrace } from 'nest-live-flow';
+
+@Injectable()
+export class UsersService {
+  @FlowTrace()
+  findAll() {
+    return [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }];
+  }
+
+  @FlowTrace('Create User Operation')
+  create(user: any) {
+    return { id: Date.now(), ...user };
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- NestJS 10+ or 11+
+- Total.js Flow (for visualization)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+If you encounter any issues or have questions, please file an issue on our GitHub repository.

package/dist/core.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Initializes the tracing engine. Call this in main.ts before NestFactory.
+ * @param totalJsUrl - The URL of the Total.js backend
+ * @throws Error if initialization fails
+ */
+export declare function initFlow(totalJsUrl: string): void;
+/**
+ * Wraps any function to trace its execution and data flow.
+ * @param name - The display name for the trace span
+ * @param fn - The function to trace (can be sync or async)
+ * @returns Promise resolving to the function result
+ * @throws Error if tracing is not initialized
+ */
+export declare function flowTrace<T>(name: string, fn: () => T | Promise<T>): Promise<T>;

package/dist/core.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initFlow = initFlow;
+exports.flowTrace = flowTrace;
+const api_1 = require("@opentelemetry/api");
+const resources_1 = require("@opentelemetry/resources");
+const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const exporter_1 = require("./exporter");
+let tracer = null;
+/**
+ * Initializes the tracing engine. Call this in main.ts before NestFactory.
+ * @param totalJsUrl - The URL of the Total.js backend
+ * @throws Error if initialization fails
+ */
+function initFlow(totalJsUrl) {
+    if (!totalJsUrl) {
+        throw new Error('Total.js URL is required for flow initialization');
+    }
+    try {
+        const provider = new sdk_trace_node_1.NodeTracerProvider({
+            resource: (0, resources_1.resourceFromAttributes)({
+                [semantic_conventions_1.ATTR_SERVICE_NAME]: 'nestjs-app',
+            }),
+            spanProcessors: [
+                new sdk_trace_node_1.SimpleSpanProcessor(new exporter_1.TotalJsExporter(totalJsUrl)),
+            ],
+        });
+        provider.register();
+        tracer = api_1.trace.getTracer('nest-live-flow');
+        console.log('✨ Nest-Live-Flow: OpenTelemetry Engine Initialized');
+    }
+    catch (error) {
+        console.error('❌ Failed to initialize Flow tracing:', error);
+        throw error;
+    }
+}
+/**
+ * Wraps any function to trace its execution and data flow.
+ * @param name - The display name for the trace span
+ * @param fn - The function to trace (can be sync or async)
+ * @returns Promise resolving to the function result
+ * @throws Error if tracing is not initialized
+ */
+async function flowTrace(name, fn) {
+    console.log(`🔍 flowTrace called for: ${name}`);
+    if (!tracer) {
+        console.error('❌ Flow tracing not initialized. Call initFlow() first.');
+        throw new Error('Flow tracing not initialized. Call initFlow() first.');
+    }
+    if (!name?.trim()) {
+        console.error('❌ Trace name cannot be empty');
+        throw new Error('Trace name cannot be empty');
+    }
+    console.log(`🟢 Starting active span for: ${name}`);
+    return tracer.startActiveSpan(name, async (span) => {
+        console.log(`📍 Inside span for: ${name}`);
+        const startTime = Date.now();
+        try {
+            console.log(`⚙️ Executing function for: ${name}`);
+            const result = await fn();
+            console.log(`✅ Function completed for: ${name}`);
+            // Safely serialize result for data flow visualization
+            try {
+                const serializedResult = typeof result === 'object' && result !== null
+                    ? JSON.stringify(result)
+                    : String(result);
+                // Limit attribute size to prevent memory issues
+                const maxLength = 1000;
+                const truncatedResult = serializedResult.length > maxLength
+                    ? `${serializedResult.substring(0, maxLength)}...`
+                    : serializedResult;
+                span.setAttribute('flow.data', truncatedResult);
+                console.log(`📊 Set span data for: ${name}`);
+            }
+            catch {
+                span.setAttribute('flow.data', '[Unable to serialize result]');
+                console.log(`⚠️ Unable to serialize result for: ${name}`);
+            }
+            span.setAttribute('flow.duration', Date.now() - startTime);
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+            console.log(`🏆 Span completed successfully for: ${name}`);
+            return result;
+        }
+        catch (error) {
+            console.error(`💥 Error in span for ${name}:`, error);
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : 'Unknown error',
+            });
+            span.setAttribute('flow.error', error instanceof Error ? error.message : String(error));
+            throw error;
+        }
+        finally {
+            console.log(`🔚 Ending span for: ${name}`);
+            span.end();
+        }
+    });
+}

package/dist/discovery.service.d.ts

@@ -0,0 +1,56 @@
+import { OnApplicationBootstrap } from '@nestjs/common';
+import { ModulesContainer } from '@nestjs/core';
+import 'reflect-metadata';
+export declare class FlowScannerService implements OnApplicationBootstrap {
+    private readonly modulesContainer;
+    constructor(modulesContainer: ModulesContainer);
+    onApplicationBootstrap(): Promise<void>;
+    /**
+     * Safely extracts the module name from a module reference
+     */
+    private getModuleName;
+    /**
+     * Safely extracts the wrapper name from a controller/provider wrapper
+     */
+    private getWrapperName;
+    /**
+     * Generic name extraction with type safety
+     */
+    private extractName;
+    /**
+     * Checks if an object has a valid collection (controllers, providers, etc.)
+     */
+    private hasValidCollection;
+    /**
+     * Scans all modules and builds the dependency graph
+     */
+    private scanAllModules;
+    /**
+     * Processes a single module and its components
+     */
+    private processModule;
+    /**
+     * Processes controllers within a module
+     */
+    private processControllers;
+    /**
+     * Processes providers/services within a module
+     */
+    private processProviders;
+    /**
+     * Processes module imports
+     */
+    private processImports;
+    /**
+     * Adds edges between controllers and their injected services
+     */
+    private addServiceDependencyEdges;
+    /**
+     * Extracts constructor dependencies using reflection
+     */
+    private extractConstructorDependencies;
+    /**
+     * Syncs the discovered architecture to Total.js Flow
+     */
+    private syncToTotalJs;
+}

package/dist/discovery.service.js

@@ -0,0 +1,234 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowScannerService = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const axios_1 = __importDefault(require("axios"));
+require("reflect-metadata");
+let FlowScannerService = class FlowScannerService {
+    constructor(modulesContainer) {
+        this.modulesContainer = modulesContainer;
+    }
+    async onApplicationBootstrap() {
+        try {
+            const nodeMap = new Map();
+            const connections = [];
+            this.scanAllModules(nodeMap, connections);
+            this.addServiceDependencyEdges(nodeMap, connections);
+            const nodes = Array.from(nodeMap.values());
+            await this.syncToTotalJs({ nodes, connections });
+            console.log(`✅ Discovered ${nodes.length} components and ${connections.length} connections`);
+        }
+        catch (error) {
+            console.error('❌ Failed to scan modules:', error);
+            throw error;
+        }
+    }
+    /**
+     * Safely extracts the module name from a module reference
+     */
+    getModuleName(modRef) {
+        return this.extractName(modRef);
+    }
+    /**
+     * Safely extracts the wrapper name from a controller/provider wrapper
+     */
+    getWrapperName(wrapper) {
+        return this.extractName(wrapper);
+    }
+    /**
+     * Generic name extraction with type safety
+     */
+    extractName(obj) {
+        return obj?.metatype?.name && typeof obj.metatype.name === 'string'
+            ? obj.metatype.name
+            : null;
+    }
+    /**
+     * Checks if an object has a valid collection (controllers, providers, etc.)
+     */
+    hasValidCollection(obj, property) {
+        const moduleRef = obj;
+        const collection = moduleRef?.[property];
+        // Check if it's a Map-like collection with values method
+        return (collection != null &&
+            typeof collection === 'object' &&
+            'values' in collection &&
+            typeof collection.values === 'function');
+    }
+    /**
+     * Scans all modules and builds the dependency graph
+     */
+    scanAllModules(nodeMap, connections) {
+        for (const modRef of this.modulesContainer.values()) {
+            this.processModule(modRef, nodeMap, connections);
+        }
+    }
+    /**
+     * Processes a single module and its components
+     */
+    processModule(modRef, nodeMap, connections) {
+        const moduleName = this.getModuleName(modRef);
+        if (!moduleName)
+            return;
+        // Add module node
+        nodeMap.set(moduleName, {
+            id: moduleName,
+            name: moduleName,
+            type: 'module',
+        });
+        // Process controllers
+        this.processControllers(modRef, moduleName, nodeMap, connections);
+        // Process providers/services
+        this.processProviders(modRef, moduleName, nodeMap, connections);
+        // Process module imports
+        this.processImports(modRef, moduleName, nodeMap, connections);
+    }
+    /**
+     * Processes controllers within a module
+     */
+    processControllers(modRef, moduleName, nodeMap, connections) {
+        if (!this.hasValidCollection(modRef, 'controllers'))
+            return;
+        const controllersMap = modRef.controllers;
+        for (const ctrlWrapper of controllersMap.values()) {
+            const ctrlName = this.getWrapperName(ctrlWrapper);
+            if (!ctrlName)
+                continue;
+            nodeMap.set(ctrlName, {
+                id: ctrlName,
+                name: ctrlName,
+                type: 'controller',
+            });
+            connections.push({ from: moduleName, to: ctrlName });
+        }
+    }
+    /**
+     * Processes providers/services within a module
+     */
+    processProviders(modRef, moduleName, nodeMap, connections) {
+        if (!this.hasValidCollection(modRef, 'providers'))
+            return;
+        const providersMap = modRef.providers;
+        for (const provWrapper of providersMap.values()) {
+            const provName = this.getWrapperName(provWrapper);
+            if (!provName || provName === moduleName)
+                continue;
+            nodeMap.set(provName, {
+                id: provName,
+                name: provName,
+                type: 'service',
+            });
+            connections.push({ from: moduleName, to: provName });
+        }
+    }
+    /**
+     * Processes module imports
+     */
+    processImports(modRef, moduleName, nodeMap, connections) {
+        if (!modRef.imports || !modRef.imports.forEach)
+            return;
+        modRef.imports.forEach((imported) => {
+            const importedName = this.getModuleName(imported);
+            if (importedName && importedName !== moduleName) {
+                nodeMap.set(importedName, {
+                    id: importedName,
+                    name: importedName,
+                    type: 'module',
+                });
+                connections.push({ from: moduleName, to: importedName });
+            }
+        });
+    }
+    /**
+     * Adds edges between controllers and their injected services
+     */
+    addServiceDependencyEdges(nodeMap, connections) {
+        for (const modRef of this.modulesContainer.values()) {
+            if (!this.hasValidCollection(modRef, 'controllers'))
+                continue;
+            const moduleRef = modRef;
+            for (const ctrlWrapper of moduleRef.controllers.values()) {
+                const ctrlName = this.getWrapperName(ctrlWrapper);
+                if (!ctrlName || !ctrlWrapper.instance)
+                    continue;
+                this.extractConstructorDependencies(ctrlWrapper, ctrlName, nodeMap, connections);
+            }
+        }
+    }
+    /**
+     * Extracts constructor dependencies using reflection
+     */
+    extractConstructorDependencies(wrapper, ctrlName, nodeMap, connections) {
+        try {
+            const instance = wrapper.instance;
+            const proto = Object.getPrototypeOf(instance);
+            const ctor = proto?.constructor;
+            if (!ctor)
+                return;
+            const paramTypes = Reflect.getMetadata('design:paramtypes', ctor) || [];
+            for (const param of paramTypes) {
+                if (typeof param === 'function' &&
+                    param['name'] &&
+                    nodeMap.has(param['name'])) {
+                    connections.push({ from: ctrlName, to: param['name'] });
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to extract dependencies for ${ctrlName}:`, error);
+        }
+    }
+    /**
+     * Syncs the discovered architecture to Total.js Flow
+     */
+    async syncToTotalJs(data) {
+        const TOTAL_JS_URL = 'http://localhost:8000';
+        try {
+            const response = await axios_1.default.post(`${TOTAL_JS_URL}/api/flow/design`, data, {
+                timeout: 5000,
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (response.status === 200) {
+                console.log('✅ Total.js Flow Design Synced Successfully');
+            }
+            else {
+                console.warn(`⚠️ Unexpected response status: ${response.status}`);
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            if (axios_1.default.isAxiosError(error)) {
+                if (error.code === 'ECONNREFUSED') {
+                    console.error('❌ Total.js Flow server is not running. Please start it on port 8000.');
+                }
+                else {
+                    console.error(`❌ Sync Failed: ${error.response?.status || 'Network error'} - ${errorMessage}`);
+                }
+            }
+            else {
+                console.error(`❌ Sync Failed: ${errorMessage}`);
+            }
+            // Don't rethrow - this shouldn't break the application startup
+        }
+    }
+};
+exports.FlowScannerService = FlowScannerService;
+exports.FlowScannerService = FlowScannerService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.ModulesContainer])
+], FlowScannerService);

package/dist/exporter.d.ts

@@ -0,0 +1,8 @@
+import { ExportResult } from '@opentelemetry/core';
+import { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+export declare class TotalJsExporter implements SpanExporter {
+    private readonly url;
+    constructor(url: string);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+}

package/dist/exporter.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TotalJsExporter = void 0;
+const core_1 = require("@opentelemetry/core");
+const axios_1 = __importDefault(require("axios"));
+class TotalJsExporter {
+    constructor(url) {
+        this.url = url;
+    }
+    export(spans, resultCallback) {
+        console.log(`📦 TotalJsExporter: Exporting ${spans.length} spans`);
+        for (const span of spans) {
+            const data = span.attributes?.['flow.data'] || null;
+            const duration = span.duration[1] / 1000000;
+            console.log(`📡 Exporting span:`, {
+                name: span.name,
+                duration: duration,
+                hasData: !!data,
+                url: `${this.url}/api/pulse`,
+            });
+            const pulseData = {
+                id: span.name, // Matches the Controller/Service name
+                status: 'pulse',
+                duration: duration,
+                data,
+            };
+            console.log(`🚀 Sending pulse data:`, pulseData);
+            axios_1.default
+                .post(`${this.url}/api/pulse`, pulseData)
+                .then((response) => {
+                console.log(`✅ Pulse sent successfully for ${span.name}:`, response.status);
+            })
+                .catch((err) => {
+                if (err instanceof Error) {
+                    console.error(`❌ Pulse send error for ${span.name}:`, err.message);
+                }
+                else {
+                    console.error(`❌ Pulse send error for ${span.name}:`, err);
+                }
+            });
+        }
+        console.log(`📋 Export completed, calling result callback`);
+        resultCallback({ code: core_1.ExportResultCode.SUCCESS });
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}
+exports.TotalJsExporter = TotalJsExporter;

package/dist/flow.decorator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Decorator to automatically trace method execution and send pulse data to Total.js Flow
+ * @param traceName Optional custom trace name, defaults to ClassName.methodName
+ */
+export declare function FlowTrace(traceName?: string): (target: any, propertyName: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/flow.decorator.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowTrace = FlowTrace;
+const index_1 = require("./index");
+/**
+ * Decorator to automatically trace method execution and send pulse data to Total.js Flow
+ * @param traceName Optional custom trace name, defaults to ClassName.methodName
+ */
+function FlowTrace(traceName) {
+    return function (target, propertyName, descriptor) {
+        const method = descriptor.value;
+        const className = target?.constructor?.name;
+        const defaultTraceName = `${className}`;
+        const finalTraceName = traceName || defaultTraceName;
+        descriptor.value = async function (...args) {
+            return (0, index_1.flowTrace)(finalTraceName, async () => {
+                return await method.apply(this, args);
+            });
+        };
+        return descriptor;
+    };
+}

package/dist/flow.interceptor.d.ts

@@ -0,0 +1,12 @@
+import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+/**
+ * Global interceptor that automatically traces all controller method executions
+ */
+export declare class FlowInterceptor implements NestInterceptor {
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+    /**
+     * Sends flow pulse without blocking the main request
+     */
+    private sendFlowPulse;
+}

package/dist/flow.interceptor.js

@@ -0,0 +1,65 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const operators_1 = require("rxjs/operators");
+const index_1 = require("./index");
+/**
+ * Global interceptor that automatically traces all controller method executions
+ */
+let FlowInterceptor = class FlowInterceptor {
+    intercept(context, next) {
+        const className = context.getClass().name;
+        const methodName = context.getHandler().name;
+        const displayName = `${className}.${methodName}`;
+        console.log(`🎯 INTERCEPTOR TRIGGERED: ${displayName}`);
+        // Execute the handler and capture the result for flow tracing
+        return next.handle().pipe((0, operators_1.tap)({
+            next: (result) => {
+                console.log(`✅ ${displayName} completed, sending pulse...`);
+                // Trigger flow trace with the actual result (non-blocking)
+                this.sendFlowPulse(displayName, result);
+            },
+            error: (error) => {
+                const errorMessage = typeof error === 'object' && error !== null && 'message' in error
+                    ? error.message
+                    : String(error);
+                console.error(`❌ ${displayName} failed:`, errorMessage);
+                // Send pulse for errors too
+                this.sendFlowPulse(displayName, { error: errorMessage });
+            },
+            complete: () => {
+                console.log(`🏁 ${displayName} stream completed`);
+            },
+        }));
+    }
+    /**
+     * Sends flow pulse without blocking the main request
+     */
+    sendFlowPulse(displayName, result) {
+        console.log(`📡 Sending flow pulse for ${displayName}...`);
+        // Use flowTrace to send the pulse
+        (0, index_1.flowTrace)(displayName, () => {
+            console.log(`🔄 Executing flowTrace for ${displayName}`);
+            return result;
+        })
+            .then(() => {
+            console.log(`📊 Flow pulse sent successfully for ${displayName}`);
+        })
+            .catch((error) => {
+            console.error(`⚠️ Flow pulse failed for ${displayName}:`, typeof error === 'object' && error !== null && 'message' in error
+                ? error.message
+                : error);
+        });
+    }
+};
+exports.FlowInterceptor = FlowInterceptor;
+exports.FlowInterceptor = FlowInterceptor = __decorate([
+    (0, common_1.Injectable)()
+], FlowInterceptor);

package/dist/flow.module.d.ts

@@ -0,0 +1,2 @@
+export declare class NestLiveFlowModule {
+}

package/dist/flow.module.js

@@ -0,0 +1,30 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NestLiveFlowModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const discovery_service_1 = require("./discovery.service");
+const flow_interceptor_1 = require("./flow.interceptor");
+let NestLiveFlowModule = class NestLiveFlowModule {
+};
+exports.NestLiveFlowModule = NestLiveFlowModule;
+exports.NestLiveFlowModule = NestLiveFlowModule = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        imports: [core_1.DiscoveryModule],
+        providers: [
+            discovery_service_1.FlowScannerService,
+            {
+                provide: core_1.APP_INTERCEPTOR,
+                useClass: flow_interceptor_1.FlowInterceptor,
+            },
+        ],
+        exports: [discovery_service_1.FlowScannerService],
+    })
+], NestLiveFlowModule);

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { initFlow, flowTrace } from './core';
+export { FlowTrace } from './flow.decorator';
+export { FlowInterceptor } from './flow.interceptor';
+export { NestLiveFlowModule } from './flow.module';
+export { FlowScannerService } from './discovery.service';
+export { ServiceInstrumentor } from './service-instrumentor';
+export { TotalJsExporter } from './exporter';

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TotalJsExporter = exports.ServiceInstrumentor = exports.FlowScannerService = exports.NestLiveFlowModule = exports.FlowInterceptor = exports.FlowTrace = exports.flowTrace = exports.initFlow = void 0;
+// Core initialization functions
+var core_1 = require("./core");
+Object.defineProperty(exports, "initFlow", { enumerable: true, get: function () { return core_1.initFlow; } });
+Object.defineProperty(exports, "flowTrace", { enumerable: true, get: function () { return core_1.flowTrace; } });
+// Decorators and Interceptors
+var flow_decorator_1 = require("./flow.decorator");
+Object.defineProperty(exports, "FlowTrace", { enumerable: true, get: function () { return flow_decorator_1.FlowTrace; } });
+var flow_interceptor_1 = require("./flow.interceptor");
+Object.defineProperty(exports, "FlowInterceptor", { enumerable: true, get: function () { return flow_interceptor_1.FlowInterceptor; } });
+// Module and Services
+var flow_module_1 = require("./flow.module");
+Object.defineProperty(exports, "NestLiveFlowModule", { enumerable: true, get: function () { return flow_module_1.NestLiveFlowModule; } });
+var discovery_service_1 = require("./discovery.service");
+Object.defineProperty(exports, "FlowScannerService", { enumerable: true, get: function () { return discovery_service_1.FlowScannerService; } });
+// Service Instrumentor for manual instrumentation
+var service_instrumentor_1 = require("./service-instrumentor");
+Object.defineProperty(exports, "ServiceInstrumentor", { enumerable: true, get: function () { return service_instrumentor_1.ServiceInstrumentor; } });
+// Exporter for custom integrations
+var exporter_1 = require("./exporter");
+Object.defineProperty(exports, "TotalJsExporter", { enumerable: true, get: function () { return exporter_1.TotalJsExporter; } });

package/dist/service-instrumentor.d.ts

@@ -0,0 +1,11 @@
+import { OnApplicationBootstrap } from '@nestjs/common';
+import { ModulesContainer } from '@nestjs/core';
+export declare class ServiceInstrumentor implements OnApplicationBootstrap {
+    private readonly modulesContainer;
+    constructor(modulesContainer: ModulesContainer);
+    onApplicationBootstrap(): Promise<void>;
+    private instrumentServices;
+    private instrumentInstance;
+    private wrapMethod;
+    private shouldSkip;
+}

package/dist/service-instrumentor.js

@@ -0,0 +1,93 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceInstrumentor = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const index_1 = require("./index");
+let ServiceInstrumentor = class ServiceInstrumentor {
+    constructor(modulesContainer) {
+        this.modulesContainer = modulesContainer;
+    }
+    async onApplicationBootstrap() {
+        // Temporarily disable ServiceInstrumentor to avoid recursive instrumentation issues
+        // TODO: Implement a better approach that doesn't instrument itself
+        console.log('⚠️  ServiceInstrumentor disabled to prevent recursive instrumentation');
+    }
+    instrumentServices() {
+        for (const module of this.modulesContainer.values()) {
+            // Instrument providers (services)
+            for (const provider of module.providers.values()) {
+                if (provider.instance && provider.metatype) {
+                    this.instrumentInstance(provider.instance, provider.metatype.name);
+                }
+            }
+        }
+    }
+    instrumentInstance(instance, className) {
+        if (!instance || typeof instance !== 'object')
+            return;
+        // Skip if already instrumented
+        if (instance.__flowInstrumented)
+            return;
+        // Skip internal NestJS classes and our own flow classes
+        if (this.shouldSkip(className))
+            return;
+        const prototype = Object.getPrototypeOf(instance);
+        const methodNames = Object.getOwnPropertyNames(prototype).filter((name) => {
+            const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+            return (name !== 'constructor' &&
+                typeof descriptor?.value === 'function' &&
+                !name.startsWith('_') &&
+                !name.includes('Symbol'));
+        });
+        methodNames.forEach((methodName) => {
+            const originalMethod = instance[methodName];
+            if (typeof originalMethod === 'function') {
+                instance[methodName] = this.wrapMethod(originalMethod, className, methodName);
+            }
+        });
+        // Mark as instrumented
+        instance.__flowInstrumented = true;
+    }
+    wrapMethod(originalMethod, className, methodName) {
+        return async function (...args) {
+            const traceName = `${className}.${methodName}`;
+            return (0, index_1.flowTrace)(traceName, async () => {
+                const result = originalMethod.apply(this, args);
+                // Handle both sync and async methods
+                return result instanceof Promise ? await result : result;
+            });
+        };
+    }
+    shouldSkip(className) {
+        const skipPrefixes = [
+            'Flow',
+            'Discovery',
+            'Metadata',
+            'Module',
+            'Reflector',
+            'Application',
+            'Internal',
+            'Logger',
+            'Config',
+        ];
+        return (skipPrefixes.some((prefix) => className.startsWith(prefix)) ||
+            className.includes('Wrapper') ||
+            className.includes('Container') ||
+            className.includes('Factory'));
+    }
+};
+exports.ServiceInstrumentor = ServiceInstrumentor;
+exports.ServiceInstrumentor = ServiceInstrumentor = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.ModulesContainer])
+], ServiceInstrumentor);

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "nest-live-flow",
+  "version": "1.0.0",
+  "description": "A NestJS library for live application architecture visualization and flow tracing with Total.js Flow integration",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "jest",
+    "lint": "eslint \"src/**/*.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\""
+  },
+  "keywords": [
+    "nestjs",
+    "tracing",
+    "architecture",
+    "visualization",
+    "totaljs",
+    "flow",
+    "opentelemetry",
+    "dependency-injection",
+    "live-monitoring"
+  ],
+  "author": "Michael Musni <mike.musni@me.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michaelmusni/nest-live-flow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/michaelmusni/nest-live-flow/issues"
+  },
+  "homepage": "https://github.com/michaelmusni/nest-live-flow#readme",
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@opentelemetry/sdk-trace-node": "^2.2.0",
+    "@opentelemetry/semantic-conventions": "^1.38.0",
+    "axios": "^1.13.2"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/core": "^11.0.1",
+    "@types/node": "^22.10.7",
+    "eslint": "^9.18.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.3",
+    "jest": "^30.0.0",
+    "ts-jest": "^29.2.5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}