digitaltwin-core 0.14.2 → 1.0.0

package/dist/components/harvester.js

@@ -0,0 +1,406 @@
+import { StorageError } from '../errors/index.js';
+import { Logger } from '../utils/logger.js';
+/**
+ * Utility class for parsing harvester source range configurations.
+ *
+ * Handles conversion of various source range formats (time-based like '1h', '30m'
+ * or count-based like '100') into structured date ranges for data retrieval.
+ *
+ * @example
+ * ```typescript
+ * // Parse time-based range: get data from last hour
+ * const result = SourceRangeParser.parseSourceRange(new Date(), '1h');
+ *
+ * // Parse count-based range: get last 50 records
+ * const result = SourceRangeParser.parseSourceRange(new Date(), 50);
+ * ```
+ */
+class SourceRangeParser {
+    static { this.ZERO_DATE = new Date('1970-01-01T00:00:00Z'); }
+    /**
+     * Gets the zero date used as fallback for empty datasets.
+     *
+     * @returns Unix epoch date (1970-01-01T00:00:00Z)
+     */
+    static get zeroDate() {
+        return new Date(this.ZERO_DATE);
+    }
+    /**
+     * Parses source range configuration into a structured result.
+     *
+     * @param latestDate - The latest date in the existing data
+     * @param sourceRange - Range specification (e.g., '1h', '30m', '7d', or number for count)
+     * @returns Parsed range result with start/end dates or record limit
+     *
+     * @throws {Error} When source range format is invalid
+     */
+    static parseSourceRange(latestDate, sourceRange) {
+        if (!sourceRange) {
+            return { startDate: latestDate, limit: 1 };
+        }
+        // If it's a number or numeric string (limit mode)
+        if (typeof sourceRange === 'number' || /^\d+$/.test(sourceRange)) {
+            return { startDate: latestDate, limit: Number(sourceRange) };
+        }
+        const sourceRangeStr = sourceRange.toString();
+        let value;
+        let unit;
+        // Parse time-based ranges
+        if (sourceRangeStr.includes('d')) {
+            value = parseInt(sourceRangeStr.replace('d', ''));
+            unit = 'days';
+        }
+        else if (sourceRangeStr.includes('h')) {
+            value = parseInt(sourceRangeStr.replace('h', ''));
+            unit = 'hours';
+        }
+        else if (sourceRangeStr.includes('m')) {
+            value = parseInt(sourceRangeStr.replace('m', ''));
+            unit = 'minutes';
+        }
+        else if (sourceRangeStr.includes('s')) {
+            value = parseInt(sourceRangeStr.replace('s', ''));
+            unit = 'seconds';
+        }
+        else {
+            throw new Error(`Invalid source range format: ${sourceRange}`);
+        }
+        // For time-based ranges, start from latestDate and go forward
+        const startDate = latestDate;
+        const endDate = this.addTime(startDate, value, unit);
+        return { startDate, endDate };
+    }
+    /**
+     * Adds time to a date based on the specified unit.
+     *
+     * @param date - Base date to add time to
+     * @param value - Amount of time to add
+     * @param unit - Time unit ('days', 'hours', 'minutes', 'seconds')
+     * @returns New date with added time
+     */
+    static addTime(date, value, unit) {
+        const result = new Date(date);
+        switch (unit) {
+            case 'days':
+                result.setDate(result.getDate() + value);
+                break;
+            case 'hours':
+                result.setHours(result.getHours() + value);
+                break;
+            case 'minutes':
+                result.setMinutes(result.getMinutes() + value);
+                break;
+            case 'seconds':
+                result.setSeconds(result.getSeconds() + value);
+                break;
+        }
+        return result;
+    }
+}
+/**
+ * Abstract base class for data harvesting components.
+ *
+ * Harvesters process and analyze data that has been collected by Collectors,
+ * applying transformations, aggregations, or other data processing operations.
+ * They can be triggered by new source data or run on a schedule.
+ *
+ * Key features:
+ * - Process existing collected data with configurable ranges
+ * - Support both time-based and count-based data retrieval
+ * - Can be triggered by source data changes or scheduled execution
+ * - Provide HTTP endpoints for accessing processed results
+ *
+ * @example
+ * ```typescript
+ * class TrafficAnalysisHarvester extends Harvester {
+ *   getUserConfiguration() {
+ *     return {
+ *       name: 'traffic-analysis',
+ *       type: 'harvester',
+ *       source: 'traffic-collector',
+ *       source_range: '1h', // Process last hour of data
+ *       schedule: '0 *\/15 * * * *' // Run every 15 minutes
+ *     };
+ *   }
+ *
+ *   async harvest(data: DataRecord[]): Promise<DataRecord[]> {
+ *     // Process traffic data and return analysis results
+ *     return this.analyzeTrafficPatterns(data);
+ *   }
+ * }
+ * ```
+ */
+export class Harvester {
+    /**
+     * Injects database and storage dependencies into the harvester.
+     *
+     * Called during component initialization to provide access to
+     * data storage and file operations.
+     *
+     * @param db - Database adapter for reading source data
+     * @param storage - Storage service for file operations
+     */
+    setDependencies(db, storage) {
+        this.db = db;
+        this.storage = storage;
+    }
+    /**
+     * Returns the complete harvester configuration with defaults applied.
+     *
+     * Merges user configuration with sensible defaults for optional settings.
+     * This final configuration is used by the engine and scheduler.
+     *
+     * @returns Complete configuration with all defaults applied
+     */
+    getConfiguration() {
+        if (this._configCache) {
+            return this._configCache;
+        }
+        const userConfig = this.getUserConfiguration();
+        // Apply defaults first, then user config
+        const defaults = {
+            triggerMode: 'on-source',
+            source_range: 1,
+            multiple_results: false,
+            source_range_min: false,
+            debounceMs: 1000,
+            dependencies: [],
+            dependenciesLimit: []
+        };
+        this._configCache = {
+            ...defaults,
+            ...userConfig
+        };
+        return this._configCache;
+    }
+    /**
+     * Returns the cron schedule for this harvester.
+     *
+     * For 'on-source' trigger mode, returns empty string (no schedule).
+     * For 'scheduled' mode, uses the provided schedule or defaults to every minute.
+     *
+     * @returns Cron expression string or empty string for source-triggered mode
+     */
+    getSchedule() {
+        const config = this.getConfiguration();
+        if (config.triggerMode === 'on-source') {
+            return '';
+        }
+        // Default to every minute instead of every second
+        return '0 * * * * *';
+    }
+    /**
+     * Main execution method for the harvester.
+     *
+     * Orchestrates the harvesting process by:
+     * 1. Determining the date range for data retrieval
+     * 2. Fetching source and dependency data
+     * 3. Calling the harvest method with the data
+     * 4. Storing the results in the database
+     *
+     * @returns True if harvesting was successful, false if no data to process
+     *
+     * @throws {Error} When source component is not specified
+     * @throws {Error} When data processing fails
+     */
+    async run() {
+        const config = this.getConfiguration();
+        const logger = new Logger(`Harvester:${config.name}`);
+        if (!config.source) {
+            throw new Error(`Harvester ${config.name} must specify a source component`);
+        }
+        try {
+            // Get the latest harvested date
+            const latestHarvestedRecord = await this.db.getLatestByName(config.name);
+            // Calculate the starting point for harvesting
+            let latestDate;
+            if (!latestHarvestedRecord) {
+                // First run - get first source record and start from one second before
+                const firstSourceRecord = await this.db.getFirstByName(config.source);
+                if (!firstSourceRecord) {
+                    return false;
+                }
+                latestDate = new Date(firstSourceRecord.date.getTime() - 1000);
+            }
+            else {
+                latestDate = latestHarvestedRecord.date;
+            }
+            // Parse source range
+            const { startDate, endDate, limit } = SourceRangeParser.parseSourceRange(latestDate, config.source_range);
+            // Get source data based on range
+            const sourceData = await this.getSourceData(config.source, startDate, endDate, limit);
+            if (!sourceData || sourceData.length === 0) {
+                return false;
+            }
+            // Check if we have enough data (strict mode)
+            if (limit && config.source_range_min && sourceData.length < limit) {
+                return false;
+            }
+            // Calculate storage date
+            const storageDate = endDate || sourceData[sourceData.length - 1].date;
+            // Prepare source data for harvesting
+            const sourceForHarvesting = limit === 1 && !endDate ? sourceData[0] : sourceData;
+            // Get dependencies data
+            const dependenciesData = await this.getDependenciesData(config.dependencies || [], config.dependenciesLimit || [], storageDate);
+            // Execute harvesting
+            const result = await this.harvest(sourceForHarvesting, dependenciesData);
+            // Store results
+            await this.storeResults(config, result, sourceData, storageDate);
+            return true;
+        }
+        catch (error) {
+            logger.error(`Harvester execution failed: ${error instanceof Error ? error.message : String(error)}`, {
+                harvesterName: config.name,
+                source: config.source,
+                stack: error instanceof Error ? error.stack : undefined
+            });
+            throw new StorageError(`Harvester ${config.name} execution failed: ${error instanceof Error ? error.message : String(error)}`, { harvesterName: config.name, source: config.source });
+        }
+    }
+    /**
+     * HTTP endpoints
+     */
+    getEndpoints() {
+        return [
+            {
+                method: 'get',
+                path: `/${this.getConfiguration().endpoint}`,
+                handler: this.retrieve.bind(this),
+                responseType: this.getConfiguration().contentType
+            }
+        ];
+    }
+    /**
+     * Retrieve latest harvested data
+     */
+    async retrieve() {
+        const config = this.getConfiguration();
+        const record = await this.db.getLatestByName(config.name);
+        if (!record) {
+            return {
+                status: 404,
+                content: 'No data available'
+            };
+        }
+        const blob = await record.data();
+        return {
+            status: 200,
+            content: blob,
+            headers: { 'Content-Type': record.contentType }
+        };
+    }
+    /**
+     * Get source data within the specified range
+     */
+    async getSourceData(sourceName, startDate, endDate, limit) {
+        let sourceData;
+        if (endDate) {
+            // Time-based range: get records between startDate and endDate
+            sourceData = await this.db.getByDateRange(sourceName, startDate, endDate, limit);
+        }
+        else if (limit) {
+            // Count-based: get records after startDate with limit
+            sourceData = await this.db.getAfterDate(sourceName, startDate, limit);
+        }
+        else {
+            // Default: get latest record after startDate
+            sourceData = await this.db.getAfterDate(sourceName, startDate, 1);
+        }
+        return sourceData;
+    }
+    /**
+     * Get data from dependent components
+     */
+    async getDependenciesData(dependencies, dependenciesLimit, storageDate) {
+        const dependenciesData = {};
+        for (let i = 0; i < dependencies.length; i++) {
+            const dependency = dependencies[i];
+            const limit = dependenciesLimit[i] || 1;
+            if (limit === 1) {
+                // Get single latest record before storage date
+                const dependencyRecord = await this.db.getLatestBefore(dependency, storageDate);
+                dependenciesData[dependency] = dependencyRecord || null;
+            }
+            else {
+                // Get multiple latest records before storage date
+                const dependencyRecords = await this.db.getLatestRecordsBefore(dependency, storageDate, limit);
+                dependenciesData[dependency] = dependencyRecords.length > 0 ? dependencyRecords : null;
+            }
+        }
+        return dependenciesData;
+    }
+    /**
+     * Store harvesting results
+     */
+    async storeResults(config, result, sourceData, storageDate) {
+        if (config.multiple_results && Array.isArray(result) && Array.isArray(sourceData)) {
+            // Store each result with its corresponding source date
+            for (let i = 0; i < result.length; i++) {
+                const item = result[i];
+                const source = sourceData[i];
+                const url = await this.storage.save(item, config.name);
+                await this.db.save({
+                    name: config.name,
+                    type: config.contentType,
+                    url,
+                    date: source.date
+                });
+            }
+        }
+        else {
+            // Store single result
+            const buffer = Array.isArray(result) ? result[0] : result;
+            const url = await this.storage.save(buffer, config.name);
+            await this.db.save({
+                name: config.name,
+                type: config.contentType,
+                url,
+                date: storageDate
+            });
+        }
+    }
+    /**
+     * Returns the OpenAPI specification for this harvester's endpoints.
+     *
+     * Generates documentation for the GET endpoint that retrieves harvested data.
+     * Can be overridden by subclasses for more detailed specifications.
+     *
+     * @returns {OpenAPIComponentSpec} OpenAPI paths, tags, and schemas for this harvester
+     */
+    getOpenAPISpec() {
+        const config = this.getConfiguration();
+        const path = `/${config.endpoint}`;
+        const tagName = config.tags?.[0] || config.name;
+        return {
+            paths: {
+                [path]: {
+                    get: {
+                        summary: `Get ${config.name} harvested data`,
+                        description: config.description,
+                        tags: [tagName],
+                        responses: {
+                            '200': {
+                                description: 'Latest harvested data',
+                                content: {
+                                    [config.contentType]: {
+                                        schema: { type: 'object' }
+                                    }
+                                }
+                            },
+                            '404': {
+                                description: 'No data available'
+                            }
+                        }
+                    }
+                }
+            },
+            tags: [
+                {
+                    name: tagName,
+                    description: config.description
+                }
+            ]
+        };
+    }
+}
+//# sourceMappingURL=harvester.js.map

package/dist/components/harvester.js.map

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

package/dist/components/index.d.ts

@@ -0,0 +1,11 @@
+export { Collector } from './collector.js';
+export { Harvester } from './harvester.js';
+export { Handler } from './handler.js';
+export { AssetsManager, type AssetMetadataRow, type CreateAssetRequest, type UpdateAssetRequest } from './assets_manager.js';
+export { TilesetManager, type TilesetMetadataRow } from './tileset_manager.js';
+export { MapManager, type MapLayerMetadataRow } from './map_manager.js';
+export { GlobalAssetsHandler } from './global_assets_handler.js';
+export { CustomTableManager, type CustomTableRecord, type QueryValidationOptions, type CustomTableComponent } from './custom_table_manager.js';
+export { Component, Servable } from './interfaces.js';
+export { ComponentConfiguration, AssetsConfiguration, DataResponse, StoreConfiguration, type EndpointDefinition } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EACH,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EAC1B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9E,OAAO,EAAE,UAAU,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EACH,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC5B,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,EACH,sBAAsB,EACtB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,KAAK,kBAAkB,EAC1B,MAAM,YAAY,CAAA"}

package/dist/components/index.js

@@ -0,0 +1,9 @@
+export { Collector } from './collector.js';
+export { Harvester } from './harvester.js';
+export { Handler } from './handler.js';
+export { AssetsManager } from './assets_manager.js';
+export { TilesetManager } from './tileset_manager.js';
+export { MapManager } from './map_manager.js';
+export { GlobalAssetsHandler } from './global_assets_handler.js';
+export { CustomTableManager } from './custom_table_manager.js';
+//# sourceMappingURL=index.js.map

package/dist/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EACH,aAAa,EAIhB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,cAAc,EAA2B,MAAM,sBAAsB,CAAA;AAC9E,OAAO,EAAE,UAAU,EAA4B,MAAM,kBAAkB,CAAA;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EACH,kBAAkB,EAIrB,MAAM,2BAA2B,CAAA"}

package/dist/components/interfaces.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @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;
+    }>;
+}
+//# sourceMappingURL=interfaces.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +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

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

package/dist/components/map_manager.d.ts

@@ -0,0 +1,61 @@
+import { AssetsManager } from './assets_manager.js';
+import type { DataResponse } from './types.js';
+/**
+ * Extended metadata for map layer assets
+ */
+export interface MapLayerMetadataRow {
+    id?: number;
+    name: string;
+    type: string;
+    url: string;
+    date: Date;
+    description: string;
+    source: string;
+    owner_id: number | null;
+    filename: string;
+    layer_type?: string;
+    layer_name?: string;
+    geometry_type?: string;
+    properties_count?: number;
+}
+/**
+ * Specialized Assets Manager for handling map layer data.
+ *
+ * Extends the base AssetsManager with specialized logic for:
+ * - Processing JSON layer objects containing map data
+ * - Extracting and analyzing layer metadata
+ * - Storing layer-specific information
+ *
+ * Inherits all CRUD endpoints from AssetsManager:
+ * - GET /{name} - List all layers
+ * - POST /{name}/upload - Upload layer data (overridden)
+ * - GET /{name}/:id - Get layer data
+ * - PUT /{name}/:id - Update layer metadata
+ * - DELETE /{name}/:id - Delete layer
+ * - GET /{name}/:id/download - Download layer data
+ */
+export declare abstract class MapManager extends AssetsManager {
+    /**
+     * Override the upload handler to process JSON layer objects instead of files.
+     *
+     * Processes the layer data:
+     * 1. Validates the layer object structure
+     * 2. Extracts layer-specific metadata
+     * 3. Stores the layer data as JSON
+     *
+     * @param req - HTTP request with layer JSON data
+     * @returns DataResponse with upload result
+     */
+    handleUpload(req: any): Promise<DataResponse>;
+    /**
+     * Analyze layer content to extract metadata
+     * @param layer - The layer object to analyze
+     * @returns Layer metadata information
+     */
+    private analyzeLayerContent;
+    /**
+     * Override retrieve to include layer-specific metadata in the response
+     */
+    retrieve(): Promise<DataResponse>;
+}
+//# sourceMappingURL=map_manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"map_manager.d.ts","sourceRoot":"","sources":["../../src/components/map_manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,IAAI,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;IAEhB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,8BAAsB,UAAW,SAAQ,aAAa;IAClD;;;;;;;;;;OAUG;IACG,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,YAAY,CAAC;IA+HnD;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IA+D3B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC;CAwC1C"}