@signalk/tracks-plugin 3.0.0-beta.5 → 3.0.0-beta.7

package/dist/sqliteStore.d.ts

@@ -34,6 +34,8 @@ export interface SqliteStoreConfig {
 export declare class SqliteTrackStore implements TrackStore {
     private readonly db;
     private readonly insert;
+    private readonly insertName;
+    private readonly selectName;
     private readonly maxCells;
     private readonly segmentGap;
     private readonly retention;
@@ -92,6 +94,8 @@ export declare class SqliteTrackStore implements TrackStore {
      * straight line across the anchorage.
      */
     segments(context: Context, window?: TimeWindow): LatLngTuple[][];
+    recordName(context: Context, name: string, timestamp?: number): void;
+    nameFor(context: Context): string | undefined;
     prune(maxAge: number, keep?: Context): void;
     close(): void;
     /** Unsigned round-trip check, used by the tests. */

package/dist/store.d.ts

@@ -51,6 +51,21 @@ 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>;
+    /**
+     * Remember the name a context is currently known by.
+     *
+     * Names are resolved live from the server's data model on every request,
+     * because an AIS static report can arrive long after the first position. But
+     * the model is empty after a restart, so a track recorded for months would
+     * show as a bare MMSI until the vessel next transmits — and never again for
+     * one that has since left. Storing what was known closes that gap.
+     *
+     * `timestamp` dates the observation so a later report replaces an earlier
+     * one rather than the first sighting winning forever.
+     */
+    recordName(context: Context, name: string, timestamp?: number): void;
+    /** The last name stored for a context, or undefined if none ever was. */
+    nameFor(context: Context): string | undefined;
     /**
      * Drop contexts whose newest position is older than `maxAge` ms.
      *

package/dist/timeWindow.d.ts

@@ -24,7 +24,7 @@ export interface TrackQuery {
  * `timespan`/`timespanOffset` pair. Absent all of them, no window is applied
  * and the whole retained track is returned, as before.
  */
-export declare function parseTrackQuery(query: Record<string, unknown>, now?: number): TrackQuery;
+export declare function parseTrackQuery(query: Record<string, unknown>, now?: number, alsoAllowed?: readonly string[]): TrackQuery;
 /**
  * Drop points closer together than `resolution` milliseconds, always keeping
  * the first and last so the track keeps its extent.

package/dist/tracks.d.ts

@@ -47,6 +47,16 @@ 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>;
+    /**
+     * Remembered names, by context.
+     *
+     * In memory only: this store is the client-side accumulator, so there is no
+     * restart for a stored name to survive. It implements the same contract so
+     * the two stores stay interchangeable and the plugin needs no special case.
+     */
+    private readonly names;
+    recordName(context: Context, name: string, timestamp?: number): void;
+    nameFor(context: Context): string | undefined;
     prune(maxAge: number, keep?: Context): void;
 }
 interface AccumulatorParams {

package/dist/utils.d.ts

@@ -25,6 +25,25 @@ export declare function createInBounds(bounds: GeoBounds): (position: LatLngTupl
  * iterate the result.
  */
 export declare function splitAtAntimeridian(bounds: GeoBounds): GeoBounds[];
+/**
+ * A query parameter was present but malformed.
+ *
+ * Distinct from absent: a filter nobody asked for is not an error, but one
+ * that cannot be honoured must not quietly widen the query. Carries its own
+ * message so the handler can hand it to the client, the way `TimeWindowError`
+ * already does for the time window.
+ */
+export declare class QueryParameterError extends Error {
+}
+/**
+ * A well-formed query the server cannot currently answer.
+ *
+ * `radius` measures from the own vessel, so it needs a self position. Not
+ * having one is an outage, not a client mistake -- the same distinction the
+ * single-vessel route already draws for a history provider it cannot read.
+ */
+export declare class SelfPositionUnavailableError extends Error {
+}
 export declare function validateParameters(params: QueryParameters, defaultMaxRadius: number | undefined): TrackParams;
 export declare function createDistanceTo([lat1d, lon1d]: LatLngTuple, debug?: Debug): (d: LatLngTuple | null) => number;
 export declare function resolveContext(vesselId: string, selfContext?: string): string;
@@ -70,6 +89,8 @@ export declare function contextName(context: string, lookup: (path: string) => u
  * context, because a label has to render something.
  */
 export declare function trackLabel(context: string, selfContext: string | undefined, lookup: (path: string) => unknown): string;
+/** Accepts both a bare string and the `{value}` wrapper deltas arrive in. */
+export declare function unwrapString(raw: unknown): string | undefined;
 /**
  * A track label as a filename a browser can save.
  *

package/docs/history-and-storage.md

@@ -0,0 +1,94 @@
+# Where a track comes from
+
+The plugin can answer a query from two places: its own store, and a history
+provider such as [signalk-questdb](https://www.npmjs.com/package/signalk-questdb)
+or [signalk-to-influxdb2](https://www.npmjs.com/package/signalk-to-influxdb2).
+Neither is simply better than the other, which is why both are used.
+
+|                              | The plugin's store                 | A history provider                               |
+| ---------------------------- | ---------------------------------- | ------------------------------------------------ |
+| How often a position is kept | coarse, at a configurable interval | fine, at whatever interval it was configured for |
+| How long it is kept          | see below                          | until its retention drops it                     |
+| Size                         | small                              | far larger, which is why retention exists        |
+
+The plugin writes its positions to a SQLite file in its data directory, so they
+survive a restart. How long they are kept depends on two settings: the own
+vessel's track is kept indefinitely by default, and another vessel is dropped
+30 days after its last fix.
+
+So the provider is the finer record of the recent past, and the plugin's store
+is what remains of everything older. The interval and the retention are both
+settings on the plugin's configuration page, which is where their current
+defaults are shown.
+
+## What you get with no history provider
+
+Everything comes from the plugin's own store, at whatever interval it is
+configured to keep, for as far back as it has been running. Nothing else is needed, and no other plugin has to
+be installed.
+
+```
+query window
+├──────────────────────────────────────────────────┤
+│ plugin store, at the configured interval          │
+```
+
+## What you get with one
+
+The provider answers for the period it covers, and the plugin's store fills
+everything else.
+
+```
+query window: last two years
+├───────────────────────────────────────┬──────────┤
+│ plugin store, coarse                  │ provider │
+│                                       │ finer    │
+                                        └ retention begins
+```
+
+A track can therefore change granularity partway along: coarse where it came
+from the store, fine where the provider reached. That is expected. Passing
+`resolution` on a query thins the result to a spacing you choose, which is the
+way to get an evenly spaced track regardless of where each part came from.
+
+## When the provider has holes
+
+Retention is only one way a provider's coverage can be incomplete. All of these
+happen, and all are handled the same way:
+
+- it was installed after the boat had already been recording
+- it was disabled for a while, or its database was down
+- its retention has dropped the older data
+
+In each case the provider simply returns nothing for that period, and the
+plugin's store supplies it instead:
+
+```
+├─────────┬──────────────┬─────────┬──────────────┤
+│ store   │ provider     │ store   │ provider     │
+│         │              │ ↑ provider was down    │
+```
+
+Nothing has to be configured for this. The plugin does not read the provider's
+retention setting, or ask how long it has been running — it asks for the window
+and uses what comes back, so coverage that changes underneath needs no
+attention.
+
+## Why the two never double up
+
+A provider aggregates into buckets and stamps each one on its boundary:
+`19:00:00.000`, `19:01:00.000`. The plugin's store keeps the time a fix
+actually arrived: `19:00:01.212`. The same physical position therefore has two
+different timestamps in the two sources, and simply merging them would keep
+both.
+
+Instead, each bucket of time is filled from exactly one source: the provider
+where it has a position, the store everywhere else. Individual points are never
+compared, so there is nothing to get wrong.
+
+## If a vessel was not moving
+
+Neither source has anything, and the track is correctly empty for that period
+rather than filled in. A gap in a track means the vessel was not being
+recorded — which, with the **Pause recording while navigation.state is one of**
+setting, may be deliberate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalk/tracks-plugin",
-  "version": "3.0.0-beta.5",
+  "version": "3.0.0-beta.7",
   "description": "Plugin to keep track of tracks of vessels",
   "type": "module",
   "exports": {
@@ -14,12 +14,17 @@
   "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": [
+    "app-icon.svg",
     "dist",
+    "docs",
     "public"
   ],
   "signalk": {
     "displayName": "Tracks",
-    "appIcon": "./app-icon.svg"
+    "appIcon": "./app-icon.svg",
+    "screenshots": [
+      "./docs/screenshots/tracks_1.png"
+    ]
   },
   "keywords": [
     "signalk-node-server-plugin",