@signalk/tracks-plugin 3.0.0-beta.1 → 3.0.0-beta.2

package/dist/sqliteStore.d.ts

@@ -55,16 +55,20 @@ export declare class SqliteTrackStore implements TrackStore {
         track: LatLngTuple[];
     }[]>;
     /**
-     * Tracks whose last position matches the spatial predicate.
+     * Tracks matching the spatial predicate, which depends on who is asking.
+     *
+     * `intersects: false` — the v1 routes — matches a track's *last* position:
+     * "which vessels are near me now". `intersects: true` — the v2 Track API —
+     * matches a track that passed through the box at any point in the window,
+     * including one that has since left.
      *
      * Two filters run, and they are not redundant despite both testing bounds:
      *
      * - `contextsInBounds` asks the cell index which contexts have *any* position
      *   near the box. It is a cheap prefilter that keeps the query off every row
      *   in the table, and it decides nothing on its own.
-     * - `matcher` — the same predicate the in-memory store uses — then tests each
-     *   track's *last* position, which is what the endpoint actually means by
-     *   "in this box". That test is authoritative.
+     * - `matcher` — the same predicate the in-memory store uses — then applies
+     *   whichever rule the caller asked for. That test is authoritative.
      *
      * Because `matcher` has the final say, dropping the exact-bounds check inside
      * `contextsInBounds` does not change any result; it only widens the candidate
@@ -88,7 +92,7 @@ export declare class SqliteTrackStore implements TrackStore {
      * straight line across the anchorage.
      */
     segments(context: Context, window?: TimeWindow): LatLngTuple[][];
-    prune(maxAge: number): void;
+    prune(maxAge: number, keep?: Context): void;
     close(): void;
     /** Unsigned round-trip check, used by the tests. */
     cellIdsFor(context: Context): bigint[];

package/dist/stateGate.d.ts

@@ -1,8 +1,4 @@
 import { Context } from './types.js';
-/**
- * Off unless a user opts in, per the request and because the states worth
- * pausing on depend on how a boat is used.
- */
 export declare const DEFAULT_PAUSE_STATES: string[];
 /**
  * The states a boat is plausibly parked in, offered in the plugin UI.

package/dist/store.d.ts

@@ -8,12 +8,12 @@ import { TrackQuery } from './timeWindow.js';
  * calls in `index.ts` and nothing more, so that adding an implementation cannot
  * quietly widen what a store is expected to do.
  *
- * Note what is *not* here. `getAllTracks` and `getFilteredTracks` are derived
- * operations — filtering is a predicate over whole tracks, which the in-memory
- * implementation applies in JS and a database implementation will want to push
- * into the query. Both stay on the interface for that reason: a store that can
- * filter in SQL must be allowed to, rather than being forced to materialise
- * every track so a caller can filter it afterwards.
+ * `getAllTracks` and `getFilteredTracks` are derived operations, and they are
+ * on the interface deliberately: filtering is a predicate over whole tracks,
+ * which the in-memory implementation applies in JS and a database
+ * implementation will want to push into the query. A store that can filter in
+ * SQL must be allowed to, rather than being forced to materialise every track
+ * so a caller can filter it afterwards.
  */
 export interface TrackStore {
     /** Record a position for a context. `timestamp` defaults to now. */
@@ -21,7 +21,8 @@ export interface TrackStore {
     /**
      * Seed a context's track, replacing whatever it held.
      *
-     * Used by the History API bootstrap at startup. `timestamps` is positional
+     * A test helper: it is how a known track is installed without going through
+     * the position bus, which throttles on write. `timestamps` is positional
      * against `track`; points without one are dated to the start of time so a
      * time-window query treats them as older than anything live.
      */
@@ -50,8 +51,26 @@ export interface TrackStore {
      * "vessels currently near here" rather than "vessels that ever passed here".
      */
     getFilteredTracks(params: TrackParams, selfPosition?: LatLngTuple, debug?: Debug, query?: TrackQuery): Promise<TrackCollection>;
-    /** Drop contexts whose newest position is older than `maxAge` ms. */
-    prune(maxAge: number): void;
+    /**
+     * Drop contexts whose newest position is older than `maxAge` ms.
+     *
+     * `keep` is never pruned however long it has been idle. The own vessel's
+     * track is the one a user came for — it has to survive a winter on a
+     * mooring, a passage with the server off, and any gap in reception. Other
+     * vessels age out: a harbour puts hundreds of AIS targets past a receiver in
+     * a day, and keeping every one of them forever is not what anybody asked for.
+     *
+     * An implementation must also apply whatever row-level retention it was
+     * configured with, scoped to `keep`. The two are separate: one drops a whole
+     * vessel that has gone quiet, the other trims old points from the vessel a
+     * user is actually recording, and neither may switch the other off.
+     *
+     * `Infinity` ages nothing out, which is how a caller asks for the retention
+     * pass alone. A negative `maxAge` puts the cutoff in the future and so drops
+     * every context — the tests use `-1` for exactly that; the plugin's schema
+     * keeps it out of a real configuration.
+     */
+    prune(maxAge: number, keep?: Context): void;
     /**
      * Release any resources held by the store.
      *

package/dist/trackProvider.d.ts

@@ -1,5 +1,6 @@
 import { TrackStore } from './store.js';
 import { TrackApi } from './trackApi.js';
+import { TimedPosition, TimeWindow } from './types.js';
 /**
  * Serves the v2 Track API from this plugin's store.
  *
@@ -17,5 +18,19 @@ export interface TrackProviderDeps {
     selfContext: () => string;
     /** Gap in ms that starts a new segment; 0 leaves the track as one line. */
     segmentGap: () => number;
+    /**
+     * Positions a history provider holds for a context and window, reconciled
+     * with the store's own.
+     *
+     * Injected rather than reached for directly: the reconciliation belongs to
+     * the plugin, and the v1 routes have done it since #73 — a query answered
+     * through the v2 provider has to give the same answer as the same query
+     * answered through v1, or the plugin contradicts itself depending on which
+     * route a client happens to use.
+     *
+     * Resolves to the store's own points unchanged when no provider is
+     * installed, which is the common case.
+     */
+    reconcileWithHistory: (context: string, stored: TimedPosition[], window: TimeWindow | undefined, resolutionMs: number | undefined) => Promise<TimedPosition[]>;
 }
 export declare function createTrackProvider(deps: TrackProviderDeps): TrackApi;

package/dist/tracks.d.ts

@@ -15,9 +15,12 @@ export interface TracksConfig {
     fetchInitialTrack?: boolean;
 }
 /**
- * The in-memory store: a bounded sliding window of positions per context,
- * held in RxJS accumulators and lost on restart. `bootstrapSelfTrack()` in
- * index.ts is what re-hydrates it from a History provider at startup.
+ * The in-memory store: a bounded sliding window of positions per context, held
+ * in RxJS accumulators and lost on restart.
+ *
+ * No longer used by the plugin, which always records to SQLite. It remains as
+ * the client-side `TrackAccumulator` this package exports, where a browser
+ * holding one vessel's recent track in memory is exactly the right shape.
  */
 export declare class Tracks implements TrackStore {
     tracks: TracksMap;
@@ -44,7 +47,7 @@ export declare class Tracks implements TrackStore {
      * which tracks match — the filter runs once, here.
      */
     getFilteredTimedTracks(params: TrackParams, selfPosition?: LatLngTuple, debug?: Debug, query?: TrackQuery): Promise<TimedTrackCollection>;
-    prune(maxAge: number): void;
+    prune(maxAge: number, keep?: Context): void;
 }
 interface AccumulatorParams {
     resolution: number;

package/dist/utils.d.ts

@@ -29,3 +29,12 @@ export declare function validateParameters(params: QueryParameters, defaultMaxRa
 export declare function createDistanceTo([lat1d, lon1d]: LatLngTuple, debug?: Debug): (d: LatLngTuple | null) => number;
 export declare function resolveContext(vesselId: string, selfContext?: string): string;
 export declare function createMatcher(params: TrackParams, selfPosition?: LatLngTuple, debug?: Debug): (track: LatLngTuple[]) => boolean;
+/**
+ * A history row is `[timestamp, position]`. Both encodings are legal: the
+ * History API types a value as `unknown` and its own comment names "objects
+ * (like navigation.position)" alongside primitives, so signalk-questdb returns
+ * `{latitude, longitude}` and signalk-to-influxdb2 returns `[lon, lat]`.
+ * Accept both — neither is an error, so rejecting one silently yields an empty
+ * track rather than a failure anybody can see.
+ */
+export declare const historyRowPosition: (row: unknown) => LatLngTuple | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalk/tracks-plugin",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.2",
   "description": "Plugin to keep track of tracks of vessels",
   "type": "module",
   "exports": {

package/dist/source.test.d.ts

@@ -1 +0,0 @@
-export {};