@mxtommy/kip 4.5.0-beta.1 → 4.5.1

package/plugin/history-series.service.js

@@ -0,0 +1,439 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HistorySeriesService = void 0;
+/**
+ * Manages history capture series definitions and serves History API-compatible query results.
+ */
+class HistorySeriesService {
+    nowProvider;
+    retainSamplesInMemory;
+    seriesById = new Map();
+    lastAcceptedTimestampBySeriesKey = new Map();
+    sampleSink = null;
+    constructor(nowProvider = () => Date.now(), retainSamplesInMemory = true) {
+        this.nowProvider = nowProvider;
+        this.retainSamplesInMemory = retainSamplesInMemory;
+    }
+    /**
+     * Returns all configured series sorted by `seriesId`.
+     *
+     * @returns Ordered list of series definitions.
+     *
+     * @example
+     * const list = service.listSeries();
+     * console.log(list.length);
+     */
+    listSeries() {
+        return Array.from(this.seriesById.values()).sort((left, right) => {
+            return left.seriesId.localeCompare(right.seriesId);
+        });
+    }
+    /**
+    * Finds a series by identifier.
+    *
+    * @param {string} seriesId Series identifier.
+    * @returns {ISeriesDefinition | null} Matching series or null.
+    *
+    * @example
+    * const row = service.findSeriesById('series-1');
+     */
+    findSeriesById(seriesId) {
+        return this.seriesById.get(seriesId) ?? null;
+    }
+    /**
+     * Creates or updates a series definition.
+     *
+     * @param {ISeriesDefinition} input The incoming series definition payload.
+     * @returns {ISeriesDefinition} The normalized and stored series definition.
+     *
+     * @example
+     * service.upsertSeries({
+     *   seriesId: 'abc',
+     *   datasetUuid: 'abc',
+     *   ownerWidgetUuid: 'widget-1',
+     *   path: 'navigation.speedOverGround'
+     * });
+     */
+    upsertSeries(input) {
+        const normalized = this.normalizeSeries(input);
+        const key = normalized.seriesId;
+        this.seriesById.set(key, normalized);
+        return normalized;
+    }
+    /**
+     * Registers a callback invoked for every accepted sample.
+     *
+     * @param {(sample: IRecordedSeriesSample) => void | null} sink Callback used to forward samples to persistent storage.
+     * @returns {void}
+     *
+     * @example
+     * service.setSampleSink(sample => console.log(sample.seriesId));
+     */
+    setSampleSink(sink) {
+        this.sampleSink = sink;
+    }
+    /**
+     * Deletes an existing series definition and all captured samples for the series.
+     *
+     * @param {string} seriesId Unique series identifier.
+     * @returns {boolean} True when a series existed and was deleted.
+     *
+     * @example
+     * const deleted = service.deleteSeries('abc');
+     */
+    deleteSeries(seriesId) {
+        const keysToDelete = Array.from(this.seriesById.entries())
+            .filter(([, series]) => series.seriesId === seriesId)
+            .map(([key]) => key);
+        if (keysToDelete.length === 0) {
+            return false;
+        }
+        keysToDelete.forEach(key => {
+            this.seriesById.delete(key);
+            this.lastAcceptedTimestampBySeriesKey.delete(key);
+        });
+        return true;
+    }
+    /**
+     * Reconciles the entire desired series set against the current state.
+     *
+     * @param {ISeriesDefinition[]} desiredSeries Full desired series payload list.
+     * @returns {{ created: number; updated: number; deleted: number; total: number }} Reconciliation summary.
+     *
+     * @example
+     * const result = service.reconcileSeries([{ seriesId: 's1', datasetUuid: 's1', ownerWidgetUuid: 'w1', path: 'p' }]);
+     * console.log(result.created, result.deleted);
+     */
+    reconcileSeries(desiredSeries) {
+        const now = Date.now();
+        const desiredById = new Map();
+        desiredSeries.forEach(entry => {
+            const normalized = this.normalizeSeries(entry);
+            const key = normalized.seriesId;
+            desiredById.set(key, normalized);
+        });
+        let created = 0;
+        let updated = 0;
+        let deleted = 0;
+        desiredById.forEach((desired, seriesKey) => {
+            const existing = this.seriesById.get(seriesKey);
+            // Always update reconcile_ts on reconcile
+            const desiredWithReconcile = { ...desired, reconcileTs: now };
+            if (!existing) {
+                this.seriesById.set(seriesKey, desiredWithReconcile);
+                created += 1;
+                return;
+            }
+            if (JSON.stringify(existing) !== JSON.stringify(desired)) {
+                this.seriesById.set(seriesKey, desiredWithReconcile);
+                updated += 1;
+            }
+            else {
+                // Even if not updated, update reconcileTs
+                this.seriesById.set(seriesKey, { ...existing, reconcileTs: now });
+            }
+        });
+        Array.from(this.seriesById.keys()).forEach(seriesKey => {
+            if (!desiredById.has(seriesKey)) {
+                this.seriesById.delete(seriesKey);
+                this.lastAcceptedTimestampBySeriesKey.delete(seriesKey);
+                deleted += 1;
+            }
+        });
+        return {
+            created,
+            updated,
+            deleted,
+            total: this.seriesById.size
+        };
+    }
+    /**
+     * Records a single numeric sample for a configured series.
+     *
+     * @param {string} seriesId Unique series identifier.
+     * @param {number} value Numeric sample value.
+     * @param {number} timestamp Sample timestamp in milliseconds.
+     * @returns {boolean} True when sample was accepted.
+     *
+     * @example
+     * service.recordSample('abc', 12.4, Date.now());
+     */
+    recordSample(seriesId, value, timestamp) {
+        const seriesEntry = Array.from(this.seriesById.entries())
+            .find(([, series]) => series.seriesId === seriesId);
+        if (!seriesEntry) {
+            return false;
+        }
+        return this.recordSampleByKey(seriesEntry[0], value, timestamp);
+    }
+    recordSampleByKey(seriesKey, value, timestamp) {
+        const series = this.seriesById.get(seriesKey);
+        if (!series || series.enabled === false || !Number.isFinite(value) || !Number.isFinite(timestamp)) {
+            return false;
+        }
+        const samplingIntervalMs = this.resolveSampleTimeMs(series.sampleTime);
+        const previousTimestamp = this.lastAcceptedTimestampBySeriesKey.get(seriesKey);
+        if (previousTimestamp !== undefined && (timestamp - previousTimestamp) < samplingIntervalMs) {
+            return false;
+        }
+        const context = series.context ?? 'vessels.self';
+        const source = series.source ?? 'default';
+        this.sampleSink?.({
+            seriesId: series.seriesId,
+            datasetUuid: series.datasetUuid,
+            ownerWidgetUuid: series.ownerWidgetUuid,
+            path: series.path,
+            context,
+            source,
+            timestamp,
+            value
+        });
+        this.lastAcceptedTimestampBySeriesKey.set(seriesKey, timestamp);
+        return true;
+    }
+    /**
+     * Records a sample based on a Signal K stream value by matching path/context/source against configured series.
+     *
+     * @param {{ path?: unknown; value?: unknown; timestamp?: unknown; context?: unknown; source?: unknown; $source?: unknown }} sample Signal K normalized value entry.
+     * @returns {number} Number of configured series that accepted the sample.
+     *
+     * @example
+     * const count = service.recordFromSignalKSample({ path: 'navigation.speedOverGround', value: 6.2, timestamp: new Date().toISOString() });
+     */
+    recordFromSignalKSample(sample) {
+        const path = this.normalizePathIdentifier(typeof sample.path === 'string' ? sample.path : '');
+        if (!path) {
+            return 0;
+        }
+        const ts = this.resolveTimestamp(sample.timestamp);
+        const context = typeof sample.context === 'string' && sample.context ? sample.context : 'vessels.self';
+        const source = this.resolveSource(sample);
+        const leafSamples = this.extractNumericLeafSamples(path, sample.value);
+        if (leafSamples.length === 0) {
+            return 0;
+        }
+        let recorded = 0;
+        leafSamples.forEach(leaf => {
+            this.seriesById.forEach((series, seriesKey) => {
+                if (series.path !== leaf.path || series.enabled === false) {
+                    return;
+                }
+                const seriesContext = series.context ?? 'vessels.self';
+                if (!this.isContextMatch(seriesContext, context)) {
+                    return;
+                }
+                const seriesSource = series.source ?? 'default';
+                if (!this.isSourceMatch(seriesSource, source)) {
+                    return;
+                }
+                if (this.recordSampleByKey(seriesKey, leaf.value, ts)) {
+                    recorded += 1;
+                }
+            });
+        });
+        return recorded;
+    }
+    extractNumericLeafSamples(basePath, value) {
+        const samples = [];
+        const addNumeric = (samplePath, sampleValue) => {
+            const normalizedPath = this.normalizePathIdentifier(samplePath);
+            if (!normalizedPath) {
+                return;
+            }
+            const numericValue = Number(sampleValue);
+            if (!Number.isFinite(numericValue)) {
+                return;
+            }
+            samples.push({ path: normalizedPath, value: numericValue });
+        };
+        const walk = (currentPath, currentValue) => {
+            if (currentValue && typeof currentValue === 'object') {
+                if (Array.isArray(currentValue)) {
+                    currentValue.forEach((entry, index) => {
+                        walk(`${currentPath}.${index}`, entry);
+                    });
+                    return;
+                }
+                Object.entries(currentValue).forEach(([key, child]) => {
+                    walk(`${currentPath}.${key}`, child);
+                });
+                return;
+            }
+            addNumeric(currentPath, currentValue);
+        };
+        walk(basePath, value);
+        return samples;
+    }
+    /**
+     * Returns all known history paths.
+     *
+     * @returns {string[]} Ordered unique path list.
+     *
+     * @example
+     * const paths = service.getPaths();
+     */
+    getPaths() {
+        const paths = new Set();
+        this.seriesById.forEach(series => {
+            paths.add(series.path);
+        });
+        return Array.from(paths).sort();
+    }
+    /**
+     * Returns all known history contexts.
+     *
+     * @returns {string[]} Ordered unique context list.
+     *
+     * @example
+     * const contexts = service.getContexts();
+     */
+    getContexts() {
+        const contexts = new Set();
+        this.seriesById.forEach(series => {
+            contexts.add(series.context ?? 'vessels.self');
+        });
+        return Array.from(contexts).sort();
+    }
+    normalizeSeries(input) {
+        const seriesId = (input.seriesId || input.datasetUuid || '').trim();
+        if (!seriesId) {
+            throw new Error('seriesId is required');
+        }
+        const datasetUuid = (input.datasetUuid || seriesId).trim();
+        if (!datasetUuid) {
+            throw new Error('datasetUuid is required');
+        }
+        const ownerWidgetUuid = (input.ownerWidgetUuid || '').trim();
+        if (!ownerWidgetUuid) {
+            throw new Error('ownerWidgetUuid is required');
+        }
+        const path = this.normalizePathIdentifier(input.path || '');
+        if (!path) {
+            throw new Error('path is required');
+        }
+        // Determine if this is a data chart based widget
+        const dsSampleTime = ownerWidgetUuid?.startsWith('widget-windtrends-chart') ||
+            ownerWidgetUuid?.startsWith('widget-data-chart');
+        let sampleTime;
+        const retentionMs = input.retentionDurationMs ?? this.resolveRetentionMs(input);
+        if (dsSampleTime && Number.isFinite(retentionMs) && retentionMs > 0) {
+            // regular widget sampleTime: 15 sec
+            sampleTime = Math.max(1, Math.trunc(15000));
+        }
+        else {
+            sampleTime = this.resolveSampleTimeMs(input.sampleTime);
+        }
+        return {
+            ...input,
+            seriesId,
+            datasetUuid,
+            ownerWidgetUuid,
+            path,
+            source: input.source ?? 'default',
+            context: input.context ?? 'vessels.self',
+            enabled: input.enabled !== false,
+            retentionDurationMs: retentionMs,
+            sampleTime
+        };
+    }
+    resolveSampleTimeMs(sampleTime) {
+        const parsed = Number(sampleTime);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return Math.max(1, Math.trunc(parsed));
+        }
+        return 1000;
+    }
+    buildSeriesMapKey(seriesId) {
+        // userScope removed; now returns only seriesId
+        return String(seriesId).trim();
+    }
+    resolveRetentionMs(series) {
+        if (Number.isFinite(series.retentionDurationMs) && series.retentionDurationMs > 0) {
+            return series.retentionDurationMs;
+        }
+        const period = Number(series.period ?? 0);
+        const scale = String(series.timeScale ?? '').toLowerCase();
+        if (scale === 'last minute')
+            return 60_000;
+        if (scale === 'last 5 minutes')
+            return 5 * 60_000;
+        if (scale === 'last 30 minutes')
+            return 30 * 60_000;
+        if (scale === 'second')
+            return Math.max(0, period) * 1_000;
+        if (scale === 'minute')
+            return Math.max(0, period) * 60_000;
+        if (scale === 'hour')
+            return Math.max(0, period) * 60 * 60_000;
+        if (scale === 'day')
+            return Math.max(0, period) * 24 * 60 * 60_000;
+        return 24 * 60 * 60_000;
+    }
+    normalizePathIdentifier(path) {
+        const trimmed = String(path).trim();
+        if (!trimmed) {
+            return '';
+        }
+        if (trimmed.startsWith('vessels.self.')) {
+            return trimmed.slice('vessels.self.'.length);
+        }
+        if (trimmed.startsWith('self.')) {
+            return trimmed.slice('self.'.length);
+        }
+        return trimmed;
+    }
+    resolveTimestamp(timestamp) {
+        if (typeof timestamp === 'number' && Number.isFinite(timestamp)) {
+            return timestamp;
+        }
+        if (typeof timestamp === 'string') {
+            const parsed = Date.parse(timestamp);
+            if (Number.isFinite(parsed)) {
+                return parsed;
+            }
+        }
+        return this.nowProvider();
+    }
+    resolveSource(sample) {
+        if (typeof sample.$source === 'string' && sample.$source.trim().length > 0) {
+            return sample.$source;
+        }
+        if (typeof sample.source === 'string' && sample.source.trim().length > 0) {
+            return sample.source;
+        }
+        if (sample.source && typeof sample.source === 'object') {
+            const source = sample.source;
+            const label = typeof source.label === 'string' ? source.label : '';
+            const src = typeof source.src === 'string' || typeof source.src === 'number' ? String(source.src) : '';
+            if (label && src) {
+                return `${label}.${src}`;
+            }
+            if (label) {
+                return label;
+            }
+        }
+        return 'default';
+    }
+    isContextMatch(seriesContext, sampleContext) {
+        if (seriesContext === sampleContext) {
+            return true;
+        }
+        if (seriesContext === 'vessels.self') {
+            return sampleContext === 'vessels.self' || sampleContext.startsWith('vessels.');
+        }
+        return false;
+    }
+    isSourceMatch(seriesSource, sampleSource) {
+        if (seriesSource === '*' || seriesSource === 'any') {
+            return true;
+        }
+        if (seriesSource === 'default') {
+            return true;
+        }
+        if (!sampleSource) {
+            return false;
+        }
+        return seriesSource === sampleSource;
+    }
+}
+exports.HistorySeriesService = HistorySeriesService;