signalk-tides 1.3.0 → 1.5.0

package/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 100
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 100

package/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push: {}
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run linter
+        run: npm run lint
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    env:
+      CI: true
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run build
+        run: npm run build

package/README.md

@@ -1,6 +1,6 @@
 # signalk-tides
 
-A SignalK plugin that provides tidal predictions for the vessel's position from various online sources.
+A SignalK plugin that provides tidal predictions for the vessel's position from various [sources](#sources).
 
 ## Installation
 
@@ -18,6 +18,8 @@ It publishes the following [tide data](https://signalk.org/specification/1.7.0/d
 * `environment.tide.timeHigh`
 * `environment.tide.heightLow`
 * `environment.tide.timeLow`
+* `environment.tide.heightNow`
+* `environment.tide.stationName`
 
 ### Tides resource
 
@@ -204,9 +206,18 @@ $ curl http://localhost:3000/signalk/v2/api/resources/tides
 
 ## Sources
 
-- [NOAA](https://tidesandcurrents.noaa.gov/web_services_info.html) (US only)
-- [WorldTides API](https://www.worldtides.info/) (requires an API key)
-- [StormGlass.io](https://stormglass.io/) (requires an API key)
+- [Neaps](https://github.com/neaps/neaps)
+  - Offline, open source, runs locally
+  - Coverage: Regional — United States and territories (currently)
+- [NOAA](https://tidesandcurrents.noaa.gov/web_services_info.html)
+  - Online (NOAA web services)
+  - Regional — United States and territories
+- [WorldTides API](https://www.worldtides.info/)
+  - Online (requires API key, subject to API quotas)
+  - Coverage: Global - station and model coverage varies by location
+- [StormGlass.io](https://stormglass.io/)
+  - Online (requires API key)
+  - Coverage: Global - aggregated marine data; tide availability varies
 
 ## License
 

package/dist/cache.js

@@ -0,0 +1,25 @@
+import { join } from "path";
+import { writeFile, readFile, mkdir } from "fs/promises";
+export default class FileCache {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async get(key) {
+        try {
+            const content = await readFile(this.getKey(key), "utf-8");
+            return JSON.parse(content);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async set(key, value) {
+        // Ensure directory exists
+        await mkdir(this.path, { recursive: true });
+        return writeFile(this.getKey(key), JSON.stringify(value));
+    }
+    getKey(key) {
+        return join(this.path, `${key}.json`);
+    }
+}

package/dist/calculations.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.approximateTideHeightAt = approximateTideHeightAt;
 /** Given a list of tide extremes, estimate the height at a specific time. */
-function approximateTideHeightAt(extremes, time) {
+export function approximateTideHeightAt(extremes, time) {
     const sorted = extremes.slice().sort((a, b) => new Date(a.time).getTime() - new Date(b.time).getTime());
     const prev = sorted.filter(h => new Date(h.time) <= time).at(-1);
     const next = sorted.filter(h => new Date(h.time) >= time).at(0);

package/dist/index.js

@@ -1,4 +1,3 @@
-"use strict";
 /*
  * Copyright 2017 Scott Bender <scott@scottbender.net> and Joachim Bakke
  * Copyright 2025 Brandon Keepers <brandon@opensoul.org>
@@ -14,27 +13,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-const noaa_js_1 = __importDefault(require("./sources/noaa.js"));
-const stormglass_js_1 = __importDefault(require("./sources/stormglass.js"));
-const worldtides_js_1 = __importDefault(require("./sources/worldtides.js"));
-const calculations_js_1 = require("./calculations.js");
-module.exports = function (app) {
+import { approximateTideHeightAt } from "./calculations.js";
+import FileCache from "./cache.js";
+import createSources from "./sources/index.js";
+export default function (app) {
     // Interval to update tide data
     const defaultPeriod = 60; // 1 hour
     let unsubscribes = [];
-    let lastForecast = null;
-    const sources = [
-        (0, noaa_js_1.default)(app),
-        (0, stormglass_js_1.default)(app),
-        (0, worldtides_js_1.default)(app),
-    ];
+    const sources = createSources(app);
     const plugin = {
         id: "tides",
         name: "Tides",
-        // @ts-expect-error: TODO[TS]: fix Plugin type upstream
         description: "Tidal predictions for the vessel's position from various online sources.",
         schema: () => ({
             title: "Tides API",
@@ -43,9 +32,9 @@ module.exports = function (app) {
                 source: {
                     title: "Data source",
                     type: "string",
-                    "anyOf": sources.map(({ id, title }) => ({
+                    anyOf: sources.map(({ id, title }) => ({
                         const: id,
-                        title
+                        title,
                     })),
                     default: sources[0].id,
                 },
@@ -58,17 +47,21 @@ module.exports = function (app) {
                     default: 60,
                     minimum: 1,
                 },
-            }
+            },
         }),
+        start,
         stop() {
             unsubscribes.forEach((f) => f());
             unsubscribes = [];
-        }
+        },
     };
-    plugin.start = async function (props) {
+    async function start(props) {
         app.debug("Starting tides-api: " + JSON.stringify(props));
+        let lastForecast = null;
+        let lastPosition = null;
+        const cache = new FileCache(app.getDataDirPath());
         // Use the selected source, or the first one if not specified
-        const source = sources.find(source => source.id === props.source) || sources[0];
+        const source = sources.find((source) => source.id === props.source) || sources[0];
         // Load the selected source
         const provider = await source.start(props);
         // Register the source as a resource provider
@@ -76,7 +69,9 @@ module.exports = function (app) {
             type: "tides",
             methods: {
                 async listResources(query) {
-                    return provider(query);
+                    if (!lastPosition)
+                        throw new Error("No position available");
+                    return provider({ position: lastPosition, ...query });
                 },
                 getResource() {
                     throw new Error("Not implemented");
@@ -86,11 +81,11 @@ module.exports = function (app) {
                 },
                 deleteResource() {
                     throw new Error("Not implemented");
-                }
-            }
+                },
+            },
         });
         app.subscriptionmanager.subscribe({
-            context: "vessels." + app.selfId,
+            context: ("vessels." + app.selfId),
             subscribe: [
                 {
                     path: "navigation.position",
@@ -100,45 +95,24 @@ module.exports = function (app) {
             ],
         }, unsubscribes, (subscriptionError) => {
             app.error("Error:" + subscriptionError);
-        }, (delta) => {
-            // @ts-expect-error: TODO[TS]: fix Delta type upstream
-            delta.updates.forEach(({ values }) => {
-                // @ts-expect-error: TODO[TS]: fix Delta type upstream
-                values.forEach(({ path }) => {
-                    if (path === "navigation.position") {
-                        updateForecast();
-                    }
-                });
-            });
-        });
-        async function updateForecast(now = new Date()) {
+        }, updatePosition);
+        async function updatePosition() {
+            lastPosition =
+                app.getSelfPath("navigation.position.value") || (await cache.get("position")) || null;
+            if (lastPosition) {
+                await cache.set("position", lastPosition);
+                await updateForecast();
+            }
+        }
+        async function updateForecast() {
+            if (!lastPosition) {
+                app.debug("No position available, cannot fetch tide data");
+                return;
+            }
             try {
-                lastForecast = await provider();
-                const nextTide = {};
-                lastForecast.extremes.forEach(({ type, value, time }) => {
-                    // Get the first tide of this type after now
-                    if (!nextTide[type] && new Date(time) > now) {
-                        nextTide[type] = { time, value };
-                    }
-                });
-                const delta = {
-                    context: "vessels." + app.selfId,
-                    updates: [
-                        {
-                            timestamp: now.toISOString(),
-                            values: Object.entries(nextTide).flatMap(([type, { time, value }]) => {
-                                return [
-                                    { path: `environment.tide.height${type}`, value: value },
-                                    { path: `environment.tide.time${type}`, value: time },
-                                ];
-                            }),
-                        },
-                    ],
-                };
-                app.debug("Sending delta: " + JSON.stringify(delta));
-                app.handleMessage(plugin.id, delta);
-                updateHeightNow();
-                app.setPluginStatus("Updated tide data");
+                lastForecast = await provider({ position: lastPosition });
+                app.setPluginStatus("Updated tide forecast from " + source.title);
+                updateTides();
             }
             catch (e) {
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -147,28 +121,47 @@ module.exports = function (app) {
                 app.error(e);
             }
         }
-        async function updateHeightNow(now = new Date()) {
+        async function updateTides(now = new Date()) {
             if (!lastForecast)
                 return;
-            // Combine heights and extremes to account for min/max being between height samples
-            const height = (0, calculations_js_1.approximateTideHeightAt)(lastForecast.extremes, now);
-            app.handleMessage(plugin.id, {
-                context: "vessels." + app.selfId,
+            // Get the next two upcoming extremes
+            const nextTides = lastForecast.extremes
+                .filter(({ time }) => new Date(time) >= now)
+                .slice(0, 2);
+            const delta = {
+                context: ("vessels." + app.selfId),
                 updates: [
                     {
                         timestamp: now.toISOString(),
-                        values: [{ path: "environment.tide.heightNow", value: height }]
-                    }
-                ]
-            });
+                        values: [
+                            {
+                                path: "environment.tide.stationName",
+                                value: lastForecast.station.name,
+                            },
+                            {
+                                path: "environment.tide.heightNow",
+                                value: approximateTideHeightAt(lastForecast.extremes, now),
+                            },
+                            ...nextTides.flatMap(({ type, time, value }) => {
+                                return [
+                                    { path: `environment.tide.height${type}`, value },
+                                    { path: `environment.tide.time${type}`, value: time },
+                                ];
+                            }),
+                        ],
+                    },
+                ],
+            };
+            app.debug("Sending delta: " + JSON.stringify(delta));
+            app.handleMessage(plugin.id, delta);
         }
         // Perform initial update on startup after short delay to allow gnss position to be populated
-        delay(4000).then(() => { updateForecast(); });
-        // Update heightNow every minute
-        setInterval(updateHeightNow, 60 * 1000);
-    };
+        delay(4000).then(updatePosition);
+        // Update every minute
+        setInterval(updateTides, 60 * 1000);
+    }
     function delay(time) {
         return new Promise((resolve) => setTimeout(resolve, time));
     }
     return plugin;
-};
+}

package/dist/sources/index.js

@@ -0,0 +1,7 @@
+import neaps from "./neaps.js";
+import noaa from "./noaa.js";
+import stormglass from "./stormglass.js";
+import worldtides from "./worldtides.js";
+export default function createSources(app) {
+    return [neaps, noaa, stormglass, worldtides].map(s => s(app));
+}

package/dist/sources/neaps.js

@@ -0,0 +1,39 @@
+import { getExtremesPrediction } from "neaps";
+import moment from 'moment';
+export default function (app) {
+    return {
+        id: 'neaps',
+        title: 'Neaps',
+        properties: {},
+        start() {
+            app.debug("Using Neaps");
+            return async ({ position, date = moment().subtract(1, "days").toISOString() }) => {
+                const { station, extremes } = getExtremesPrediction({
+                    ...position,
+                    start: new Date(date),
+                    end: moment(date).add(7, "days").toDate(),
+                    labels: {
+                        high: "High",
+                        low: "Low"
+                    }
+                });
+                return {
+                    station: {
+                        name: station.name,
+                        position: {
+                            latitude: station.latitude,
+                            longitude: station.longitude,
+                        },
+                    },
+                    extremes: extremes.map(({ time, level, label }) => {
+                        return {
+                            type: label,
+                            value: level,
+                            time: time.toISOString(),
+                        };
+                    }),
+                };
+            };
+        }
+    };
+}

package/dist/sources/noaa.js

@@ -1,33 +1,32 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = default_1;
-const path_1 = __importDefault(require("path"));
-const promises_1 = __importDefault(require("fs/promises"));
-const geolib_1 = require("geolib");
-const moment_1 = __importDefault(require("moment"));
+import path from "path";
+import { unlink } from "fs/promises";
+import { getDistance } from "geolib";
+import moment from "moment";
+import FileCache from "../cache.js";
 const stationsUrl = `https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations.json?type=tidepredictions`;
-const dataGetterUrl = 'https://api.tidesandcurrents.noaa.gov/api/prod/datagetter';
-const datum = 'MLLW';
-function default_1(app) {
+const dataGetterUrl = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter";
+const datum = "MLLW";
+export default function (app) {
     return {
-        id: 'noaa',
-        title: 'NOAA (US only)',
+        id: "noaa",
+        title: "NOAA (US only)",
         async start() {
-            const stations = await StationList.load(app);
-            return async ({ date } = {}) => {
-                const position = app.getSelfPath("navigation.position.value");
-                if (!position)
-                    throw new Error("no position");
+            const cache = new FileCache(path.join(app.getDataDirPath(), "noaa"));
+            const stations = await StationList.load(cache, app);
+            // Remove old cache file
+            // @ts-expect-error: configPath exists, just not part of the types
+            unlink(path.join(app.config.configPath, "noaastations.json")).catch(() => {
+                /* ignore */
+            });
+            return async (params) => {
+                const { position, date = moment().subtract(1, "days") } = params;
                 const station = stations.closestTo(position);
                 const endpoint = new URL(dataGetterUrl);
                 endpoint.search = new URLSearchParams({
                     product: "predictions",
                     application: "signalk.org/node-server",
-                    begin_date: (0, moment_1.default)(date).format("YYYYMMDD"),
-                    end_date: (0, moment_1.default)(date).add(7, "days").format("YYYYMMDD"),
+                    begin_date: moment(date).format("YYYYMMDD"),
+                    end_date: moment(date).add(7, "days").format("YYYYMMDD"),
                     datum,
                     station: station.id,
                     time_zone: "gmt",
@@ -40,7 +39,7 @@ function default_1(app) {
                     const res = await fetch(endpoint.toString());
                     if (!res.ok)
                         throw new Error("Failed to fetch NOAA tides: " + res.statusText);
-                    const body = await res.json();
+                    const body = (await res.json());
                     app.debug("NOAA response: \n" + JSON.stringify(body, null, 2));
                     if (body.error)
                         throw new Error(body.error.message);
@@ -66,26 +65,22 @@ function default_1(app) {
                     throw err;
                 }
             };
-        }
+        },
     };
 }
-;
 class StationList extends Map {
-    static async load(app) {
-        const filename = path_1.default.join(app.config.configPath, "noaastations.json");
-        let data;
-        try {
-            data = JSON.parse(await promises_1.default.readFile(filename, 'utf-8'));
-            app.debug("NOAA: Loaded cached tide stations from " + filename);
+    static async load(cache, app) {
+        let data = (await cache.get("stations"));
+        if (data) {
+            app.debug("NOAA: Loaded cached tide stations");
         }
-        catch (e) {
-            app.debug(`NOAA: failed to load cached tide stations: ${e}`);
-            app.debug('NOAA: Downloading tide stations');
+        else {
+            app.debug("NOAA: Downloading tide stations");
             const res = await fetch(stationsUrl);
             if (!res.ok)
                 throw new Error(`Failed to download stations: ${res.statusText}`);
-            data = await res.json();
-            await promises_1.default.writeFile(filename, JSON.stringify(data));
+            data = (await res.json());
+            await cache.set("stations", data);
         }
         return new this(data.stations);
     }
@@ -98,8 +93,13 @@ class StationList extends Map {
     near(position, limit = 10) {
         const stationsWithDistances = Array.from(this.values()).map((station) => ({
             ...station,
-            distance: (0, geolib_1.getDistance)(position, { latitude: station.lat, longitude: station.lng })
+            distance: getDistance(position, {
+                latitude: station.lat,
+                longitude: station.lng,
+            }),
         }));
-        return stationsWithDistances.sort((a, b) => a.distance - b.distance).slice(0, limit);
+        return stationsWithDistances
+            .sort((a, b) => a.distance - b.distance)
+            .slice(0, limit);
     }
 }

package/dist/sources/stormglass.js

@@ -1,11 +1,5 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = default_1;
-const moment_1 = __importDefault(require("moment"));
-function default_1(app) {
+import moment from 'moment';
+export default function (app) {
     return {
         id: 'stormglass',
         title: 'StormGlass.io',
@@ -17,18 +11,14 @@ function default_1(app) {
         },
         start({ stormglassApiKey } = {}) {
             app.debug("Using StormGlass.io API");
-            return async (params = {}) => {
-                const { date = (0, moment_1.default)().subtract(1, "days").toISOString() } = params;
+            return async ({ position, date = moment().subtract(1, "days").toISOString() }) => {
                 const endPoint = new URL("https://api.stormglass.io/v2/tide/extremes/point");
-                const position = app.getSelfPath("navigation.position.value");
-                if (!position)
-                    throw new Error("no position");
                 endPoint.search = new URLSearchParams({
-                    start: (0, moment_1.default)(date).format("YYYY-MM-DD"),
-                    end: (0, moment_1.default)(date).add(7, "days").format("YYYY-MM-DD"),
+                    start: moment(date).format("YYYY-MM-DD"),
+                    end: moment(date).add(7, "days").format("YYYY-MM-DD"),
                     // datum: "CD",
-                    lat: position.latitude,
-                    lng: position.longitude,
+                    lat: position.latitude.toString(),
+                    lng: position.longitude.toString()
                 }).toString();
                 app.debug("Fetching StormGlass.io: " + endPoint.toString());
                 const res = await fetch(endPoint, {
@@ -40,7 +30,7 @@ function default_1(app) {
                 app.debug(JSON.stringify(data, null, 2));
                 return {
                     station: {
-                        name: data.meta.station.name,
+                        name: `${data.meta.station.name} (${data.meta.station.source})`,
                         position: {
                             latitude: data.meta.station.lat,
                             longitude: data.meta.station.lng,

package/dist/sources/worldtides.js

@@ -1,11 +1,5 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = default_1;
-const moment_1 = __importDefault(require("moment"));
-function default_1(app) {
+import moment from 'moment';
+export default function (app) {
     return {
         id: 'WorldTides.info',
         title: 'worldtides.info',
@@ -17,20 +11,17 @@ function default_1(app) {
         },
         start({ worldtidesApiKey = '' } = {}) {
             app.debug("Using WorldTides API");
-            return async (params = {}) => {
-                const { date = (0, moment_1.default)().subtract(1, "days") } = params;
+            return async (params) => {
+                const { position, date = moment().subtract(1, "days") } = params;
                 const endPoint = new URL("https://www.worldtides.info/api/v3");
-                const position = app.getSelfPath("navigation.position.value");
-                if (!position)
-                    throw new Error("no position");
                 endPoint.search = new URLSearchParams({
-                    date: (0, moment_1.default)(date).format("YYYY-MM-DD"),
+                    date: moment(date).format("YYYY-MM-DD"),
                     datum: "CD",
                     days: "7",
                     extremes: "true",
                     key: worldtidesApiKey,
-                    lat: position.latitude,
-                    lon: position.longitude,
+                    lat: position.latitude.toString(),
+                    lon: position.longitude.toString(),
                 }).toString();
                 app.debug("Fetching worldtides: " + endPoint.toString());
                 const res = await fetch(endPoint);
@@ -42,7 +33,7 @@ function default_1(app) {
                     throw new Error("worldtides data: " + data.error ? data.error : "none");
                 return {
                     station: {
-                        name: "WorldTides",
+                        name: `${data.station} (${data.atlas})`,
                         position: {
                             latitude: data.responseLat,
                             longitude: data.responseLon,

package/dist/types.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};