@signalk/tracks-plugin 3.2.0 → 3.4.0

package/dist/sqliteStore.d.ts

@@ -1,6 +1,6 @@
 import { TrackQuery } from './timeWindow.js';
 import { TrackStore } from './store.js';
-import { BinEntry, Context, Debug, ImportedTrack, ImportFilter, LatLngTuple, RecordedSpan, RestoreResult, TimedPosition, TimedTrackCollection, TimeWindow, TrackCollection, TrackParams } from './types.js';
+import { BinEntry, Context, Debug, ImportedTrack, StoredImport, ImportFilter, LatLngTuple, RecordedSpan, RestoreResult, TimedPosition, TimedTrackCollection, TimeWindow, TrackCollection, TrackParams } from './types.js';
 export declare class TransactionStateError extends Error {
 }
 export interface SqliteStoreConfig {
@@ -132,6 +132,15 @@ export declare class SqliteTrackStore implements TrackStore {
      * same id fails rather than replacing the first.
      */
     storeImport(track: ImportedTrack): void;
+    /**
+     * Write a track imported for a vessel into its recording, in place of what
+     * was recorded over the same time. The positions within each segment's
+     * span go to the recycle bin first, one entry per segment, so a restore
+     * brings them back beside the import. Every span is binned before any point
+     * is written, so segments that overlap in time cannot bin each other.
+     * Resolves to the bin entries made.
+     */
+    recordTrack(context: Context, segments: TimedPosition[][], deletedAt: number, keepEmpty: boolean): number[];
     /**
      * Move a vessel's positions recorded within `[from, to]` into the recycle
      * bin, resolving to the entry's id and whether the store held the vessel at
@@ -176,9 +185,9 @@ export declare class SqliteTrackStore implements TrackStore {
      * earlier with it, since they have no track left to be restored into.
      */
     private purge;
-    getImport(id: string): ImportedTrack | undefined;
+    getImport(id: string): StoredImport | undefined;
     /** Imported tracks the filter lets through, in the order they were stored. */
-    findImports(filter?: ImportFilter): ImportedTrack[];
+    findImports(filter?: ImportFilter): StoredImport[];
     private importFrom;
     /** Worker startup snapshot; queries and name lookups must not open a second database. */
     storedNames(): {

package/dist/store.d.ts

@@ -1,4 +1,4 @@
-import { BinEntry, Context, Debug, ImportedTrack, ImportFilter, LatLngTuple, RecordedSpan, RestoreResult, TimedPosition, TimedTrackCollection, TimeWindow, TrackCollection, TrackParams } from './types.js';
+import { BinEntry, Context, Debug, ImportedTrack, StoredImport, ImportFilter, LatLngTuple, RecordedSpan, RestoreResult, TimedPosition, TimedTrackCollection, TimeWindow, TrackCollection, TrackParams } from './types.js';
 import { TrackQuery } from './timeWindow.js';
 /**
  * A track store: somewhere positions are accumulated and queried back.
@@ -96,8 +96,8 @@ export interface TrackStore {
      * back at once.
      */
     storeImport?(track: ImportedTrack): void | Promise<void>;
-    getImport?(id: string): ImportedTrack | undefined | Promise<ImportedTrack | undefined>;
-    findImports?(filter?: ImportFilter): ImportedTrack[] | Promise<ImportedTrack[]>;
+    getImport?(id: string): StoredImport | undefined | Promise<StoredImport | undefined>;
+    findImports?(filter?: ImportFilter): StoredImport[] | Promise<StoredImport[]>;
     /**
      * The recycle bin. Optional like the import methods: a store without it
      * cannot delete. A delete moves rows into the bin rather than removing them,
@@ -113,6 +113,11 @@ export interface TrackStore {
         id?: number;
         known: boolean;
     }>;
+    /**
+     * Write a track imported for a vessel into its recording, binning what was
+     * recorded over the same time; resolves to the bin entries made.
+     */
+    recordTrack?(context: Context, segments: TimedPosition[][], deletedAt: number, keepEmpty: boolean): number[] | Promise<number[]>;
     binImport?(importId: string, span: {
         from?: number;
         to?: number;

package/dist/trackApi.d.ts

@@ -59,6 +59,8 @@ export interface TrackProperties {
     contextName?: string;
     /** The track's own name, as an imported GPX `<trk><name>` carries. */
     name?: string;
+    /** When a client stored the track, as an ISO 8601 time; absent on a recorded one. */
+    imported?: string;
     /** Absent, with `to`, for a track whose points carry no times. */
     from?: string;
     to?: string;

package/dist/trackProvider.d.ts

@@ -1,6 +1,6 @@
 import { TrackStore } from './store.js';
 import { TrackApi } from './trackApi.js';
-import { TimedPosition, TimeWindow } from './types.js';
+import { ImportedTrack, TimedPosition, TimeWindow } from './types.js';
 /**
  * Serves the v2 Track API from this plugin's store.
  *
@@ -54,5 +54,65 @@ export interface TrackProviderDeps {
     /** Called after a delete, so whatever hides deleted spans from history reloads them. */
     deleted: () => void;
     reconcileWithHistory: (context: string, stored: TimedPosition[], window: TimeWindow | undefined, resolutionMs: number | undefined) => Promise<TimedPosition[]>;
+    /**
+     * What the store and history hold for a context over a window, rejecting
+     * when history could not be read: an import that fills only the gaps
+     * cannot tell a gap from an outage.
+     */
+    recordedOver: (context: string, window: TimeWindow) => Promise<TimedPosition[]>;
+}
+/** The Track API provider, plus the import route's way in with an overlap choice. */
+export type TrackProvider = TrackApi & {
+    importTrack(track: ImportedTrack, onOverlap: OnOverlap): Promise<KeptTrack>;
+};
+export declare function createTrackProvider(deps: TrackProviderDeps): TrackProvider;
+/**
+ * What an import does where the vessel's recording already holds positions.
+ * `keep` leaves them alone and fills only the stretches with nothing; `replace`
+ * puts the import in their place, sending them to the recycle bin.
+ */
+export type OnOverlap = 'keep' | 'replace';
+/**
+ * The shortest stretch without positions that an import kept beside a
+ * recording may fill. Filling every pause between recorded points would
+ * interleave two sources minute by minute, and any offset between them would
+ * draw as a sawtooth; whole stretches keep each part of the line from one.
+ */
+export declare const MIN_FILLED_GAP_MS: number;
+export interface KeepTrackDeps {
+    store: Required<Pick<TrackStore, 'storeImport' | 'recordTrack'>>;
+    selfContext: string;
+    historyKnows: (context: string) => Promise<boolean>;
+    /** The vessel's positions over a window, from the store and history alike. */
+    recorded: (context: string, from: number, to: number) => Promise<TimedPosition[]>;
+    deleted: () => void;
+}
+export interface KeptTrack {
+    id: string;
+    /** Points left out because the vessel already had positions there. */
+    overlapping: number;
 }
-export declare function createTrackProvider(deps: TrackProviderDeps): TrackApi;
+/**
+ * Keep a client's track, resolving to the id that addresses it.
+ *
+ * A timed track of the own vessel is the vessel's own passage, from before
+ * the plugin recorded it or from another plotter, so it is written into the
+ * recording and answers as `recorded:<context>`: with `keep`, only where the
+ * recording has nothing (see {@link fillGaps}); with `replace`, in place of
+ * what was recorded over the same time. Everything else is kept as an import:
+ * another vessel's track is not this boat's recording, and an untimed one
+ * cannot be placed in it.
+ */
+export declare function keepTrack(track: ImportedTrack, deps: KeepTrackDeps, onOverlap: OnOverlap): Promise<KeptTrack>;
+/**
+ * The parts of an import that fall where a recording has nothing for at least
+ * `minGap`, as runs to record, and how many points were left out.
+ *
+ * Each recorded point covers its own instant, or a history bucket's whole
+ * span, so a coarse provider read still counts as covering the time between
+ * its buckets. A run never crosses a recorded stretch or a segment boundary.
+ */
+export declare function fillGaps(segments: TimedPosition[][], recorded: readonly TimedPosition[], minGap: number): {
+    runs: TimedPosition[][];
+    overlapping: number;
+};

package/dist/trackStoreProtocol.d.ts

@@ -1,5 +1,5 @@
 import { SqliteTrackStore } from './sqliteStore.js';
-export type StoreMethod = 'newPosition' | 'recordName' | 'initialTrack' | 'prune' | 'get' | 'getTimed' | 'getAllTracks' | 'getFilteredTracks' | 'getFilteredTimedTracks' | 'storeImport' | 'getImport' | 'findImports' | 'binRecorded' | 'binImport' | 'restoreFromBin' | 'purgeFromBin' | 'binEntries' | 'deletedSpans' | 'close';
+export type StoreMethod = 'newPosition' | 'recordName' | 'initialTrack' | 'prune' | 'get' | 'getTimed' | 'getAllTracks' | 'getFilteredTracks' | 'getFilteredTimedTracks' | 'storeImport' | 'getImport' | 'findImports' | 'binRecorded' | 'recordTrack' | 'binImport' | 'restoreFromBin' | 'purgeFromBin' | 'binEntries' | 'deletedSpans' | 'close';
 export type Operation = {
     [K in StoreMethod]: {
         id: number;

package/dist/trackStoreWorker.js

@@ -11305,6 +11305,7 @@ var coveringFor = (bounds, maxCells) => {
 		});
 	});
 };
+var SELECT_IMPORTS = "SELECT * FROM imported_tracks JOIN import_times USING (id)";
 /** Longitude intervals as `[west, east]`, either of which may cross the antimeridian. */
 var longitudesOverlap = (a, b) => {
 	const pieces = ([west, east]) => west <= east ? [[west, east]] : [[west, 180], [-180, east]];
@@ -11398,6 +11399,13 @@ var SqliteTrackStore = class {
         north       REAL    NOT NULL
       );
       CREATE INDEX IF NOT EXISTS idx_imported_context ON imported_tracks(context);
+      -- When each import was kept. Its own table, like names, so a database
+      -- written before it existed opens unchanged; it stays while the import
+      -- is in the recycle bin, for a restore, and goes when that is purged.
+      CREATE TABLE IF NOT EXISTS import_times (
+        id          TEXT PRIMARY KEY,
+        imported_at INTEGER NOT NULL
+      );
       CREATE TABLE IF NOT EXISTS imported_points (
         track_id  TEXT    NOT NULL,
         seq       INTEGER NOT NULL,
@@ -11455,6 +11463,9 @@ var SqliteTrackStore = class {
       );
       CREATE INDEX IF NOT EXISTS idx_binned_imported_points ON binned_imported_points(bin_id);
     `);
+		const now = Date.now();
+		this.db.prepare(`INSERT OR IGNORE INTO import_times (id, imported_at)
+         SELECT id, ? FROM imported_tracks UNION SELECT id, ? FROM binned_imported_tracks`).run(now, now);
 		this.insert = this.db.prepare("INSERT INTO positions (context, timestamp, lat, lon, s2cell) VALUES (?, ?, ?, ?, ?)");
 		this.insertName = this.db.prepare(`INSERT INTO names (context, name, timestamp) VALUES (?, ?, ?)
        ON CONFLICT(context) DO UPDATE SET name = excluded.name, timestamp = excluded.timestamp
@@ -11692,6 +11703,7 @@ var SqliteTrackStore = class {
 	storeImport(track) {
 		const points = track.segments.flat();
 		if (points.length === 0) throw new Error("An imported track needs at least one point");
+		if (this.db.prepare("SELECT 1 AS found FROM import_times WHERE id = ?").get(track.id)) throw new Error(`An import with id ${track.id} already exists`);
 		let south = points[0].position[0];
 		let north = south;
 		let firstTime;
@@ -11707,11 +11719,32 @@ var SqliteTrackStore = class {
 		const [west, east] = longitudeSpan(points.map(({ position }) => position[1]));
 		this.db.prepare(`INSERT INTO imported_tracks (id, context, name, metadata, first_time, last_time, west, south, east, north)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(track.id, track.context ?? null, track.name ?? null, JSON.stringify(track.metadata), firstTime ?? null, lastTime ?? null, west, south, east, north);
+		this.db.prepare("INSERT INTO import_times (id, imported_at) VALUES (?, ?)").run(track.id, Date.now());
 		const insert = this.db.prepare("INSERT INTO imported_points (track_id, seq, segment, timestamp, lat, lon) VALUES (?, ?, ?, ?, ?, ?)");
 		let seq = 0;
 		for (const [segment, segmentPoints] of track.segments.entries()) for (const { position, timestamp } of segmentPoints) insert.run(track.id, seq++, segment, timestamp ?? null, position[0], position[1]);
 	}
 	/**
+	* Write a track imported for a vessel into its recording, in place of what
+	* was recorded over the same time. The positions within each segment's
+	* span go to the recycle bin first, one entry per segment, so a restore
+	* brings them back beside the import. Every span is binned before any point
+	* is written, so segments that overlap in time cannot bin each other.
+	* Resolves to the bin entries made.
+	*/
+	recordTrack(context, segments, deletedAt, keepEmpty) {
+		const binned = [];
+		for (const points of segments) {
+			const first = points[0];
+			const last = points.at(-1);
+			if (first === void 0 || last === void 0) continue;
+			const { id } = this.binRecorded(context, first.timestamp, last.timestamp, deletedAt, keepEmpty);
+			if (id !== void 0) binned.push(id);
+		}
+		for (const points of segments) for (const { position, timestamp } of points) this.store(context, position, timestamp);
+		return binned;
+	}
+	/**
 	* Move a vessel's positions recorded within `[from, to]` into the recycle
 	* bin, resolving to the entry's id and whether the store held the vessel at
 	* all.
@@ -11861,9 +11894,10 @@ var SqliteTrackStore = class {
 			if (entry.import_id === null) this.db.prepare("UPDATE recycle_bin SET purged = 1 WHERE id = ?").run(id);
 			else this.db.prepare("DELETE FROM recycle_bin WHERE id = ?").run(id);
 		}
+		if (entry.whole === 1 && entry.import_id !== null) this.db.prepare("DELETE FROM import_times WHERE id = ?").run(entry.import_id);
 	}
 	getImport(id) {
-		const row = this.db.prepare("SELECT * FROM imported_tracks WHERE id = ?").get(id);
+		const row = this.db.prepare(`${SELECT_IMPORTS} WHERE id = ?`).get(id);
 		return row ? this.importFrom(row) : void 0;
 	}
 	/** Imported tracks the filter lets through, in the order they were stored. */
@@ -11884,7 +11918,7 @@ var SqliteTrackStore = class {
 			params.push(filter.bbox.ne[0], filter.bbox.sw[0]);
 		}
 		const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
-		let rows = this.db.prepare(`SELECT * FROM imported_tracks ${where} ORDER BY rowid`).all(...params);
+		let rows = this.db.prepare(`${SELECT_IMPORTS} ${where} ORDER BY imported_tracks.rowid`).all(...params);
 		const box = filter.bbox;
 		if (box) rows = rows.filter((row) => longitudesOverlap([row.west, row.east], [box.sw[1], box.ne[1]]));
 		return rows.map((row) => this.importFrom(row));
@@ -11910,7 +11944,8 @@ var SqliteTrackStore = class {
 			...row.context === null ? {} : { context: row.context },
 			...row.name === null ? {} : { name: row.name },
 			metadata: JSON.parse(row.metadata),
-			segments
+			segments,
+			importedAt: row.imported_at
 		};
 	}
 	/** Worker startup snapshot; queries and name lookups must not open a second database. */
@@ -11999,6 +12034,7 @@ function mutate(operation, target) {
 var ACKNOWLEDGED = /* @__PURE__ */ new Set([
 	"storeImport",
 	"binRecorded",
+	"recordTrack",
 	"binImport",
 	"restoreFromBin",
 	"purgeFromBin"
@@ -12007,6 +12043,7 @@ function acknowledge(operation, target) {
 	switch (operation.method) {
 		case "storeImport": return target.storeImport(...operation.args);
 		case "binRecorded": return target.binRecorded(...operation.args);
+		case "recordTrack": return target.recordTrack(...operation.args);
 		case "binImport": return target.binImport(...operation.args);
 		case "restoreFromBin": return target.restoreFromBin(...operation.args);
 		case "purgeFromBin": return target.purgeFromBin(...operation.args);