@signalk/tracks-plugin 3.2.0 → 3.4.0

package/README.md

@@ -49,29 +49,51 @@ other track, filtered by vessel, time window and area, but as a feature of its o
 it names a vessel the plugin also records. It is never merged with a history provider's data,
 never removed by the retention settings, and never returned by the v1 routes, which answer
 where vessels are now. Its own name and any other properties it was posted with come back as
-posted.
-
-A track needs times (`coordTimes`) or a vessel (`context`). One with neither is refused:
-it would match no time window, and a query across every vessel needs one, so it could
-only be found again by its id.
+posted. It carries `imported`, the time it was stored, which a recorded track does not, so a
+client drawing a vessel's recording can leave the import out of it. Imports stored by a version
+before that time was kept are dated to the first start of a version that keeps it.
+
+A timed track of the own vessel is the exception: it is the boat's own passage, logged before
+the plugin was installed or by another plotter, so it is written into the own vessel's
+recording instead of being kept as an import, and the answer is the recording's id,
+`tracks:recorded:<context>`. By default it only fills what the recording is missing: its
+points are used where the vessel has no position, from this plugin or a history provider, for
+at least five minutes, and left out elsewhere, so nothing recorded is overwritten and two
+sources are never interleaved minute by minute; while a history provider cannot be read, such an
+import is refused with a 503 rather than drawn over what it holds. Asked to replace instead, it takes the place of
+what was recorded over the same time: the positions this plugin stored there go to the recycle
+bin first, one entry per segment, and a history provider's data over that time is hidden while
+the entry is there. Restoring the entry brings both back. An untimed track of the own vessel
+stays an import, since it cannot be placed in time.
+
+A track with neither times (`coordTimes`) nor a vessel (`context`) is kept too. No time
+window or vessel query matches it, but `GET /plugins/tracks/imports` lists it with every other
+import, and `GET /signalk/v2/api/tracks/<id>` returns it.
 
 ### Importing a GPX file
 
 The Tracks webapp imports a GPX file from the **Import** form, and a client can do the same
 with `POST /plugins/tracks/imports`, the file as the request body with `Content-Type:
-application/gpx+xml`. Each track in the file
-becomes an imported track as above. Ticking **Tracks of my own vessel** (`?self=true`) files
-them under the own vessel; otherwise a track names a vessel only if the file says which, as
-the plugin's own GPX export does.
-
-A file with a track that cannot be kept is refused whole: if any track in it has neither times
-nor a vessel, nothing is stored and the reason is shown. In a timed track, points without a time are
-skipped, and the answer says how many. The route needs write access on a Signal K server that
-lets a plugin say so, and administrator rights on an older one.
+application/gpx+xml`. Each track in the file becomes an imported track as above. Ticking
+**Tracks of my own vessel** (`?self=true`) files them under the own vessel, which writes a
+timed one into the recording; otherwise a track names a vessel only if the file says which, as
+the plugin's own GPX export does. Ticking **Replace what my vessel recorded over the same time**
+as well (`onOverlap=replace`; the default is `keep`) replaces the recording rather than filling
+it.
+
+In a timed track, points without a time are skipped, and the answer says how many
+(`skippedPoints`), as it does for the points left out where the recording already has positions
+(`overlappingPoints`). A track posted through the Track API's `POST /signalk/v2/api/tracks` is
+always kept beside the recording this way, since that API has no such choice yet. The route
+needs write access on a Signal K server that lets a plugin say so, and administrator rights on
+an older one.
 
 The webapp lists every imported track, however old and whether or not it has times, next to
 the last 30 days of recorded ones, so a passage imported from years ago can be found there. It
-can be deleted there on a Signal K server that deletes tracks by id. `GET /plugins/tracks/imports` returns every imported track, and no recorded ones.
+can be deleted there on a Signal K server that deletes tracks by id.
+
+`GET /plugins/tracks/imports` returns every imported track, and no recorded ones, each with
+`imported`, the time it was stored.
 
 The Tracks webapp exports an imported track as GPX from its row, as it was imported. A client
 can download the same file from `GET /plugins/tracks/imports/<id>/track.gpx`, with the id less

package/dist/asyncTrackStore.d.ts

@@ -1,6 +1,6 @@
 import { TrackStore } from './store.js';
 import { SqliteStoreConfig } from './sqliteStore.js';
-import { Debug, Context, ImportedTrack, ImportFilter, LatLngTuple, TimeWindow, TrackParams } from './types.js';
+import { Debug, Context, ImportedTrack, ImportFilter, LatLngTuple, TimedPosition, TimeWindow, TrackParams } from './types.js';
 import { TrackQuery } from './timeWindow.js';
 interface Limits {
     maxItems?: number;
@@ -58,7 +58,7 @@ export declare class AsyncTrackStore implements TrackStore {
     initialTrack(context: Context, track: LatLngTuple[], timestamps?: number[]): void;
     prune(maxAge: number, keep?: Context): void;
     get(context: Context, window?: TimeWindow): Promise<LatLngTuple[]>;
-    getTimed(context: Context, window?: TimeWindow): Promise<import('./types.js').TimedPosition[]>;
+    getTimed(context: Context, window?: TimeWindow): Promise<TimedPosition[]>;
     getAllTracks(query?: TrackQuery): Promise<{
         context: string;
         track: LatLngTuple[];
@@ -70,6 +70,7 @@ export declare class AsyncTrackStore implements TrackStore {
         id?: number;
         known: boolean;
     }>;
+    recordTrack(context: Context, segments: TimedPosition[][], deletedAt: number, keepEmpty: boolean): Promise<number[]>;
     binImport(importId: string, span: {
         from?: number;
         to?: number;
@@ -78,8 +79,8 @@ export declare class AsyncTrackStore implements TrackStore {
     purgeFromBin(id: number): Promise<boolean>;
     binEntries(): Promise<import('./types.js').BinEntry[]>;
     deletedSpans(): Promise<import('./types.js').RecordedSpan[]>;
-    getImport(id: string): Promise<ImportedTrack | undefined>;
-    findImports(filter?: ImportFilter): Promise<ImportedTrack[]>;
+    getImport(id: string): Promise<import('./types.js').StoredImport | undefined>;
+    findImports(filter?: ImportFilter): Promise<import('./types.js').StoredImport[]>;
     close(): Promise<void>;
 }
 export {};

package/dist/import.js

@@ -10,12 +10,26 @@ import { refusal } from './bin.js'
 /** Relative, because the server mounts this page under /@signalk/tracks-plugin. */
 const IMPORT_URL = '../../plugins/tracks/imports'
 
+const points = (count) => `${count} point${count === 1 ? '' : 's'}`
+
 /** What an import came to, in words. */
-export function imported({ ids, skippedPoints }) {
-  const count = `Imported ${ids.length} track${ids.length === 1 ? '' : 's'}.`
-  return skippedPoints > 0
-    ? `${count} ${skippedPoints} point${skippedPoints === 1 ? '' : 's'} without a time left out.`
-    : count
+export function imported({ ids, skippedPoints, overlappingPoints = 0 }) {
+  return [
+    `Imported ${ids.length} track${ids.length === 1 ? '' : 's'}.`,
+    ...(skippedPoints > 0 ? [`${points(skippedPoints)} without a time left out.`] : []),
+    ...(overlappingPoints > 0 ? [`${points(overlappingPoints)} left out where your vessel already has a track.`] : []),
+  ].join(' ')
+}
+
+/**
+ * The upload's query. Only the own vessel's tracks go into a recording, so
+ * replacing is offered for those alone; the route keeps by default.
+ */
+export function importQuery({ self, replace }) {
+  if (!self) {
+    return ''
+  }
+  return replace ? '?self=true&onOverlap=replace' : '?self=true'
 }
 
 async function messageOf(response) {
@@ -31,6 +45,13 @@ export function start() {
   const form = document.getElementById('import-form')
   const status = document.getElementById('import-status')
   const button = form.querySelector('button[type="submit"]')
+  const { self, replace } = form.elements
+  // Only the own vessel has a recording to replace.
+  const allowReplace = () => {
+    replace.disabled = !self.checked
+  }
+  allowReplace()
+  self.addEventListener('change', allowReplace)
 
   function show(message, state) {
     // A failed upload can be tried again; a successful one reloads the page.
@@ -58,7 +79,7 @@ export function start() {
       show('Choose a GPX file first.', 'error')
       return
     }
-    const query = form.elements.self.checked ? '?self=true' : ''
+    const query = importQuery({ self: self.checked, replace: replace.checked })
     button.disabled = true
     show('Importing…')
     let response

package/dist/importedTracks.d.ts

@@ -14,9 +14,8 @@ export declare const isImportedId: (id: string) => boolean;
  * thinning and window code assume time order, and a segment boundary is a gap
  * in recording, so segments are never merged or reordered.
  *
- * Refuses a track with neither times nor a vessel. Such a track answers no
- * time window, and the server refuses a query across all vessels without one,
- * so it could only ever be found again by an id the client would have to keep.
+ * A track with neither times nor a vessel answers no time window and no
+ * vessel query; the plugin's import list and its id are what find it again.
  */
 export declare function toImportedTrack(track: TrackImport, id?: string): ImportedTrack;
 /**
@@ -27,7 +26,6 @@ export declare function toImportedTrack(track: TrackImport, id?: string): Import
  * becomes an untimed import; a file with some keeps only its timed points,
  * because an import is timed throughout or not at all, and its times are what
  * let a query find it. `context` names the vessel in place of the file's own.
- * Refused, like any import, when it ends up with neither times nor a vessel.
  */
 export declare function fromGpxTrack(gpx: GpxTrack, context?: string | undefined, id?: string): {
     track: ImportedTrack;

package/dist/index.html

@@ -31,6 +31,10 @@
         <form id="import-form">
           <label>GPX file <input type="file" name="file" accept=".gpx,application/gpx+xml" required /></label>
           <label><input type="checkbox" name="self" /> Tracks of my own vessel</label>
+          <label
+            ><input type="checkbox" name="replace" /> Replace what my vessel recorded over the same time (it goes to the
+            recycle bin)</label
+          >
           <button type="submit">Import</button>
         </form>
         <p id="import-status" role="status" hidden></p>