@openwaters/noaa-current-stations 0.4.0

package/src/extract.js

@@ -0,0 +1,156 @@
+// Build a current-station bundle from NOAA CO-OPS metadata.
+//
+// Two station kinds end up in the bundle:
+//   harmonic    — has its own constituents; predicted by summing them.
+//   subordinate — no constituents; predicted by applying time/speed offsets to a
+//                 reference station's harmonic prediction.
+//
+// The two traps this encodes, both found by validating against NOAA's own
+// predictions (docs/noaa-api.md, docs/validation.md):
+//   1. A reference is (station, BIN), not a station. Constituents vary by depth bin
+//      and a station may publish several. Keying by id alone silently predicts from
+//      the wrong depth — and a single-station test can pass by luck.
+//   2. A `type: S` station is not necessarily offset-reduced. Many survey-derived
+//      ones carry their own harcon and NOAA predicts those harmonically; applying
+//      the reduction to them overshoots badly (PUG1716: 89 min wrong as a reduction,
+//      6.8 min as harmonic). Always try own-harcon first.
+
+import { fetchStationList, fetchHarcon, fetchOffsets } from './noaa.js';
+import { crossFlowCensus } from './cross-flow.js';
+
+const BUNDLE_NOTE = 'Generated from NOAA CO-OPS mdapi (harcon@currbin + currentpredictionoffsets). '
+  + 'NOAA data is public domain; derived predictions are UNOFFICIAL and not for navigation.';
+
+/** A harmonic entry's bundle key: plain id at the primary bin, `id@bin` otherwise. */
+export const harmonicKey = (id, bin, primaryBin) => (bin === primaryBin ? id : `${id}@${bin}`);
+
+/**
+ * @param {object} opts
+ * @param {[number,number,number,number]} [opts.box] [south, west, north, east]; omit for all US.
+ * @param {string[]} [opts.stations] explicit station ids; overrides `box`.
+ * @param {(msg: string) => void} [opts.log]
+ */
+export async function extractBundle(opts = {}) {
+  const { box, stations: wanted, log = () => {}, ...fetchOpts } = opts;
+
+  const all = await fetchStationList(fetchOpts);
+  const primaryBin = new Map(all.map((s) => [s.id, s.currbin]));
+
+  let selected = all;
+  if (wanted?.length) {
+    const want = new Set(wanted);
+    selected = all.filter((s) => want.has(s.id));
+    const missing = wanted.filter((id) => !selected.some((s) => s.id === id));
+    if (missing.length) throw new Error(`not in NOAA's station list: ${missing.join(', ')}`);
+  } else if (box) {
+    const [south, west, north, east] = box;
+    selected = all.filter((s) => s.lat >= south && s.lat <= north && s.lng >= west && s.lng <= east);
+  }
+  log(`${selected.length} stations selected (of ${all.length} US current stations)`);
+
+  const harmonic = new Map();
+  const subs = [];
+  const skipped = { typeW: 0, emptyHarcon: [], noReference: [], failed: [] };
+  // Sampled as each harmonic record is built, because the minor axis is in the
+  // harcon we already hold here and nowhere else downstream.
+  const crossFlowSamples = [];
+
+  // Store (id, bin) if it has a non-empty harcon. Returns whether it did.
+  async function ensureHarmonic(key, id, bin, name, lat, lng) {
+    if (harmonic.has(key)) return true;
+    let cons;
+    try {
+      cons = await fetchHarcon(id, bin, fetchOpts);
+    } catch (e) {
+      skipped.failed.push(`${key}: ${e.message}`);
+      return false;
+    }
+    if (!cons.length) return false;
+    // azi is the major-axis azimuth (flood set); ebb is its reciprocal.
+    // majorMeanSpeed is Z0 — the station's net mean flow along that axis. Omitting
+    // it shifts every slack, because slack is where the curve crosses zero.
+    const azi = cons[0].azi ?? 0;
+    harmonic.set(key, {
+      id: key, name, type: 'harmonic',
+      latitude: lat, longitude: lng,
+      floodDirection: azi,
+      ebbDirection: (azi + 180) % 360,
+      offset: cons[0].majorMeanSpeed ?? 0,
+      constituents: cons.map((c) => ({
+        name: c.constituentName,
+        amplitude: c.majorAmplitude,   // knots, because units=english
+        phase: c.majorPhaseGMT,        // Greenwich phase — pairs with a Greenwich V₀
+      })),
+    });
+    crossFlowSamples.push({
+      id: key,
+      crossFlow: Math.abs(cons[0].minorMeanSpeed ?? 0),
+      alongAxisPeak: cons.reduce((sum, c) => sum + Math.abs(c.majorAmplitude ?? 0), 0)
+        + Math.abs(cons[0].majorMeanSpeed ?? 0),
+    });
+    return true;
+  }
+
+  for (const s of selected) {
+    if (s.type === 'W') { skipped.typeW++; continue; }  // weak/rotary — not modeled
+    if (await ensureHarmonic(s.id, s.id, s.currbin, s.name, s.lat, s.lng)) continue;
+    if (s.type === 'H') { skipped.emptyHarcon.push(s.id); continue; }
+
+    let o;
+    try {
+      o = await fetchOffsets(s.id, s.currbin, fetchOpts);
+    } catch (e) {
+      skipped.failed.push(`${s.id}: ${e.message}`);
+      continue;
+    }
+    if (!o.refStationId) { skipped.noReference.push(s.id); continue; }
+    subs.push({
+      id: s.id, name: s.name, type: 'subordinate',
+      latitude: s.lat, longitude: s.lng,
+      reference: harmonicKey(o.refStationId, o.refStationBin, primaryBin.get(o.refStationId)),
+      _refId: o.refStationId, _refBin: o.refStationBin,
+      floodDirection: o.meanFloodDir, ebbDirection: o.meanEbbDir,
+      // Two slack offsets: a slack takes the offset for the phase it PRECEDES.
+      slackBeforeFloodOffset: Math.round((o.sbfTimeAdjMin ?? 0) * 60),
+      slackBeforeEbbOffset: Math.round((o.sbeTimeAdjMin ?? 0) * 60),
+      floodTimeOffset: Math.round((o.mfcTimeAdjMin ?? 0) * 60),
+      ebbTimeOffset: Math.round((o.mecTimeAdjMin ?? 0) * 60),
+      floodSpeedRatio: o.mfcAmpAdj ?? 1,   // ratios on the reference peak, not deltas
+      ebbSpeedRatio: o.mecAmpAdj ?? 1,
+    });
+  }
+
+  // Pull in each referenced (id, bin) that selection didn't already cover.
+  for (const sub of subs) {
+    if (harmonic.has(sub.reference)) continue;
+    const ref = all.find((s) => s.id === sub._refId);
+    if (!ref) {
+      // No station-list record means no lat/lng — building the harmonic entry anyway
+      // would silently violate the schema's required position fields.
+      skipped.failed.push(`${sub.id}: reference station ${sub._refId} not in NOAA's station list`);
+      continue;
+    }
+    await ensureHarmonic(sub.reference, sub._refId, sub._refBin, ref.name, ref.lat, ref.lng);
+  }
+
+  const resolved = subs.filter((x) => harmonic.has(x.reference));
+  const unresolvable = subs.length - resolved.length;
+  const stations = [
+    ...harmonic.values(),
+    ...resolved.map(({ _refId, _refBin, ...x }) => x),
+  ];
+
+  log(`${harmonic.size} harmonic, ${resolved.length} subordinate, ${skipped.typeW} type-W skipped, `
+    + `${unresolvable} unresolvable references dropped`);
+  for (const f of skipped.failed) log(`  failed: ${f}`);
+
+  return {
+    bundle: {
+      note: BUNDLE_NOTE,
+      generated: new Date().toISOString(),
+      crossFlow: crossFlowCensus(crossFlowSamples),
+      stations,
+    },
+    skipped: { ...skipped, unresolvable },
+  };
+}

package/src/golden.js

@@ -0,0 +1,52 @@
+// Capture a validation fixture: a station's constituents PLUS NOAA's own published
+// predictions for the same station and days.
+//
+// This is the heart of how anything here gets trusted. A current engine is a pile of
+// trigonometry that always produces plausible-looking output; the only way to know it
+// is right is to feed it NOAA's constituents, predict the same window NOAA published,
+// and diff. Both halves come from NOAA, so the comparison is self-contained and the
+// resulting fixture replays offline forever.
+
+import { fetchHarcon, fetchCurrentPredictions } from './noaa.js';
+
+/**
+ * @param {string} stationId
+ * @param {number} currbin the station's reference bin — harcon is EMPTY at any other
+ * @param {Date} start
+ * @param {Date} end
+ */
+export async function captureGolden(stationId, currbin, start, end, opts = {}) {
+  const cons = await fetchHarcon(stationId, currbin, opts);
+  if (!cons.length) {
+    throw new Error(`${stationId}: empty harcon at bin ${currbin} — wrong bin, or a true subordinate`);
+  }
+
+  let events = [];
+  let predictionsError;
+  try {
+    events = await fetchCurrentPredictions(stationId, currbin, start, end, opts);
+  } catch (e) {
+    // The currents_predictions product has had outages (it was down 2026-07-18, which
+    // cost us a day of wrong conclusions). Capture the constituents anyway and let the
+    // consuming test skip until this is re-run.
+    predictionsError = e.message;
+  }
+
+  const azi = cons[0].azi ?? 0;
+  return {
+    note: 'NOAA CO-OPS: harmonic constituents + NOAA\'s own published predictions for the '
+      + 'same window. Public domain. Regenerate with `noaa-current-stations golden`.',
+    station: stationId,
+    bin: currbin,
+    start: start.toISOString(),
+    end: end.toISOString(),
+    floodDirection: azi,
+    ebbDirection: (azi + 180) % 360,
+    offset: cons[0].majorMeanSpeed ?? 0,
+    constituents: cons.map((c) => ({
+      name: c.constituentName, amplitude: c.majorAmplitude, phase: c.majorPhaseGMT,
+    })),
+    events,
+    ...(predictionsError ? { predictionsError } : {}),
+  };
+}

package/src/noaa.js

@@ -0,0 +1,110 @@
+// NOAA CO-OPS API client — the single place this org talks to tidesandcurrents.noaa.gov.
+//
+// Everything surprising about this API is documented in docs/noaa-api.md. The short
+// version, because it costs people days:
+//   - harcon.json returns an EMPTY constituent list unless you pass the station's
+//     `currbin`. bin=0 looks like "NOAA has no current constituents". It does.
+//   - `units=english` yields knots; `units=metric` yields cm/s. We use english.
+//   - the station list repeats each station once per depth bin; de-dup keep-first.
+//   - NOAA throttles bulk callers. An extraction is thousands of requests: pace them.
+
+const MDAPI = 'https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi';
+const DATAGETTER = 'https://api.tidesandcurrents.noaa.gov/api/prod/datagetter';
+
+// NOAA has been reported to 404 unfamiliar clients. We could not reproduce that in
+// 2026-07 (see docs/noaa-api.md § User-Agent), but a real UA costs nothing and the
+// `application` parameter below is NOAA's documented way to identify a caller.
+const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 '
+  + '(KHTML, like Gecko) Chrome/126.0 Safari/537.36';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Paced JSON GET. NOAA throttles bulk callers, and an extraction is thousands of
+ * requests — `paceMs` is the knob that keeps a full run from getting rate-limited.
+ *
+ * Retries 5xx/429 and network errors with exponential backoff. A full extraction is
+ * ~2,800 requests over ~25 minutes; without this a single transient 504 fails the run
+ * (2026-08-01: HUR0615 504'd once, discarding the whole monthly refresh). A 4xx is a
+ * real answer about the station — retrying it just wastes the pacing budget.
+ */
+export async function getJson(url, { paceMs = 400, fetchFn = fetch, retries = 3, retryMs = 1000 } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    if (paceMs) await sleep(paceMs);
+    let resp;
+    try {
+      resp = await fetchFn(url, { headers: { 'User-Agent': UA } });
+    } catch (e) {
+      if (attempt >= retries) throw e;
+      await sleep(retryMs * 2 ** attempt);
+      continue;
+    }
+    if (resp.ok) return resp.json();
+    if (attempt >= retries || (resp.status < 500 && resp.status !== 429)) {
+      throw new Error(`NOAA ${resp.status} ${url}`);
+    }
+    await sleep(retryMs * 2 ** attempt);
+  }
+}
+
+/** Every current-prediction station NOAA publishes, de-duped to its primary bin. */
+export async function fetchStationList(opts = {}) {
+  const list = await getJson(`${MDAPI}/stations.json?type=currentpredictions&units=english`, opts);
+  const seen = new Set();
+  // The list repeats a station once per bin; the FIRST entry carries the primary bin.
+  return list.stations.filter((s) => (seen.has(s.id) ? false : (seen.add(s.id), true)));
+}
+
+/**
+ * Harmonic constituents at a specific depth bin. Returns [] when the station has
+ * none at that bin — which is the normal, expected answer for a true subordinate,
+ * and also what you get for ANY station if you pass the wrong bin.
+ */
+export async function fetchHarcon(stationId, bin, opts = {}) {
+  const hc = await getJson(`${MDAPI}/stations/${stationId}/harcon.json?units=english&bin=${bin}`, opts);
+  return hc.HarmonicConstituents ?? [];
+}
+
+/** Subordinate-station time/speed offsets. Note the `<id>_<currbin>` composite path. */
+export async function fetchOffsets(stationId, currbin, opts = {}) {
+  return getJson(`${MDAPI}/stations/${stationId}_${currbin}/currentpredictionoffsets.json`, opts);
+}
+
+/**
+ * NOAA's own published slack/max-flood/max-ebb predictions — the oracle every
+ * prediction engine in this org is validated against, and a live data source in
+ * its own right.
+ */
+export async function fetchCurrentPredictions(stationId, bin, start, end, opts = {}) {
+  const ymd = (d) => d.toISOString().slice(0, 10).replace(/-/g, '');
+  const params = new URLSearchParams({
+    product: 'currents_predictions', interval: 'max_slack', time_zone: 'gmt',
+    units: 'english', format: 'json', application: opts.application ?? 'noaa-current-stations',
+    station: stationId, bin: String(bin), begin_date: ymd(start), end_date: ymd(end),
+  });
+  const body = await getJson(`${DATAGETTER}?${params}`, { paceMs: 0, ...opts });
+  // NOAA has shipped both shapes of this response.
+  const rows = Array.isArray(body.current_predictions)
+    ? body.current_predictions
+    : (body.current_predictions?.cp ?? []);
+  return rows.map((r) => {
+    const raw = String(r.Type ?? r.type ?? '').toLowerCase();
+    // Only these three are meaningful. Anything else becomes 'unknown' rather than
+    // being folded into one of them — a mislabeled ebb is worse than an ignored row.
+    const kind = raw.startsWith('slack') ? 'slack'
+      : raw.startsWith('flood') ? 'flood'
+        : raw.startsWith('ebb') ? 'ebb' : 'unknown';
+    return {
+      // "YYYY-MM-DD HH:MM" is UTC when requested with time_zone=gmt.
+      time: new Date(String(r.Time ?? r.t).replace(' ', 'T') + 'Z').toISOString(),
+      kind,
+      velocityMajor: Number(r.Velocity_Major ?? r.velocity ?? 0),
+      // Both directions are repeated on every row; they are the station's measured
+      // principal axes and are more authoritative than anything hand-configured.
+      meanFloodDir: Number(r.meanFloodDir),
+      meanEbbDir: Number(r.meanEbbDir),
+    };
+  });
+}
+
+export { MDAPI, DATAGETTER, UA };

package/src/validate.js

@@ -0,0 +1,61 @@
+// Structural checks on a bundle. Cheap, and they catch the failures that actually
+// happen: a truncated/partial extraction, or a subordinate pointing at a reference
+// that isn't there (which silently yields no prediction at that station).
+
+import { CROSS_FLOW_RATIO_MAX } from './cross-flow.js';
+
+/** @returns {{ok: boolean, counts: object, crossFlow: object|null, errors: string[]}} */
+export function validateBundle(bundle) {
+  const errors = [];
+  const stations = bundle?.stations;
+  if (!Array.isArray(stations)) return { ok: false, counts: {}, crossFlow: null, errors: ['no stations array'] };
+
+  const harmonic = stations.filter((s) => s.type === 'harmonic');
+  const subordinate = stations.filter((s) => s.type === 'subordinate');
+  const ids = new Set(harmonic.map((s) => s.id));
+
+  const orphans = subordinate.filter((s) => !ids.has(s.reference));
+  if (orphans.length) {
+    errors.push(`${orphans.length} subordinate(s) reference a missing station: `
+      + orphans.slice(0, 5).map((s) => `${s.id}→${s.reference}`).join(', '));
+  }
+
+  const dupes = stations.length - new Set(stations.map((s) => s.id)).size;
+  if (dupes) errors.push(`${dupes} duplicate station id(s)`);
+
+  const noCons = harmonic.filter((s) => !s.constituents?.length);
+  if (noCons.length) errors.push(`${noCons.length} harmonic station(s) with no constituents`);
+
+  // Z0 absent is a silent, systematic slack-timing error — the exact bug this project
+  // was started to fix. A bundle without it anywhere is a broken extraction.
+  const withZ0 = harmonic.filter((s) => typeof s.offset === 'number').length;
+  if (harmonic.length && withZ0 === 0) errors.push('no harmonic station carries a Z0 offset');
+
+  const unknownType = stations.filter((s) => s.type !== 'harmonic' && s.type !== 'subordinate');
+  if (unknownType.length) errors.push(`${unknownType.length} station(s) of unknown type`);
+
+  const badPosition = stations.filter((s) => !Number.isFinite(s.latitude) || !Number.isFinite(s.longitude));
+  if (badPosition.length) {
+    errors.push(`${badPosition.length} station(s) missing a finite latitude/longitude: `
+      + badPosition.slice(0, 5).map((s) => s.id).join(', '));
+  }
+
+  // The bundle's whole model is one signed speed along a fixed flood axis. When
+  // cross-axis flow gets large next to the along-axis flow, that axis has stopped
+  // describing the station and the model there is suspect. A bundle predating this
+  // census carries no block — absent is "not measured", not "failed".
+  const cf = bundle.crossFlow ?? null;
+  if (cf?.worstRatio && cf.worstRatio.ratio > CROSS_FLOW_RATIO_MAX) {
+    errors.push(
+      `cross-flow ratio ${cf.worstRatio.ratio} at ${cf.worstRatio.id} exceeds ${CROSS_FLOW_RATIO_MAX} `
+      + '— the flood axis no longer describes that station, so its major-axis model is suspect',
+    );
+  }
+
+  return {
+    ok: errors.length === 0,
+    counts: { harmonic: harmonic.length, subordinate: subordinate.length, total: stations.length },
+    crossFlow: cf,
+    errors,
+  };
+}