ether-to-astro 1.0.0

package/dist/eclipses.d.ts

@@ -0,0 +1,85 @@
+import type { EphemerisCalculator } from './ephemeris.js';
+import type { EclipseInfo } from './types.js';
+/**
+ * Calculator for solar and lunar eclipses
+ *
+ * @remarks
+ * Finds upcoming solar and lunar eclipses using Swiss Ephemeris.
+ * Returns basic eclipse information including type and timing.
+ * TODO: Enhance with richer phase timing and visibility data.
+ */
+export declare class EclipseCalculator {
+    /** Ephemeris calculator instance */
+    private ephem;
+    /**
+     * Create a new eclipse calculator
+     *
+     * @param ephem - Initialized ephemeris calculator
+     * @throws Error if ephemeris is not initialized
+     *
+     * @remarks
+     * The ephemeris calculator must be initialized before passing
+     * to the EclipseCalculator constructor.
+     */
+    constructor(ephem: EphemerisCalculator);
+    private callSolarEclipseWhenGlob;
+    /**
+     * Find the next solar eclipse after a given date
+     *
+     * @param startJD - Julian Day to start searching from
+     * @returns Solar eclipse info or null if none found
+     * @throws Error if ephemeris not initialized
+     *
+     * @remarks
+     * Searches globally for the next solar eclipse. Returns basic
+     * information about the eclipse type and maximum time.
+     */
+    findNextSolarEclipse(startJD: number): EclipseInfo | null;
+    /**
+     * Find the next lunar eclipse after a given date
+     *
+     * @param startJD - Julian Day to start searching from
+     * @returns Lunar eclipse info or null if none found
+     * @throws Error if ephemeris not initialized
+     *
+     * @remarks
+     * Searches globally for the next lunar eclipse. Returns basic
+     * information about the eclipse type and maximum time.
+     */
+    findNextLunarEclipse(startJD: number): EclipseInfo | null;
+    /**
+     * Get the next eclipses (both solar and lunar) after a given date
+     *
+     * @param startJD - Julian Day to start searching from
+     * @returns Array of upcoming eclipses sorted by date
+     * @throws Error if ephemeris not initialized
+     *
+     * @remarks
+     * Finds the next solar and lunar eclipses. Returns them in
+     * chronological order. May return only one type if the other
+     * is too far in the future.
+     */
+    getNextEclipses(startJD: number): Promise<EclipseInfo[] | null>;
+    /**
+     * Get solar eclipse type from Swiss Ephemeris return code
+     *
+     * @param returnCode - Swiss Ephemeris solar eclipse return code
+     * @returns Human-readable eclipse type string
+     *
+     * @remarks
+     * Maps Swiss Ephemeris numeric codes to descriptive types.
+     * TODO: Should use constrained union types for better type safety.
+     */
+    private getSolarEclipseType;
+    /**
+     * Get lunar eclipse type from Swiss Ephemeris return code
+     *
+     * @param returnCode - Swiss Ephemeris lunar eclipse return code
+     * @returns Human-readable eclipse type string
+     *
+     * @remarks
+     * Maps Swiss Ephemeris numeric codes to descriptive types.
+     * TODO: Should use constrained union types for better type safety.
+     */
+    private getLunarEclipseType;
+}

package/dist/eclipses.js

@@ -0,0 +1,184 @@
+import { constants as Constants } from 'sweph';
+import { ErrorCategory } from './constants.js';
+import { logger } from './logger.js';
+function isEclipseWhenResult(value) {
+    if (typeof value !== 'object' || value == null)
+        return false;
+    const obj = value;
+    return (typeof obj.flag === 'number' &&
+        typeof obj.error === 'string' &&
+        Array.isArray(obj.data) &&
+        obj.data.every((v) => typeof v === 'number'));
+}
+/**
+ * Calculator for solar and lunar eclipses
+ *
+ * @remarks
+ * Finds upcoming solar and lunar eclipses using Swiss Ephemeris.
+ * Returns basic eclipse information including type and timing.
+ * TODO: Enhance with richer phase timing and visibility data.
+ */
+export class EclipseCalculator {
+    /** Ephemeris calculator instance */
+    ephem;
+    /**
+     * Create a new eclipse calculator
+     *
+     * @param ephem - Initialized ephemeris calculator
+     * @throws Error if ephemeris is not initialized
+     *
+     * @remarks
+     * The ephemeris calculator must be initialized before passing
+     * to the EclipseCalculator constructor.
+     */
+    constructor(ephem) {
+        this.ephem = ephem;
+    }
+    callSolarEclipseWhenGlob(startJD) {
+        if (!this.ephem.eph) {
+            throw new Error('Ephemeris not initialized');
+        }
+        // sweph typings currently declare `backwards` as number, but runtime expects boolean.
+        const callable = this.ephem.eph.sol_eclipse_when_glob;
+        const raw = callable(startJD, Constants.SEFLG_SWIEPH, 0, false);
+        if (!isEclipseWhenResult(raw)) {
+            throw new Error('Unexpected sol_eclipse_when_glob result shape');
+        }
+        return raw;
+    }
+    /**
+     * Find the next solar eclipse after a given date
+     *
+     * @param startJD - Julian Day to start searching from
+     * @returns Solar eclipse info or null if none found
+     * @throws Error if ephemeris not initialized
+     *
+     * @remarks
+     * Searches globally for the next solar eclipse. Returns basic
+     * information about the eclipse type and maximum time.
+     */
+    findNextSolarEclipse(startJD) {
+        if (!this.ephem.eph) {
+            throw new Error('Ephemeris not initialized');
+        }
+        try {
+            const result = this.callSolarEclipseWhenGlob(startJD);
+            if (result.error || !result.data || result.data.length < 1) {
+                return null;
+            }
+            const eclipseType = this.getSolarEclipseType(result.flag);
+            return {
+                type: 'solar',
+                date: this.ephem.julianDayToDate(result.data[0]),
+                eclipseType,
+                maxTime: this.ephem.julianDayToDate(result.data[0]),
+            };
+        }
+        catch (e) {
+            logger.error('Solar eclipse calculation failed', ErrorCategory.CALCULATION, e instanceof Error ? e : new Error(String(e)));
+            return null;
+        }
+    }
+    /**
+     * Find the next lunar eclipse after a given date
+     *
+     * @param startJD - Julian Day to start searching from
+     * @returns Lunar eclipse info or null if none found
+     * @throws Error if ephemeris not initialized
+     *
+     * @remarks
+     * Searches globally for the next lunar eclipse. Returns basic
+     * information about the eclipse type and maximum time.
+     */
+    findNextLunarEclipse(startJD) {
+        if (!this.ephem.eph) {
+            throw new Error('Ephemeris not initialized');
+        }
+        try {
+            const result = this.ephem.eph.lun_eclipse_when(startJD, Constants.SEFLG_SWIEPH, 0, false);
+            if (result.error || !result.data || result.data.length < 1) {
+                return null;
+            }
+            const eclipseType = this.getLunarEclipseType(result.flag);
+            return {
+                type: 'lunar',
+                date: this.ephem.julianDayToDate(result.data[0]),
+                eclipseType,
+                maxTime: this.ephem.julianDayToDate(result.data[0]),
+            };
+        }
+        catch (e) {
+            logger.error('Lunar eclipse calculation failed', ErrorCategory.CALCULATION, e instanceof Error ? e : new Error(String(e)));
+            return null;
+        }
+    }
+    /**
+     * Get the next eclipses (both solar and lunar) after a given date
+     *
+     * @param startJD - Julian Day to start searching from
+     * @returns Array of upcoming eclipses sorted by date
+     * @throws Error if ephemeris not initialized
+     *
+     * @remarks
+     * Finds the next solar and lunar eclipses. Returns them in
+     * chronological order. May return only one type if the other
+     * is too far in the future.
+     */
+    async getNextEclipses(startJD) {
+        if (!this.ephem.eph) {
+            throw new Error('Ephemeris not initialized');
+        }
+        try {
+            const solarEclipse = this.findNextSolarEclipse(startJD);
+            const lunarEclipse = this.findNextLunarEclipse(startJD);
+            const eclipses = await Promise.all([solarEclipse, lunarEclipse]);
+            const filteredEclipses = eclipses.filter((eclipse) => eclipse !== null);
+            if (filteredEclipses.length === 0) {
+                return null;
+            }
+            return filteredEclipses.sort((a, b) => a.date.getTime() - b.date.getTime());
+        }
+        catch (e) {
+            logger.error('Eclipse calculation failed', ErrorCategory.CALCULATION, e instanceof Error ? e : new Error(String(e)));
+            return null;
+        }
+    }
+    /**
+     * Get solar eclipse type from Swiss Ephemeris return code
+     *
+     * @param returnCode - Swiss Ephemeris solar eclipse return code
+     * @returns Human-readable eclipse type string
+     *
+     * @remarks
+     * Maps Swiss Ephemeris numeric codes to descriptive types.
+     * TODO: Should use constrained union types for better type safety.
+     */
+    getSolarEclipseType(returnCode) {
+        if (returnCode & Constants.SE_ECL_TOTAL)
+            return 'Total';
+        if (returnCode & Constants.SE_ECL_ANNULAR)
+            return 'Annular';
+        if (returnCode & Constants.SE_ECL_PARTIAL)
+            return 'Partial';
+        return 'Unknown';
+    }
+    /**
+     * Get lunar eclipse type from Swiss Ephemeris return code
+     *
+     * @param returnCode - Swiss Ephemeris lunar eclipse return code
+     * @returns Human-readable eclipse type string
+     *
+     * @remarks
+     * Maps Swiss Ephemeris numeric codes to descriptive types.
+     * TODO: Should use constrained union types for better type safety.
+     */
+    getLunarEclipseType(returnCode) {
+        if (returnCode & Constants.SE_ECL_TOTAL)
+            return 'Total';
+        if (returnCode & Constants.SE_ECL_PARTIAL)
+            return 'Partial';
+        if (returnCode & Constants.SE_ECL_PENUMBRAL)
+            return 'Penumbral';
+        return 'Unknown';
+    }
+}

package/dist/ephemeris.d.ts

@@ -0,0 +1,120 @@
+import sweph from 'sweph';
+import { type PlanetPosition } from './types.js';
+/**
+ * Ephemeris calculator wrapper for native Swiss Ephemeris (sweph)
+ *
+ * @remarks
+ * Provides a high-level interface for planetary calculations using the
+ * Swiss Ephemeris Node bindings. Handles initialization,
+ * coordinate conversions, and common astrological calculations.
+ *
+ * All longitudes are tropical (not sidereal) and geocentric.
+ */
+export declare class EphemerisCalculator {
+    /** Native sweph module instance */
+    eph: typeof sweph | null;
+    /**
+     * Initialize the Swiss Ephemeris native module
+     *
+     * @returns Promise that resolves when initialization is complete
+     * @throws Error if module setup fails
+     *
+     * @remarks
+     * Must be called before any other methods. Loads the Swiss Ephemeris
+     * data files and prepares the calculation engine.
+     */
+    init(): Promise<void>;
+    /**
+     * Convert a JavaScript Date to Julian Day
+     *
+     * @param date - Date to convert (should be in UTC)
+     * @returns Julian Day number
+     * @throws Error if ephemeris not initialized
+     *
+     * @remarks
+     * Julian Day is a continuous count of days since noon Universal Time
+     * on January 1, 4713 BCE. It's the standard time system for astronomical
+     * calculations.
+     */
+    dateToJulianDay(date: Date): number;
+    /**
+     * Normalize angle to 0-360 degree range
+     *
+     * @param angle - Angle in degrees (may be negative or > 360)
+     * @returns Normalized angle in degrees (0-360)
+     *
+     * @remarks
+     * Uses modulo arithmetic to handle negative angles correctly.
+     * Example: -10° becomes 350°, 370° becomes 10°.
+     */
+    private normalizeAngle;
+    /**
+     * Get position of a single planet at a specific time
+     *
+     * @param planetId - Swiss Ephemeris planet ID (from PLANETS constant)
+     * @param jd - Julian Day for the calculation
+     * @returns Planet position with all relevant data
+     * @throws Error if ephemeris not initialized or invalid planet ID
+     *
+     * @remarks
+     * Returns tropical, geocentric coordinates. Includes zodiac sign
+     * calculation and retrograde status.
+     */
+    getPlanetPosition(planetId: number, jd: number): PlanetPosition;
+    /**
+     * Get positions for multiple planets at a specific time
+     *
+     * @param planetIds - Array of Swiss Ephemeris planet IDs
+     * @param jd - Julian Day for the calculation
+     * @returns Array of planet positions in the same order as planetIds
+     * @throws Error if ephemeris not initialized
+     *
+     * @remarks
+     * Convenience wrapper that maps over planetIds and calls getPlanetPosition for each.
+     */
+    getAllPlanets(jd: number, planetIds: number[]): PlanetPosition[];
+    /**
+     * Calculate angular distance between two planets
+     *
+     * @param lon1 - First planet's longitude
+     * @param lon2 - Second planet's longitude
+     * @returns Angular distance in degrees (0-180)
+     *
+     * @remarks
+     * Always returns the shorter arc between the two planets.
+     * For example, 350° and 10° have a distance of 20°, not 340°.
+     */
+    calculateAspectAngle(lon1: number, lon2: number): number;
+    /**
+     * Find all exact times when planet reaches a specific longitude
+     *
+     * @param planetId - Swiss Ephemeris planet ID
+     * @param targetLongitude - Target longitude in degrees (will be normalized to 0-360)
+     * @param startJD - Start of search window (Julian Day)
+     * @param endJD - End of search window (Julian Day)
+     * @param tolerance - Desired precision in degrees (default: 0.01°)
+     * @returns Array of Julian Days where crossings occur, sorted earliest-first, or empty array if none
+     * @throws Error if ephemeris not initialized or invalid inputs
+     *
+     * @remarks
+     * Uses multi-stage search: coarse scan for root detection, then bracket/minimum refinement.
+     * Endpoint-near-zero cases are collected directly as candidate roots.
+     * Only sign-change intervals are refined via bisection.
+     * Local minima of |diff| are refined to catch tangential no-sign-change roots.
+     * Returns all detected crossings in the interval, deduplicated within 1 minute,
+     * and sorted earliest-first. No guarantees are made outside the searched interval.
+     */
+    findExactTransitTimes(planetId: number, targetLongitude: number, startJD: number, endJD: number, tolerance?: number): number[];
+    /**
+     * Convert Julian Day to JavaScript Date
+     *
+     * @param jd - Julian Day number
+     * @returns JavaScript Date in UTC
+     * @throws Error if ephemeris not initialized
+     *
+     * @remarks
+     * The returned Date is always in UTC regardless of the original
+     * timezone of the calculation.
+     */
+    julianDayToDate(jd: number): Date;
+}