ether-to-astro 1.0.0

package/src/constants.ts

@@ -0,0 +1,89 @@
+// Log levels
+export const LogLevel = {
+  DEBUG: 'DEBUG',
+  INFO: 'INFO',
+  WARN: 'WARN',
+  ERROR: 'ERROR',
+} as const;
+
+export type LogLevelType = (typeof LogLevel)[keyof typeof LogLevel];
+
+// Error categories
+export const ErrorCategory = {
+  EPHEMERIS: 'EPHEMERIS',
+  CALCULATION: 'CALCULATION',
+  STORAGE: 'STORAGE',
+  VALIDATION: 'VALIDATION',
+  CHART_RENDERING: 'CHART_RENDERING',
+  SERVER: 'SERVER',
+} as const;
+
+export type ErrorCategoryType = (typeof ErrorCategory)[keyof typeof ErrorCategory];
+
+// Chart theme colors
+export const LIGHT_THEME_COLORS = [
+  '#ffffff', // Aries - White (fire)
+  '#c1e6d1', // Taurus - Mint (earth)
+  '#ffffff', // Gemini - White (air)
+  '#c1e6d1', // Cancer - Mint (water)
+  '#ffffff', // Leo - White (fire)
+  '#c1e6d1', // Virgo - Mint (earth)
+  '#ffffff', // Libra - White (air)
+  '#c1e6d1', // Scorpio - Mint (water)
+  '#ffffff', // Sagittarius - White (fire)
+  '#c1e6d1', // Capricorn - Mint (earth)
+  '#ffffff', // Aquarius - White (air)
+  '#c1e6d1', // Pisces - Mint (water)
+];
+
+export const DARK_THEME_COLORS = [
+  '#282c34', // Aries - Dark (fire)
+  '#8545b0', // Taurus - Purple (earth)
+  '#282c34', // Gemini - Dark (air)
+  '#8545b0', // Cancer - Purple (water)
+  '#282c34', // Leo - Dark (fire)
+  '#8545b0', // Virgo - Purple (earth)
+  '#282c34', // Libra - Dark (air)
+  '#8545b0', // Scorpio - Purple (water)
+  '#282c34', // Sagittarius - Dark (fire)
+  '#8545b0', // Capricorn - Purple (earth)
+  '#282c34', // Aquarius - Dark (air)
+  '#8545b0', // Pisces - Purple (water)
+];
+
+// Aspect colors for light theme
+export const LIGHT_ASPECT_COLORS = {
+  conjunction: { degree: 0, orbit: 10, color: 'transparent' },
+  square: { degree: 90, orbit: 8, color: '#fb923c' }, // Orange
+  trine: { degree: 120, orbit: 8, color: '#34d399' }, // Emerald
+  opposition: { degree: 180, orbit: 10, color: '#a78bfa' }, // Purple
+  sextile: { degree: 60, orbit: 6, color: '#22d3ee' }, // Cyan
+};
+
+// Aspect colors for dark theme
+export const DARK_ASPECT_COLORS = {
+  conjunction: { degree: 0, orbit: 10, color: 'transparent' },
+  square: { degree: 90, orbit: 8, color: '#f97316' }, // Orange
+  trine: { degree: 120, orbit: 8, color: '#10b981' }, // Emerald
+  opposition: { degree: 180, orbit: 10, color: '#8b5cf6' }, // Purple
+  sextile: { degree: 60, orbit: 6, color: '#06b6d4' }, // Cyan
+};
+
+/**
+ * Determine chart theme based on time of day
+ * Dark theme: 6 PM - 6 AM (18:00 - 06:00)
+ * Light theme: 6 AM - 6 PM (06:00 - 18:00)
+ *
+ * @param timezone - Optional IANA timezone to use (e.g., 'America/New_York'). Defaults to server local time.
+ * @returns 'dark' or 'light' theme
+ */
+export function getDefaultTheme(timezone?: string): 'light' | 'dark' {
+  const now = new Date();
+  const hour = timezone
+    ? Number.parseInt(
+        now.toLocaleString('en-US', { timeZone: timezone, hour: '2-digit', hour12: false }),
+        10
+      )
+    : now.getHours();
+  return hour >= 18 || hour < 6 ? 'dark' : 'light';
+}

package/src/eclipses.ts

@@ -0,0 +1,226 @@
+import { constants as Constants } from 'sweph';
+import { ErrorCategory } from './constants.js';
+import type { EphemerisCalculator } from './ephemeris.js';
+import { logger } from './logger.js';
+import type { EclipseInfo } from './types.js';
+
+interface EclipseWhenResult {
+  flag: number;
+  error: string;
+  data: number[];
+}
+
+function isEclipseWhenResult(value: unknown): value is EclipseWhenResult {
+  if (typeof value !== 'object' || value == null) return false;
+  const obj = value as Record<string, unknown>;
+  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 */
+  private ephem: EphemerisCalculator;
+
+  /**
+   * 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) {
+    this.ephem = ephem;
+  }
+
+  private callSolarEclipseWhenGlob(startJD: number): EclipseWhenResult {
+    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 as unknown as (
+      startJd: number,
+      flags: number,
+      eclipseType: number,
+      backwards: boolean
+    ) => unknown;
+
+    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: number): EclipseInfo | null {
+    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: number): EclipseInfo | null {
+    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: number): Promise<EclipseInfo[] | null> {
+    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.
+   */
+  private getSolarEclipseType(returnCode: number): string {
+    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.
+   */
+  private getLunarEclipseType(returnCode: number): string {
+    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';
+  }
+}