@sailingnaturali/signalk-currents 0.2.0 → 0.4.0

package/README.md

@@ -47,8 +47,8 @@ Each entry in `stations`:
 | `noaaBin` | number | NOAA current-station bin (NOAA only). |
 | `label` | string | Human-readable name. |
 | `lat` / `lon` | number | Station position (used for nearest-station selection). |
-| `floodDir` | number | Set direction (°true) while flooding. |
-| `ebbDir` | number | Set direction (°true) while ebbing. |
+| `floodDir` | number | Set direction (°true) while flooding. **CHS: required** (from the Canadian Tide and Current Tables / Sailing Directions). **NOAA: optional** — the API's measured `meanFloodDir` overrides whatever is configured. |
+| `ebbDir` | number | Set direction (°true) while ebbing. Same sourcing rules as `floodDir` (NOAA `meanEbbDir`). |
 
 ### Example station config
 
@@ -99,7 +99,8 @@ ebb — fill them from a current atlas or pilot book for your stations.
 
 ### `/currents` resource
 
-Mounted at `/plugins/signalk-currents/currents`:
+Served at `/signalk/v2/api/resources/currents` (anonymously readable under
+`allow_readonly`):
 
 ```json
 {
@@ -109,6 +110,8 @@ Mounted at `/plugins/signalk-currents/currents`:
       "label": "Gillard Passage",
       "lat": 50.3933,
       "lon": -125.1567,
+      "floodDir": 160,
+      "ebbDir": 340,
       "events": [
         { "utc": "2026-06-06T04:14:00.000Z", "kind": "slack", "speedKn": 0 },
         { "utc": "2026-06-06T05:40:00.000Z", "kind": "flood", "speedKn": 4.1 }
@@ -119,6 +122,8 @@ Mounted at `/plugins/signalk-currents/currents`:
 ```
 
 `kind` is `slack` | `flood` | `ebb`; `speedKn` is the event speed magnitude in knots.
+`floodDir` / `ebbDir` are the station's set directions in °true, straight from the
+station config — so consumers can say which way the water flows, not just when it turns.
 
 ## Development
 

package/dist/cache.d.ts

@@ -1,3 +1,3 @@
-import { CurrentEvent } from './types';
-export type DayCache = Map<string, CurrentEvent[]>;
+import { DayData } from './fetch';
+export type DayCache = Map<string, DayData>;
 export declare function createCache(): DayCache;

package/dist/calculations.js

@@ -40,5 +40,7 @@ function interpolateCurrent(now, events, station) {
         extremum = e0;
     } // rare flood↔ebb, linear
     const dir = extremum.kind === 'ebb' ? station.ebbDir : station.floodDir;
+    if (dir === undefined)
+        return undefined; // no honest setTrue without a set direction
     return { drift: speedKn * KN_TO_MS, setTrue: (dir * Math.PI) / 180 };
 }

package/dist/fetch.d.ts

@@ -1,4 +1,7 @@
-import { CurrentEvent, StationConfig } from './types';
-type DayFetcher = (s: StationConfig, dayStart: Date, dayEnd: Date) => Promise<CurrentEvent[]>;
-export declare function stationEvents(station: StationConfig, start: Date, horizonDays: number, cache: Map<string, CurrentEvent[]>, fetcher?: DayFetcher): Promise<CurrentEvent[]>;
+import { CurrentEvent, StationConfig, StationDirs } from './types';
+export interface DayData extends StationDirs {
+    events: CurrentEvent[];
+}
+type DayFetcher = (s: StationConfig, dayStart: Date, dayEnd: Date) => Promise<DayData>;
+export declare function stationData(station: StationConfig, start: Date, horizonDays: number, cache: Map<string, DayData>, fetcher?: DayFetcher): Promise<DayData>;
 export {};

package/dist/fetch.js

@@ -1,28 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stationEvents = stationEvents;
+exports.stationData = stationData;
 const chs_1 = require("./sources/chs");
 const noaa_1 = require("./sources/noaa");
-const defaultFetcher = (s, a, b) => s.provider === 'chs'
-    ? (0, chs_1.fetchChsEvents)(s.stationId, a, b)
+const defaultFetcher = async (s, a, b) => s.provider === 'chs'
+    ? { events: await (0, chs_1.fetchChsEvents)(s.stationId, a, b) }
     : (0, noaa_1.fetchNoaaEvents)(s.stationId, s.noaaBin ?? 0, a, b);
 function utcDays(start, n) {
     const base = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), start.getUTCDate()));
     return Array.from({ length: n }, (_, i) => new Date(base.getTime() + i * 86400000).toISOString().slice(0, 10));
 }
-async function stationEvents(station, start, horizonDays, cache, fetcher = defaultFetcher) {
-    const out = [];
+async function stationData(station, start, horizonDays, cache, fetcher = defaultFetcher) {
+    const events = [];
+    let floodDir, ebbDir;
     for (const day of utcDays(start, horizonDays)) {
         const key = `${station.provider}:${station.stationId}:${day}`;
-        let events = cache.get(key);
-        if (!events) {
+        let data = cache.get(key);
+        if (!data) {
             const dayStart = new Date(`${day}T00:00:00Z`);
             const dayEnd = new Date(dayStart.getTime() + 86400000);
-            events = await fetcher(station, dayStart, dayEnd);
-            cache.set(key, events);
+            data = await fetcher(station, dayStart, dayEnd);
+            cache.set(key, data);
         }
-        out.push(...events);
+        events.push(...data.events);
+        floodDir = floodDir ?? data.floodDir;
+        ebbDir = ebbDir ?? data.ebbDir;
     }
-    out.sort((a, b) => a.utc.localeCompare(b.utc));
-    return out;
+    events.sort((a, b) => a.utc.localeCompare(b.utc));
+    return { events, floodDir, ebbDir };
 }

package/dist/index.js

@@ -1,4 +1,5 @@
 "use strict";
+const types_1 = require("./types");
 const cache_1 = require("./cache");
 const fetch_1 = require("./fetch");
 const calculations_1 = require("./calculations");
@@ -19,13 +20,13 @@ module.exports = function (app) {
             properties: {
                 stations: {
                     type: 'array', title: 'Current stations',
-                    items: { type: 'object', required: ['provider', 'stationId', 'label', 'lat', 'lon', 'floodDir', 'ebbDir'],
+                    items: { type: 'object', required: ['provider', 'stationId', 'label', 'lat', 'lon'],
                         properties: {
                             provider: { type: 'string', enum: ['chs', 'noaa'] },
                             stationId: { type: 'string' }, noaaBin: { type: 'number' },
                             label: { type: 'string' }, lat: { type: 'number' }, lon: { type: 'number' },
-                            floodDir: { type: 'number', title: 'Flood set (°true)' },
-                            ebbDir: { type: 'number', title: 'Ebb set (°true)' },
+                            floodDir: { type: 'number', title: 'Flood set (°true) — required for CHS; NOAA stations use the API\'s measured meanFloodDir' },
+                            ebbDir: { type: 'number', title: 'Ebb set (°true) — required for CHS; NOAA stations use the API\'s measured meanEbbDir' },
                         } },
                 },
                 horizonDays: { type: 'number', default: 3 },
@@ -59,8 +60,9 @@ module.exports = function (app) {
                     // others (or skip the environment.current publish) for the whole cycle.
                     for (const station of stations) {
                         try {
-                            const events = await (0, fetch_1.stationEvents)(station, now, horizonDays, cache);
-                            series.set(station.stationId, { station, events });
+                            const data = await (0, fetch_1.stationData)(station, now, horizonDays, cache);
+                            // Provider-measured set directions (NOAA) beat the config values.
+                            series.set(station.stationId, { station: (0, types_1.resolveStation)(station, data), events: data.events });
                         }
                         catch (e) {
                             app.error(`station ${station.label} fetch failed: ${e.message}`);
@@ -80,7 +82,8 @@ module.exports = function (app) {
                         app.setPluginStatus('No station near vessel position');
                         return;
                     }
-                    const current = (0, calculations_1.interpolateCurrent)(now, entry.events, station);
+                    // entry.station carries the resolved dirs; `station` is raw config.
+                    const current = (0, calculations_1.interpolateCurrent)(now, entry.events, entry.station);
                     if (!current) {
                         app.setPluginStatus(`No current data bracketing now for ${station.label}`);
                         return;

package/dist/routes.d.ts

@@ -9,6 +9,8 @@ export declare function currentsPayload(series: Map<string, StationSeries>): {
         label: string;
         lat: number;
         lon: number;
+        floodDir: number | undefined;
+        ebbDir: number | undefined;
         events: CurrentEvent[];
     }[];
 };

package/dist/routes.js

@@ -7,7 +7,9 @@ function currentsPayload(series) {
     return {
         stations: [...series.values()].map(s => ({
             stationId: s.station.stationId, label: s.station.label,
-            lat: s.station.lat, lon: s.station.lon, events: s.events,
+            lat: s.station.lat, lon: s.station.lon,
+            floodDir: s.station.floodDir, ebbDir: s.station.ebbDir,
+            events: s.events,
         })),
     };
 }

package/dist/sources/noaa.d.ts

@@ -1,2 +1,5 @@
-import { CurrentEvent } from '../types';
-export declare function fetchNoaaEvents(stationId: string, bin: number, start: Date, end: Date, fetchFn?: typeof fetch): Promise<CurrentEvent[]>;
+import { CurrentEvent, StationDirs } from '../types';
+export interface NoaaDayData extends StationDirs {
+    events: CurrentEvent[];
+}
+export declare function fetchNoaaEvents(stationId: string, bin: number, start: Date, end: Date, fetchFn?: typeof fetch): Promise<NoaaDayData>;

package/dist/sources/noaa.js

@@ -18,12 +18,21 @@ async function fetchNoaaEvents(stationId, bin, start, end, fetchFn = fetch) {
     if (!resp.ok)
         throw new Error(`NOAA ${resp.status}`);
     const cp = (await resp.json())?.current_predictions?.cp ?? [];
-    const out = [];
+    const events = [];
+    let floodDir, ebbDir;
     for (const row of cp) {
+        // Every row repeats the station/bin's measured principal directions; take
+        // the first finite pair — this is the authority config can't match.
+        if (floodDir === undefined && Number.isFinite(Number(row.meanFloodDir))) {
+            floodDir = Number(row.meanFloodDir);
+        }
+        if (ebbDir === undefined && Number.isFinite(Number(row.meanEbbDir))) {
+            ebbDir = Number(row.meanEbbDir);
+        }
         const kind = String(row.Type ?? '').toLowerCase();
         if (kind !== 'slack' && kind !== 'flood' && kind !== 'ebb')
             continue;
-        out.push((0, types_1.eventFromParts)(parseNoaaTime(row.Time), kind, parseFloat(row.Velocity_Major)));
+        events.push((0, types_1.eventFromParts)(parseNoaaTime(row.Time), kind, parseFloat(row.Velocity_Major)));
     }
-    return out;
+    return { events, floodDir, ebbDir };
 }

package/dist/types.d.ts

@@ -11,7 +11,12 @@ export interface StationConfig {
     label: string;
     lat: number;
     lon: number;
-    floodDir: number;
-    ebbDir: number;
+    floodDir?: number;
+    ebbDir?: number;
 }
+export interface StationDirs {
+    floodDir?: number;
+    ebbDir?: number;
+}
+export declare function resolveStation(station: StationConfig, fetched: StationDirs): StationConfig;
 export declare function eventFromParts(utc: string, kind: CurrentKind, speed: number): CurrentEvent;

package/dist/types.js

@@ -1,6 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStation = resolveStation;
 exports.eventFromParts = eventFromParts;
+// Measured dirs from the provider (NOAA meanFloodDir/meanEbbDir) beat whatever
+// was typed into config; config is the fallback (and the only source for CHS).
+function resolveStation(station, fetched) {
+    return {
+        ...station,
+        floodDir: fetched.floodDir ?? station.floodDir,
+        ebbDir: fetched.ebbDir ?? station.ebbDir,
+    };
+}
 function eventFromParts(utc, kind, speed) {
     return { utc: new Date(utc).toISOString(), kind, speedKn: Math.abs(speed) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sailingnaturali/signalk-currents",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Publish CHS/NOAA tidal-current predictions to SignalK — environment.current + a /currents resource, for a configured station list.",
   "main": "dist/index.js",
   "scripts": {