digitaltwin-core/dist/engine/digital_twin_engine.d.ts

Minimalist framework to collect and handle data in a Digital Twin project

import type { Collector } from '../components/collector.js';
import type { Harvester } from '../components/harvester.js';
import type { Handler } from '../components/handler.js';
import type { AssetsManager } from '../components/assets_manager.js';
import type { StorageService } from '../storage/storage_service.js';
import type { DatabaseAdapter } from '../database/database_adapter.js';
import type { ConnectionOptions } from 'bullmq';
import { LogLevel } from '../utils/logger.js';
import type { QueueConfig } from './queue_manager.js';
/**
 * Result of component validation
 */
export interface ComponentValidationResult {
    /** Component name */
    name: string;
    /** Component type */
    type: 'collector' | 'harvester' | 'handler' | 'assets_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[];
    /** 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;
}
/**
 * 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;
    /**
     * Stops the Digital Twin Engine gracefully
     *
     * This method:
     * 1. Closes HTTP server
     * 2. Stops background workers
     * 3. Closes all queue connections
     * 4. Closes database connections
     * 5. Clean up resources
     *
     * @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