digitaltwin-core 0.1.0

package/dist/database/database_adapter.d.ts

@@ -0,0 +1,92 @@
+import { DataRecord } from '../types/data_record.js';
+/**
+ * Structure used to store metadata about a data blob in the database.
+ *
+ * Extended to support asset-specific fields for AssetsManager components.
+ * These fields are optional and only used by AssetsManager instances.
+ */
+export interface MetadataRow {
+    /** Unique identifier of the data row */
+    id?: number;
+    /** Logical name of the data source (usually the collector name) */
+    name: string;
+    /** MIME type of the associated blob (e.g. 'application/json') */
+    type: string;
+    /** Path or URL where the blob is stored (resolved by the StorageService) */
+    url: string;
+    /** Timestamp indicating when the data was collected */
+    date: Date;
+    /** Human-readable description of the asset (AssetsManager only) */
+    description?: string;
+    /** Source URL for data provenance (AssetsManager only) */
+    source?: string;
+    /** ID of the user who owns this asset (AssetsManager only) */
+    owner_id?: string | null;
+    /** Original filename provided by the user (AssetsManager only) */
+    filename?: string;
+}
+/**
+ * Extended abstraction for the database layer with advanced querying capabilities.
+ */
+export declare abstract class DatabaseAdapter {
+    abstract save(meta: MetadataRow): Promise<DataRecord>;
+    abstract delete(id: string): Promise<void>;
+    abstract getById(id: string): Promise<DataRecord | undefined>;
+    abstract getLatestByName(name: string): Promise<DataRecord | undefined>;
+    abstract doesTableExists(name: string): Promise<boolean>;
+    abstract createTable(name: string): Promise<void>;
+    /**
+     * Get the first (oldest) record for a given component name.
+     * @param name - The component name
+     * @returns The oldest DataRecord or undefined if none found
+     */
+    abstract getFirstByName(name: string): Promise<DataRecord | undefined>;
+    /**
+     * Get records between two dates for a given component.
+     * @param name - The component name
+     * @param startDate - Start date (inclusive)
+     * @param endDate - End date (exclusive), optional
+     * @param limit - Maximum number of records to return, optional
+     * @returns Array of DataRecords matching the criteria
+     */
+    abstract getByDateRange(name: string, startDate: Date, endDate?: Date, limit?: number): Promise<DataRecord[]>;
+    /**
+     * Get records after a specific date for a given component.
+     * @param name - The component name
+     * @param afterDate - Date to search after (exclusive)
+     * @param limit - Maximum number of records to return
+     * @returns Array of DataRecords after the specified date
+     */
+    abstract getAfterDate(name: string, afterDate: Date, limit?: number): Promise<DataRecord[]>;
+    /**
+     * Get the latest record before a specific date for a given component.
+     * @param name - The component name
+     * @param beforeDate - Date to search before (exclusive)
+     * @returns The latest DataRecord before the date, or undefined if none found
+     */
+    abstract getLatestBefore(name: string, beforeDate: Date): Promise<DataRecord | undefined>;
+    /**
+     * Get the latest N records before a specific date for a given component.
+     * @param name - The component name
+     * @param beforeDate - Date to search before (exclusive)
+     * @param limit - Number of records to return
+     * @returns Array of the latest DataRecords before the date
+     */
+    abstract getLatestRecordsBefore(name: string, beforeDate: Date, limit: number): Promise<DataRecord[]>;
+    /**
+     * Check if any records exist after a specific date for a given component.
+     * @param name - The component name
+     * @param afterDate - Date to check after (exclusive)
+     * @returns True if records exist after the date, false otherwise
+     */
+    abstract hasRecordsAfterDate(name: string, afterDate: Date): Promise<boolean>;
+    /**
+     * Count records for a given component within a date range.
+     * @param name - The component name
+     * @param startDate - Start date (inclusive)
+     * @param endDate - End date (exclusive), optional
+     * @returns Number of records in the range
+     */
+    abstract countByDateRange(name: string, startDate: Date, endDate?: Date): Promise<number>;
+}
+//# sourceMappingURL=database_adapter.d.ts.map

package/dist/database/database_adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database_adapter.d.ts","sourceRoot":"","sources":["../../src/database/database_adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IACxB,wCAAwC;IACxC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAA;IACZ,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAA;IACX,uDAAuD;IACvD,IAAI,EAAE,IAAI,CAAA;IAGV,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,8BAAsB,eAAe;IAGjC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IACvE,QAAQ,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IACxD,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAEtE;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CACnB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,IAAI,EACf,OAAO,CAAC,EAAE,IAAI,EACd,KAAK,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,EAAE,CAAC;IAExB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CACjB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,IAAI,EACf,KAAK,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,EAAE,CAAC;IAExB;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CACpB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,IAAI,GACjB,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAElC;;;;;;OAMG;IACH,QAAQ,CAAC,sBAAsB,CAC3B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,IAAI,EAChB,KAAK,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,EAAE,CAAC;IAExB;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,CACxB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,IAAI,GAChB,OAAO,CAAC,OAAO,CAAC;IAEnB;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CACrB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,IAAI,EACf,OAAO,CAAC,EAAE,IAAI,GACf,OAAO,CAAC,MAAM,CAAC;CACrB"}

package/dist/database/database_adapter.js

@@ -0,0 +1,6 @@
+/**
+ * Extended abstraction for the database layer with advanced querying capabilities.
+ */
+export class DatabaseAdapter {
+}
+//# sourceMappingURL=database_adapter.js.map

package/dist/database/database_adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database_adapter.js","sourceRoot":"","sources":["../../src/database/database_adapter.ts"],"names":[],"mappings":"AAgCA;;GAEG;AACH,MAAM,OAAgB,eAAe;CA8FpC"}

package/dist/engine/digital_twin_engine.d.ts

@@ -0,0 +1,237 @@
+import { Collector } from '../components/collector.js';
+import { Harvester } from '../components/harvester.js';
+import { Handler } from '../components/handler.js';
+import { AssetsManager } from '../components/assets_manager.js';
+import { StorageService } from '../storage/storage_service.js';
+import { DatabaseAdapter } from '../database/database_adapter.js';
+import { ConnectionOptions } from 'bullmq';
+import { LogLevel } from "../utils/logger.js";
+import { 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. Closes all queue connections
+     * 3. Stops background workers
+     * 4. 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

package/dist/engine/digital_twin_engine.d.ts.map

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