@signalk/tracks-plugin 3.1.0 → 3.2.0

package/dist/reconcile.d.ts

@@ -14,3 +14,14 @@ export interface ReconcileResult {
  * bucket.
  */
 export declare function reconcile(history: TimedPosition[], stored: TimedPosition[], resolution: number): ReconcileResult;
+/**
+ * Merge history that is coarser than the store into it, the store first.
+ *
+ * The rule above holds while history is the finer source. A history read
+ * widened to stay within its bucket budget is not: one of its buckets spans
+ * several stored fixes, and letting it win would replace them all with one
+ * point. So here the store keeps every bucket it has a point in, and history
+ * fills only the buckets the store has nothing for — where the provider
+ * recorded before this plugin was installed, or while it was off.
+ */
+export declare function fillFromHistory(history: TimedPosition[], stored: TimedPosition[], resolution: number): ReconcileResult;

package/dist/recycleBin.d.ts

@@ -0,0 +1,20 @@
+import { DeletedSpan, TimedPosition } from './types.js';
+/**
+ * Prefix of a recorded track's id. The rest is the vessel's context: a vessel
+ * has one recording, so its context is all an id needs, and a provider may
+ * derive the id from it, as the server's Track API foresees.
+ */
+export declare const RECORDED_PREFIX = "recorded:";
+export declare const recordedId: (context: string) => string;
+/** The context a recorded track's id names, or undefined for any other id. */
+export declare const recordedContext: (id: string) => string | undefined;
+/**
+ * The points outside every deleted span.
+ *
+ * Applied to what a history provider returns, which this plugin cannot delete
+ * from: without it the next query would fill a deleted span back in. A
+ * history point stands for a bucket starting at its timestamp, and the fix it
+ * carries can lie anywhere in that bucket, so a bucket that overlaps a span at
+ * all is dropped; the store's own points answer for the rest of it.
+ */
+export declare function outsideSpans(points: TimedPosition[], spans: readonly DeletedSpan[]): TimedPosition[];

package/dist/recycleBin.test.d.ts

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

package/dist/recycleBinApi.test.d.ts

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

package/dist/sqliteStore.d.ts

@@ -1,6 +1,6 @@
 import { TrackQuery } from './timeWindow.js';
 import { TrackStore } from './store.js';
-import { Context, Debug, LatLngTuple, TimedPosition, TimedTrackCollection, TimeWindow, TrackCollection, TrackParams } from './types.js';
+import { BinEntry, Context, Debug, ImportedTrack, ImportFilter, LatLngTuple, RecordedSpan, RestoreResult, TimedPosition, TimedTrackCollection, TimeWindow, TrackCollection, TrackParams } from './types.js';
 export declare class TransactionStateError extends Error {
 }
 export interface SqliteStoreConfig {
@@ -17,6 +17,8 @@ export interface SqliteStoreConfig {
     resolution?: number;
     /** Drop positions older than this many ms. 0 keeps everything. */
     retention?: number;
+    /** Purge a recycle bin entry this many ms after its delete. 0 never purges. */
+    binRetention?: number;
     /** Cells per bounding box covering. */
     maxCells?: number;
     /** A gap longer than this ms starts a new track segment. */
@@ -38,9 +40,11 @@ export declare class SqliteTrackStore implements TrackStore {
     private readonly insert;
     private readonly insertName;
     private readonly selectName;
+    private readonly selectImportedPoints;
     private readonly maxCells;
     private readonly segmentGap;
     private readonly retention;
+    private readonly binRetention;
     private readonly resolution;
     /** See CLIP_STRETCH_GAP; widened so a coarse write resolution does not split every fix. */
     private readonly stretchGap;
@@ -123,6 +127,59 @@ export declare class SqliteTrackStore implements TrackStore {
     recordName(context: Context, name: string, timestamp?: number): void;
     nameFor(context: Context): string | undefined;
     prune(maxAge: number, keep?: Context, now?: number): void;
+    /**
+     * Keep an imported track. The caller mints the id; a second track under the
+     * same id fails rather than replacing the first.
+     */
+    storeImport(track: ImportedTrack): void;
+    /**
+     * Move a vessel's positions recorded within `[from, to]` into the recycle
+     * bin, resolving to the entry's id and whether the store held the vessel at
+     * all.
+     *
+     * An entry is made even when the store holds nothing there if `keepEmpty`
+     * says another source does: the span still has to hide what a history
+     * provider holds. Without one, an empty delete leaves no entry behind.
+     */
+    binRecorded(context: Context, from: number | undefined, to: number, deletedAt: number, keepEmpty: boolean): {
+        id?: number;
+        known: boolean;
+    };
+    /**
+     * Move an imported track into the recycle bin, or with a span only its
+     * points within it, resolving to the entry's id; undefined when there is no
+     * such import, or the span holds none of its points.
+     */
+    binImport(importId: string, span: {
+        from?: number;
+        to?: number;
+    } | undefined, deletedAt: number): number | undefined;
+    private newBinEntry;
+    /**
+     * Put a recycle bin entry's rows back where they were deleted from.
+     *
+     * A span of an import whose whole track has since gone to the bin as well
+     * is a conflict: its points have no track to return to until that is
+     * restored first.
+     */
+    restoreFromBin(id: number): RestoreResult;
+    /** Purge one recycle bin entry now, resolving whether it was in the bin. */
+    purgeFromBin(id: number): boolean;
+    /** Entries still in the recycle bin, newest delete first. */
+    binEntries(): BinEntry[];
+    /** Every deleted span of a recorded track, purged or not: what history must not show. */
+    deletedSpans(): RecordedSpan[];
+    private liveEntry;
+    /**
+     * Remove an entry's rows for good. A recorded span stays as a tombstone, so
+     * history cannot refill it; a whole import takes the spans deleted from it
+     * earlier with it, since they have no track left to be restored into.
+     */
+    private purge;
+    getImport(id: string): ImportedTrack | undefined;
+    /** Imported tracks the filter lets through, in the order they were stored. */
+    findImports(filter?: ImportFilter): ImportedTrack[];
+    private importFrom;
     /** Worker startup snapshot; queries and name lookups must not open a second database. */
     storedNames(): {
         context: string;

package/dist/store.d.ts

@@ -1,4 +1,4 @@
-import { Context, Debug, LatLngTuple, TimedPosition, TimedTrackCollection, TimeWindow, TrackCollection, TrackParams } from './types.js';
+import { BinEntry, Context, Debug, ImportedTrack, ImportFilter, LatLngTuple, RecordedSpan, RestoreResult, TimedPosition, TimedTrackCollection, TimeWindow, TrackCollection, TrackParams } from './types.js';
 import { TrackQuery } from './timeWindow.js';
 /**
  * A track store: somewhere positions are accumulated and queried back.
@@ -86,6 +86,43 @@ export interface TrackStore {
      * keeps it out of a real configuration.
      */
     prune(maxAge: number, keep?: Context): void;
+    /**
+     * Keep a track a client imported. Optional: a store that only records what
+     * it observes leaves the four import methods out, and the Track API then
+     * answers that storing tracks is not supported.
+     *
+     * Resolves once the track is durably stored, unlike the recording writes
+     * above: the caller hands its id to a client, which must be able to read it
+     * back at once.
+     */
+    storeImport?(track: ImportedTrack): void | Promise<void>;
+    getImport?(id: string): ImportedTrack | undefined | Promise<ImportedTrack | undefined>;
+    findImports?(filter?: ImportFilter): ImportedTrack[] | Promise<ImportedTrack[]>;
+    /**
+     * The recycle bin. Optional like the import methods: a store without it
+     * cannot delete. A delete moves rows into the bin rather than removing them,
+     * and each of these resolves once committed, like `storeImport`.
+     *
+     * `binRecorded` moves a vessel's positions recorded within `[from, to]`;
+     * `binImport` moves an imported track, or only its points within a span.
+     */
+    binRecorded?(context: Context, from: number | undefined, to: number, deletedAt: number, keepEmpty: boolean): {
+        id?: number;
+        known: boolean;
+    } | Promise<{
+        id?: number;
+        known: boolean;
+    }>;
+    binImport?(importId: string, span: {
+        from?: number;
+        to?: number;
+    } | undefined, deletedAt: number): number | undefined | Promise<number | undefined>;
+    restoreFromBin?(id: number): RestoreResult | Promise<RestoreResult>;
+    /** Purge an entry now, resolving whether it was in the bin. */
+    purgeFromBin?(id: number): boolean | Promise<boolean>;
+    binEntries?(): BinEntry[] | Promise<BinEntry[]>;
+    /** Every deleted span of a recorded track, purged or not: what history must not show. */
+    deletedSpans?(): RecordedSpan[] | Promise<RecordedSpan[]>;
     /**
      * Release any resources held by the store.
      *

package/dist/style.css

@@ -47,3 +47,81 @@ tbody tr:hover {
 .self {
   font-weight: 600;
 }
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+h2 {
+  font-size: 1.1rem;
+  margin: 2rem 0 0.25rem;
+}
+
+#import-form {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem 1rem;
+}
+
+#bin-status,
+#import-status {
+  color: GrayText;
+  margin: 0 0 1rem;
+}
+
+.error,
+#bin-status[data-state='error'],
+#import-status[data-state='error'] {
+  color: crimson;
+}
+
+.imported {
+  color: GrayText;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.danger {
+  color: crimson;
+}
+
+dialog {
+  max-width: min(32rem, calc(100vw - 2rem));
+}
+
+dialog h2 {
+  margin-top: 0;
+}
+
+dialog fieldset {
+  display: grid;
+  gap: 0.5rem;
+  border: none;
+  padding: 0;
+  margin: 0 0 1rem;
+}
+
+dialog .span {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem 1rem;
+  margin-left: 1.5rem;
+}
+
+dialog menu {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.5rem;
+  padding: 0;
+  margin: 0;
+}

package/dist/trackApi.d.ts

@@ -8,7 +8,10 @@ import { Temporal } from '@js-temporal/polyfill';
  * imports when it is.
  *
  * Specified in https://github.com/SignalK/signalk-server/issues/2504 and
- * implemented in https://github.com/SignalK/signalk-server/pull/2995.
+ * implemented in https://github.com/SignalK/signalk-server/pull/2995; storing,
+ * fetching and deleting a track by id in
+ * https://github.com/SignalK/signalk-server/pull/3038, and deleting part of
+ * one in the server's `deleteTrackSpan`.
  */
 /** `[west, south, east, north]` — GeoJSON coordinate order. */
 export type TrackBoundingBox = [number, number, number, number];
@@ -47,11 +50,18 @@ export interface TracksRequest {
     geometry?: boolean;
 }
 export interface TrackProperties {
-    context: string;
-    isSelf: boolean;
+    /** Identifies a stored track within this provider; recorded tracks carry none. */
+    id?: string;
+    /** Absent for an imported track that names no vessel. */
+    context?: string;
+    /** Absent along with `context`. */
+    isSelf?: boolean;
     contextName?: string;
-    from: string;
-    to: string;
+    /** The track's own name, as an imported GPX `<trk><name>` carries. */
+    name?: string;
+    /** Absent, with `to`, for a track whose points carry no times. */
+    from?: string;
+    to?: string;
     bbox?: TrackBoundingBox;
     pointCount: number;
     resolution?: string;
@@ -59,6 +69,8 @@ export interface TrackProperties {
     coordTimes?: string[][];
     appliedProperties?: string[];
     values?: Record<string, (number | string | null)[][]>;
+    /** Whatever else an imported track was posted with, returned as posted. */
+    [key: string]: unknown;
 }
 export interface TrackFeature {
     type: 'Feature';
@@ -76,6 +88,50 @@ export interface TracksResponse {
 export interface TrackApi {
     getTracks(query: TracksRequest): Promise<TracksResponse>;
     getTrackContexts(query: TracksRequest): Promise<string[]>;
+    /** One stored track by id, or undefined when there is none. */
+    getTrack?(id: string): Promise<TrackFeature | undefined>;
+    /** Keep a track a client supplied, resolving to the id it was given. */
+    storeTrack?(track: TrackImport): Promise<string>;
+    /** Delete a stored track by id, resolving false when there is none. */
+    deleteTrack?(id: string): Promise<boolean>;
+    /** Delete the part of a stored track recorded within `span`, resolving false when there is no such track. */
+    deleteTrackSpan?(id: string, span: TrackSpan): Promise<boolean>;
+}
+/** Every point recorded at or after `from` and at or before `to`; an absent bound is open. */
+export interface TrackSpan {
+    from?: Temporal.Instant;
+    to?: Temporal.Instant;
+}
+/**
+ * A track offered for storage, in the canonical form the server reduces every
+ * import to: a MultiLineString, `coordTimes` nested to match it and in UTC, a
+ * qualified context, and none of the properties a provider derives itself.
+ */
+export interface TrackImport {
+    type: 'Feature';
+    geometry: {
+        type: 'MultiLineString';
+        coordinates: [number, number][][];
+    };
+    properties: TrackImportProperties;
+}
+export interface TrackImportProperties {
+    coordTimes?: string[][];
+    name?: string;
+    context?: string;
+    /** The client's own metadata, stored as posted. */
+    [key: string]: unknown;
+}
+/**
+ * Thrown by `storeTrack` when this provider will not keep the track, which
+ * the server answers with a 400 rather than a 500.
+ *
+ * The server recognises it by `isTrackRejected` rather than by class, since
+ * this is a copy of its own.
+ */
+export declare class TrackRejectedError extends Error {
+    readonly isTrackRejected: true;
+    constructor(message?: string);
 }
 /** Present on servers that carry the Track API; absent on older ones. */
 export interface WithTrackApi {

package/dist/trackProvider.d.ts

@@ -49,6 +49,10 @@ export interface TrackProviderDeps {
      * only before this plugin was installed is known to history alone.
      */
     historyContexts: (window: TimeWindow | undefined) => Promise<ReadonlySet<string>>;
+    /** Whether a history provider holds anything at all for a context. */
+    historyKnows: (context: string) => Promise<boolean>;
+    /** Called after a delete, so whatever hides deleted spans from history reloads them. */
+    deleted: () => void;
     reconcileWithHistory: (context: string, stored: TimedPosition[], window: TimeWindow | undefined, resolutionMs: number | undefined) => Promise<TimedPosition[]>;
 }
 export declare function createTrackProvider(deps: TrackProviderDeps): TrackApi;

package/dist/trackStoreProtocol.d.ts

@@ -1,5 +1,5 @@
 import { SqliteTrackStore } from './sqliteStore.js';
-export type StoreMethod = 'newPosition' | 'recordName' | 'initialTrack' | 'prune' | 'get' | 'getTimed' | 'getAllTracks' | 'getFilteredTracks' | 'getFilteredTimedTracks' | 'close';
+export type StoreMethod = 'newPosition' | 'recordName' | 'initialTrack' | 'prune' | 'get' | 'getTimed' | 'getAllTracks' | 'getFilteredTracks' | 'getFilteredTimedTracks' | 'storeImport' | 'getImport' | 'findImports' | 'binRecorded' | 'binImport' | 'restoreFromBin' | 'purgeFromBin' | 'binEntries' | 'deletedSpans' | 'close';
 export type Operation = {
     [K in StoreMethod]: {
         id: number;