@sailingnaturali/signalk-currents 0.3.0 → 0.5.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
 
@@ -112,6 +112,7 @@ Served at `/signalk/v2/api/resources/currents` (anonymously readable under
       "lon": -125.1567,
       "floodDir": 160,
       "ebbDir": 340,
+      "dirsSource": "config",
       "events": [
         { "utc": "2026-06-06T04:14:00.000Z", "kind": "slack", "speedKn": 0 },
         { "utc": "2026-06-06T05:40:00.000Z", "kind": "flood", "speedKn": 4.1 }
@@ -122,8 +123,11 @@ Served at `/signalk/v2/api/resources/currents` (anonymously readable under
 ```
 
 `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.
+`floodDir` / `ebbDir` are the station's set directions in °true — so consumers can say
+which way the water flows, not just when it turns. `dirsSource` says where they came
+from: `"api"` (NOAA-measured) or `"config"`; absent means nobody knows. Config-sourced
+directions may also carry `floodDirEstimated` / `ebbDirEstimated: true` when the config
+value is an assumption (e.g. the reciprocal of a stated flood) — consumers should say so.
 
 ## 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,15 @@ 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' },
+                            floodDirEstimated: { type: 'boolean', title: 'Flood set is an assumption (not from the tables)' },
+                            ebbDirEstimated: { type: 'boolean', title: 'Ebb set is an assumption (e.g. reciprocal of flood)' },
                         } },
                 },
                 horizonDays: { type: 'number', default: 3 },
@@ -59,8 +62,13 @@ 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,
+                                dirsSource: (0, types_1.dirsSource)(station, data),
+                            });
                         }
                         catch (e) {
                             app.error(`station ${station.label} fetch failed: ${e.message}`);
@@ -80,7 +88,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

@@ -1,7 +1,8 @@
-import { StationConfig, CurrentEvent } from './types';
+import { StationConfig, CurrentEvent, DirsSource } from './types';
 export interface StationSeries {
     station: StationConfig;
     events: CurrentEvent[];
+    dirsSource?: DirsSource;
 }
 export declare function currentsPayload(series: Map<string, StationSeries>): {
     stations: {
@@ -9,8 +10,11 @@ export declare function currentsPayload(series: Map<string, StationSeries>): {
         label: string;
         lat: number;
         lon: number;
-        floodDir: number;
-        ebbDir: number;
+        floodDir: number | undefined;
+        ebbDir: number | undefined;
+        dirsSource: DirsSource | undefined;
+        floodDirEstimated: boolean | undefined;
+        ebbDirEstimated: boolean | undefined;
         events: CurrentEvent[];
     }[];
 };

package/dist/routes.js

@@ -9,6 +9,11 @@ function currentsPayload(series) {
             stationId: s.station.stationId, label: s.station.label,
             lat: s.station.lat, lon: s.station.lon,
             floodDir: s.station.floodDir, ebbDir: s.station.ebbDir,
+            dirsSource: s.dirsSource,
+            // Estimated flags qualify *config* values; API-measured dirs supersede
+            // the config entry the flags were describing.
+            floodDirEstimated: s.dirsSource === 'config' ? s.station.floodDirEstimated : undefined,
+            ebbDirEstimated: s.dirsSource === 'config' ? s.station.ebbDirEstimated : undefined,
             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,16 @@ export interface StationConfig {
     label: string;
     lat: number;
     lon: number;
-    floodDir: number;
-    ebbDir: number;
+    floodDir?: number;
+    ebbDir?: number;
+    floodDirEstimated?: boolean;
+    ebbDirEstimated?: boolean;
 }
+export interface StationDirs {
+    floodDir?: number;
+    ebbDir?: number;
+}
+export declare function resolveStation(station: StationConfig, fetched: StationDirs): StationConfig;
+export type DirsSource = 'api' | 'config';
+export declare function dirsSource(station: StationConfig, fetched: StationDirs): DirsSource | undefined;
 export declare function eventFromParts(utc: string, kind: CurrentKind, speed: number): CurrentEvent;

package/dist/types.js

@@ -1,6 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStation = resolveStation;
+exports.dirsSource = dirsSource;
 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,
+    };
+}
+// Where the resolved directions came from: provider-measured ('api'), config
+// ('config'), or undefined when neither knows.
+function dirsSource(station, fetched) {
+    if (fetched.floodDir !== undefined || fetched.ebbDir !== undefined)
+        return 'api';
+    if (station.floodDir !== undefined || station.ebbDir !== undefined)
+        return 'config';
+    return undefined;
+}
 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.3.0",
+  "version": "0.5.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": {