digitaltwin-core 0.8.2 → 0.9.0

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"}

package/dist/env/env.d.ts

@@ -1,5 +1,45 @@
+/**
+ * @fileoverview Environment variable validation and configuration management
+ *
+ * This utility class provides type-safe environment variable parsing with
+ * validation rules for string, number, boolean, and enum types.
+ */
+/**
+ * Environment variable validation and configuration utility.
+ *
+ * The Env class provides a schema-based approach to validating and parsing
+ * environment variables with type safety and format validation.
+ *
+ * @example
+ * ```typescript
+ * const config = Env.validate({
+ *   PORT: Env.schema.number({ optional: true, default: 3000 }),
+ *   API_URL: Env.schema.string({ format: 'url' }),
+ *   DEBUG: Env.schema.boolean({ optional: true, default: false }),
+ *   NODE_ENV: Env.schema.enum(['development', 'production', 'test'])
+ * });
+ *
+ * // config is now type-safe and validated
+ * console.log(config.PORT); // number
+ * console.log(config.API_URL); // validated URL string
+ * ```
+ */
 export declare class Env {
+    /**
+     * Schema builders for different environment variable types.
+     *
+     * Provides factory methods for creating validation rules for different
+     * data types that can be parsed from environment variables.
+     */
     static schema: {
+        /**
+         * Creates a string validation rule.
+         *
+         * @param opts - Optional configuration for string validation
+         * @param opts.optional - Whether the environment variable is optional
+         * @param opts.format - Format validation ('url' or 'email')
+         * @returns String validation rule object
+         */
         string: (opts?: {
             optional?: boolean;
             format?: "url" | "email";
@@ -8,12 +48,29 @@ export declare class Env {
             format?: "url" | "email";
             type: "string";
         };
+        /**
+         * Creates a number validation rule.
+         *
+         * @param opts - Optional configuration for number validation
+         * @param opts.optional - Whether the environment variable is optional
+         * @returns Number validation rule object
+         */
         number: (opts?: {
             optional?: boolean;
         }) => {
             optional?: boolean;
             type: "number";
         };
+        /**
+         * Creates a boolean validation rule.
+         *
+         * Accepts 'true'/'false' or '1'/'0' as valid boolean values.
+         *
+         * @param opts - Optional configuration for boolean validation
+         * @param opts.optional - Whether the environment variable is optional
+         * @param opts.default - Default value if the variable is missing
+         * @returns Boolean validation rule object
+         */
         boolean: (opts?: {
             optional?: boolean;
             default?: boolean;
@@ -22,12 +79,56 @@ export declare class Env {
             default?: boolean;
             type: "boolean";
         };
+        /**
+         * Creates an enum validation rule.
+         *
+         * @template T - Array of allowed string values
+         * @param values - Array of allowed values for this environment variable
+         * @returns Enum validation rule object
+         */
         enum: <T extends string[]>(values: T) => {
             type: "enum";
             values: T;
         };
     };
+    /**
+     * Stores the last validated configuration.
+     *
+     * This static property holds the most recently validated environment
+     * configuration for reference by other parts of the application.
+     */
     static config: Record<string, any>;
+    /**
+     * Validates environment variables against a schema definition.
+     *
+     * Parses and validates environment variables according to the provided
+     * schema, returning a type-safe configuration object.
+     *
+     * @template T - The expected type of the returned configuration object
+     * @param schema - Object mapping environment variable names to validation rules
+     * @param rawEnv - Environment variables object (defaults to process.env)
+     * @returns Validated and parsed configuration object
+     *
+     * @throws {Error} When required environment variables are missing
+     * @throws {Error} When environment variables fail format validation
+     *
+     * @example
+     * ```typescript
+     * interface Config {
+     *   DATABASE_URL: string;
+     *   PORT: number;
+     *   DEBUG: boolean;
+     *   NODE_ENV: 'development' | 'production';
+     * }
+     *
+     * const config: Config = Env.validate({
+     *   DATABASE_URL: Env.schema.string({ format: 'url' }),
+     *   PORT: Env.schema.number({ optional: true }),
+     *   DEBUG: Env.schema.boolean({ optional: true, default: false }),
+     *   NODE_ENV: Env.schema.enum(['development', 'production'])
+     * });
+     * ```
+     */
     static validate<T extends Record<string, any>>(schema: Record<string, any>, rawEnv?: NodeJS.ProcessEnv): T;
 }
 //# sourceMappingURL=env.d.ts.map

package/dist/env/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/env/env.ts"],"names":[],"mappings":"AAAA,qBAAa,GAAG;IACZ,MAAM,CAAC,MAAM;wBACO;YAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;SAAE;uBAAnC,OAAO;qBAAW,KAAK,GAAG,OAAO;;;wBAK9C;YAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;SAAE;uBAAT,OAAO;;;yBAKnB;YAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;YAAC,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE;uBAA5B,OAAO;sBAAY,OAAO;;;eAKjD,CAAC,SAAS,MAAM,EAAE,UAAU,CAAC;;;;MAIvC;IAED,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAK;IAEvC,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,oBAAc,GAAG,CAAC;CA2DvG"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/env/env.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,GAAG;IACZ;;;;;OAKG;IACH,MAAM,CAAC,MAAM;QACT;;;;;;;WAOG;wBACa;YAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;SAAE;uBAAnC,OAAO;qBAAW,KAAK,GAAG,OAAO;;;QAK9D;;;;;;WAMG;wBACa;YAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;SAAE;uBAAT,OAAO;;;QAKpC;;;;;;;;;WASG;yBACc;YAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;YAAC,OAAO,CAAC,EAAE,OAAO,CAAA;SAAE;uBAA5B,OAAO;sBAAY,OAAO;;;QAKxD;;;;;;WAMG;eACI,CAAC,SAAS,MAAM,EAAE,UAAU,CAAC;;;;MAIvC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAK;IAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,oBAAc,GAAG,CAAC;CA2DvG"}