v0.5.0 — the bundle ships

The package now ships currents.json, the thing it is named for. The README has
claimed this since before the cutover — "ships it as a versioned bundle ... so you
don't have to talk to the API at all" — but files excluded it, so the published
tarball was 24 KB of tooling and getting the data meant a paced, several-minute
extraction against NOAA CO-OPS.

Use it

import bundle from "@openwaters/noaa-current-stations/currents.json" with { type: "json" };

// { note, generated, crossFlow, stations } — records live under `stations`,
// and their ids are bare NOAA keys, unprefixed.
const deception = bundle.stations.find((s) => s.id === "PUG1701");

That path is a supported entry point and will not move without a major version.
Both details above are easy to get wrong from outside the package, which is why
they are now in the README rather than left to be reverse-engineered.

2,561 stations — 856 harmonic and the rest subordinate, carrying constituents,
flood and ebb directions, offsets and positions.

Cost

About 260 KB on the wire, 3.2 MB unpacked. JSON compresses well, so the
download grows roughly 12×, not the 125× the unpacked size implies. Nothing imports
the bundle implicitly: consumers that only want the extractor, the CLI or the
schema are unaffected.

Not included

No exports map. The package has never had one, so every path in the tarball is
importable today; adding one would restrict src/ and docs/ and break any
consumer reaching for them. That is a major-version decision, separate from
shipping data.

0.4.0

Clean-break release under Open Waters:

• npm: @openwaters/noaa-current-stations
• CLI: noaa-current-stations
• repository: openwatersio/noaa-current-stations

The JavaScript API and NOAA current-station bundle format remain unchanged. The old @sailingnaturali/current-stations package remains installable for pinned consumers and points new consumers here.

v0.3.0 — cross-flow census and bound

Measures and bounds the 1-D major-axis approximation this package emits.

What this adds

The bundle models each station as 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 — which the extractor fetched and discarded.

Bundles now carry a crossFlow census at the root (~200 bytes) recording how much the major-axis model drops:

cross-flow (856 harmonic records): 62 >= 0.25 kn, 12 >= 0.50 kn
  worst ratio    0.241 at BOS1130 (0.178 kn across a 0.74 kn axis)
  worst absolute 0.803 kn at PUG1619

validateBundle fails above a cross-flow/along-axis ratio of 0.5. Because the census is stored on the bundle rather than printed, that check runs offline against any bundle with no re-extraction. extract and validate both print it.

alongAxisPeak is Σ|majorAmplitude| + |Z₀| — a theoretical maximum where every constituent aligns, not a realized peak. The ratio only means anything given that denominator, so it is documented in the schema and the types.

What this deliberately does not add

No per-station minor-axis data. Bundling the full minor axis was measured and rejected: it is worth a median 4% of peak speed, and a 2-D magnitude series never crosses zero — so slack detection silently returns nothing at 836 of 850 stations. The census provides the diagnostic without the payload.

Compatibility

Additive and backward compatible. A bundle without a crossFlow block still validates — absent means "not measured", never "failed". No breaking changes to any existing field.

index.d.ts gains CrossFlowCensus, Bundle.crossFlow, and a previously missing NoaaConstituent.minorMeanSpeed.

Bundle asset

The attached currents.json is the minified US bundle: 856 harmonic + 1,705 subordinate stations, 0 unresolvable references. No NOAA station data changed since the previous bundle — the diff is the census block alone.

v0.2.1

Guard: a subordinate whose reference station is absent from NOAA's station list is skipped loudly instead of emitting an unpositioned bundle entry; validate.js now requires finite positions.

v0.2.0

Bundle entries now carry latitude/longitude from the NOAA station list.

v0.1.0

First release.

NOAA CO-OPS tidal-current station data — the extractor, the schema, the validation
method, and a write-up of how the API actually behaves.

currents.json (attached) is the prebuilt US bundle: 856 harmonic + 1,705
subordinate stations, 0 unresolved references. Vendor it, or extract your own subset
with the CLI.

npm install @sailingnaturali/current-stations
npx current-stations extract mine.json --stations PUG1717,PUG1701

What's in here

• Extractor for NOAA's station list, harmonic constituents, and subordinate offsets
• Live predictions client (currents_predictions)
• current-stations check — one request, fails when NOAA's station list drifts from
  the pinned lock (runs weekly here)
• current-stations golden — captures constituents plus NOAA's own predictions into
  one fixture, so a prediction engine can be validated offline
• JSON Schema for the bundle, and TypeScript types

The parts that cost us days

Documented in docs/noaa-api.md:

• harcon.json returns an empty list at any bin except the station's currbin —
  which reads as "NOAA doesn't publish current constituents." It does, for 856 stations.
• Z₀ (majorMeanSpeed) is a DC offset on the velocity curve, and slack is where that
  curve crosses zero. Omitting it measured 15.6 min mean error; including it, 7.4.
• A reference is a (station, bin) pair, not a station — 14 subordinates in US waters
  reduce against a non-primary bin.
• A type: S station is not necessarily offset-reduced; 1 of 1,706 carries its own
  harcon, and predicting it the other way is 89 minutes wrong.

Zero dependencies. Code MIT; NOAA data is public domain. Derived predictions are
unofficial — not for navigation.