@openwaters/almanac 0.1.0 → 0.2.0

package/README.md

@@ -15,7 +15,9 @@ Supported interval: 1950-01-01T00:00Z ≤ t < 2101-01-01T00:00Z; results outside
 raise a typed error. All instants are UT1-accurate, not civil-UTC-accurate in the far
 future — see the design spec's Conventions section for what that means and why.
 
-Design: [`docs/superpowers/specs/2026-08-28-almanac-v1-design.md`](docs/superpowers/specs/2026-08-28-almanac-v1-design.md)
+- Design: [`docs/superpowers/specs/2026-08-28-almanac-v1-design.md`](docs/superpowers/specs/2026-08-28-almanac-v1-design.md)
+- Roadmap: [`docs/ROADMAP.md`](docs/ROADMAP.md) — what ships next, and what will not.
+- Landing page: [openwaters.io/sky](https://openwaters.io/sky) — the library running live in a browser.
 
 Algorithms translated from [Astronomy Engine](https://github.com/cosinekitty/astronomy)
 (MIT, Don Cross) — see [NOTICE](NOTICE). MIT licensed.
@@ -47,7 +49,7 @@ for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
 ### Swift
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.1.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.2.0")
 ```
 
 ```swift
@@ -67,9 +69,33 @@ for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
 }
 ```
 
+### Eclipse searches
+
+Search for a previous eclipse or all eclipses in a time window:
+
+```ts
+import { previousLunarEclipse, lunarEclipses } from '@openwaters/almanac';
+const last = previousLunarEclipse(new Date());
+const eclipses = lunarEclipses(new Date('2026-08-24T00:00:00Z'), new Date('2026-09-02T12:00:00Z'));
+```
+
+```swift
+let last = try previousLunarEclipse(before: Date())
+let eclipses = try lunarEclipses(from: today, to: tomorrow)
+```
+
+Ranges include peaks at the start and exclude peaks at the end. Contacts may
+extend outside the range. Previous/next searches skip peaks within 100 ms of the
+anchor. Search results are global; apply `lunarEclipseVisibility` for an observer.
+
 ### Performance
 
 Event searches (`sunEvents`/`moonEvents`) are linear in window length. The full
 151-year supported interval is a measured cost, not a guess: ~68 s in TypeScript,
 ~44 s in Swift release builds. Chunk or worker a full-range call rather than
 running it inline.
+
+Run `node benchmarks/run.mjs --base origin/main` from the repository root to
+compare both ports against a baseline. CI reports timings and fails on median
+regressions over 20%; see [the performance harness](CONTRIBUTING.md#performance)
+for workloads, results and local options.

package/dist/eclipse.d.ts

@@ -52,6 +52,18 @@ export interface LunarEclipseVisibility {
  *      interval, or if the next eclipse falls at or past the end of it.
  */
 export declare function nextLunarEclipse(after: Date): LunarEclipse;
+/**
+ * The last lunar eclipse whose peak falls strictly before `before`, skipping
+ * peaks within 100 ms of it, just as `nextLunarEclipse` does on the other side.
+ *
+ * @throws {AlmanacOutOfRangeError} if `before` is outside the supported
+ *      interval, or if the previous eclipse falls before its beginning.
+ */
+export declare function previousLunarEclipse(before: Date): LunarEclipse;
+/** Lunar eclipses with peaks in `[startUtc, endUtc)`, sorted ascending.
+ *  Contacts may fall outside the window. Visibility is observer-dependent;
+ *  use `lunarEclipseVisibility` on each result to check it. */
+export declare function lunarEclipses(startUtc: Date, endUtc: Date): LunarEclipse[];
 /**
  * Whether an observer can see each phase of a lunar eclipse — purely geometric:
  * the Moon's unrefracted topocentric centre must be above the horizon. A lunar

package/dist/eclipse.js

@@ -17,7 +17,7 @@
 //     result.
 //   - upstream reports semi-durations in minutes; the spec's public shape is
 //     the contact instants themselves, and `obscuration` is not in it.
-import { assertObserver, assertSupported, AlmanacOutOfRangeError, SUPPORTED_MAX } from './types.js';
+import { assertObserver, assertSupported, assertSupportedWindowEnd, AlmanacOutOfRangeError, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
 import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
 import { KM_PER_AU, RAD2DEG } from './nutation.js';
 import { calcMoon, moonGeoVectorEqj } from './moon.js';
@@ -44,25 +44,13 @@ const SHADOW_TOL_SECONDS = 1;
 /** UPSTREAM: `Search`'s default `iter_limit`. */
 const SHADOW_ITER_CAP = 20;
 /**
- * How close a candidate peak may sit to `after` and still be judged the same
- * eclipse, milliseconds.
+ * Peaks within 100 ms of a next/previous search anchor count as the same
+ * eclipse. The fixed full-moon seed below removes within-runtime drift; keep
+ * the band for peaks saved by older versions or computed on another runtime.
  *
- * A peak is only reproducible to about a millisecond: the full-moon seed comes
- * from a root finder with a 0.1 s tolerance, and the ±0.03 d peak-shadow window
- * built around it therefore differs slightly between two calls that reach the
- * same eclipse from different starting times, which moves the interpolated root
- * by an observed ≤1 ms. A caller walking the catalog by feeding each peak back
- * in would otherwise re-find that eclipse whenever the second evaluation landed
- * a millisecond later.
- *
- * The band cuts both ways, and both are bounded:
- *   - it can never swallow a real eclipse — consecutive lunar eclipses are
- *     never less than a month apart, 25 million times this window;
- *   - it *can* skip an eclipse the caller genuinely wanted: `after` set inside
- *     the 100 ms before a peak returns the eclipse after it, not that one.
- *     That is the accepted cost, and 100 ms is its ceiling — against a peak
- *     model that agrees with the Espenak catalog to ~15 s, a caller cannot have
- *     meant a boundary that sharp.
+ * This can skip a wanted peak when the anchor is within 100 ms of it, but
+ * cannot skip a distinct eclipse (the catalog's minimum gap is 29 days).
+ * Range searches use exact half-open bounds without this band.
  */
 const SAME_ECLIPSE_MS = 100;
 /** UPSTREAM: `CalcShadow`, astronomy.ts ~8458. */
@@ -102,7 +90,14 @@ function earthShadowSlope(ut) {
  * time derivative.
  */
 function peakEarthShadow(centerUt) {
-    const ut = search(earthShadowSlope, centerUt - PEAK_WINDOW_DAYS, centerUt + PEAK_WINDOW_DAYS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'peak earth shadow');
+    // Use the same full-moon seed regardless of search direction or window.
+    // Otherwise a ~1 ms root shift can lose/duplicate a peak when a caller
+    // splits a range at a previously returned peak. Only unpruned moons pay
+    // for this second phase search; its start is a fixed whole UT day.
+    const fullmoon = searchMoonPhase(180, Math.floor(centerUt) - 1, 4);
+    if (fullmoon === null)
+        throw new Error('almanac internal: cannot refine full moon');
+    const ut = search(earthShadowSlope, fullmoon - PEAK_WINDOW_DAYS, fullmoon + PEAK_WINDOW_DAYS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'peak earth shadow');
     if (ut === null)
         throw new Error('almanac internal: failed to find peak Earth shadow time');
     return earthShadow(ut);
@@ -138,17 +133,57 @@ function moonEclipticLatitudeDeg(ut) {
  *      interval, or if the next eclipse falls at or past the end of it.
  */
 export function nextLunarEclipse(after) {
-    assertSupported(after);
-    const startUt = utDays(after);
-    let fmUt = startUt;
-    while (fmUt <= startUt + SCAN_LIMIT_DAYS) {
-        // Search for the next full moon. Any eclipse will be near it.
-        const fullmoon = searchMoonPhase(180, fmUt, 40);
+    return nearestLunarEclipse(after, 1);
+}
+/**
+ * The last lunar eclipse whose peak falls strictly before `before`, skipping
+ * peaks within 100 ms of it, just as `nextLunarEclipse` does on the other side.
+ *
+ * @throws {AlmanacOutOfRangeError} if `before` is outside the supported
+ *      interval, or if the previous eclipse falls before its beginning.
+ */
+export function previousLunarEclipse(before) {
+    return nearestLunarEclipse(before, -1);
+}
+/** Lunar eclipses with peaks in `[startUtc, endUtc)`, sorted ascending.
+ *  Contacts may fall outside the window. Visibility is observer-dependent;
+ *  use `lunarEclipseVisibility` on each result to check it. */
+export function lunarEclipses(startUtc, endUtc) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    return scanLunarEclipses(startUtc.getTime(), endUtc.getTime(), 1, false);
+}
+function nearestLunarEclipse(anchor, direction) {
+    assertSupported(anchor);
+    const ms = anchor.getTime();
+    const startMs = direction > 0 ? ms + SAME_ECLIPSE_MS + 1 : Math.max(SUPPORTED_MIN, ms - SCAN_LIMIT_DAYS * 86400000);
+    const endMs = direction > 0 ? Math.min(SUPPORTED_MAX, ms + SCAN_LIMIT_DAYS * 86400000) : ms - SAME_ECLIPSE_MS;
+    const found = scanLunarEclipses(startMs, endMs, direction, true);
+    if (found.length)
+        return found[0];
+    if (direction > 0 ? endMs === SUPPORTED_MAX : startMs === SUPPORTED_MIN)
+        throw new AlmanacOutOfRangeError();
+    // The longest catalog gap is 178 days: exhausting 730 inside the supported
+    // interval is a broken shadow model, not a normal out-of-range result.
+    throw new Error(`almanac internal: no lunar eclipse within ${SCAN_LIMIT_DAYS} days of ${anchor.toISOString()}`);
+}
+function scanLunarEclipses(startMs, endMs, direction, firstOnly) {
+    const found = [];
+    if (startMs >= endMs)
+        return found;
+    // Peak and full moon differ. Include the entire peak-search margin at
+    // both ends, then apply the caller's bounds to the reported peak below.
+    const startUt = utDays(new Date(startMs)) - PEAK_WINDOW_DAYS;
+    const endUt = utDays(new Date(endMs)) + PEAK_WINDOW_DAYS;
+    let fmUt = direction > 0 ? startUt : endUt;
+    const limitUt = direction > 0 ? endUt : startUt;
+    while (direction * (limitUt - fmUt) > 0) {
+        const fullmoon = searchMoonPhase(180, fmUt, direction * Math.min(40, Math.abs(limitUt - fmUt)));
         if (fullmoon === null)
-            throw new Error('almanac internal: cannot find full moon');
+            break;
         // UPSTREAM `SearchLunarEclipse`: step past this full moon before the
         // next probe, so the same one cannot be found twice.
-        fmUt = fullmoon + 10;
+        fmUt = fullmoon + direction * 10;
         // Pruning: if the full Moon's ecliptic latitude is too large, a lunar
         // eclipse is not possible. Avoid needless work searching for the
         // minimum moon distance.
@@ -159,20 +194,14 @@ export function nextLunarEclipse(after) {
         const shadow = peakEarthShadow(fullmoon);
         if (shadow.r >= shadow.p + MOON_MEAN_RADIUS_KM)
             continue; // not even penumbral
-        // A full moon before `after` can still carry the eclipse the caller
-        // already has; the spec's contract is strictly-later peaks.
         const peak = dateFromUt(shadow.ut);
-        if (peak.getTime() <= after.getTime() + SAME_ECLIPSE_MS)
+        if (peak.getTime() < startMs || peak.getTime() >= endMs)
             continue;
-        if (peak.getTime() >= SUPPORTED_MAX)
-            throw new AlmanacOutOfRangeError();
-        return buildEclipse(shadow, peak);
+        found.push(buildEclipse(shadow, peak));
+        if (firstOnly)
+            break;
     }
-    // Not an AlmanacOutOfRangeError: the interval is fine, the sky is not. The
-    // longest real gap over 1950-2100 is 178 days, so exhausting 730 means the
-    // shadow model is broken — an internal invariant, like every other
-    // `almanac internal:` throw in this package.
-    throw new Error(`almanac internal: no lunar eclipse within ${SCAN_LIMIT_DAYS} days of ${after.toISOString()}`);
+    return found;
 }
 /** UPSTREAM: the classification and semi-duration block of `SearchLunarEclipse`, astronomy.ts ~8730-8755. */
 function buildEclipse(shadow, peak) {

package/dist/events.d.ts

@@ -64,8 +64,8 @@ export declare function moonEvents(startUtc: Date, endUtc: Date, observer: Obser
  */
 export declare function search(f: (ut: number) => number, t1: number, t2: number, dtToleranceSeconds: number, iterLimit?: number, what?: string): number | null;
 /**
- * UPSTREAM: `SearchMoonPhase`, astronomy.ts ~5260 — forward search only, which
- * is all the quarter walk needs. The phase repeats every synodic month, so the
+ * UPSTREAM: `SearchMoonPhase`, astronomy.ts ~5260 — a negative limit searches
+ * backward. The phase repeats every synodic month, so the
  * time of the next occurrence is predicted from the current offset and then
  * bracketed ±1.5 days: the Moon's eccentricity has been seen to move a quarter
  * more than 0.9 days off the simple prediction.

package/dist/events.js

@@ -390,8 +390,10 @@ export function search(f, t1, t2, dtToleranceSeconds, iterLimit = MOON_PHASE_ITE
         assertReached(iter < iterLimit, what);
         const tmid = (t1 + t2) / 2;
         const dt = tmid - t1;
+        // A caller may clip the initial bracket to a short range. Small
+        // width alone does not prove that it contains an ascending root.
         if (Math.abs(dt) < dtDays)
-            return tmid;
+            return f1 <= 0 && f2 >= 0 ? tmid : null;
         if (calcFmid)
             fmid = f(tmid);
         else
@@ -434,8 +436,8 @@ export function search(f, t1, t2, dtToleranceSeconds, iterLimit = MOON_PHASE_ITE
     }
 }
 /**
- * UPSTREAM: `SearchMoonPhase`, astronomy.ts ~5260 — forward search only, which
- * is all the quarter walk needs. The phase repeats every synodic month, so the
+ * UPSTREAM: `SearchMoonPhase`, astronomy.ts ~5260 — a negative limit searches
+ * backward. The phase repeats every synodic month, so the
  * time of the next occurrence is predicted from the current offset and then
  * bracketed ±1.5 days: the Moon's eccentricity has been seen to move a quarter
  * more than 0.9 days off the simple prediction.
@@ -444,13 +446,25 @@ export function searchMoonPhase(targetLonDeg, startUt, limitDays) {
     const moonOffset = (ut) => angleOffset(moonPhaseDeg(ttDaysFromUt(ut)) - targetLonDeg);
     const uncertainty = 1.5;
     let ya = moonOffset(startUt);
-    if (ya > 0)
-        ya -= 360;
-    const estDt = -(MEAN_SYNODIC_MONTH * ya) / 360;
-    const dt1 = estDt - uncertainty;
-    if (dt1 > limitDays)
-        return null;
-    const dt2 = Math.min(limitDays, estDt + uncertainty);
+    let dt1, dt2;
+    if (limitDays < 0) {
+        if (ya < 0)
+            ya += 360;
+        const estDt = -(MEAN_SYNODIC_MONTH * ya) / 360;
+        dt2 = estDt + uncertainty;
+        if (dt2 < limitDays)
+            return null;
+        dt1 = Math.max(limitDays, estDt - uncertainty);
+    }
+    else {
+        if (ya > 0)
+            ya -= 360;
+        const estDt = -(MEAN_SYNODIC_MONTH * ya) / 360;
+        dt1 = estDt - uncertainty;
+        if (dt1 > limitDays)
+            return null;
+        dt2 = Math.min(limitDays, estDt + uncertainty);
+    }
     return search(moonOffset, startUt + dt1, startUt + dt2, 0.1);
 }
 /**

package/dist/index.d.ts

@@ -9,4 +9,4 @@ export { moonIllumination } from './illumination.js';
 export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent, MoonPhaseName } from './events.js';
 export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
 export type { LunarEclipse, LunarEclipseVisibility } from './eclipse.js';
-export { nextLunarEclipse, lunarEclipseVisibility } from './eclipse.js';
+export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';

package/dist/index.js

@@ -3,4 +3,4 @@ export { sunPosition, moonPosition } from './positions.js';
 export { sunAltAz, moonAltAz } from './transforms.js';
 export { moonIllumination } from './illumination.js';
 export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
-export { nextLunarEclipse, lunarEclipseVisibility } from './eclipse.js';
+export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar eclipses.",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/openwatersio/almanac.git", "directory": "typescript" },
+  "homepage": "https://openwaters.io/sky",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",