@openwaters/noaa-current-stations 0.4.0

package/docs/validation.md

@@ -0,0 +1,102 @@
+# Validation
+
+A tidal-current engine always produces plausible-looking output. Sinusoids sum to
+something that rises and falls twice a day no matter how wrong the constituents,
+conventions, or offsets are. The only way to know an implementation is right is to
+diff it against NOAA's own published predictions.
+
+## Method
+
+Both halves come from NOAA, so the comparison is self-contained:
+
+1. Pull a station's constituents from `harcon.json` at its `currbin`.
+2. Pull NOAA's `currents_predictions` (`interval=max_slack`) for a window of days.
+3. Predict that window from the constituents; pair each NOAA event with the nearest
+   predicted event of the same kind; report mean and worst timing error and mean
+   speed error.
+
+```bash
+noaa-current-stations golden pug1741.json --station PUG1741 --bin 27 \
+  --start 2026-07-19 --end 2026-07-21
+```
+
+The fixture holds constituents *and* NOAA's events, so the check replays offline
+forever. Wire it into your test suite; it is the regression gate for every convention
+decision below.
+
+## What this method settled
+
+Each of these was an open question that the diff answered unambiguously — the wrong
+choice produces structural, obvious error, not noise:
+
+| Question | Answer | Wrong-choice cost |
+|---|---|---|
+| Which phase field? | `majorPhaseGMT` | structural offset across all events |
+| Sign convention for labeling? | classify by **velocity sign**, not extremum high/low | a relaxation peak during a long ebb mislabels as flood |
+| Are `mfcAmpAdj`/`mecAmpAdj` ratios or deltas? | ratios | immediate, large speed error |
+| Include `majorMeanSpeed` (Z₀)? | yes | 15.6 → 7.4 min mean timing (see below) |
+| Reference keyed by id, or (id, bin)? | (id, bin) | ~50 min at any station whose reference isn't primary-bin |
+| Predict type-S via offsets or own harcon? | own harcon when non-empty | 89 min vs 6.8 min at PUG1716 |
+
+## Measured results
+
+From the reference implementation ([slackwater-engine](https://github.com/openwatersio/slackwater-engine),
+Swift), against NOAA's own predictions:
+
+| Check | Station(s) | Result |
+|---|---|---|
+| Harmonic oracle | PUG1741 Bellingham Channel (2.8 kn reversing) | **9.7 min / 0.055 kn** (11 events) |
+| Subordinate reduction | PCT0236 (ref SFB1201) | **6.1 min / 0.05 kn** (11 events) |
+| Subordinate batch | 9 pure subordinates — mixed regions, offset signs, ratios 0.2–1.5 | worst **7.7 min / 0.101 kn** |
+| Salish Sea passes | Deception, Rosario, San Juan Ch., Turn Point, Admiralty, Race Rocks | worst **15.3 min / 0.28 kn** |
+
+Per-pass: Deception 14.2 min · Rosario 2.2 · San Juan Channel 8.4 · Turn Point 15.3 ·
+Admiralty Inlet 3.5 · Race Rocks 6.0.
+
+And independently, from a second implementation
+([signalk-currents](https://github.com/sailingnaturali/signalk-currents), TypeScript
+over [Neaps](https://github.com/neaps/neaps)) — the Z₀ measurement at Turn Point,
+three days, 24 events:
+
+| | mean timing | worst | mean speed |
+|---|---|---|---|
+| without Z₀ | 15.6 min | 55 min | 0.147 kn |
+| with Z₀ | **7.4 min** | **21 min** | **0.066 kn** |
+
+## Realistic tolerances
+
+Harmonic **±20 min / ±0.35 kn**; subordinate **±30 min / ±0.4 kn**. Tighter than that
+and you are fitting noise: the subordinate reduction is a published *table*
+approximation, and constricted passes are genuinely harder than open water — Deception
+Pass and Turn Point are the worst performers above for real physical reasons, not
+implementation ones.
+
+**These are planning-grade numbers.** A 15-minute slack error matters at a pass where
+the gate is 20 minutes wide. Derived predictions are unofficial; don't time a transit
+of a fast narrows on them alone.
+
+## Extractor fidelity
+
+`extract` is diffed against a known-good bundle whenever it changes. Full US run,
+2026-07-19 — 2,785 stations selected, **856 harmonic + 1,705 subordinate**, 238 type-W
+skipped, **0 unresolvable references**:
+
+| | |
+|---|---|
+| Overlapping stations byte-identical | **2,558 of 2,558** |
+| Stations NOAA added since the reference bundle | 3 (`PUG1519`, `PCT5721`, `PCT5726`) |
+| Stations disappeared | 0 |
+| Subordinate references unresolved | 0 |
+| Reference entries at a **non-primary** bin (`id@bin`) | **14** |
+
+That last row is the per-bin trap in live data: 14 subordinates in US waters reduce
+against a reference bin that is *not* that station's primary bin. Key by station id
+alone and those 14 silently predict from the wrong depth — while every other station
+keeps passing.
+
+Station counts drift as NOAA revises its list; treat the totals as approximate and the
+**0 unresolvable references** as the invariant worth gating on.
+
+Unit tests (`npm test`) cover the traps with a fake NOAA: per-bin reference keying,
+type-S own-harcon precedence, two-slack offsets, ratio handling, list de-duplication,
+and both response shapes NOAA has shipped for `currents_predictions`.

package/index.d.ts

@@ -0,0 +1,160 @@
+export interface FetchOptions {
+  /** Delay before each request, ms. NOAA throttles bulk callers. Default 400. */
+  paceMs?: number;
+  /** Injectable fetch, for tests. */
+  fetchFn?: typeof fetch;
+  /** `application` parameter NOAA uses to identify a caller. */
+  application?: string;
+}
+
+export interface NoaaStation {
+  id: string;
+  name: string;
+  lat: number;
+  lng: number;
+  /** H = harmonic, S = subordinate (may still carry own harcon), W = weak/rotary. */
+  type: 'H' | 'S' | 'W';
+  /** The station's reference bin. harcon is EMPTY at any other bin. */
+  currbin: number;
+}
+
+export interface NoaaConstituent {
+  constituentName: string;
+  /** Knots under units=english; cm/s under units=metric. */
+  majorAmplitude: number;
+  /** Greenwich phase, degrees. */
+  majorPhaseGMT: number;
+  /** Major-axis azimuth, degrees true — the flood set. */
+  azi: number;
+  /** Z0: net mean flow along the major axis, signed. */
+  majorMeanSpeed: number;
+  /** DC cross-axis flow, knots — the minor-axis counterpart to `majorMeanSpeed`. */
+  minorMeanSpeed: number;
+  binNbr: number;
+}
+
+export interface CurrentPrediction {
+  /** ISO 8601, UTC. */
+  time: string;
+  /** 'unknown' for any Type NOAA sends that isn't one of the three — never folded in. */
+  kind: 'slack' | 'flood' | 'ebb' | 'unknown';
+  /** Signed major-axis velocity, knots. */
+  velocityMajor: number;
+  meanFloodDir: number;
+  meanEbbDir: number;
+}
+
+export interface HarmonicStation {
+  /** `id` at the primary bin, `id@bin` for a reference at another bin. */
+  id: string;
+  name: string;
+  latitude: number;
+  longitude: number;
+  type: 'harmonic';
+  floodDirection: number;
+  ebbDirection: number;
+  /** Z0 mean flow, knots. */
+  offset: number;
+  constituents: { name: string; amplitude: number; phase: number }[];
+}
+
+export interface SubordinateStation {
+  id: string;
+  name: string;
+  latitude: number;
+  longitude: number;
+  type: 'subordinate';
+  /** Bundle key of the harmonic station this reduces against. */
+  reference: string;
+  floodDirection: number;
+  ebbDirection: number;
+  /** Seconds. A slack takes the offset for the phase it precedes. */
+  slackBeforeFloodOffset: number;
+  slackBeforeEbbOffset: number;
+  floodTimeOffset: number;
+  ebbTimeOffset: number;
+  /** Ratios applied to the reference peak speed, not deltas. */
+  floodSpeedRatio: number;
+  ebbSpeedRatio: number;
+}
+
+export interface CrossFlowCensus {
+  /** What was measured, carried inline so the number explains itself. */
+  measured: string;
+  /** Harmonic records sampled, `@bin` entries included. */
+  records: number;
+  gte0_25kn: number;
+  gte0_50kn: number;
+  /** Where the flood axis describes the station worst. */
+  worstRatio: {
+    id: string;
+    crossFlow: number;
+    /** Σ|majorAmplitude| + |Z0| — a theoretical max if every constituent aligned in phase, not a realized peak speed. */
+    alongAxisPeak: number;
+    ratio: number;
+  };
+  /** Largest cross-flow in knots — usually a different station from `worstRatio`. */
+  worstAbsolute: { id: string; crossFlow: number };
+}
+
+export interface Bundle {
+  note: string;
+  generated: string;
+  /**
+   * How much the major-axis model drops. Null when the bundle has no harmonic
+   * stations. Never carried per station — see docs/schema.md.
+   */
+  crossFlow: CrossFlowCensus | null;
+  stations: (HarmonicStation | SubordinateStation)[];
+}
+
+export interface GoldenFixture {
+  note: string;
+  station: string;
+  bin: number;
+  start: string;
+  end: string;
+  floodDirection: number;
+  ebbDirection: number;
+  offset: number;
+  constituents: { name: string; amplitude: number; phase: number }[];
+  events: CurrentPrediction[];
+  /** Present when NOAA's predictions product was unavailable at capture time. */
+  predictionsError?: string;
+}
+
+export interface ExtractOptions extends FetchOptions {
+  /** [south, west, north, east]. Omit for all US stations. */
+  box?: [number, number, number, number];
+  /** Explicit station ids; overrides `box`. */
+  stations?: string[];
+  log?: (message: string) => void;
+}
+
+export interface ExtractResult {
+  bundle: Bundle;
+  skipped: {
+    typeW: number;
+    emptyHarcon: string[];
+    noReference: string[];
+    failed: string[];
+    unresolvable: number;
+  };
+}
+
+export function getJson(url: string, opts?: FetchOptions): Promise<unknown>;
+export function fetchStationList(opts?: FetchOptions): Promise<NoaaStation[]>;
+export function fetchHarcon(stationId: string, bin: number, opts?: FetchOptions): Promise<NoaaConstituent[]>;
+export function fetchOffsets(stationId: string, currbin: number, opts?: FetchOptions): Promise<Record<string, number | string>>;
+export function fetchCurrentPredictions(
+  stationId: string, bin: number, start: Date, end: Date, opts?: FetchOptions,
+): Promise<CurrentPrediction[]>;
+export function extractBundle(opts?: ExtractOptions): Promise<ExtractResult>;
+export function harmonicKey(id: string, bin: number, primaryBin: number): string;
+export function captureGolden(
+  stationId: string, currbin: number, start: Date, end: Date, opts?: FetchOptions,
+): Promise<GoldenFixture>;
+
+export const MDAPI: string;
+export const DATAGETTER: string;
+export const UA: string;

package/index.js

@@ -0,0 +1,6 @@
+export {
+  getJson, fetchStationList, fetchHarcon, fetchOffsets, fetchCurrentPredictions,
+  MDAPI, DATAGETTER, UA,
+} from './src/noaa.js';
+export { extractBundle, harmonicKey } from './src/extract.js';
+export { captureGolden } from './src/golden.js';

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@openwaters/noaa-current-stations",
+  "version": "0.4.0",
+  "description": "NOAA CO-OPS tidal-current station data: harmonic constituents, subordinate offsets, and the live predictions API — extractor, schema, and the API's undocumented gotchas",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "noaa-current-stations": "bin/noaa-current-stations.mjs"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "bin/",
+    "schema/",
+    "docs/"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "extract:us": "node bin/noaa-current-stations.mjs extract currents.json",
+    "validate": "node --test",
+    "bundle:min": "node -e \"const f=require('fs');f.writeFileSync('currents.min.json',JSON.stringify(JSON.parse(f.readFileSync('currents.json','utf8'))))\"",
+    "validate:bundle": "node bin/noaa-current-stations.mjs validate currents.json"
+  },
+  "keywords": [
+    "noaa",
+    "co-ops",
+    "tidal-currents",
+    "currents",
+    "harmonic-constituents",
+    "tides",
+    "marine",
+    "navigation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openwatersio/noaa-current-stations.git"
+  },
+  "homepage": "https://github.com/openwatersio/noaa-current-stations#readme",
+  "bugs": "https://github.com/openwatersio/noaa-current-stations/issues",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/schema/currents.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/openwatersio/noaa-current-stations/schema/currents.schema.json",
+  "title": "NOAA current-station bundle",
+  "description": "Tidal-current stations extracted from NOAA CO-OPS metadata. Harmonic stations carry their own constituents; subordinate stations reduce against a harmonic reference. Speeds are knots, directions degrees true, time offsets seconds.",
+  "type": "object",
+  "required": ["note", "stations"],
+  "properties": {
+    "note": { "type": "string", "description": "Provenance and licensing." },
+    "generated": { "type": "string", "format": "date-time" },
+    "crossFlow": {
+      "type": ["object", "null"],
+      "description": "Census of NOAA `minorMeanSpeed` — flow perpendicular to the flood axis, present at all times including slack. This bundle's major-axis model drops it; this records how much it drops. Not carried per station. Null when the bundle has no harmonic stations.",
+      "properties": {
+        "measured": { "type": "string" },
+        "records": { "type": "integer", "description": "Harmonic records sampled, `@bin` entries included." },
+        "gte0_25kn": { "type": "integer" },
+        "gte0_50kn": { "type": "integer" },
+        "worstRatio": {
+          "type": "object",
+          "description": "Largest crossFlow/alongAxisPeak — where the flood axis describes the station worst.",
+          "properties": {
+            "id": { "type": "string" },
+            "crossFlow": { "type": "number" },
+            "alongAxisPeak": {
+              "type": "number",
+              "description": "Σ|majorAmplitude| + |Z0| — a theoretical maximum reached only if every constituent aligned in phase, not a realized peak speed. The denominator `ratio` and the 0.5 bound are only meaningful given this definition."
+            },
+            "ratio": { "type": "number" }
+          }
+        },
+        "worstAbsolute": {
+          "type": "object",
+          "description": "Largest crossFlow in knots — usually a different station from worstRatio.",
+          "properties": {
+            "id": { "type": "string" },
+            "crossFlow": { "type": "number" }
+          }
+        }
+      }
+    },
+    "stations": {
+      "type": "array",
+      "items": { "oneOf": [{ "$ref": "#/$defs/harmonic" }, { "$ref": "#/$defs/subordinate" }] }
+    }
+  },
+  "$defs": {
+    "harmonic": {
+      "type": "object",
+      "required": ["id", "name", "latitude", "longitude", "type", "floodDirection", "ebbDirection", "offset", "constituents"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "NOAA station id at its primary bin, or `id@bin` for a reference at a non-primary bin. Constituents vary by depth bin, so identity is (station, bin)."
+        },
+        "name": { "type": "string" },
+        "latitude": { "type": "number" },
+        "longitude": { "type": "number" },
+        "type": { "const": "harmonic" },
+        "floodDirection": { "type": "number", "description": "Major-axis azimuth (NOAA `azi`), degrees true." },
+        "ebbDirection": { "type": "number", "description": "floodDirection + 180." },
+        "offset": {
+          "type": "number",
+          "description": "Z0 — net mean flow along the major axis, knots, signed (NOAA `majorMeanSpeed`). A DC offset on the velocity curve; omitting it moves every slack."
+        },
+        "constituents": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["name", "amplitude", "phase"],
+            "properties": {
+              "name": { "type": "string", "description": "Darwin symbol, e.g. M2, K1." },
+              "amplitude": { "type": "number", "description": "Knots (NOAA `majorAmplitude` under units=english)." },
+              "phase": { "type": "number", "description": "Greenwich phase, degrees (NOAA `majorPhaseGMT`)." }
+            }
+          }
+        }
+      }
+    },
+    "subordinate": {
+      "type": "object",
+      "required": ["id", "name", "latitude", "longitude", "type", "reference"],
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "latitude": { "type": "number" },
+        "longitude": { "type": "number" },
+        "type": { "const": "subordinate" },
+        "reference": {
+          "type": "string",
+          "description": "`id` of the harmonic station in this bundle to reduce against — including the `@bin` suffix when the reference is at a non-primary bin."
+        },
+        "floodDirection": { "type": "number" },
+        "ebbDirection": { "type": "number" },
+        "slackBeforeFloodOffset": { "type": "number", "description": "Seconds. Applied to a slack that precedes a flood." },
+        "slackBeforeEbbOffset": { "type": "number", "description": "Seconds. Applied to a slack that precedes an ebb." },
+        "floodTimeOffset": { "type": "number", "description": "Seconds, applied to max flood." },
+        "ebbTimeOffset": { "type": "number", "description": "Seconds, applied to max ebb." },
+        "floodSpeedRatio": { "type": "number", "description": "Multiplier on the reference max flood speed. A ratio, not a delta." },
+        "ebbSpeedRatio": { "type": "number", "description": "Multiplier on the reference max ebb speed." }
+      }
+    }
+  }
+}

package/src/cross-flow.js

@@ -0,0 +1,74 @@
+// What this package emits is a MAJOR-AXIS model: one signed speed along a fixed
+// flood axis. NOAA also publishes `minorMeanSpeed` — the DC component of flow
+// perpendicular to that axis, running at all times INCLUDING slack — and a
+// major-axis model drops it.
+//
+// The per-station minor axis is deliberately not carried (docs/schema.md). But a
+// bundle should be able to state the bound on its own approximation rather than
+// leave it unmeasured, so the extractor records this census instead.
+//
+// Measured 2026-08-15. Across the 856 records a full US bundle holds: worst
+// ratio 0.241 (BOS1130), worst absolute 0.80 kn (PUG1619 Marrowstone Point).
+// The 0.241 also holds across the full 2,800 bin-records across NOAA's 850
+// harmonic stations (not every bin at every one of NOAA's ~2,785 stations —
+// subordinates have no harcon at all), so the bound below is safe for bins we
+// don't currently take.
+
+/** Provenance, carried in the census so the number explains itself in the file. */
+const MEASURED =
+  'NOAA minorMeanSpeed — flow perpendicular to the flood axis, present at all times including slack';
+
+/**
+ * Ratio of cross-flow to along-axis peak above which the flood axis is a poor
+ * description of the station, and so the major-axis model there is suspect.
+ * ~2x the worst real value: a regression guard, not a quality gate.
+ */
+export const CROSS_FLOW_RATIO_MAX = 0.5;
+
+const r3 = (n) => Math.round(n * 1000) / 1000;
+
+/**
+ * @param {{id: string, crossFlow: number, alongAxisPeak: number}[]} samples
+ * @returns {object|null} the census, or null when there is nothing to measure
+ */
+export function crossFlowCensus(samples) {
+  if (!samples?.length) return null;
+
+  let gte0_25kn = 0;
+  let gte0_50kn = 0;
+  // Kept as raw (unrounded) values through the loop — comparing a raw incoming
+  // value against an already-r3-rounded stored one lets a within-0.0005 runner-up
+  // win by rounding luck. Rounding happens once, on the way out.
+  let worstRatio = null;
+  let worstAbsolute = null;
+
+  for (const s of samples) {
+    // A station with no along-axis flow has no axis to be wrong about.
+    const ratio = s.alongAxisPeak > 0 ? s.crossFlow / s.alongAxisPeak : 0;
+    if (s.crossFlow >= 0.25) gte0_25kn += 1;
+    if (s.crossFlow >= 0.5) gte0_50kn += 1;
+
+    // Tracked separately on purpose: the largest ratio and the largest current
+    // are usually different stations, and they answer different questions.
+    if (!worstRatio || ratio > worstRatio.ratio) {
+      worstRatio = { id: s.id, crossFlow: s.crossFlow, alongAxisPeak: s.alongAxisPeak, ratio };
+    }
+    if (!worstAbsolute || s.crossFlow > worstAbsolute.crossFlow) {
+      worstAbsolute = { id: s.id, crossFlow: s.crossFlow };
+    }
+  }
+
+  return {
+    measured: MEASURED,
+    records: samples.length,
+    gte0_25kn,
+    gte0_50kn,
+    worstRatio: worstRatio && {
+      id: worstRatio.id,
+      crossFlow: r3(worstRatio.crossFlow),
+      alongAxisPeak: r3(worstRatio.alongAxisPeak),
+      ratio: r3(worstRatio.ratio),
+    },
+    worstAbsolute: worstAbsolute && { id: worstAbsolute.id, crossFlow: r3(worstAbsolute.crossFlow) },
+  };
+}

package/src/drift.js

@@ -0,0 +1,64 @@
+// Detect drift in NOAA's current-station list.
+//
+// NOAA revises the list — stations get added, retired, or reclassified. That is not an
+// error, but it must never be silent: a station appearing means the bundle is stale, and
+// one disappearing means something downstream may reference a station that no longer
+// exists. We went 855 → 856 harmonic between two extractions and only noticed by
+// diffing bundles.
+//
+// This is deliberately cheap — ONE request for the station list, no per-station harcon
+// fetches — so it can run on a schedule. It detects list-level drift (which stations
+// exist, and their type). It does NOT detect a station's constituents being revised in
+// place; that needs a full re-extraction and a bundle diff.
+
+import { fetchStationList } from './noaa.js';
+
+/** Reduce a live station list to the shape we pin. */
+export function summarize(stations) {
+  const counts = { H: 0, S: 0, W: 0 };
+  for (const s of stations) counts[s.type] = (counts[s.type] ?? 0) + 1;
+  return {
+    counts: { ...counts, total: stations.length },
+    ids: stations.map((s) => `${s.id}:${s.type}`).sort(),
+  };
+}
+
+/**
+ * Compare a live summary against a pinned lock.
+ * @returns {{drifted: boolean, added: string[], removed: string[], retyped: string[],
+ *            counts: object, expected: object}}
+ */
+export function diffAgainstLock(live, lock) {
+  const parse = (list) => new Map(list.map((e) => e.split(':')));
+  const now = parse(live.ids);
+  const then = parse(lock.ids);
+
+  const added = [...now.keys()].filter((id) => !then.has(id)).map((id) => `${id} (${now.get(id)})`);
+  const removed = [...then.keys()].filter((id) => !now.has(id)).map((id) => `${id} (${then.get(id)})`);
+  // A reclassification changes how a station is predicted — it matters as much as an
+  // addition, and a plain count check can miss it entirely (H→S keeps the total equal).
+  const retyped = [...now.keys()]
+    .filter((id) => then.has(id) && then.get(id) !== now.get(id))
+    .map((id) => `${id} (${then.get(id)} → ${now.get(id)})`);
+
+  return {
+    drifted: added.length > 0 || removed.length > 0 || retyped.length > 0,
+    added, removed, retyped,
+    counts: live.counts, expected: lock.counts,
+  };
+}
+
+export async function checkDrift(lock, opts = {}) {
+  const live = summarize(await fetchStationList({ paceMs: 0, ...opts }));
+  return diffAgainstLock(live, lock);
+}
+
+export function buildLock(stations) {
+  return {
+    note: 'Pinned NOAA current-station list. `noaa-current-stations check` fails when NOAA\'s '
+      + 'live list no longer matches this. Regenerate with `noaa-current-stations lock`, and '
+      + 're-extract the bundle when it changes.',
+    generated: new Date().toISOString(),
+    ...summarize(stations),
+  };
+}