@signalk/tracks-plugin 3.0.0-beta.0 → 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/timeWindow.d.ts

@@ -30,6 +30,24 @@ export declare function parseTrackQuery(query: Record<string, unknown>, now?: nu
  * the first and last so the track keeps its extent.
  */
 export declare function thin(points: TimedPosition[], resolution: number | undefined): TimedPosition[];
+/**
+ * Thin to at most `maxPoints`, widening the spacing until the budget fits.
+ *
+ * A budget, not a fidelity contract: the caller has said how many points it can
+ * afford to transfer and draw, whatever shape the track is. Returns the
+ * resolution actually applied so the response can report it — a client that is
+ * given 29 points instead of the 546 it would otherwise have received should be
+ * able to see the spacing that produced them.
+ *
+ * Widening by doubling from the span-derived estimate rather than binary
+ * searching: `thin` keeps the first point and the last unconditionally, so the
+ * count is not a clean function of the spacing and an exact solve would be
+ * false precision. Two or three passes settle it in practice.
+ */
+export declare function thinToBudget(points: TimedPosition[], maxPoints: number, resolution: number | undefined): {
+    points: TimedPosition[];
+    resolution: number | undefined;
+};
 /**
  * Split points into segments wherever recording stopped for longer than `gap`.
  *

package/dist/trackApi.d.ts

@@ -15,13 +15,15 @@ export type TrackBoundingBox = [number, number, number, number];
 /**
  * A request as the server hands it to a provider.
  *
- * Not every field is honoured here. `maxPoints`, `simplify`, `epsilon` and
- * `properties` are accepted by the API and ignored by this provider: it serves
- * positions, and has no co-recorded values to attach or geometry simplifier to
- * run. A caller gets the full, unsimplified track for the window it asked for,
- * which is a superset of what it requested rather than a wrong answer. The
- * response echoes `resolution` when one was requested, so a client can tell a
- * thinned track from a full one.
+ * Not every field is honoured here. `simplify`, `epsilon` and `properties` are
+ * accepted by the API and ignored by this provider: it serves positions, and
+ * has no co-recorded values to attach or geometry simplifier to run. Geometry
+ * comes back unsimplified, which is a superset of what such a request asked for
+ * rather than a wrong answer.
+ *
+ * `resolution` and `maxPoints` are both applied, and the response reports the
+ * spacing actually used — which is not always the one asked for, since a
+ * budget widens it.
  *
  * Simplification and co-recorded properties are tracked separately; see
  * SignalK/tracks.

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/types.d.ts

@@ -48,6 +48,16 @@ export type QueryParameters = Record<string, unknown>;
 export interface TrackParams {
     bbox: GeoBounds | null;
     radius: number | null;
+    /**
+     * Match a track on *any* position rather than its last.
+     *
+     * The v1 routes answer "vessels near here now", so they match the last
+     * position — a vessel that has left is no longer near. The v2 Track API asks
+     * a different question, "tracks that passed through this box within the
+     * window", and its contract says a vessel that crossed an hour ago and has
+     * since left still matches. Same filter, two questions.
+     */
+    intersects?: boolean;
 }
 export interface Debug {
     (...args: unknown[]): void;

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.0",
+  "version": "3.0.0-beta.2",
   "description": "Plugin to keep track of tracks of vessels",
   "type": "module",
   "exports": {
@@ -12,9 +12,15 @@
   "//main": "Signal K resolves an installed plugin by directory. Node's CJS directory resolution and the server's esm-resolve fallback both read `main`, not `exports`, so dropping this makes the plugin unloadable.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "//files": "app-icon.svg ships alongside dist because `files` is an allowlist: the app store probes the declared signalk.appIcon path inside the published tarball, so an icon left out here 404s and the plugin falls back to a placeholder.",
   "files": [
-    "dist"
+    "dist",
+    "app-icon.svg"
   ],
+  "signalk": {
+    "displayName": "Tracks",
+    "appIcon": "app-icon.svg"
+  },
   "keywords": [
     "signalk-node-server-plugin",
     "signalk-category-utility"

package/dist/source.test.d.ts

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