@signalk/tracks-plugin 3.0.2 → 3.1.0

package/dist/sqliteStore.d.ts

@@ -42,6 +42,8 @@ export declare class SqliteTrackStore implements TrackStore {
     private readonly segmentGap;
     private readonly retention;
     private readonly resolution;
+    /** See CLIP_STRETCH_GAP; widened so a coarse write resolution does not split every fix. */
+    private readonly stretchGap;
     private readonly debug;
     /** Timestamp of the last position stored per context, for throttling. */
     private readonly lastStored;
@@ -94,8 +96,24 @@ export declare class SqliteTrackStore implements TrackStore {
      * last-position test run once, here.
      */
     getFilteredTimedTracks(params: TrackParams, selfPosition?: LatLngTuple, debug?: Debug, query?: TrackQuery): Promise<TimedTrackCollection>;
+    /** The cell index condition for rows near `bounds`, or none for an empty covering. */
+    private coveringClause;
     /** Contexts with at least one position inside `bounds`, via the cell index. */
     private contextsInBounds;
+    /**
+     * Per context, the positions a track clipped to `bounds` is made of, and
+     * only those: every position inside the box within the window, plus the one
+     * either side of each stretch inside, which carries the line to the edge.
+     *
+     * The cell index finds the times a context was inside the box. Times closer
+     * together than `stretchGap` are read as one stretch, including any
+     * excursion outside it, since the clip that follows cuts those anyway;
+     * further apart they are read separately and the time between is skipped.
+     * Nothing between two stretches is inside the box, so skipping it loses
+     * nothing the clip would keep: how they are grouped decides only how many
+     * rows are read, never the result.
+     */
+    private rowsNearBounds;
     /**
      * Split a context's positions into segments, breaking where the recording
      * stopped for longer than `segmentGap` — an overnight stop should not draw a

package/dist/timeWindow.d.ts

@@ -25,9 +25,32 @@ export interface TrackQuery {
  * and the whole retained track is returned, as before.
  */
 export declare function parseTrackQuery(query: Record<string, unknown>, now?: number, alsoAllowed?: readonly string[]): TrackQuery;
+/**
+ * The time between two points that no history bucket either side can account
+ * for.
+ *
+ * Providers disagree on whether a bucket's timestamp marks its start or its
+ * end, so a bucket may cover up to its width on either side of it. Two
+ * buckets, however, cover the time between their timestamps once between
+ * them, so one width is taken off, the wider of the two: exact between
+ * buckets under either convention, and between a fix and a bucket never more
+ * than the pause could be.
+ */
+export declare function uncoveredBetween(previous: TimedPosition, point: TimedPosition): number;
+/**
+ * The pause in the recording between two consecutive points: where thinning
+ * dropped the points between them, the longest pause among those it recorded,
+ * and otherwise whatever of the time between them no bucket accounts for.
+ */
+export declare function pauseBetween(previous: TimedPosition, point: TimedPosition): number;
 /**
  * Drop points closer together than `resolution` milliseconds, always keeping
  * the first and last so the track keeps its extent.
+ *
+ * A point kept after dropped ones records the longest pause among them as
+ * `pauseBefore`: the kept points are further apart than anything recorded
+ * between them, so without it `segment()` would read the spacing thinning
+ * made as a stop in the recording.
  */
 export declare function thin(points: TimedPosition[], resolution: number | undefined): TimedPosition[];
 /**
@@ -57,11 +80,16 @@ export declare function thinToBudget(points: TimedPosition[], maxPoints: number,
  * over an anchorage it actually sat still in.
  *
  * Operates on timestamped points rather than inside a store, so both the
- * in-memory and sqlite stores segment identically, and so it composes with
- * `thin()` — thinning first, then segmenting, keeps a thinned-away gap from
- * being invented as a join.
+ * in-memory and sqlite stores segment identically. A gap is a pause in the
+ * recording, not in the points given: see `pauseBetween`, which lets a
+ * thinned track, or one reconciled with history buckets, segment exactly as
+ * the recording would.
+ *
+ * A point marked `breakBefore` starts a new segment whatever the gap: a
+ * clipped track leaves the box there.
  *
- * `gap` of 0 or undefined returns a single segment, preserving the old shape.
+ * `gap` of 0 or undefined otherwise returns a single segment, preserving the
+ * old shape.
  * An empty input returns no segments rather than one empty one, so a caller can
  * distinguish "no track" from "a track with no points".
  */

package/dist/trackApi.d.ts

@@ -32,6 +32,12 @@ export interface TracksRequest {
     to?: Temporal.Instant;
     duration?: Temporal.Duration;
     bbox?: TrackBoundingBox;
+    /**
+     * Cut each track to `bbox`. The server resolves the default, so a provider
+     * sees an explicit value; absent means a server that predates the
+     * parameter, which returned whole tracks.
+     */
+    clip?: boolean;
     resolution?: Temporal.Duration;
     maxPoints?: number;
     simplify?: boolean;

package/dist/trackProvider.d.ts

@@ -40,6 +40,15 @@ export interface TrackProviderDeps {
      * Resolves to the store's own points unchanged when no provider is
      * installed, which is the common case.
      */
+    /**
+     * Contexts a history provider holds data for within the window, empty when
+     * there is no provider.
+     *
+     * The store can be far younger than the provider, so it alone cannot say
+     * which vessels exist or which passed through a box: a vessel recorded
+     * only before this plugin was installed is known to history alone.
+     */
+    historyContexts: (window: TimeWindow | undefined) => Promise<ReadonlySet<string>>;
     reconcileWithHistory: (context: string, stored: TimedPosition[], window: TimeWindow | undefined, resolutionMs: number | undefined) => Promise<TimedPosition[]>;
 }
 export declare function createTrackProvider(deps: TrackProviderDeps): TrackApi;

package/dist/trackStoreWorker.js

@@ -1,4 +1,4 @@
-import { b as thin, f as splitAtAntimeridian, n as SelfPositionUnavailableError, o as createInBounds, s as createMatcher } from "./utils-OGjP1B0D.js";
+import { c as createMatcher, n as SelfPositionUnavailableError, p as splitAtAntimeridian, s as createInBounds, x as thin } from "./utils-CGIGp4Xf.js";
 import { parentPort, workerData } from "node:worker_threads";
 import { DatabaseSync } from "node:sqlite";
 //#region \0rolldown/runtime.js
@@ -11234,6 +11234,20 @@ var _index$5 = {
 //#endregion
 //#region src/sqliteStore.ts
 var TransactionStateError = class extends Error {};
+var toTimed = ({ lat, lon, timestamp }) => ({
+	position: [lat, lon],
+	timestamp
+});
+/** Sorted times grouped into `[first, last]` stretches, split where two lie more than `gap` apart. */
+var stretchesOf = (times, gap) => {
+	const stretches = [];
+	for (const time of times) {
+		const current = stretches[stretches.length - 1];
+		if (current && time - current[1] <= gap) current[1] = time;
+		else stretches.push([time, time]);
+	}
+	return stretches;
+};
 /**
 * S2 cell ids are unsigned 64-bit; SQLite's INTEGER is signed 64-bit, and
 * node:sqlite refuses to bind a bigint above INT64_MAX outright:
@@ -11294,6 +11308,13 @@ var coveringFor = (bounds, maxCells) => {
 var DEFAULT_MAX_CELLS = 8;
 var DEFAULT_SEGMENT_GAP = 3e5;
 /**
+* How far apart two fixes inside a clipping box may be and still be read as
+* one stretch. A vessel cannot get far between fixes this close, so reading
+* what lies between them costs less than the two extra queries a separate
+* stretch takes. Any value gives the same clipped track.
+*/
+var CLIP_STRETCH_GAP = 6e5;
+/**
 * A position store backed by SQLite, so tracks survive a restart.
 *
 * Uses node:sqlite rather than better-sqlite3: it is built into Node >= 22, so
@@ -11313,6 +11334,8 @@ var SqliteTrackStore = class {
 	segmentGap;
 	retention;
 	resolution;
+	/** See CLIP_STRETCH_GAP; widened so a coarse write resolution does not split every fix. */
+	stretchGap;
 	debug;
 	/** Timestamp of the last position stored per context, for throttling. */
 	lastStored = /* @__PURE__ */ new Map();
@@ -11327,6 +11350,7 @@ var SqliteTrackStore = class {
 		this.segmentGap = config.segmentGap ?? DEFAULT_SEGMENT_GAP;
 		this.retention = config.retention ?? 0;
 		this.resolution = config.resolution ?? 0;
+		this.stretchGap = Math.max(CLIP_STRETCH_GAP, 2 * this.resolution);
 		this.debug = debug;
 		this.db = new DatabaseSync(config.file);
 		this.db.exec("PRAGMA journal_mode = WAL");
@@ -11437,31 +11461,93 @@ var SqliteTrackStore = class {
 	* last-position test run once, here.
 	*/
 	async getFilteredTimedTracks(params, selfPosition, debug, query) {
-		const candidates = params.bbox ? this.contextsInBounds(params.bbox) : void 0;
+		const near = params.bbox && params.clip ? this.rowsNearBounds(params.bbox, query?.window) : void 0;
+		const candidates = near ? new Set(near.keys()) : params.bbox ? this.contextsInBounds(params.bbox) : void 0;
 		const matcher = createMatcher(params, selfPosition, debug);
-		return (await Promise.all(this.contexts().map((context) => this.getTimed(context, query?.window).then((points) => ({
-			context,
-			points: thin(points, query?.resolution)
-		}))))).reduce((acc, { context, points }) => {
-			if ((!candidates || candidates.has(context)) && matcher(points.map(({ position }) => position))) acc[context] = points;
+		const requested = params.contexts ? new Set(params.contexts) : void 0;
+		const contexts = this.contexts().filter((context) => (!candidates || candidates.has(context)) && (!requested || requested.has(context)));
+		return (await Promise.all(contexts.map((context) => {
+			const rows = near?.get(context);
+			return (rows ? Promise.resolve(rows.map(toTimed)) : this.getTimed(context, query?.window)).then((points) => ({
+				context,
+				points: thin(points, query?.resolution)
+			}));
+		}))).reduce((acc, { context, points }) => {
+			if (matcher(points.map(({ position }) => position))) acc[context] = points;
 			return acc;
 		}, {});
 	}
+	/** The cell index condition for rows near `bounds`, or none for an empty covering. */
+	coveringClause(bounds) {
+		const covering = coveringFor(bounds, this.maxCells);
+		if (covering.length === 0) return;
+		const ranges = covering.map(cellRange);
+		return {
+			where: ranges.map(() => "(s2cell BETWEEN ? AND ?)").join(" OR "),
+			params: ranges.flatMap(({ start, end }) => [toSigned(start), toSigned(end)]),
+			cells: covering.length
+		};
+	}
 	/** Contexts with at least one position inside `bounds`, via the cell index. */
 	contextsInBounds(bounds) {
-		const covering = coveringFor(bounds, this.maxCells);
 		const found = /* @__PURE__ */ new Set();
-		if (covering.length === 0) return found;
-		const ranges = covering.map(cellRange);
-		const where = ranges.map(() => "(s2cell BETWEEN ? AND ?)").join(" OR ");
-		const params = ranges.flatMap(({ start, end }) => [toSigned(start), toSigned(end)]);
+		const clause = this.coveringClause(bounds);
+		if (!clause) return found;
+		const { where, params, cells } = clause;
 		const rows = this.db.prepare(`SELECT DISTINCT context, lat, lon FROM positions WHERE ${where}`).all(...params);
 		const inBounds = createInBounds(bounds);
 		for (const { context, lat, lon } of rows) if (inBounds([lat, lon])) found.add(context);
-		if (this.debug.enabled) this.debug(`bbox covering ${covering.length} cells -> ${rows.length} rows -> ${found.size} contexts`);
+		if (this.debug.enabled) this.debug(`bbox covering ${cells} cells -> ${rows.length} rows -> ${found.size} contexts`);
 		return found;
 	}
 	/**
+	* Per context, the positions a track clipped to `bounds` is made of, and
+	* only those: every position inside the box within the window, plus the one
+	* either side of each stretch inside, which carries the line to the edge.
+	*
+	* The cell index finds the times a context was inside the box. Times closer
+	* together than `stretchGap` are read as one stretch, including any
+	* excursion outside it, since the clip that follows cuts those anyway;
+	* further apart they are read separately and the time between is skipped.
+	* Nothing between two stretches is inside the box, so skipping it loses
+	* nothing the clip would keep: how they are grouped decides only how many
+	* rows are read, never the result.
+	*/
+	rowsNearBounds(bounds, window) {
+		const near = /* @__PURE__ */ new Map();
+		const clause = this.coveringClause(bounds);
+		if (!clause) return near;
+		const timeClauses = window ? ["timestamp >= ?", window.inclusiveEnd ? "timestamp <= ?" : "timestamp < ?"] : [];
+		const timeParams = window ? [window.from, window.to] : [];
+		const inWindow = timeClauses.map((c) => ` AND ${c}`).join("");
+		const inside = this.db.prepare(`SELECT context, timestamp, lat, lon FROM positions WHERE (${clause.where})${inWindow} ORDER BY context, timestamp`).all(...clause.params, ...timeParams);
+		const inBounds = createInBounds(bounds);
+		const times = /* @__PURE__ */ new Map();
+		for (const { context, timestamp, lat, lon } of inside) if (inBounds([lat, lon])) {
+			const list = times.get(context);
+			if (list) list.push(timestamp);
+			else times.set(context, [timestamp]);
+		}
+		const columns = "SELECT rowid AS id, context, timestamp, lat, lon FROM positions WHERE context = ?";
+		const between = this.db.prepare(`${columns} AND timestamp >= ? AND timestamp <= ? ORDER BY timestamp, rowid`);
+		const before = this.db.prepare(`${columns} AND timestamp < ?${inWindow} ORDER BY timestamp DESC, rowid DESC LIMIT 1`);
+		const after = this.db.prepare(`${columns} AND timestamp > ?${inWindow} ORDER BY timestamp, rowid LIMIT 1`);
+		for (const [context, list] of times) {
+			const rows = /* @__PURE__ */ new Map();
+			for (const [start, end] of stretchesOf(list, this.stretchGap)) {
+				const read = [
+					...before.all(context, start, ...timeParams),
+					...between.all(context, start, end),
+					...after.all(context, end, ...timeParams)
+				];
+				for (const row of read) rows.set(row.id, row);
+			}
+			near.set(context, [...rows.values()].sort((a, b) => a.timestamp - b.timestamp || a.id - b.id));
+		}
+		if (this.debug.enabled) this.debug(`clip covering ${clause.cells} cells -> ${inside.length} rows -> ${near.size} contexts`);
+		return near;
+	}
+	/**
 	* Split a context's positions into segments, breaking where the recording
 	* stopped for longer than `segmentGap` — an overnight stop should not draw a
 	* straight line across the anchorage.