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

package/README.md

@@ -133,7 +133,8 @@ so thinning never shortens the track._
   ],
   "times": [["2026-08-14T09:00:00.000Z", "2026-08-14T09:01:00.000Z"]],
   "context": "vessels.urn:mrn:imo:mmsi:123456789",
-  "isSelf": true
+  "isSelf": true,
+  "name": "Own Ship"
 }
 ```
 
@@ -146,6 +147,11 @@ _`context` is the fully qualified context the track belongs to, and `isSelf` say
 the own vessel. Asking for `self` resolves the alias, so the response tells you which vessel
 `self` actually is._
 
+_`name` is a display label, the way a chart plotter shows one: `Own Ship`, or `AIS <shipname>`
+falling back to `AIS <mmsi>` and finally the raw context. It is for putting in a list — the v2
+Track API's `contextName` carries the undecorated vessel name instead, and is absent for a
+vessel that has not sent one._
+
 ---
 
 **Retrieve tracks for all vessels:**
@@ -155,7 +161,7 @@ the own vessel. Asking for `self` resolves the alias, so the response tells you
 _Every vessel the plugin holds a track for. Add `?radius=` to narrow it to vessels near your own._
 
 _Each entry carries `isSelf`, so the own vessel can be told from an AIS target without
-string-matching the context against the server's self identity._
+string-matching the context against the server's self-identity, and `name` for display._
 
 _`?times` works here too, adding a `times` array to every vessel's entry. Note that asking for
 times also segments each track on the gap threshold, so `coordinates` and `times` line up;

package/dist/e2e.test-utils.d.ts

@@ -35,6 +35,16 @@ export interface E2EOptions {
      * depends on — rather than against a provider's private storage.
      */
     plugins?: Record<string, Record<string, unknown>>;
+    /**
+     * Plugin id to pin as the server's default history provider.
+     *
+     * The server takes the *first* provider that registers as the default, so a
+     * second one installed in the server checkout — KIP registers as a history
+     * provider, and a dev checkout usually has it — silently wins and answers
+     * every unqualified history query with nothing. Naming the one the test
+     * installed makes the run independent of whatever else is lying around.
+     */
+    historyProvider?: string;
     /** Port to boot on, when a test needs its own server. */
     port?: number;
 }

package/dist/gpx.d.ts

@@ -0,0 +1,59 @@
+import { TimedPosition } from './types.js';
+/** Identity of the vessel a track belongs to, as far as it is known. */
+export interface GpxTrackIdentity {
+    /** Display label, e.g. `Own Ship` or `AIS Ariadne`. Becomes `<name>`. */
+    name: string;
+    /** Fully qualified Signal K context, when there is one. */
+    context?: string;
+}
+export interface GpxTrack extends GpxTrackIdentity {
+    /** Segments as `segment()` produces them: a recording gap starts a new one. */
+    segments: TimedPosition[][];
+}
+/**
+ * Serialise tracks as a GPX 1.1 document.
+ *
+ * Several tracks go in one file, each as its own `<trk>`. GPX allows it, and
+ * it is what makes "select three trips, export" produce one file rather than
+ * three — TimeZero writes one file per vessel, which is a choice rather than a
+ * constraint of the format.
+ *
+ * The Signal K context travels in `<extensions>`. TimeZero puts an opaque
+ * GUID there and drops the MMSI entirely, so its exports cannot round-trip an
+ * identity; carrying the context means ours can, while staying readable by
+ * anything else, since `<extensions>` is ignorable by specification.
+ */
+export declare function toGpx(tracks: GpxTrack[], now?: Date): string;
+/**
+ * Parse a GPX document into tracks.
+ *
+ * Structure follows GPX's own hierarchy: the root is `<gpx>`, tracks are its
+ * children, segments are a track's, points are a segment's. Anything else —
+ * a `<trkseg>` inside an `<extensions>` payload, a `<trk>` below the root — is
+ * not track data, and a namespace check alone cannot tell the difference,
+ * since a payload declaring no namespace inherits GPX's own.
+ *
+ * Deliberately forgiving about structure and strict about values: elements it
+ * does not recognise are ignored rather than rejected, but a coordinate that is
+ * not an `xsd:decimal` in range, or a time that is not an `xsd:dateTime`, is
+ * refused. One NaN reaching the store stretches every bounding box that track
+ * appears in.
+ *
+ * **Points are sorted by time within each segment.** TimeZero paginates its
+ * export in blocks of 150 and the block seams overlap: the last point of a
+ * block can be a few milliseconds newer than the first point of the next. Out
+ * of 5,550 points in a real export, 16 pairs are out of order, every one on a
+ * 150-point boundary. Anything downstream that assumes ordering — time-window
+ * queries, the history reconciliation — would quietly misbehave on such a file.
+ *
+ * Sorting stops at the segment boundary, deliberately: a segment is a stretch
+ * of continuous recording, and reordering points across a gap would merge two
+ * passages into one line. So `segments.flat()` is not globally sorted for a
+ * file whose segments interleave in time, and a caller that needs that must
+ * sort for itself.
+ *
+ * A document the parser rejects yields no tracks rather than throwing: this
+ * reads files the plugin did not write, and an import that fails should say so
+ * by returning nothing rather than by taking the caller down.
+ */
+export declare function fromGpx(xml: string): GpxTrack[];

package/dist/gpx.test.d.ts

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

package/dist/harness.test-utils.d.ts

@@ -34,6 +34,13 @@ export interface TestHarness {
     /** The own vessel's navigation.state, as reported by `getSelfPath`. */
     setSelfState: (state: string | undefined) => void;
     stop: () => void;
+    /**
+     * Start the same plugin instance again, with the config it was built with.
+     *
+     * A fresh harness would not do: what a restart has to show is the state the
+     * instance drops on `stop()`, which a new instance never had.
+     */
+    restart: () => void;
     /**
      * How many positions the plugin's bus subscription has accepted.
      *
@@ -57,10 +64,71 @@ export interface HarnessOptions {
     selfPosition?: LatLngTuple;
     /** Initial navigation.state for the own vessel. */
     selfState?: string;
+    /**
+     * Data-model entries other vessels' paths resolve to, keyed by full path
+     * (e.g. `vessels.urn:...:244813000.name`). Omit to stand in for an older
+     * server with no `getPath`, where track naming falls back to the MMSI.
+     */
+    paths?: Record<string, unknown>;
     /**
      * Stand in for a server without the v2 Track API, to check the plugin still
      * starts when `registerTrackApiProvider` is absent.
      */
     withoutTrackApi?: boolean;
+    /**
+     * A history provider for the plugin to reconcile against.
+     *
+     * `contexts` is what `getContexts` lists, and `rows` what `getValues`
+     * returns — separately, because the difference between them is the whole
+     * point of the existence probe: a provider can know a vessel and still have
+     * no rows inside the asked window.
+     *
+     * `contextsSince` back-dates those contexts: a real provider filters its
+     * context list by the asked range (questdb builds a `WHERE` from it), so a
+     * stub that answers regardless of range cannot show what the probe misses.
+     * `getContextsRejects` and `getContextsHangs` cover the other two ways a
+     * provider can fail to answer.
+     */
+    history?: {
+        /** Read on every `getContexts` call, so a getter can count the probes. */
+        contexts?: string[];
+        contextsSince?: number;
+        rows?: unknown[];
+        withoutGetContexts?: boolean;
+        getContextsRejects?: boolean;
+        getContextsHangs?: boolean;
+        /**
+         * Hold every `getContexts` call open until the returned release is run.
+         *
+         * A provider that answers immediately cannot distinguish sharing an
+         * in-flight query from reusing a cached result: the first caller would
+         * have filled the cache before the rest arrived. Deferring the answer
+         * parks every caller inside the probe at once, so only sharing can
+         * collapse them.
+         */
+        deferContexts?: {
+            release: () => void;
+            wait: Promise<void>;
+        };
+        /** Fail the windowed read, leaving the provider unable to answer at all. */
+        getValuesRejects?: boolean;
+        /**
+         * Reject `getHistoryApi` itself, as the server does when no provider is
+         * registered — the default install, and not an outage.
+         */
+        noProvider?: boolean;
+        /** Never resolve `getHistoryApi`: a registered provider that wedges. */
+        providerHangs?: boolean;
+    };
 }
+/**
+ * A promise held open until a test releases it.
+ *
+ * Lets a test observe that every request has reached the provider before any
+ * answer exists, which a timed wait can only assume.
+ */
+export declare function deferred(): {
+    release: () => void;
+    wait: Promise<void>;
+};
 export declare function createHarness(options?: HarnessOptions): TestHarness;

package/dist/index.d.ts

@@ -29,6 +29,19 @@ interface HistoryValuesQuery {
 }
 interface HistoryApi {
     getValues(query: HistoryValuesQuery): Promise<HistoryValuesResponse>;
+    /**
+     * Contexts the provider holds data for, within a time range.
+     *
+     * Optional here though the upstream interface requires it: a provider
+     * registered against an older server-api may not implement it, and a missing
+     * method must degrade rather than throw.
+     */
+    getContexts?(query: HistoryContextsQuery): Promise<unknown[]>;
+}
+/** `ContextsRequest` upstream: a time range, with Instants rather than strings. */
+interface HistoryContextsQuery {
+    from: Temporal.Instant;
+    to: Temporal.Instant;
 }
 interface HistoryValuesResponse {
     context: string;
@@ -49,6 +62,14 @@ interface App {
         };
     };
     getSelfPath: (path: string) => unknown;
+    /**
+     * Read any path in the full data model, including other vessels'.
+     *
+     * `getSelfPath` only reaches the own vessel, so naming an AIS track needs
+     * this. Optional: absent on older servers, where tracks fall back to the
+     * MMSI parsed out of the context.
+     */
+    getPath?: (path: string) => unknown;
     selfContext: string;
     /** Shown against the plugin in the server's dashboard. Absent on older servers. */
     setPluginStatus?: (msg: string) => void;
@@ -105,6 +126,8 @@ interface TracksPluginConfig {
     pauseWhenState?: string[];
 }
 export default function ThePlugin(app: App): Plugin;
+export { fromGpx, toGpx } from './gpx.js';
+export type { GpxTrack, GpxTrackIdentity } from './gpx.js';
 export { Tracks, TrackAccumulator } from './tracks.js';
 export type { TracksConfig } from './tracks.js';
 export type { TrackStore } from './store.js';

package/dist/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Tracks</title>
+    <link rel="stylesheet" href="./style.css" />
+  </head>
+  <body>
+    <header>
+      <h1>Tracks</h1>
+      <p id="status" role="status">Loading…</p>
+    </header>
+    <main>
+      <table id="tracks" hidden>
+        <thead>
+          <tr>
+            <th scope="col">Vessel</th>
+            <th scope="col">From</th>
+            <th scope="col">To</th>
+            <th scope="col" class="num">Points</th>
+            <th scope="col">Export</th>
+          </tr>
+        </thead>
+        <tbody></tbody>
+      </table>
+    </main>
+    <script type="module" src="./tracks.js"></script>
+  </body>
+</html>