@cepseudo/engine 1.0.0

package/dist/digital_twin_engine.d.ts

@@ -0,0 +1,390 @@
+import type { Collector, Harvester, Handler, CustomTableManager } from '@cepseudo/components';
+import type { AssetsManager } from '@cepseudo/assets';
+import type { StorageService } from '@cepseudo/storage';
+import type { DatabaseAdapter } from '@cepseudo/database';
+import type { Router as ExpressRouter } from 'ultimate-express';
+import type { ConnectionOptions } from 'bullmq';
+import { type AnyComponent, type LoadedComponents } from './component_types.js';
+import { LogLevel } from '@cepseudo/shared';
+import type { QueueConfig } from './queue_manager.js';
+import { type HealthCheckFn } from './health.js';
+/**
+ * Result of component validation
+ */
+export interface ComponentValidationResult {
+    /** Component name */
+    name: string;
+    /** Component type */
+    type: 'collector' | 'harvester' | 'handler' | 'assets_manager' | 'custom_table_manager';
+    /** Validation status */
+    valid: boolean;
+    /** Validation errors if any */
+    errors: string[];
+    /** Validation warnings if any */
+    warnings: string[];
+}
+/**
+ * Overall validation result
+ */
+export interface ValidationResult {
+    /** Overall validation status */
+    valid: boolean;
+    /** Individual component results */
+    components: ComponentValidationResult[];
+    /** Engine-level errors */
+    engineErrors: string[];
+    /** Summary statistics */
+    summary: {
+        total: number;
+        valid: number;
+        invalid: number;
+        warnings: number;
+    };
+}
+/**
+ * Configuration options for the Digital Twin Engine
+ *
+ * @interface EngineOptions
+ * @example
+ * ```typescript
+ * const options: EngineOptions = {
+ *   storage: storageService,
+ *   database: databaseAdapter,
+ *   collectors: [myCollector],
+ *   harvesters: [myHarvester],
+ *   handlers: [myHandler],
+ *   server: { port: 3000, host: 'localhost' },
+ *   queues: {
+ *     multiQueue: true,
+ *     workers: { collectors: 2, harvesters: 1 }
+ *   }
+ * }
+ * ```
+ */
+export interface EngineOptions {
+    /** Array of data collectors to register with the engine */
+    collectors?: Collector[];
+    /** Array of data harvesters to register with the engine */
+    harvesters?: Harvester[];
+    /** Array of request handlers to register with the engine */
+    handlers?: Handler[];
+    /** Array of assets managers to register with the engine */
+    assetsManagers?: AssetsManager[];
+    /** Array of custom table managers to register with the engine */
+    customTableManagers?: CustomTableManager[];
+    /** Storage service instance for persisting data (required) */
+    storage: StorageService;
+    /** Database adapter instance for data operations (required) */
+    database: DatabaseAdapter;
+    /** Redis connection options for queue management */
+    redis?: ConnectionOptions;
+    /** Queue configuration options */
+    queues?: {
+        /** Enable multi-queue mode (default: true) */
+        multiQueue?: boolean;
+        /** Worker configuration for different component types */
+        workers?: {
+            /** Number of collector workers (default: 1) */
+            collectors?: number;
+            /** Number of harvester workers (default: 1) */
+            harvesters?: number;
+        };
+        /** Additional queue configuration options */
+        options?: QueueConfig['queueOptions'];
+    };
+    /** HTTP server configuration */
+    server?: {
+        /** Server port (default: 3000) */
+        port: number;
+        /** Server host (default: '0.0.0.0') */
+        host?: string;
+    };
+    /** Logging configuration */
+    logging?: {
+        /** Log level (default: LogLevel.INFO) */
+        level: LogLevel;
+        /** Log format (default: 'text') */
+        format?: 'json' | 'text';
+    };
+    /** Dry run mode - validate configuration without persisting data (default: false) */
+    dryRun?: boolean;
+    /**
+     * Enable automatic schema migration for existing tables (default: true)
+     *
+     * When enabled, the engine will automatically add missing columns with safe defaults
+     * to existing tables at startup. Only safe operations are performed:
+     * - Adding columns with DEFAULT values
+     * - Adding nullable columns
+     * - Adding indexes
+     *
+     * Set to false to require manual migrations via SQL scripts.
+     */
+    autoMigration?: boolean;
+}
+/**
+ * Digital Twin Engine - Core orchestrator for collectors, harvesters, and handlers
+ *
+ * The engine manages the lifecycle of all components, sets up queues for processing,
+ * exposes HTTP endpoints, and handles the overall coordination of the digital twin system.
+ *
+ * @class DigitalTwinEngine
+ * @example
+ * ```TypeScript
+ * import { DigitalTwinEngine } from './digital_twin_engine.js'
+ * import { StorageServiceFactory } from '../storage/storage_factory.js'
+ * import { KnexDatabaseAdapter } from '../database/adapters/knex_database_adapter.js'
+ *
+ * const storage = StorageServiceFactory.create()
+ * const database = new KnexDatabaseAdapter({ client: 'sqlite3', connection: ':memory:' }, storage)
+ *
+ * const engine = new DigitalTwinEngine({
+ *   storage,
+ *   database,
+ *   collectors: [myCollector],
+ *   server: { port: 3000 }
+ * })
+ *
+ * await engine.start()
+ * ```
+ */
+export declare class DigitalTwinEngine {
+    #private;
+    /**
+     * Creates a new Digital Twin Engine instance
+     *
+     * @param {EngineOptions} options - Configuration options for the engine
+     * @throws {Error} If required options (storage, database) are missing
+     *
+     * @example
+     * ```TypeScript
+     * const engine = new DigitalTwinEngine({
+     *   storage: myStorageService,
+     *   database: myDatabaseAdapter,
+     *   collectors: [collector1, collector2],
+     *   server: { port: 4000, host: 'localhost' }
+     * })
+     * ```
+     */
+    constructor(options: EngineOptions);
+    /**
+     * Starts the Digital Twin Engine
+     *
+     * This method:
+     * 1. Initializes all registered components (collectors, harvesters, handlers)
+     * 2. Set up HTTP endpoints for component access
+     * 3. Configures and starts background job queues
+     * 4. Starts the HTTP server
+     * 5. Exposes queue monitoring endpoints
+     *
+     * @async
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```TypeScript
+     * await engine.start()
+     * console.log('Engine is running!')
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Get the server port
+     *
+     * @returns {number | undefined} The server port or undefined if not started
+     *
+     * @example
+     * ```TypeScript
+     * const port = engine.getPort()
+     * console.log(`Server running on port ${port}`)
+     * ```
+     */
+    getPort(): number | undefined;
+    /**
+     * Returns the internal Express Router.
+     * Used by optional plugin packages to register additional routes.
+     */
+    getRouter(): ExpressRouter;
+    /**
+     * Returns the DatabaseAdapter instance.
+     * Used by optional plugin packages for their own persistence needs.
+     */
+    getDatabase(): DatabaseAdapter;
+    /**
+     * Returns the Redis connection configuration extracted from engine options.
+     * Falls back to localhost:6379 when no Redis config was provided.
+     */
+    getRedisConfig(): {
+        host: string;
+        port: number;
+        password?: string;
+    };
+    /**
+     * Returns a flat list of all components registered with the engine.
+     * Used by optional plugin packages to inspect component capabilities.
+     */
+    getAllComponents(): AnyComponent[];
+    /**
+     * Registers a single component with automatic type detection.
+     *
+     * The engine automatically detects the component type based on its class
+     * and adds it to the appropriate internal collection.
+     *
+     * @param component - Component instance to register
+     * @returns The engine instance for method chaining
+     * @throws Error if component type cannot be determined or is already registered
+     *
+     * @example
+     * ```typescript
+     * const engine = new DigitalTwinEngine({ storage, database })
+     *
+     * engine
+     *   .register(new WeatherCollector())
+     *   .register(new TrafficAnalysisHarvester())
+     *   .register(new ApiHandler())
+     *   .register(new GLTFAssetsManager())
+     *
+     * await engine.start()
+     * ```
+     */
+    register(component: AnyComponent): this;
+    /**
+     * Registers multiple components at once with automatic type detection.
+     *
+     * Useful for registering all components from a module or when loading
+     * components dynamically.
+     *
+     * @param components - Array of component instances to register
+     * @returns The engine instance for method chaining
+     * @throws Error if any component type cannot be determined or is duplicate
+     *
+     * @example
+     * ```typescript
+     * const engine = new DigitalTwinEngine({ storage, database })
+     *
+     * engine.registerAll([
+     *   new WeatherCollector(),
+     *   new TrafficCollector(),
+     *   new AnalysisHarvester(),
+     *   new ApiHandler()
+     * ])
+     *
+     * await engine.start()
+     * ```
+     */
+    registerAll(components: AnyComponent[]): this;
+    /**
+     * Registers components with explicit type specification.
+     *
+     * Provides full type safety at compile time. Use this method when you
+     * have pre-sorted components from auto-discovery or want explicit control.
+     *
+     * @param components - Object with typed component arrays
+     * @returns The engine instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const loaded = await loadComponents('./src/components')
+     *
+     * engine.registerComponents({
+     *   collectors: loaded.collectors,
+     *   harvesters: loaded.harvesters,
+     *   handlers: loaded.handlers,
+     *   assetsManagers: loaded.assetsManagers,
+     *   customTableManagers: loaded.customTableManagers
+     * })
+     * ```
+     */
+    registerComponents(components: Partial<LoadedComponents>): this;
+    /**
+     * Configure the shutdown timeout (in ms)
+     * @param timeout Timeout in milliseconds (default: 30000)
+     */
+    setShutdownTimeout(timeout: number): void;
+    /**
+     * Check if the engine is currently shutting down
+     * @returns true if shutdown is in progress
+     */
+    isShuttingDown(): boolean;
+    /**
+     * Register a custom health check
+     * @param name Unique name for the check
+     * @param checkFn Function that performs the check
+     *
+     * @example
+     * ```typescript
+     * engine.registerHealthCheck('external-api', async () => {
+     *     try {
+     *         const res = await fetch('https://api.example.com/health')
+     *         return { status: res.ok ? 'up' : 'down' }
+     *     } catch (error) {
+     *         return { status: 'down', error: error.message }
+     *     }
+     * })
+     * ```
+     */
+    registerHealthCheck(name: string, checkFn: HealthCheckFn): void;
+    /**
+     * Remove a custom health check
+     * @param name Name of the check to remove
+     * @returns true if the check was removed, false if it didn't exist
+     */
+    removeHealthCheck(name: string): boolean;
+    /**
+     * Get list of registered health check names
+     */
+    getHealthCheckNames(): string[];
+    /**
+     * Stops the Digital Twin Engine with graceful shutdown
+     *
+     * This method:
+     * 1. Prevents new work from being accepted
+     * 2. Removes all event listeners
+     * 3. Closes HTTP server
+     * 4. Drains queues and waits for active jobs
+     * 5. Closes all queue workers
+     * 6. Stops upload processor
+     * 7. Closes queue manager
+     * 8. Closes database connections
+     *
+     * @async
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```TypeScript
+     * await engine.stop()
+     * console.log('Engine stopped gracefully')
+     * ```
+     */
+    stop(): Promise<void>;
+    /**
+     * Validate the engine configuration and all components
+     *
+     * This method checks that all components are properly configured and can be initialized
+     * without actually creating tables or starting the server.
+     *
+     * @returns {Promise<ValidationResult>} Comprehensive validation results
+     *
+     * @example
+     * ```typescript
+     * const result = await engine.validateConfiguration()
+     * if (!result.valid) {
+     *   console.error('Validation errors:', result.engineErrors)
+     * }
+     * ```
+     */
+    validateConfiguration(): Promise<ValidationResult>;
+    /**
+     * Test all components by running their core methods without persistence
+     *
+     * @returns {Promise<ComponentValidationResult[]>} Test results for each component
+     *
+     * @example
+     * ```typescript
+     * const results = await engine.testComponents()
+     * results.forEach(result => {
+     *   console.log(`${result.name}: ${result.valid ? '✅' : '❌'}`)
+     * })
+     * ```
+     */
+    testComponents(): Promise<ComponentValidationResult[]>;
+}
+//# sourceMappingURL=digital_twin_engine.d.ts.map

package/dist/digital_twin_engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digital_twin_engine.d.ts","sourceRoot":"","sources":["../src/digital_twin_engine.ts"],"names":[],"mappings":"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"}