@signalk/tracks-plugin 3.3.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 {
@@ -185,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,

package/dist/trackApi.d.ts

@@ -59,8 +59,8 @@ export interface TrackProperties {
     contextName?: string;
     /** The track's own name, as an imported GPX `<trk><name>` carries. */
     name?: string;
-    /** Set on a track a client stored, absent on a recorded one. */
-    imported?: true;
+    /** 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

@@ -54,22 +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[]>;
 }
-export declare function createTrackProvider(deps: TrackProviderDeps): TrackApi;
+/** 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;
+}
 /**
  * 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 in place of what was recorded over the same time and answers
- * as `recorded:<context>`. 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.
+ * 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 keepTrack(track: ImportedTrack, deps: KeepTrackDeps): Promise<string>;
+export declare function fillGaps(segments: TimedPosition[][], recorded: readonly TimedPosition[], minGap: number): {
+    runs: TimedPosition[][];
+    overlapping: 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,6 +11719,7 @@ 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]);
@@ -11881,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. */
@@ -11904,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));
@@ -11930,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. */