Add createCorrectionsCache to cache expensive calculations

[bkeepers]

When predicting tides for many stations at the same time, astronomical computations (node corrections, equilibrium arguments) are identical across all stations for a given time. By default each predictor computes these independently. Passing a shared CorrectionsCache eliminates this redundancy.

import { createCorrectionsCache, createTidePredictor } from "@neaps/tide-predictor";

const cache = createCorrectionsCache();
const time = new Date();

for (const station of stations) {
  const predictor = createTidePredictor(station.constituents, { cache });
  results.push(predictor.getWaterLevelAtTime({ time }));
}

createCorrectionsCache(options?)

Returns a CorrectionsCache that can be passed to multiple createTidePredictor calls.

Options:

• interval - Quantization interval in hours for node corrections (default: 24). Node corrections change by less than 0.01% per day, so the default introduces less than 0.1 mm of error.

Note

The cache grows by roughly 36 KB per 24-hour bucket (corrections are stored for all ~400 constituent models to enable sharing across any station), so a year of predictions uses around 13 MB. For century-scale prediction tables, consider creating a new cache per time range.

---

$ npx vitest bench
…
 BENCH  Summary

  with shared cache — corrections computed once - test/benchmarks/corrections-cache.bench.ts > many-stations-single-time: getWaterLevelAtTime
    30.54x faster than without cache — corrections recomputed per station

  with shared cache — corrections shared across time steps and stations - test/benchmarks/corrections-cache.bench.ts > time-series × many-stations: getWaterLevelAtTime
    36.91x faster than without cache — corrections recomputed per (time, station)

fixes #222

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!