signalk-tides 2.2.0 → 2.3.0

package/.github/mise.node24.toml

@@ -0,0 +1,3 @@
+# Lockfile checks and npm trusted publishing use Node 24.
+[tools]
+node = "24"

package/.github/workflows/ci.yml

@@ -13,6 +13,8 @@ jobs:
 
       - name: Setup Node.js
         uses: actions/setup-node@v7
+        with:
+          node-version-file: mise.toml
 
       - name: Install dependencies
         run: npm install
@@ -31,6 +33,8 @@ jobs:
 
       - name: Setup Node.js
         uses: actions/setup-node@v7
+        with:
+          node-version-file: mise.toml
 
       - name: Install dependencies
         run: npm install
@@ -54,6 +58,8 @@ jobs:
       - uses: actions/checkout@v7
 
       - uses: actions/setup-node@v7
+        with:
+          node-version-file: mise.toml
 
       - name: Install modules
         run: npm install

package/.github/workflows/lockfile.yml

@@ -0,0 +1,31 @@
+name: Lockfile
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  # A pull request can slip a package in through package-lock.json, which
+  # reviewers rarely read. npm keeps existing resolved URLs when it regenerates,
+  # so the diff alone misses a swapped tarball; lockfile-lint catches that.
+  lockfile:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .github/mise.node24.toml
+      - name: Check the lockfile regenerates from package.json
+        run: |
+          git ls-files --error-unmatch package-lock.json
+          npm install --package-lock-only --ignore-scripts
+          git diff --exit-code -- package-lock.json
+      - name: Check every package resolves from the npm registry
+        # @isaacs/cliui installs CommonJS releases of these packages under -cjs aliases.
+        run: |
+          npx -y lockfile-lint@5.0.1 --path package-lock.json --allowed-hosts npm --validate-https --validate-integrity --validate-package-names \
+            --allowed-package-name-aliases string-width-cjs:string-width strip-ansi-cjs:strip-ansi wrap-ansi-cjs:wrap-ansi

package/.github/workflows/release.yml

@@ -17,9 +17,24 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: 24 # npm >= 11.5.1 for trusted publishing
+          node-version-file: .github/mise.node24.toml # npm >= 11.5.1 for trusted publishing
           registry-url: https://registry.npmjs.org
 
+      # Before anything installs, so a preview build is neither run nor published.
+      # Overrides don't reach people installing the plugin, so these specs are
+      # what they get.
+      - name: Refuse dependencies from outside the registry
+        run: |
+          node -e '
+            const { dependencies = {}, optionalDependencies = {} } = require("./package.json");
+            const outside = Object.entries({ ...dependencies, ...optionalDependencies })
+              .filter(([, spec]) => /[:/]/.test(spec));
+            if (outside.length) {
+              console.error("Not from the registry:", Object.fromEntries(outside));
+              process.exit(1);
+            }
+          '
+
       - name: Install dependencies
         run: npm install
 

package/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+## Releasing
+
+Publishing to npm runs from [release.yml](.github/workflows/release.yml) when a GitHub release is created. A person creates the release by hand: choose or create a `vX.Y.Z` tag, then fill in the title and notes.
+
+Title and notes follow the Open Waters [release notes guidance](https://github.com/openwatersio/.github/blob/main/docs/agents/releases.md#release-notes). Write them for boaters running Signal K, not for developers reading commit subjects:
+
+- Title the release with a short headline of what changed, in sentence case with no period and no version. Patch releases get a headline too. Put a new requirement in the headline, such as "requires Node 24".
+- Open the notes with what is new and who it is for. Put breaking changes and upgrade steps first.
+- List the changes users will notice, one per bullet, each linking its pull request. Leave out chores, CI changes, and bot dependency bumps unless a runtime dependency change matters to users.

package/README.md

@@ -1,6 +1,6 @@
 # signalk-tides
 
-A SignalK plugin that provides offline tidal predictions for the vessel's position, powered by [Neaps](https://github.com/neaps/neaps).
+A SignalK plugin that provides offline tidal predictions for the vessel's position, powered by [Slackwater](https://openwaters.io/tides/slackwater/).
 
 Since 2.0, predictions are computed locally from harmonic constituents — no network access or API keys required.
 
@@ -21,12 +21,13 @@ It publishes the following [tide data](https://signalk.org/specification/1.7.0/d
 * `environment.tide.timeLow`
 * `environment.tide.heightNow`
 * `environment.tide.stationName`
+* `environment.tide.stationDistance` — metres from the vessel to the station, when it was chosen by position
 * `environment.tide.state` — tide trend, `rising` or `falling`
 * `environment.tide.timeToNextExtreme` — seconds until the next high or low water
 
 ### Tides API
 
-The plugin mounts the [Neaps API](https://github.com/neaps/neaps) at `/signalk/v2/api/tides`, which serves station search, extremes, and timeline predictions. The synthetic station `vessel/default` resolves to the configured default station, or the nearest station to the vessel when none is set:
+The plugin mounts the [Slackwater API](https://openwaters.io/api/tides/) at `/signalk/v2/api/tides`, which serves station search, extremes, and timeline predictions. The synthetic station `vessel/default` resolves to the configured default station, or the nearest station with tide predictions within 100 km when none is set or the configured one has no predictions. With none in range, the plugin publishes no tide and says so in its status, and the API answers 404:
 
 ```
 $ curl http://localhost:3000/signalk/v2/api/tides/stations/vessel/default/extremes

package/dist/calculations.js

@@ -1,3 +1,23 @@
+/**
+ * How far from the vessel a station may be and still stand in for its tide. Past
+ * this a station gives a plausible tide for other water, so the plugin publishes
+ * none. Half of the CHS positions with no model have a station that predicts
+ * within 28 km, and 184 of 1,057 have none within 100 km. This project's
+ * definition, not a published figure.
+ */
+export const MAX_STATION_KM = 100;
+/** Whether a location lookup found nothing in range. */
+export function isNoStationNearby(e) {
+    return e instanceof Error && e.message.startsWith("No stations found");
+}
+/** Whether a lookup failed on the id, rather than on loading the database. */
+export function isStationNotFound(e) {
+    return e instanceof Error && e.message.startsWith("Station not found");
+}
+// CHS stations carry identity only, and predicting from one gives a flat zero tide.
+export function hasTideModel(station) {
+    return station.harmonic_constituents.length > 0 || station.offsets !== undefined;
+}
 /**
  * Trend of the tide at `time`: "rising" if the next extreme is a High,
  * "falling" if it is a Low.

package/dist/index.js

@@ -13,16 +13,35 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createRoutes } from "@neaps/api";
-import { findStation, nearestStation, stationsNear } from "neaps";
-import { tideStateAt, timeToNextExtreme } from "./calculations.js";
+import { createRoutes } from "@slackwater/api";
+import { findStation, nearestStation, stationsNear } from "slackwater";
+import { MAX_STATION_KM, hasTideModel, isNoStationNearby, isStationNotFound, tideStateAt, timeToNextExtreme, } from "./calculations.js";
 import FileCache from "./cache.js";
 import { withVesselPosition } from "./middleware.js";
 import { PLOTTER_EXTENSION_ID, plotterExtensionManifest, } from "./plotter-extension.js";
 // Recompute and republish on a fixed interval. Predictions are computed locally
-// by neaps, so this is cheap and needs no configuration.
+// by slackwater, so this is cheap and needs no configuration.
 const UPDATE_INTERVAL = 60 * 1000; // 1 minute
 const API_PATH = "/signalk/v2/api/tides";
+const TIDE_PATHS = [
+    "environment.tide.stationName",
+    "environment.tide.stationDistance",
+    "environment.tide.heightNow",
+    "environment.tide.state",
+    "environment.tide.timeToNextExtreme",
+    "environment.tide.heightHigh",
+    "environment.tide.timeHigh",
+    "environment.tide.heightLow",
+    "environment.tide.timeLow",
+];
+// Tide heights are water levels, so clients should show them in the user's
+// depth unit. Without a category the server picks one from the unit alone, and
+// for meters that is distance: kilometers or miles, depending on the preset.
+const TIDE_HEIGHT_PATHS = [
+    "environment.tide.heightHigh",
+    "environment.tide.heightNow",
+    "environment.tide.heightLow",
+];
 export default function (app) {
     let unsubscribes = [];
     let activeRouter = null;
@@ -41,8 +60,9 @@ export default function (app) {
     const plugin = {
         id: "tides",
         name: "Tides",
-        description: "Offline tidal predictions for the vessel's position, powered by Neaps.",
-        schema: () => ({
+        description: "Offline tidal predictions for the vessel's position, powered by Slackwater.",
+        // signalk-server awaits this, but a rejection would fail its whole plugin list
+        schema: async () => ({
             title: "Tides",
             type: "object",
             properties: {
@@ -51,7 +71,7 @@ export default function (app) {
                     title: "Default tide station",
                     description: "Use the closest station to the vessel's current position, or pick a default nearby station.",
                     default: "auto",
-                    oneOf: defaultStationOptions(),
+                    oneOf: await defaultStationOptions(),
                 },
             },
         }),
@@ -62,11 +82,20 @@ export default function (app) {
             activeRouter = null;
         },
     };
-    function defaultStationOptions() {
+    async function defaultStationOptions() {
         const options = [{ const: "auto", title: "Closest station" }];
         if (lastPosition) {
-            for (const station of stationsNear({ ...lastPosition, maxResults: 10 })) {
-                options.push({ const: station.id, title: stationTitle(station) });
+            try {
+                const nearby = await stationsNear({
+                    ...lastPosition,
+                    maxResults: 10,
+                });
+                for (const station of nearby) {
+                    options.push({ const: station.id, title: stationTitle(station) });
+                }
+            }
+            catch (e) {
+                app.error(`Could not list nearby tide stations: ${errorMessage(e)}`);
             }
         }
         // Keep the saved station selectable even when it is not in the nearby
@@ -76,15 +105,40 @@ export default function (app) {
         if (saved && saved !== "auto" && !options.some((o) => o.const === saved)) {
             let title = saved;
             try {
-                title = stationTitle(findStation(saved));
+                const station = await findStation(saved);
+                title = hasTideModel(station)
+                    ? stationTitle(station)
+                    : `${stationTitle(station)} (no tide predictions)`;
             }
-            catch {
+            catch (e) {
                 // Unknown id: keep the raw value as the label
+                if (!isStationNotFound(e)) {
+                    app.error(`Could not load saved tide station: ${errorMessage(e)}`);
+                }
             }
             options.splice(1, 0, { const: saved, title });
         }
         return options;
     }
+    // The server keeps display units the user chose for a path, and stores the
+    // suggestion, so later starts leave a path alone while it has display units.
+    async function suggestDepthUnits() {
+        // Signal K server 2.30 added setDefaultMetadata
+        if (typeof app.setDefaultMetadata !== "function")
+            return;
+        for (const path of TIDE_HEIGHT_PATHS) {
+            try {
+                // MetaValue types displayUnits as the server resolves it; a suggestion
+                // needs only the category.
+                await app.setDefaultMetadata(path, {
+                    displayUnits: { category: "depth" },
+                });
+            }
+            catch (e) {
+                app.error(`Could not suggest display units for ${path}: ${e}`);
+            }
+        }
+    }
     function savedDefaultStation() {
         try {
             const saved = app.readPluginOptions();
@@ -94,18 +148,37 @@ export default function (app) {
             return undefined;
         }
     }
-    async function start(options) {
+    // Not async: signalk-server only rolls back a start() that throws synchronously,
+    // and that rollback does not call stop().
+    function start(options) {
+        try {
+            startPublishing(options);
+        }
+        catch (e) {
+            plugin.stop();
+            throw e;
+        }
+    }
+    function startPublishing(options) {
         app.debug("Starting tides");
         config = (options ?? {});
+        void suggestDepthUnits();
         // Keep the forecast and the predictor that produced it together, so the
         // extremes and the current height are always read from the same station.
         let lastForecast = null;
         let lastPredictor = null;
+        let latestUpdate = 0;
+        let stopped = false;
+        let tidesCleared = false;
+        let positionWrite = Promise.resolve();
+        unsubscribes.push(() => {
+            stopped = true;
+        });
         const cache = new FileCache(app.getDataDirPath());
-        // Mount the Neaps API, with vessel/default resolved to the configured
+        // Mount the Slackwater API, with vessel/default resolved to the configured
         // default station (or the nearest one).
         activeRouter = withVesselPosition(
-        // @neaps/api bundles its own Express declarations, so its Router is
+        // @slackwater/api bundles its own Express declarations, so its Router is
         // callable at runtime but not structurally compatible with ours.
         // The OpenAPI server URL comes from req.baseUrl, set by the
         // app.use(API_PATH, ...) mount above.
@@ -115,7 +188,7 @@ export default function (app) {
             type: "tides",
             methods: {
                 async listResources() {
-                    const predictor = resolvePredictor();
+                    const predictor = await resolvePredictor();
                     if (!predictor) {
                         throw new Error("No position or default station available");
                     }
@@ -165,25 +238,51 @@ export default function (app) {
         }, unsubscribes, (subscriptionError) => {
             app.error("Error:" + subscriptionError);
         }, updatePosition);
-        function resolvePredictor() {
+        async function resolvePredictor(report = reportLookupFailure) {
+            let failed = false;
             if (config.defaultStation && config.defaultStation !== "auto") {
                 try {
-                    return findStation(config.defaultStation);
+                    const station = await findStation(config.defaultStation);
+                    if (hasTideModel(station))
+                        return station;
+                    throw new Error("Station has no tide predictions");
                 }
-                catch {
-                    app.error(`Configured tide station not found: ${config.defaultStation}`);
+                catch (e) {
+                    failed = true;
+                    report(`Could not load tide station ${config.defaultStation}: ${errorMessage(e)}`);
                 }
             }
             if (lastPosition) {
                 try {
-                    return nearestStation(lastPosition);
+                    return await nearestStation({
+                        ...lastPosition,
+                        maxDistance: MAX_STATION_KM,
+                    });
                 }
-                catch {
-                    app.error("No tide station found near vessel position");
+                catch (e) {
+                    if (isNoStationNearby(e)) {
+                        // A status would replace the error about the saved station
+                        if (!stopped && !failed) {
+                            app.setPluginStatus(`No tide station within ${MAX_STATION_KM} km of the vessel`);
+                        }
+                        return null;
+                    }
+                    report(`Could not find a tide station near vessel position: ${errorMessage(e)}`);
                 }
             }
             return null;
         }
+        function reportLookupFailure(message) {
+            if (stopped)
+                return;
+            app.error(message);
+            app.setPluginError(message);
+        }
+        function forecastStatus({ station, distance }) {
+            return distance === undefined
+                ? "Updated tide forecast"
+                : `Updated tide forecast from ${station.name}, ${Math.round(distance)} km away`;
+        }
         function forecastFor(predictor) {
             const now = new Date();
             return predictor.getExtremesPrediction({
@@ -191,32 +290,63 @@ export default function (app) {
                 end: new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000),
             });
         }
+        // Runs from a timer and a delta callback, which both drop its promise, so
+        // it must never reject.
         async function updatePosition() {
-            const newPosition = app.getSelfPath("navigation.position.value");
-            // New position received, save it to the cache
-            if (newPosition) {
-                lastPosition = newPosition;
-                await cache.set("position", lastPosition);
+            try {
+                const newPosition = app.getSelfPath("navigation.position.value");
+                // New position received, save it to the cache
+                if (newPosition) {
+                    lastPosition = newPosition;
+                    // Writes run in turn and each saves the newest position, so an older
+                    // one can't land last
+                    positionWrite = positionWrite
+                        .catch(() => { })
+                        .then(() => cache.set("position", lastPosition));
+                    await positionWrite;
+                }
+                // No last known position, try to load from cache.
+                if (!lastPosition) {
+                    const cached = (await cache.get("position"));
+                    // A delta may have set a newer position during the read
+                    lastPosition ??= cached ?? null;
+                }
             }
-            // No last known position, try to load from cache.
-            if (!lastPosition) {
-                lastPosition = (await cache.get("position"));
+            catch (e) {
+                app.error(`Could not update cached position: ${errorMessage(e)}`);
             }
             // A configured default station predicts without a position
-            updateForecast();
+            await updateForecast();
         }
-        function updateForecast() {
-            const predictor = resolvePredictor();
-            if (!predictor) {
-                app.debug("No position or default station available, cannot compute tide data");
-                lastForecast = null;
-                lastPredictor = null;
-                return;
-            }
+        async function updateForecast() {
+            const update = ++latestUpdate;
             try {
+                let lookupFailed = false;
+                const predictor = await resolvePredictor((message) => {
+                    lookupFailed = true;
+                    reportLookupFailure(message);
+                });
+                // The first lookup waits for the database, so a newer update or stop()
+                // can overtake this one.
+                if (stopped || update !== latestUpdate)
+                    return;
+                if (!predictor) {
+                    app.debug("No position or default station available, cannot compute tide data");
+                    // Once per loss, and once after a restart, which can't tell what the
+                    // run before it published
+                    if (!tidesCleared)
+                        clearTides();
+                    tidesCleared = true;
+                    lastForecast = null;
+                    lastPredictor = null;
+                    return;
+                }
                 lastForecast = forecastFor(predictor);
                 lastPredictor = predictor;
-                app.setPluginStatus("Updated tide forecast");
+                tidesCleared = false;
+                // A fallback keeps the lookup's error showing
+                if (!lookupFailed)
+                    app.setPluginStatus(forecastStatus(lastForecast));
                 updateTides();
             }
             catch (e) {
@@ -226,6 +356,19 @@ export default function (app) {
                 app.error(e);
             }
         }
+        // Signal K keeps a path's last value, so a tide that no longer applies has
+        // to be cleared or it stays on displays, frozen.
+        function clearTides() {
+            app.handleMessage(plugin.id, {
+                context: ("vessels." + app.selfId),
+                updates: [
+                    {
+                        timestamp: new Date().toISOString(),
+                        values: TIDE_PATHS.map((path) => ({ path, value: null })),
+                    },
+                ],
+            });
+        }
         function updateTides(now = new Date()) {
             if (!lastForecast || !lastPredictor)
                 return;
@@ -246,6 +389,13 @@ export default function (app) {
                                 path: "environment.tide.stationName",
                                 value: lastForecast.station.name,
                             },
+                            // Null for a configured station, which isn't chosen by distance
+                            {
+                                path: "environment.tide.stationDistance",
+                                value: lastForecast.distance === undefined
+                                    ? null
+                                    : lastForecast.distance * 1000,
+                            },
                             {
                                 path: "environment.tide.heightNow",
                                 value: heightNow,
@@ -286,6 +436,13 @@ export default function (app) {
                                     description: "Tide trend at the current position: rising or falling",
                                 },
                             },
+                            {
+                                path: "environment.tide.stationDistance",
+                                value: {
+                                    units: "m",
+                                    description: "Distance from the vessel to the station it was given",
+                                },
+                            },
                             {
                                 path: "environment.tide.timeToNextExtreme",
                                 value: {
@@ -311,6 +468,9 @@ export default function (app) {
     }
     return plugin;
 }
+function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
 function stationTitle(station) {
     const where = [station.region, station.country].filter(Boolean).join(", ");
     const distance = station.distance != null ? ` — ${station.distance.toFixed(1)} km` : "";