digitaltwin-core
Version:
Minimalist framework to collect and handle data in a Digital Twin project
253 lines • 8.21 kB
TypeScript
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 { CustomTableManager } from '../components/custom_table_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' | '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;
/**
* 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