@openwaters/almanac 0.7.0 → 0.8.1

package/dist/planets.js

@@ -35,6 +35,13 @@ function visualMagnitude(planet, phase, helioDist, geoDist) {
             c0 = -9.40;
             c1 = 0.50;
             break;
+        case 'uranus':
+            c0 = -7.19;
+            c1 = 0.25;
+            break;
+        case 'neptune':
+            c0 = -6.87;
+            break;
         default: throw new Error('unsupported planet in visualMagnitude');
     }
     const x = phase / 100;

package/dist/positions.d.ts

@@ -32,3 +32,18 @@ export declare function sunPosition(time: Date): SunPosition;
  * the Earth-Moon centre distance in kilometres.
  */
 export declare function moonPosition(time: Date): MoonPosition;
+/**
+ * INTERNAL: equation of time for a TT instant, in minutes. Not from upstream:
+ * Meeus, *Astronomical Algorithms*, formula 28.1, `E = L0 − 0.0057183° − α +
+ * Δψ cos ε`, with `L0` the Sun's mean longitude from formula 28.2 and `α` the
+ * apparent right ascension `sunApparentAtTT` already computes. The constant
+ * is aberration plus the FK5 correction; `Δψ cos ε` moves `L0` from the mean
+ * equinox to the true one `α` is measured from.
+ */
+export declare function equationOfTimeAtTT(tt: number): number;
+/**
+ * Equation of time: apparent solar time minus mean solar time, in minutes.
+ * Positive when a sundial runs ahead of the clock; about +16.4 at the start
+ * of November and −14.2 in mid February.
+ */
+export declare function equationOfTime(time: Date): number;

package/dist/positions.js

@@ -13,7 +13,7 @@
 // parallax subtraction) is zero and drops out.
 import { assertSupported } from './types.js';
 import { ttDays } from './time.js';
-import { KM_PER_AU, equatorialFromVector } from './nutation.js';
+import { DEG2RAD, KM_PER_AU, earthTilt, equatorialFromVector } from './nutation.js';
 import { moonGeoVector } from './moon.js';
 import { sunGeoVector } from './sun.js';
 /**
@@ -50,3 +50,30 @@ export function moonPosition(time) {
     assertSupported(time);
     return moonApparentAtTT(ttDays(time));
 }
+/**
+ * INTERNAL: equation of time for a TT instant, in minutes. Not from upstream:
+ * Meeus, *Astronomical Algorithms*, formula 28.1, `E = L0 − 0.0057183° − α +
+ * Δψ cos ε`, with `L0` the Sun's mean longitude from formula 28.2 and `α` the
+ * apparent right ascension `sunApparentAtTT` already computes. The constant
+ * is aberration plus the FK5 correction; `Δψ cos ε` moves `L0` from the mean
+ * equinox to the true one `α` is measured from.
+ */
+export function equationOfTimeAtTT(tt) {
+    const tau = tt / 365250;
+    const l0 = 280.4664567 + tau * (360007.6982779 + tau * (0.03032028
+        + tau * (1 / 49931 + tau * (-1 / 15300 + tau * (-1 / 2000000)))));
+    const tilt = earthTilt(tt);
+    const nutationRaDeg = (tilt.dpsi / 3600) * Math.cos(tilt.tobl * DEG2RAD);
+    let e = l0 - 0.0057183 - sunApparentAtTT(tt).raDeg + nutationRaDeg;
+    e = ((e % 360) + 540) % 360 - 180; // (−180, 180]
+    return e * 4; // 360° of right ascension is 1440 minutes
+}
+/**
+ * Equation of time: apparent solar time minus mean solar time, in minutes.
+ * Positive when a sundial runs ahead of the clock; about +16.4 at the start
+ * of November and −14.2 in mid February.
+ */
+export function equationOfTime(time) {
+    assertSupported(time);
+    return equationOfTimeAtTT(ttDays(time));
+}

package/dist/seasons.d.ts

@@ -0,0 +1,17 @@
+/** The season the Sun's longitude starts: 0° March equinox, 90° June solstice, 180° September equinox, 270° December solstice. */
+export type SeasonKind = 'marchEquinox' | 'juneSolstice' | 'septemberEquinox' | 'decemberSolstice';
+/** An equinox or solstice. */
+export interface SeasonEvent {
+    time: Date;
+    kind: SeasonKind;
+}
+/**
+ * The equinoxes and solstices within the half-open window `[startUtc, endUtc)`,
+ * sorted ascending.
+ *
+ * A season starts the instant the Sun's apparent geocentric ecliptic longitude
+ * reaches 0° (March equinox), 90° (June solstice), 180° (September equinox) or
+ * 270° (December solstice). The names are months, not seasons, because the
+ * same instant starts opposite seasons in the two hemispheres.
+ */
+export declare function seasons(startUtc: Date, endUtc: Date): SeasonEvent[];

package/dist/seasons.js

@@ -0,0 +1,73 @@
+// L3 season search: the four instants a year when the Sun's apparent
+// geocentric ecliptic longitude reaches 0°, 90°, 180° and 270°.
+//
+// Translated from the cosinekitty/astronomy upstream, pinned sha
+// 865d3da7d8112bbc7911238052c6af4aaf877181, source/js/astronomy.ts:
+// `SearchSunLongitude` (~4787), whose `sun_offset` and 0.01 s `Search` are
+// kept. Upstream's `Seasons(year)` (~6130) brackets each search from a fixed
+// calendar date. Here the bracket is a cell of a fixed 80-day grid anchored at
+// J2000, so every window that contains a season finds it from the same bracket
+// and reports the same millisecond — the fixed-seed rule the eclipse searches
+// follow. A cell spans under 90° of solar longitude, so it holds at most one
+// quarter crossing.
+//
+// INTERNAL except `seasons`: not part of the curated public API (see index.ts).
+import { assertSupported, assertSupportedWindowEnd } from './types.js';
+import { utDays, ttDaysFromUt, dateFromUt } from './time.js';
+import { sunEclipticLonDeg } from './illumination.js';
+import { search, angleOffset, quantizedUt, assertReached } from './events.js';
+const SEASON_KINDS = ['marchEquinox', 'juneSolstice', 'septemberEquinox', 'decemberSolstice'];
+/** Grid cell, in days since J2000 UT: under the 89-day shortest season, so a cell holds at most one crossing. */
+const SEASON_CELL_DAYS = 80;
+function sunLonDeg(ut) {
+    return sunEclipticLonDeg(ttDaysFromUt(ut));
+}
+/**
+ * UPSTREAM: `SearchSunLongitude` on one grid cell `[t1, t2]`, with
+ * `lon1 = sunLonDeg(t1)` already in hand. Returns the crossing of the next
+ * multiple of 90° after `lon1`, or `null` when the cell ends before it.
+ */
+function searchSeasonInCell(t1, t2, lon1) {
+    const quarter = (Math.floor(lon1 / 90) + 1) % 4;
+    const targetLonDeg = 90 * quarter;
+    const sunOffset = (ut) => angleOffset(sunLonDeg(ut) - targetLonDeg);
+    if (sunOffset(t2) < 0)
+        return null;
+    const ut = search(sunOffset, t1, t2, 0.01, undefined, 'season search');
+    assertReached(ut !== null, 'season search');
+    return { ut: ut, quarter };
+}
+/**
+ * The equinoxes and solstices within the half-open window `[startUtc, endUtc)`,
+ * sorted ascending.
+ *
+ * A season starts the instant the Sun's apparent geocentric ecliptic longitude
+ * reaches 0° (March equinox), 90° (June solstice), 180° (September equinox) or
+ * 270° (December solstice). The names are months, not seasons, because the
+ * same instant starts opposite seasons in the two hemispheres.
+ */
+export function seasons(startUtc, endUtc) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    const startUt = utDays(startUtc);
+    const endUt = utDays(endUtc);
+    const events = [];
+    let t1 = Math.floor(startUt / SEASON_CELL_DAYS) * SEASON_CELL_DAYS;
+    let lon1 = sunLonDeg(t1);
+    while (t1 < endUt) {
+        const t2 = t1 + SEASON_CELL_DAYS;
+        const found = searchSeasonInCell(t1, t2, lon1);
+        if (found !== null) {
+            const q = quantizedUt(found.ut); // judge the half-open bounds on the reported instant, not the raw root
+            if (q >= endUt)
+                break;
+            if (q >= startUt)
+                events.push({ time: dateFromUt(found.ut), kind: SEASON_KINDS[found.quarter] });
+        }
+        t1 = t2;
+        lon1 = sunLonDeg(t1);
+    }
+    return events;
+}

package/dist/transforms.d.ts

@@ -7,13 +7,16 @@ export interface AltAz {
 }
 /**
  * INTERNAL: what {@link topoAltAzUnrefracted} already computes on the way to
- * az/alt. The L3 event layer needs all four from a single evaluation — the
- * local hour angle brackets each daily cycle's altitude extrema, and the
- * topocentric distance sets the Moon's semidiameter, hence its rise/set target.
+ * az/alt. The L3 event layer needs these from a single evaluation — the
+ * local hour angle brackets each daily cycle's altitude extrema, the
+ * topocentric distance sets the Moon's semidiameter, hence its rise/set target,
+ * and the topocentric RA/Dec orient the Moon's disc.
  */
 export interface TopoUnrefracted extends AltAz {
     hourAngleDeg: number;
     distanceAu: number;
+    raDeg: number;
+    decDeg: number;
 }
 /**
  * UPSTREAM: `sidereal_time`, astronomy.ts ~2031 — Greenwich Apparent Sidereal

package/dist/transforms.js

@@ -160,7 +160,7 @@ export function topoAltAzUnrefracted(bodyEqj, ut, observer) {
     let hourAngleDeg = (gast + observer.longitudeDeg - raDeg) % 360;
     if (hourAngleDeg < 0)
         hourAngleDeg += 360;
-    return { azDeg: az, altDeg: 90 - zd, hourAngleDeg, distanceAu };
+    return { azDeg: az, altDeg: 90 - zd, hourAngleDeg, distanceAu, raDeg, decDeg };
 }
 /**
  * UPSTREAM: `Refraction('normal', altitude)`, astronomy.ts ~7176 — the

package/dist/types.d.ts

@@ -3,7 +3,7 @@ export interface Observer {
     longitudeDeg: number;
     elevationM?: number;
 }
-export type Planet = 'mercury' | 'venus' | 'earth' | 'mars' | 'jupiter' | 'saturn';
+export type Planet = 'mercury' | 'venus' | 'earth' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune';
 /** INTERNAL: Earth has no planetary direction from an Earth-based observer. */
 export declare function assertPlanet(planet: Planet, earthAllowed?: boolean): void;
 export declare class AlmanacOutOfRangeError extends RangeError {

package/dist/types.js

@@ -1,6 +1,6 @@
 /** INTERNAL: Earth has no planetary direction from an Earth-based observer. */
 export function assertPlanet(planet, earthAllowed = false) {
-    if (!['mercury', 'venus', 'earth', 'mars', 'jupiter', 'saturn'].includes(planet) || (!earthAllowed && planet === 'earth'))
+    if (!['mercury', 'venus', 'earth', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune'].includes(planet) || (!earthAllowed && planet === 'earth'))
         throw new RangeError(`invalid planet: ${planet}`);
 }
 export class AlmanacOutOfRangeError extends RangeError {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Offline astronomy: Sun, Moon and planet positions, apparent horizon, rise/set, phases and eclipses.",
   "license": "MIT",
   "repository": {
@@ -18,7 +18,8 @@
     "ephemeris",
     "lunar-eclipse",
     "solar-eclipse",
-    "marine"
+    "marine",
+    "suncalc"
   ],
   "publishConfig": {
     "access": "public"