digitaltwin-core 0.8.0 → 0.8.1

package/dist/components/interfaces.d.ts

@@ -1,17 +1,125 @@
+/**
+ * @fileoverview Core interfaces defining the contract for digital twin components
+ *
+ * These interfaces establish the foundation for component architecture, scheduling,
+ * and HTTP endpoint serving capabilities within the digital twin ecosystem.
+ */
 import type { ComponentConfiguration } from './types.js';
 import type { HttpMethod } from '../engine/endpoints.js';
+/**
+ * Base interface for all digital twin components.
+ *
+ * Components are the fundamental building blocks of a digital twin system,
+ * each responsible for a specific aspect of data management or processing.
+ *
+ * @template T - The type of configuration object this component uses
+ *
+ * @example
+ * ```typescript
+ * class MyCollector implements Component<MyCollectorConfig> {
+ *   getConfiguration(): MyCollectorConfig {
+ *     return { name: 'my-collector', interval: 5000 };
+ *   }
+ * }
+ * ```
+ */
 export interface Component<T extends ComponentConfiguration = ComponentConfiguration> {
+    /**
+     * Returns the configuration object for this component.
+     *
+     * The configuration contains metadata about the component such as its name,
+     * type, scheduling information, and component-specific settings.
+     *
+     * @returns The component's configuration object
+     */
     getConfiguration(): T;
 }
+/**
+ * Interface for components that can be scheduled to run periodically.
+ *
+ * Components implementing this interface can be automatically executed
+ * by the digital twin engine's scheduler based on a cron expression.
+ *
+ * @example
+ * ```typescript
+ * class DataCollector implements ScheduleRunnable {
+ *   async run(): Promise<void> {
+ *     // Collect and process data
+ *     console.log('Collecting data...');
+ *   }
+ *
+ *   getSchedule(): string {
+ *     return '0 *.5 * * * *'; // Every 5 minutes
+ *   }
+ * }
+ * ```
+ */
 export interface ScheduleRunnable {
+    /**
+     * Executes the component's main functionality.
+     *
+     * This method is called automatically by the scheduler according to
+     * the schedule returned by getSchedule(). Implementations should handle
+     * errors appropriately and return a promise that resolves when the
+     * operation is complete.
+     *
+     * @returns A promise that resolves when the run operation completes
+     */
     run(): Promise<unknown>;
+    /**
+     * Returns the cron expression defining when this component should run.
+     *
+     * The schedule follows standard cron syntax (second minute hour day month dayOfWeek).
+     *
+     * @returns A cron expression string (e.g., '0 *.5 * * * *' for every 5 minutes)
+     */
     getSchedule(): string;
 }
+/**
+ * Interface for components that can expose HTTP endpoints.
+ *
+ * Components implementing this interface can serve HTTP requests,
+ * allowing external systems to interact with the digital twin's data
+ * and functionality through REST APIs.
+ *
+ * @example
+ * ```typescript
+ * class DataProvider implements Servable {
+ *   getEndpoints() {
+ *     return [
+ *       {
+ *         method: 'GET',
+ *         path: '/api/data',
+ *         handler: this.getData.bind(this),
+ *         responseType: 'application/json'
+ *       }
+ *     ];
+ *   }
+ *
+ *   private async getData() {
+ *     return { data: 'example' };
+ *   }
+ * }
+ * ```
+ */
 export interface Servable {
+    /**
+     * Returns an array of HTTP endpoints this component exposes.
+     *
+     * Each endpoint defines the HTTP method, URL path, handler function,
+     * and optional response content type. The digital twin engine will
+     * automatically register these endpoints with the HTTP server.
+     *
+     * @returns Array of endpoint definitions
+     */
     getEndpoints(): Array<{
+        /** HTTP method for this endpoint (GET, POST, PUT, DELETE, etc.) */
         method: HttpMethod;
+        /** URL path for this endpoint (e.g., '/api/data') */
         path: string;
+        /** Function to handle requests to this endpoint */
         handler: (...args: any[]) => any;
+        /** Optional response content type (defaults to 'application/json') */
         responseType?: string;
     }>;
 }

package/dist/components/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/components/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,sBAAsB,GAAG,sBAAsB;IAChF,gBAAgB,IAAI,CAAC,CAAA;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC7B,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IACvB,WAAW,IAAI,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,QAAQ;IACrB,YAAY,IAAI,KAAK,CAAC;QAClB,MAAM,EAAE,UAAU,CAAA;QAClB,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAA;QAChC,YAAY,CAAC,EAAE,MAAM,CAAA;KACxB,CAAC,CAAA;CACL"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/components/interfaces.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,sBAAsB,GAAG,sBAAsB;IAChF;;;;;;;OAOG;IACH,gBAAgB,IAAI,CAAC,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;;;;;OASG;IACH,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IAEvB;;;;;;OAMG;IACH,WAAW,IAAI,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,QAAQ;IACrB;;;;;;;;OAQG;IACH,YAAY,IAAI,KAAK,CAAC;QAClB,mEAAmE;QACnE,MAAM,EAAE,UAAU,CAAA;QAClB,qDAAqD;QACrD,IAAI,EAAE,MAAM,CAAA;QACZ,mDAAmD;QACnD,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAA;QAChC,sEAAsE;QACtE,YAAY,CAAC,EAAE,MAAM,CAAA;KACxB,CAAC,CAAA;CACL"}

package/dist/components/interfaces.js

@@ -1,2 +1,8 @@
+/**
+ * @fileoverview Core interfaces defining the contract for digital twin components
+ *
+ * These interfaces establish the foundation for component architecture, scheduling,
+ * and HTTP endpoint serving capabilities within the digital twin ecosystem.
+ */
 export {};
 //# sourceMappingURL=interfaces.js.map

package/dist/components/interfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/components/interfaces.ts"],"names":[],"mappings":""}
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/components/interfaces.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/engine/endpoints.d.ts

@@ -1,8 +1,47 @@
+/**
+ * @fileoverview HTTP endpoint exposure utilities for digital twin components
+ *
+ * This module handles the automatic registration of HTTP endpoints from servable
+ * components to the Express router, enabling RESTful API access to digital twin data.
+ */
 import type { Router } from 'ultimate-express';
 import type { Collector } from '../components/collector.js';
 import type { Harvester } from '../components/harvester.js';
 import type { Handler } from '../components/handler.js';
 import type { AssetsManager, CustomTableManager } from '../components/index.js';
+/**
+ * Supported HTTP methods for component endpoints.
+ *
+ * These methods correspond to standard REST operations:
+ * - get: Retrieve data
+ * - post: Create new resources
+ * - put: Update existing resources (full update)
+ * - patch: Update existing resources (partial update)
+ * - delete: Remove resources
+ */
 export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch';
+/**
+ * Automatically registers HTTP endpoints from servable components to an Express router.
+ *
+ * This function iterates through all provided components, extracts their endpoints,
+ * and registers them with the Express router. Each endpoint is wrapped with error
+ * handling to ensure robust API behavior.
+ *
+ * @param router - Express router instance to register endpoints with
+ * @param servables - Array of components that expose HTTP endpoints
+ *
+ * @throws {Error} When an unsupported HTTP method is encountered
+ *
+ * @example
+ * ```typescript
+ * const router = express.Router();
+ * const components = [collector1, harvester1, assetsManager1];
+ *
+ * await exposeEndpoints(router, components);
+ *
+ * // Now the router has all endpoints from the components registered
+ * app.use('/api', router);
+ * ```
+ */
 export declare function exposeEndpoints(router: Router, servables: Array<Collector | Harvester | Handler | AssetsManager | CustomTableManager>): Promise<void>;
 //# sourceMappingURL=endpoints.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/engine/endpoints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAE/E,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAA;AASpE,wBAAsB,eAAe,CACjC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,GAAG,kBAAkB,CAAC,GACvF,OAAO,CAAC,IAAI,CAAC,CAqBf"}
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/engine/endpoints.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAE/E;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAA;AAsBpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CACjC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,GAAG,kBAAkB,CAAC,GACvF,OAAO,CAAC,IAAI,CAAC,CAyBf"}

package/dist/engine/endpoints.js

@@ -1,9 +1,39 @@
+/**
+ * @fileoverview HTTP endpoint exposure utilities for digital twin components
+ *
+ * This module handles the automatic registration of HTTP endpoints from servable
+ * components to the Express router, enabling RESTful API access to digital twin data.
+ */
+/**
+ * Automatically registers HTTP endpoints from servable components to an Express router.
+ *
+ * This function iterates through all provided components, extracts their endpoints,
+ * and registers them with the Express router. Each endpoint is wrapped with error
+ * handling to ensure robust API behavior.
+ *
+ * @param router - Express router instance to register endpoints with
+ * @param servables - Array of components that expose HTTP endpoints
+ *
+ * @throws {Error} When an unsupported HTTP method is encountered
+ *
+ * @example
+ * ```typescript
+ * const router = express.Router();
+ * const components = [collector1, harvester1, assetsManager1];
+ *
+ * await exposeEndpoints(router, components);
+ *
+ * // Now the router has all endpoints from the components registered
+ * app.use('/api', router);
+ * ```
+ */
 export async function exposeEndpoints(router, servables) {
     for (const servable of servables) {
         const endpoints = servable.getEndpoints();
         for (const ep of endpoints) {
             const method = ep.method.toLowerCase();
             if (typeof router[method] === 'function') {
+                // Register endpoint with error handling wrapper
                 router[method](ep.path, async (req, res) => {
                     try {
                         const result = await ep.handler(req);
@@ -12,6 +42,7 @@ export async function exposeEndpoints(router, servables) {
                             .send(result.content);
                     }
                     catch {
+                        // Generic error response to avoid exposing internal details
                         res.status(500).send({ error: 'Internal server error' });
                     }
                 });

package/dist/engine/endpoints.js.map

@@ -1 +1 @@
-{"version":3,"file":"endpoints.js","sourceRoot":"","sources":["../../src/engine/endpoints.ts"],"names":[],"mappings":"AAgBA,MAAM,CAAC,KAAK,UAAU,eAAe,CACjC,MAAc,EACd,SAAsF;IAEtF,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAe,QAAQ,CAAC,YAAY,EAAE,CAAA;QACrD,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,EAAgB,CAAA;YACpD,IAAI,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,UAAU,EAAE,CAAC;gBACvC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;oBAC1D,IAAI,CAAC;wBACD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;wBACpC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;6BACpB,MAAM,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;6BAC5B,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;oBAC7B,CAAC;oBAAC,MAAM,CAAC;wBACL,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,CAAA;oBAC5D,CAAC;gBACL,CAAC,CAAC,CAAA;YACN,CAAC;iBAAM,CAAC;gBACJ,MAAM,IAAI,KAAK,CAAC,4BAA4B,EAAE,CAAC,MAAM,EAAE,CAAC,CAAA;YAC5D,CAAC;QACL,CAAC;IACL,CAAC;AACL,CAAC"}
+{"version":3,"file":"endpoints.js","sourceRoot":"","sources":["../../src/engine/endpoints.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyCH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACjC,MAAc,EACd,SAAsF;IAEtF,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAe,QAAQ,CAAC,YAAY,EAAE,CAAA;QAErD,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,EAAgB,CAAA;YAEpD,IAAI,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,UAAU,EAAE,CAAC;gBACvC,gDAAgD;gBAChD,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;oBAC1D,IAAI,CAAC;wBACD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;wBACpC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;6BACpB,MAAM,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;6BAC5B,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;oBAC7B,CAAC;oBAAC,MAAM,CAAC;wBACL,4DAA4D;wBAC5D,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,CAAA;oBAC5D,CAAC;gBACL,CAAC,CAAC,CAAA;YACN,CAAC;iBAAM,CAAC;gBACJ,MAAM,IAAI,KAAK,CAAC,4BAA4B,EAAE,CAAC,MAAM,EAAE,CAAC,CAAA;YAC5D,CAAC;QACL,CAAC;IACL,CAAC;AACL,CAAC"}

package/dist/engine/events.d.ts

@@ -1,13 +1,93 @@
+/**
+ * @fileoverview Event system for digital twin engine component communication
+ *
+ * This module provides a centralized event bus for components to communicate
+ * asynchronously about their execution status and data processing events.
+ */
 import { EventEmitter } from 'events';
+/**
+ * Interface representing an event emitted by digital twin components.
+ *
+ * Component events provide information about component execution lifecycle,
+ * allowing other parts of the system to react to component state changes.
+ *
+ * @example
+ * ```typescript
+ * const event: ComponentEvent = {
+ *   type: 'collector:completed',
+ *   componentName: 'weather-data-collector',
+ *   timestamp: new Date(),
+ *   data: { recordsProcessed: 150 }
+ * };
+ * ```
+ */
 export interface ComponentEvent {
+    /** The type of event that occurred */
     type: 'collector:completed' | 'harvester:completed';
+    /** Name of the component that emitted this event */
     componentName: string;
+    /** Timestamp when the event occurred */
     timestamp: Date;
+    /** Optional additional data related to the event */
     data?: any;
 }
+/**
+ * Enhanced event bus for digital twin engine component communication.
+ *
+ * Extends Node.js EventEmitter to provide type-safe event handling
+ * for component lifecycle events. All components can emit events
+ * to notify other parts of the system about their execution status.
+ *
+ * @example
+ * ```typescript
+ * // Listen for collector completion events
+ * engineEventBus.on('collector:completed', (event) => {
+ *   console.log(`Collector ${event.componentName} completed at ${event.timestamp}`);
+ * });
+ *
+ * // Emit an event from a component
+ * engineEventBus.emit('collector:completed', {
+ *   type: 'collector:completed',
+ *   componentName: 'my-collector',
+ *   timestamp: new Date(),
+ *   data: { success: true }
+ * });
+ * ```
+ */
 export declare class EngineEventBus extends EventEmitter {
+    /**
+     * Emits a component event to all registered listeners.
+     *
+     * @param event - The event name/type to emit
+     * @param data - The component event data
+     * @returns True if the event had listeners, false otherwise
+     */
     emit(event: string, data: ComponentEvent): boolean;
+    /**
+     * Registers a listener for component events.
+     *
+     * @param event - The event name/type to listen for
+     * @param listener - Function to call when the event is emitted
+     * @returns This event bus instance for method chaining
+     */
     on(event: string, listener: (data: ComponentEvent) => void): this;
 }
+/**
+ * Global event bus instance for the digital twin engine.
+ *
+ * This singleton provides a centralized communication channel
+ * for all components within the digital twin system.
+ *
+ * @example
+ * ```typescript
+ * // Listen for all collector events
+ * engineEventBus.on('collector:completed', (event) => {
+ *   console.log(`Collector completed: ${event.componentName}`);
+ * });
+ *
+ * // Components emit events through this bus
+ * engineEventBus.emit('collector:completed', eventData);
+ * ```
+ */
 export declare const engineEventBus: EngineEventBus;
 //# sourceMappingURL=events.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/engine/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAErC,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,qBAAqB,GAAG,qBAAqB,CAAA;IACnD,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,IAAI,CAAA;IACf,IAAI,CAAC,EAAE,GAAG,CAAA;CACb;AAED,qBAAa,cAAe,SAAQ,YAAY;IAC5C,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO;IAIlD,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI;CAGpE;AAED,eAAO,MAAM,cAAc,gBAAuB,CAAA"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/engine/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAErC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC3B,sCAAsC;IACtC,IAAI,EAAE,qBAAqB,GAAG,qBAAqB,CAAA;IAEnD,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAA;IAErB,wCAAwC;IACxC,SAAS,EAAE,IAAI,CAAA;IAEf,oDAAoD;IACpD,IAAI,CAAC,EAAE,GAAG,CAAA;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC5C;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO;IAIlD;;;;;;OAMG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI;CAGpE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,gBAAuB,CAAA"}

package/dist/engine/events.js

@@ -1,11 +1,71 @@
+/**
+ * @fileoverview Event system for digital twin engine component communication
+ *
+ * This module provides a centralized event bus for components to communicate
+ * asynchronously about their execution status and data processing events.
+ */
 import { EventEmitter } from 'events';
+/**
+ * Enhanced event bus for digital twin engine component communication.
+ *
+ * Extends Node.js EventEmitter to provide type-safe event handling
+ * for component lifecycle events. All components can emit events
+ * to notify other parts of the system about their execution status.
+ *
+ * @example
+ * ```typescript
+ * // Listen for collector completion events
+ * engineEventBus.on('collector:completed', (event) => {
+ *   console.log(`Collector ${event.componentName} completed at ${event.timestamp}`);
+ * });
+ *
+ * // Emit an event from a component
+ * engineEventBus.emit('collector:completed', {
+ *   type: 'collector:completed',
+ *   componentName: 'my-collector',
+ *   timestamp: new Date(),
+ *   data: { success: true }
+ * });
+ * ```
+ */
 export class EngineEventBus extends EventEmitter {
+    /**
+     * Emits a component event to all registered listeners.
+     *
+     * @param event - The event name/type to emit
+     * @param data - The component event data
+     * @returns True if the event had listeners, false otherwise
+     */
     emit(event, data) {
         return super.emit(event, data);
     }
+    /**
+     * Registers a listener for component events.
+     *
+     * @param event - The event name/type to listen for
+     * @param listener - Function to call when the event is emitted
+     * @returns This event bus instance for method chaining
+     */
     on(event, listener) {
         return super.on(event, listener);
     }
 }
+/**
+ * Global event bus instance for the digital twin engine.
+ *
+ * This singleton provides a centralized communication channel
+ * for all components within the digital twin system.
+ *
+ * @example
+ * ```typescript
+ * // Listen for all collector events
+ * engineEventBus.on('collector:completed', (event) => {
+ *   console.log(`Collector completed: ${event.componentName}`);
+ * });
+ *
+ * // Components emit events through this bus
+ * engineEventBus.emit('collector:completed', eventData);
+ * ```
+ */
 export const engineEventBus = new EngineEventBus();
 //# sourceMappingURL=events.js.map

package/dist/engine/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/engine/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AASrC,MAAM,OAAO,cAAe,SAAQ,YAAY;IAC5C,IAAI,CAAC,KAAa,EAAE,IAAoB;QACpC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IAClC,CAAC;IAED,EAAE,CAAC,KAAa,EAAE,QAAwC;QACtD,OAAO,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IACpC,CAAC;CACJ;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,cAAc,EAAE,CAAA"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/engine/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAgCrC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,cAAe,SAAQ,YAAY;IAC5C;;;;;;OAMG;IACH,IAAI,CAAC,KAAa,EAAE,IAAoB;QACpC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IAClC,CAAC;IAED;;;;;;OAMG;IACH,EAAE,CAAC,KAAa,EAAE,QAAwC;QACtD,OAAO,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IACpC,CAAC;CACJ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,cAAc,EAAE,CAAA"}

package/dist/engine/initializer.d.ts

@@ -1,8 +1,59 @@
+/**
+ * @fileoverview Component initialization utilities for the digital twin engine
+ *
+ * This module handles the setup and initialization of digital twin components,
+ * including database table creation and dependency injection.
+ */
 import type { Collector } from '../components/collector.js';
 import type { Harvester } from '../components/harvester.js';
 import type { AssetsManager } from '../components/assets_manager.js';
 import type { DatabaseAdapter } from '../database/database_adapter.js';
 import type { StorageService } from '../storage/storage_service.js';
+/**
+ * Initializes data collection and processing components with required dependencies.
+ *
+ * This function sets up collectors and harvesters by:
+ * 1. Creating necessary database tables for each component
+ * 2. Injecting database and storage service dependencies
+ *
+ * @param components - Array of collectors and harvesters to initialize
+ * @param database - Database adapter instance for data storage
+ * @param storage - Storage service instance for file operations
+ *
+ * @throws {Error} When database table creation fails
+ *
+ * @example
+ * ```typescript
+ * const components = [weatherCollector, trafficHarvester];
+ * const database = new KnexDatabaseAdapter(config);
+ * const storage = new LocalStorageService();
+ *
+ * await initializeComponents(components, database, storage);
+ * // Components are now ready to process data
+ * ```
+ */
 export declare function initializeComponents(components: Array<Collector | Harvester>, database: DatabaseAdapter, storage: StorageService): Promise<void>;
+/**
+ * Initializes asset management components with required dependencies.
+ *
+ * Asset managers handle file-based resources (like 3D models, tilesets, maps)
+ * and require both database access for metadata and storage for file operations.
+ *
+ * @param assetsManagers - Array of asset managers to initialize
+ * @param database - Database adapter instance for metadata storage
+ * @param storage - Storage service instance for asset file operations
+ *
+ * @throws {Error} When database table creation fails
+ *
+ * @example
+ * ```typescript
+ * const managers = [tilesetManager, pointCloudManager];
+ * const database = new KnexDatabaseAdapter(config);
+ * const storage = new OvhS3StorageService(credentials);
+ *
+ * await initializeAssetsManagers(managers, database, storage);
+ * // Asset managers are now ready to handle file operations
+ * ```
+ */
 export declare function initializeAssetsManagers(assetsManagers: AssetsManager[], database: DatabaseAdapter, storage: StorageService): Promise<void>;
 //# sourceMappingURL=initializer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"initializer.d.ts","sourceRoot":"","sources":["../../src/engine/initializer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAEnE,wBAAsB,oBAAoB,CACtC,UAAU,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC,EACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,cAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,wBAAwB,CAC1C,cAAc,EAAE,aAAa,EAAE,EAC/B,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,cAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"initializer.d.ts","sourceRoot":"","sources":["../../src/engine/initializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAEnE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACtC,UAAU,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC,EACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,cAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,wBAAwB,CAC1C,cAAc,EAAE,aAAa,EAAE,EAC/B,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,cAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/engine/initializer.js

@@ -1,3 +1,32 @@
+/**
+ * @fileoverview Component initialization utilities for the digital twin engine
+ *
+ * This module handles the setup and initialization of digital twin components,
+ * including database table creation and dependency injection.
+ */
+/**
+ * Initializes data collection and processing components with required dependencies.
+ *
+ * This function sets up collectors and harvesters by:
+ * 1. Creating necessary database tables for each component
+ * 2. Injecting database and storage service dependencies
+ *
+ * @param components - Array of collectors and harvesters to initialize
+ * @param database - Database adapter instance for data storage
+ * @param storage - Storage service instance for file operations
+ *
+ * @throws {Error} When database table creation fails
+ *
+ * @example
+ * ```typescript
+ * const components = [weatherCollector, trafficHarvester];
+ * const database = new KnexDatabaseAdapter(config);
+ * const storage = new LocalStorageService();
+ *
+ * await initializeComponents(components, database, storage);
+ * // Components are now ready to process data
+ * ```
+ */
 export async function initializeComponents(components, database, storage) {
     for (const comp of components) {
         const config = comp.getConfiguration();
@@ -5,6 +34,28 @@ export async function initializeComponents(components, database, storage) {
         comp.setDependencies(database, storage);
     }
 }
+/**
+ * Initializes asset management components with required dependencies.
+ *
+ * Asset managers handle file-based resources (like 3D models, tilesets, maps)
+ * and require both database access for metadata and storage for file operations.
+ *
+ * @param assetsManagers - Array of asset managers to initialize
+ * @param database - Database adapter instance for metadata storage
+ * @param storage - Storage service instance for asset file operations
+ *
+ * @throws {Error} When database table creation fails
+ *
+ * @example
+ * ```typescript
+ * const managers = [tilesetManager, pointCloudManager];
+ * const database = new KnexDatabaseAdapter(config);
+ * const storage = new OvhS3StorageService(credentials);
+ *
+ * await initializeAssetsManagers(managers, database, storage);
+ * // Asset managers are now ready to handle file operations
+ * ```
+ */
 export async function initializeAssetsManagers(assetsManagers, database, storage) {
     for (const manager of assetsManagers) {
         const config = manager.getConfiguration();
@@ -12,6 +63,27 @@ export async function initializeAssetsManagers(assetsManagers, database, storage
         manager.setDependencies(database, storage);
     }
 }
+/**
+ * Ensures a database table exists for the specified component.
+ *
+ * Checks if a table exists in the database and creates it if missing.
+ * This function is called during component initialization to ensure
+ * each component has its required storage table available.
+ *
+ * @param database - Database adapter to check/create table with
+ * @param tableName - Name of the table to ensure exists
+ *
+ * @throws {Error} When table creation fails
+ *
+ * @example
+ * ```typescript
+ * // Internal usage during component initialization
+ * await ensureTableExists(database, 'weather_data_collector');
+ * // Table now exists and is ready for use
+ * ```
+ *
+ * @internal This function is used internally by initialization functions
+ */
 async function ensureTableExists(database, tableName) {
     const exists = await database.doesTableExists(tableName);
     if (!exists) {

package/dist/engine/initializer.js.map

@@ -1 +1 @@
-{"version":3,"file":"initializer.js","sourceRoot":"","sources":["../../src/engine/initializer.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACtC,UAAwC,EACxC,QAAyB,EACzB,OAAuB;IAEvB,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAA;QACtC,MAAM,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;QAC9C,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC3C,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC1C,cAA+B,EAC/B,QAAyB,EACzB,OAAuB;IAEvB,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAA;QACzC,MAAM,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;QAC9C,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC9C,CAAC;AACL,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,QAAyB,EAAE,SAAiB;IACzE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,eAAe,CAAC,SAAS,CAAC,CAAA;IACxD,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,OAAO,CAAC,GAAG,CAAC,iCAAiC,SAAS,MAAM,CAAC,CAAA;QAC7D,MAAM,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,CAAA;QACrC,OAAO,CAAC,GAAG,CAAC,YAAY,SAAS,wBAAwB,CAAC,CAAA;IAC9D,CAAC;AACL,CAAC"}
+{"version":3,"file":"initializer.js","sourceRoot":"","sources":["../../src/engine/initializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACtC,UAAwC,EACxC,QAAyB,EACzB,OAAuB;IAEvB,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAA;QACtC,MAAM,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;QAC9C,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC3C,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC1C,cAA+B,EAC/B,QAAyB,EACzB,OAAuB;IAEvB,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAA;QACzC,MAAM,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;QAC9C,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC9C,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,KAAK,UAAU,iBAAiB,CAAC,QAAyB,EAAE,SAAiB;IACzE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,eAAe,CAAC,SAAS,CAAC,CAAA;IACxD,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,OAAO,CAAC,GAAG,CAAC,iCAAiC,SAAS,MAAM,CAAC,CAAA;QAC7D,MAAM,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,CAAA;QACrC,OAAO,CAAC,GAAG,CAAC,YAAY,SAAS,wBAAwB,CAAC,CAAA;IAC9D,CAAC;AACL,CAAC"}