digitaltwin-core 0.6.1 → 0.7.1

package/dist/components/custom_table_manager.d.ts

@@ -0,0 +1,344 @@
+import type { Servable } from './interfaces.js';
+import type { StoreConfiguration, DataResponse } from './types.js';
+import type { DatabaseAdapter } from '../database/database_adapter.js';
+import type { HttpMethod } from '../engine/endpoints.js';
+/**
+ * Record representing a row in the custom table
+ */
+export interface CustomTableRecord {
+    id: number;
+    created_at: Date;
+    updated_at: Date;
+    [key: string]: any;
+}
+/**
+ * Query validation options
+ */
+export interface QueryValidationOptions {
+    /** Required fields that must have non-empty values */
+    required?: string[];
+    /** Custom validation function */
+    validate?: (conditions: Record<string, any>) => void;
+}
+/**
+ * Abstract base class for Custom Table Manager components in the Digital Twin framework.
+ *
+ * A CustomTableManager is responsible for:
+ * - Managing structured data in database tables with custom columns
+ * - Providing CRUD operations for the data with validation
+ * - Exposing HTTP endpoints for data manipulation
+ * - Creating and managing database schema automatically
+ *
+ * Unlike other components, CustomTableManager does NOT handle files - only structured data.
+ *
+ * @abstract
+ * @class CustomTableManager
+ * @implements {Component}
+ * @implements {Servable}
+ *
+ * @example
+ * ```typescript
+ * class WMSManager extends CustomTableManager {
+ *   getConfiguration(): StoreConfiguration {
+ *     return {
+ *       name: 'wms_layers',
+ *       description: 'Manage WMS layers for mapping',
+ *       columns: {
+ *         'wms_url': 'text not null',
+ *         'layer_name': 'text not null',
+ *         'description': 'text',
+ *         'active': 'boolean default true'
+ *       },
+ *       endpoints: [
+ *         { path: '/add-layers', method: 'post', handler: 'addLayers' }
+ *       ]
+ *     }
+ *   }
+ *
+ *   async addLayers(req: any): Promise<DataResponse> {
+ *     // Custom endpoint implementation
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Base component interface for CustomTableManager (doesn't extend ComponentConfiguration)
+ */
+export interface CustomTableComponent {
+    getConfiguration(): StoreConfiguration;
+}
+export declare abstract class CustomTableManager implements CustomTableComponent, Servable {
+    /** Database adapter for data operations */
+    protected db: DatabaseAdapter;
+    /** Cached table name from configuration */
+    protected tableName: string;
+    /**
+     * Injects required dependencies into the custom table manager instance.
+     *
+     * Called by the Digital Twin Engine during component initialization.
+     *
+     * @param {DatabaseAdapter} db - Database adapter for data operations
+     *
+     * @example
+     * ```typescript
+     * const customTableManager = new MyCustomTableManager()
+     * customTableManager.setDependencies(databaseAdapter)
+     * ```
+     */
+    setDependencies(db: DatabaseAdapter): void;
+    /**
+     * Returns the static configuration defining this custom table manager's behavior.
+     *
+     * The configuration includes the table name, description,
+     * custom columns definition, and optional custom endpoints.
+     *
+     * @abstract
+     * @returns {StoreConfiguration} The table configuration
+     *
+     * @example
+     * ```typescript
+     * getConfiguration(): StoreConfiguration {
+     *   return {
+     *     name: 'sensors',
+     *     description: 'IoT sensors data store',
+     *     columns: {
+     *       'sensor_id': 'text unique not null',
+     *       'type': 'text not null',
+     *       'location': 'text',
+     *       'active': 'boolean default true',
+     *       'last_ping': 'timestamp'
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    abstract getConfiguration(): StoreConfiguration;
+    /**
+     * Initialize the database table with custom columns.
+     *
+     * Creates the table if it doesn't exist, with standard columns (id, created_at, updated_at)
+     * plus the custom columns defined in the configuration.
+     *
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```typescript
+     * // Called automatically by the framework
+     * await customTableManager.initializeTable()
+     * ```
+     */
+    initializeTable(): Promise<void>;
+    /**
+     * Validate query conditions against requirements.
+     *
+     * @private
+     * @param {Record<string, any>} conditions - Conditions to validate
+     * @param {QueryValidationOptions} options - Validation options
+     * @throws {Error} If validation fails
+     */
+    private validateQuery;
+    /**
+     * Create a new record in the custom table.
+     *
+     * @param {Record<string, any>} data - Data to insert (excluding id, created_at, updated_at)
+     * @returns {Promise<number>} The ID of the created record
+     *
+     * @example
+     * ```typescript
+     * const id = await customTableManager.create({
+     *   sensor_id: 'TEMP001',
+     *   type: 'temperature',
+     *   location: 'Building A - Floor 1',
+     *   active: true
+     * })
+     * console.log(`Created sensor with ID: ${id}`)
+     * ```
+     */
+    create(data: Record<string, any>): Promise<number>;
+    /**
+     * Find all records in the custom table.
+     *
+     * @returns {Promise<CustomTableRecord[]>} Array of all records
+     *
+     * @example
+     * ```typescript
+     * const allSensors = await customTableManager.findAll()
+     * console.log(`Found ${allSensors.length} sensors`)
+     * ```
+     */
+    findAll(): Promise<CustomTableRecord[]>;
+    /**
+     * Find a record by its ID.
+     *
+     * @param {number} id - The record ID to find
+     * @returns {Promise<CustomTableRecord | null>} The record or null if not found
+     *
+     * @example
+     * ```typescript
+     * const sensor = await customTableManager.findById(123)
+     * if (sensor) {
+     *   console.log(`Sensor: ${sensor.sensor_id}`)
+     * }
+     * ```
+     */
+    findById(id: number): Promise<CustomTableRecord | null>;
+    /**
+     * Find records by a single column value with optional validation.
+     *
+     * @param {string} columnName - Name of the column to search by
+     * @param {any} value - Value to search for
+     * @param {boolean} required - Whether the value is required (default: true)
+     * @returns {Promise<CustomTableRecord[]>} Array of matching records
+     *
+     * @example
+     * ```typescript
+     * const wmsLayers = await wmsManager.findByColumn('wms_url', 'https://example.com/wms')
+     * const activeLayers = await wmsManager.findByColumn('active', true)
+     *
+     * // Optional value (won't throw if empty)
+     * const layers = await wmsManager.findByColumn('description', '', false)
+     * ```
+     */
+    findByColumn(columnName: string, value: any, required?: boolean): Promise<CustomTableRecord[]>;
+    /**
+     * Find records by multiple column values with validation support.
+     *
+     * @param {Record<string, any>} conditions - Key-value pairs to match
+     * @param {QueryValidationOptions} options - Validation options
+     * @returns {Promise<CustomTableRecord[]>} Array of matching records
+     *
+     * @example
+     * ```typescript
+     * // Simple query
+     * const layers = await wmsManager.findByColumns({
+     *   wms_url: 'https://example.com/wms',
+     *   active: true
+     * })
+     *
+     * // With validation
+     * const layers = await wmsManager.findByColumns(
+     *   { wms_url: wmsUrl, projection: projection },
+     *   {
+     *     required: ['wms_url', 'projection'],
+     *     validate: (conditions) => {
+     *       if (!conditions.wms_url.startsWith('http')) {
+     *         throw new Error('WMS URL must start with http or https')
+     *       }
+     *     }
+     *   }
+     * )
+     * ```
+     */
+    findByColumns(conditions: Record<string, any>, options?: QueryValidationOptions): Promise<CustomTableRecord[]>;
+    /**
+     * Find records matching specific conditions (base method).
+     *
+     * @param {Record<string, any>} conditions - Key-value pairs to match
+     * @returns {Promise<CustomTableRecord[]>} Array of matching records
+     *
+     * @example
+     * ```typescript
+     * const activeSensors = await customTableManager.findByCondition({ active: true })
+     * const tempSensors = await customTableManager.findByCondition({ type: 'temperature' })
+     * ```
+     */
+    findByCondition(conditions: Record<string, any>): Promise<CustomTableRecord[]>;
+    /**
+     * Update a record by its ID.
+     *
+     * @param {number} id - The record ID to update
+     * @param {Record<string, any>} data - Data to update (excluding id, created_at)
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```typescript
+     * await customTableManager.update(123, {
+     *   active: false,
+     *   last_ping: new Date()
+     * })
+     * ```
+     */
+    update(id: number, data: Record<string, any>): Promise<void>;
+    /**
+     * Delete a record by its ID.
+     *
+     * @param {number} id - The record ID to delete
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```typescript
+     * await customTableManager.delete(123)
+     * console.log('Sensor deleted successfully')
+     * ```
+     */
+    delete(id: number): Promise<void>;
+    /**
+     * Delete records by a single column value.
+     *
+     * @param {string} columnName - Name of the column to match for deletion
+     * @param {any} value - Value to match for deletion
+     * @returns {Promise<number>} Number of records deleted
+     *
+     * @example
+     * ```typescript
+     * const deleted = await wmsManager.deleteByColumn('active', false)
+     * console.log(`Deleted ${deleted} inactive layers`)
+     * ```
+     */
+    deleteByColumn(columnName: string, value: any): Promise<number>;
+    /**
+     * Delete records matching specific conditions.
+     *
+     * @param {Record<string, any>} conditions - Key-value pairs to match for deletion
+     * @returns {Promise<number>} Number of records deleted
+     *
+     * @example
+     * ```typescript
+     * const deleted = await customTableManager.deleteByCondition({ active: false })
+     * console.log(`Deleted ${deleted} inactive sensors`)
+     * ```
+     */
+    deleteByCondition(conditions: Record<string, any>): Promise<number>;
+    /**
+     * Extract custom fields from a database record, excluding framework fields.
+     *
+     * @private
+     * @param {any} record - Database record
+     * @returns {Record<string, any>} Custom fields only
+     */
+    private extractCustomFields;
+    /**
+     * Get HTTP endpoints exposed by this custom table manager.
+     *
+     * Returns both standard CRUD endpoints and custom endpoints defined in configuration.
+     *
+     * @returns {Array} Array of endpoint descriptors with methods, paths, and handlers
+     *
+     * @example
+     * ```typescript
+     * // Standard endpoints for a table named 'sensors':
+     * GET    /sensors         - Get all records
+     * POST   /sensors         - Create new record
+     * GET    /sensors/:id     - Get specific record
+     * PUT    /sensors/:id     - Update specific record
+     * DELETE /sensors/:id     - Delete specific record
+     *
+     * // Plus any custom endpoints defined in configuration
+     * ```
+     */
+    getEndpoints(): Array<{
+        method: HttpMethod;
+        path: string;
+        handler: (...args: any[]) => any;
+        responseType?: string;
+    }>;
+    /**
+     * Standard endpoint handlers for CRUD operations
+     */
+    handleGetAll(req: any): Promise<DataResponse>;
+    handleCreate(req: any): Promise<DataResponse>;
+    handleGetById(req: any): Promise<DataResponse>;
+    handleUpdate(req: any): Promise<DataResponse>;
+    handleDelete(req: any): Promise<DataResponse>;
+}
+//# sourceMappingURL=custom_table_manager.d.ts.map

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

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