siderust-js 0.1.0

package/siderust-node/src/observer.rs

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Vallés Puig, Ramon
+
+//! Observer (geodetic site) for topocentric computations.
+
+use napi_derive::napi;
+
+use qtty::*;
+use siderust::coordinates::centers::Geodetic;
+use siderust::coordinates::frames::ECEF;
+use siderust::observatories;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Observer class
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// A geodetic observer location on the Earth's surface (WGS84 ellipsoid).
+///
+/// Used as the reference site for all topocentric computations: altitude,
+/// azimuth, crossings, culminations, and coordinate transforms to the
+/// Horizontal frame.
+///
+/// ```js
+/// const { Observer } = require('@siderust/siderust');
+///
+/// // Custom site
+/// const obs = new Observer(-17.8925, 28.7543, 2396);
+///
+/// // Preset observatory
+/// const orm = Observer.roqueDeLasMuchachos();
+/// ```
+#[napi(js_name = "Observer")]
+pub struct JsObserver {
+    pub(crate) inner: Geodetic<ECEF>,
+}
+
+#[napi]
+impl JsObserver {
+    /// Create an observer at a geodetic position.
+    ///
+    /// @param lonDeg   — Longitude in degrees (east positive).
+    /// @param latDeg   — Latitude in degrees (north positive).
+    /// @param heightM  — Height above WGS84 ellipsoid in metres.
+    #[napi(constructor)]
+    pub fn new(lon_deg: f64, lat_deg: f64, height_m: f64) -> napi::Result<Self> {
+        if !lon_deg.is_finite() || !lat_deg.is_finite() || !height_m.is_finite() {
+            return Err(napi::Error::from_reason(
+                "Observer coordinates must be finite (not NaN or ±infinity)",
+            ));
+        }
+        Ok(Self {
+            inner: Geodetic::<ECEF>::new(
+                Degrees::new(lon_deg),
+                Degrees::new(lat_deg),
+                Meters::new(height_m),
+            ),
+        })
+    }
+
+    // ── preset observatories ─────────────────────────────────────────
+
+    /// Roque de los Muchachos Observatory (La Palma, Spain).
+    ///
+    /// Longitude −17.8925°, Latitude +28.7543°, Altitude 2396 m.
+    #[napi(factory, js_name = "roqueDeLasMuchachos")]
+    pub fn roque_de_las_muchachos() -> Self {
+        Self {
+            inner: observatories::ROQUE_DE_LOS_MUCHACHOS,
+        }
+    }
+
+    /// Paranal Observatory (ESO, Chile).
+    ///
+    /// Longitude −70.4043°, Latitude −24.6272°, Altitude 2635 m.
+    #[napi(factory, js_name = "elParanal")]
+    pub fn el_paranal() -> Self {
+        Self {
+            inner: observatories::EL_PARANAL,
+        }
+    }
+
+    /// Mauna Kea Observatory (Hawaiʻi, USA).
+    ///
+    /// Longitude −155.4681°, Latitude +19.8207°, Altitude 4207 m.
+    #[napi(factory, js_name = "maunaKea")]
+    pub fn mauna_kea() -> Self {
+        Self {
+            inner: observatories::MAUNA_KEA,
+        }
+    }
+
+    /// La Silla Observatory (ESO, Chile).
+    ///
+    /// Longitude −70.7346°, Latitude −29.2584°, Altitude 2400 m.
+    #[napi(factory, js_name = "laSilla")]
+    pub fn la_silla() -> Self {
+        Self {
+            inner: observatories::LA_SILLA_OBSERVATORY,
+        }
+    }
+
+    // ── accessors ────────────────────────────────────────────────────
+
+    /// Longitude in degrees (east positive).
+    #[napi(getter, js_name = "lonDeg")]
+    pub fn lon_deg(&self) -> f64 {
+        self.inner.lon.value()
+    }
+
+    /// Latitude in degrees (north positive).
+    #[napi(getter, js_name = "latDeg")]
+    pub fn lat_deg(&self) -> f64 {
+        self.inner.lat.value()
+    }
+
+    /// Height above the WGS84 ellipsoid in metres.
+    #[napi(getter, js_name = "heightM")]
+    pub fn height_m(&self) -> f64 {
+        self.inner.height.value()
+    }
+
+    /// Human-readable string representation.
+    #[napi]
+    pub fn format(&self) -> String {
+        format!(
+            "Observer(lon={:.4}°, lat={:.4}°, h={:.1} m)",
+            self.inner.lon.value(),
+            self.inner.lat.value(),
+            self.inner.height.value(),
+        )
+    }
+}

package/siderust-node/src/phase.rs

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Vallés Puig, Ramon
+
+//! Lunar phase queries — geometry, events, and illumination periods.
+
+use napi_derive::napi;
+
+use crate::events::{make_window, MjdPeriod};
+use crate::observer::JsObserver;
+
+use qtty::*;
+use siderust::calculus::ephemeris::Vsop87Ephemeris;
+use siderust::calculus::lunar::phase::{
+    find_phase_events, illumination_above, illumination_below, illumination_range,
+    moon_phase_geocentric, moon_phase_topocentric, MoonPhaseLabel, PhaseSearchOpts,
+};
+use siderust::time::JulianDate;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Result types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Moon phase geometry at a single instant.
+#[napi(object)]
+pub struct MoonPhase {
+    /// Phase angle in degrees (Sun-Moon-Earth/observer angle).
+    pub phase_angle_deg: f64,
+    /// Fraction of the disk illuminated [0, 1].
+    pub illuminated_fraction: f64,
+    /// Elongation in degrees (eastward from the Sun).
+    pub elongation_deg: f64,
+    /// Whether the Moon is waxing.
+    pub waxing: bool,
+    /// Named phase label (e.g. `"FullMoon"`, `"WaxingCrescent"`).
+    pub label: String,
+}
+
+/// A principal lunar phase event (New Moon, First Quarter, Full Moon, Last Quarter).
+#[napi(object)]
+pub struct PhaseEvent {
+    /// Time of the event (Modified Julian Date).
+    pub mjd: f64,
+    /// Phase kind: `"NewMoon"`, `"FirstQuarter"`, `"FullMoon"`, `"LastQuarter"`.
+    pub kind: String,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase geometry
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Compute geocentric Moon phase geometry at a Julian Date.
+///
+/// @param jd — Julian Date.
+/// @returns Phase geometry including illumination, elongation, and named label.
+///
+/// ```js
+/// const { moonPhase } = require('@siderust/siderust');
+/// const phase = moonPhase(2451545.0);
+/// console.log(phase.label, phase.illuminatedFraction);
+/// ```
+#[napi(js_name = "moonPhase")]
+pub fn moon_phase(jd: f64) -> napi::Result<MoonPhase> {
+    if !jd.is_finite() {
+        return Err(napi::Error::from_reason("jd must be finite"));
+    }
+    let geom = moon_phase_geocentric::<Vsop87Ephemeris>(JulianDate::new(jd));
+    let label = geom.label();
+    Ok(MoonPhase {
+        phase_angle_deg: geom.phase_angle.to::<Degree>().value(),
+        illuminated_fraction: geom.illuminated_fraction,
+        elongation_deg: geom.elongation.to::<Degree>().value(),
+        waxing: geom.waxing,
+        label: label_to_string(label),
+    })
+}
+
+/// Compute topocentric Moon phase geometry at a Julian Date for an observer.
+///
+/// @param jd       — Julian Date.
+/// @param observer — Observer location on Earth.
+#[napi(js_name = "moonPhaseTopocentric")]
+pub fn moon_phase_topo(jd: f64, observer: &JsObserver) -> napi::Result<MoonPhase> {
+    if !jd.is_finite() {
+        return Err(napi::Error::from_reason("jd must be finite"));
+    }
+    let geom =
+        moon_phase_topocentric::<Vsop87Ephemeris>(JulianDate::new(jd), observer.inner.clone());
+    let label = geom.label();
+    Ok(MoonPhase {
+        phase_angle_deg: geom.phase_angle.to::<Degree>().value(),
+        illuminated_fraction: geom.illuminated_fraction,
+        elongation_deg: geom.elongation.to::<Degree>().value(),
+        waxing: geom.waxing,
+        label: label_to_string(label),
+    })
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase event finding
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Find all principal lunar phase events in a time window.
+///
+/// @param startMjd — Window start (MJD).
+/// @param endMjd   — Window end (MJD).
+/// @returns Sorted array of `{ mjd, kind }` events.
+///
+/// ```js
+/// const { findPhaseEvents } = require('@siderust/siderust');
+/// const events = findPhaseEvents(60000.0, 60030.0);  // ~1 month
+/// events.forEach(e => console.log(e.kind, e.mjd));
+/// ```
+#[napi(js_name = "findPhaseEvents")]
+pub fn find_phase_events_js(start_mjd: f64, end_mjd: f64) -> napi::Result<Vec<PhaseEvent>> {
+    let window = make_window(start_mjd, end_mjd)?;
+    let events = find_phase_events::<Vsop87Ephemeris>(window, PhaseSearchOpts::default());
+    Ok(events
+        .into_iter()
+        .map(|e| PhaseEvent {
+            mjd: e.mjd.value(),
+            kind: phase_kind_to_string(e.kind),
+        })
+        .collect())
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Illumination periods
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Find periods where geocentric Moon illumination is above `kMin` ∈ [0, 1].
+///
+/// @param startMjd — Window start (MJD).
+/// @param endMjd   — Window end (MJD).
+/// @param kMin     — Minimum illumination fraction.
+/// @returns Array of MJD periods.
+#[napi(js_name = "moonIlluminationAbove")]
+pub fn moon_illumination_above(
+    start_mjd: f64,
+    end_mjd: f64,
+    k_min: f64,
+) -> napi::Result<Vec<MjdPeriod>> {
+    let window = make_window(start_mjd, end_mjd)?;
+    let periods = illumination_above::<Vsop87Ephemeris>(window, k_min, PhaseSearchOpts::default());
+    Ok(periods
+        .into_iter()
+        .map(|p| MjdPeriod {
+            start_mjd: p.start.value(),
+            end_mjd: p.end.value(),
+        })
+        .collect())
+}
+
+/// Find periods where geocentric Moon illumination is below `kMax` ∈ [0, 1].
+#[napi(js_name = "moonIlluminationBelow")]
+pub fn moon_illumination_below(
+    start_mjd: f64,
+    end_mjd: f64,
+    k_max: f64,
+) -> napi::Result<Vec<MjdPeriod>> {
+    let window = make_window(start_mjd, end_mjd)?;
+    let periods = illumination_below::<Vsop87Ephemeris>(window, k_max, PhaseSearchOpts::default());
+    Ok(periods
+        .into_iter()
+        .map(|p| MjdPeriod {
+            start_mjd: p.start.value(),
+            end_mjd: p.end.value(),
+        })
+        .collect())
+}
+
+/// Find periods where geocentric Moon illumination is in `[kMin, kMax]`.
+#[napi(js_name = "moonIlluminationRange")]
+pub fn moon_illumination_range(
+    start_mjd: f64,
+    end_mjd: f64,
+    k_min: f64,
+    k_max: f64,
+) -> napi::Result<Vec<MjdPeriod>> {
+    let window = make_window(start_mjd, end_mjd)?;
+    let periods =
+        illumination_range::<Vsop87Ephemeris>(window, k_min, k_max, PhaseSearchOpts::default());
+    Ok(periods
+        .into_iter()
+        .map(|p| MjdPeriod {
+            start_mjd: p.start.value(),
+            end_mjd: p.end.value(),
+        })
+        .collect())
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+fn label_to_string(label: MoonPhaseLabel) -> String {
+    match label {
+        MoonPhaseLabel::NewMoon => "NewMoon",
+        MoonPhaseLabel::WaxingCrescent => "WaxingCrescent",
+        MoonPhaseLabel::FirstQuarter => "FirstQuarter",
+        MoonPhaseLabel::WaxingGibbous => "WaxingGibbous",
+        MoonPhaseLabel::FullMoon => "FullMoon",
+        MoonPhaseLabel::WaningGibbous => "WaningGibbous",
+        MoonPhaseLabel::LastQuarter => "LastQuarter",
+        MoonPhaseLabel::WaningCrescent => "WaningCrescent",
+    }
+    .to_string()
+}
+
+fn phase_kind_to_string(kind: siderust::calculus::lunar::phase::PhaseKind) -> String {
+    use siderust::calculus::lunar::phase::PhaseKind;
+    match kind {
+        PhaseKind::NewMoon => "NewMoon",
+        PhaseKind::FirstQuarter => "FirstQuarter",
+        PhaseKind::FullMoon => "FullMoon",
+        PhaseKind::LastQuarter => "LastQuarter",
+    }
+    .to_string()
+}

package/siderust-node/src/position.rs

@@ -0,0 +1,292 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Vallés Puig, Ramon
+
+//! Cartesian position type for Node.js bindings.
+
+use napi_derive::napi;
+
+// Frame and center string constants
+pub const FRAME_ECL: &str = "EclipticMeanJ2000";
+pub const FRAME_EQ: &str = "EquatorialMeanJ2000";
+pub const FRAME_ICRS: &str = "ICRS";
+
+pub const CENTER_BARY: &str = "Barycentric";
+pub const CENTER_HELIO: &str = "Heliocentric";
+pub const CENTER_GEO: &str = "Geocentric";
+
+pub const UNIT_AU: &str = "au";
+pub const UNIT_KM: &str = "km";
+
+/// A 3D cartesian position with frame, center, and unit metadata.
+///
+/// This mirrors the Python `Position` type for API parity.
+#[napi]
+#[derive(Clone)]
+pub struct Position {
+    x: f64,
+    y: f64,
+    z: f64,
+    frame: String,
+    center: String,
+    unit: String,
+}
+
+#[napi]
+impl Position {
+    /// Create a new position with explicit coordinates, frame, center, and unit.
+    #[napi(constructor)]
+    pub fn new(
+        x: f64,
+        y: f64,
+        z: f64,
+        frame: String,
+        center: String,
+        unit: String,
+    ) -> napi::Result<Self> {
+        validate_frame(&frame)?;
+        validate_center(&center)?;
+        validate_unit(&unit)?;
+        Ok(Self { x, y, z, frame, center, unit })
+    }
+
+    /// X coordinate.
+    #[napi(getter)]
+    pub fn x(&self) -> f64 {
+        self.x
+    }
+
+    /// Y coordinate.
+    #[napi(getter)]
+    pub fn y(&self) -> f64 {
+        self.y
+    }
+
+    /// Z coordinate.
+    #[napi(getter)]
+    pub fn z(&self) -> f64 {
+        self.z
+    }
+
+    /// Reference frame (e.g., "EclipticMeanJ2000", "ICRS").
+    #[napi(getter)]
+    pub fn frame(&self) -> String {
+        self.frame.clone()
+    }
+
+    /// Coordinate center (e.g., "Barycentric", "Heliocentric", "Geocentric").
+    #[napi(getter)]
+    pub fn center(&self) -> String {
+        self.center.clone()
+    }
+
+    /// Distance unit ("au" or "km").
+    #[napi(getter)]
+    pub fn unit(&self) -> String {
+        self.unit.clone()
+    }
+
+    /// Euclidean distance from origin.
+    #[napi]
+    pub fn magnitude(&self) -> f64 {
+        (self.x * self.x + self.y * self.y + self.z * self.z).sqrt()
+    }
+
+    /// Subtract another position to get a displacement vector.
+    #[napi]
+    pub fn subtract(&self, other: &Position) -> napi::Result<Displacement> {
+        if self.frame != other.frame {
+            return Err(napi::Error::from_reason(format!(
+                "Cannot subtract positions in different frames: '{}' vs '{}'",
+                self.frame, other.frame
+            )));
+        }
+        if self.center != other.center {
+            return Err(napi::Error::from_reason(format!(
+                "Cannot subtract positions with different centers: '{}' vs '{}'",
+                self.center, other.center
+            )));
+        }
+        if self.unit != other.unit {
+            return Err(napi::Error::from_reason(format!(
+                "Cannot subtract positions with different units: '{}' vs '{}'",
+                self.unit, other.unit
+            )));
+        }
+        Ok(Displacement {
+            dx: self.x - other.x,
+            dy: self.y - other.y,
+            dz: self.z - other.z,
+            frame: self.frame.clone(),
+            unit: self.unit.clone(),
+        })
+    }
+
+    /// Add a displacement to get a new position.
+    #[napi]
+    pub fn add_displacement(&self, d: &Displacement) -> napi::Result<Position> {
+        if self.frame != d.frame {
+            return Err(napi::Error::from_reason(format!(
+                "Cannot add displacement in different frame: '{}' vs '{}'",
+                self.frame, d.frame
+            )));
+        }
+        if self.unit != d.unit {
+            return Err(napi::Error::from_reason(format!(
+                "Cannot add displacement with different unit: '{}' vs '{}'",
+                self.unit, d.unit
+            )));
+        }
+        Ok(Position {
+            x: self.x + d.dx,
+            y: self.y + d.dy,
+            z: self.z + d.dz,
+            frame: self.frame.clone(),
+            center: self.center.clone(),
+            unit: self.unit.clone(),
+        })
+    }
+}
+
+impl Position {
+    /// Internal constructor without validation (for Rust callers).
+    pub(crate) fn new_internal(
+        x: f64,
+        y: f64,
+        z: f64,
+        frame: &str,
+        center: &str,
+        unit: &str,
+    ) -> Self {
+        Self {
+            x,
+            y,
+            z,
+            frame: frame.to_string(),
+            center: center.to_string(),
+            unit: unit.to_string(),
+        }
+    }
+}
+
+/// A displacement vector (difference between two positions).
+#[napi]
+#[derive(Clone)]
+pub struct Displacement {
+    dx: f64,
+    dy: f64,
+    dz: f64,
+    frame: String,
+    unit: String,
+}
+
+#[napi]
+impl Displacement {
+    /// Create a new displacement.
+    #[napi(constructor)]
+    pub fn new(
+        dx: f64,
+        dy: f64,
+        dz: f64,
+        frame: String,
+        unit: String,
+    ) -> napi::Result<Self> {
+        validate_frame(&frame)?;
+        validate_unit(&unit)?;
+        Ok(Self { dx, dy, dz, frame, unit })
+    }
+
+    /// X component of displacement.
+    #[napi(getter)]
+    pub fn dx(&self) -> f64 {
+        self.dx
+    }
+
+    /// Y component of displacement.
+    #[napi(getter)]
+    pub fn dy(&self) -> f64 {
+        self.dy
+    }
+
+    /// Z component of displacement.
+    #[napi(getter)]
+    pub fn dz(&self) -> f64 {
+        self.dz
+    }
+
+    /// Reference frame.
+    #[napi(getter)]
+    pub fn frame(&self) -> String {
+        self.frame.clone()
+    }
+
+    /// Distance unit.
+    #[napi(getter)]
+    pub fn unit(&self) -> String {
+        self.unit.clone()
+    }
+
+    /// Euclidean magnitude.
+    #[napi]
+    pub fn magnitude(&self) -> f64 {
+        (self.dx * self.dx + self.dy * self.dy + self.dz * self.dz).sqrt()
+    }
+
+    /// Scale displacement by a factor.
+    #[napi]
+    pub fn scale(&self, factor: f64) -> Displacement {
+        Displacement {
+            dx: self.dx * factor,
+            dy: self.dy * factor,
+            dz: self.dz * factor,
+            frame: self.frame.clone(),
+            unit: self.unit.clone(),
+        }
+    }
+
+    /// Add another displacement.
+    #[napi]
+    pub fn add(&self, other: &Displacement) -> napi::Result<Displacement> {
+        if self.frame != other.frame || self.unit != other.unit {
+            return Err(napi::Error::from_reason(
+                "Cannot add displacements with different frame/unit",
+            ));
+        }
+        Ok(Displacement {
+            dx: self.dx + other.dx,
+            dy: self.dy + other.dy,
+            dz: self.dz + other.dz,
+            frame: self.frame.clone(),
+            unit: self.unit.clone(),
+        })
+    }
+}
+
+fn validate_frame(f: &str) -> napi::Result<()> {
+    match f {
+        FRAME_ECL | FRAME_EQ | FRAME_ICRS | "ICRF" | "EquatorialMeanOfDate" | "EquatorialTrueOfDate" => Ok(()),
+        _ => Err(napi::Error::from_reason(format!(
+            "Unknown frame '{}'. Valid: EclipticMeanJ2000, EquatorialMeanJ2000, ICRS, ICRF",
+            f
+        ))),
+    }
+}
+
+fn validate_center(c: &str) -> napi::Result<()> {
+    match c {
+        CENTER_BARY | CENTER_HELIO | CENTER_GEO => Ok(()),
+        _ => Err(napi::Error::from_reason(format!(
+            "Unknown center '{}'. Valid: Barycentric, Heliocentric, Geocentric",
+            c
+        ))),
+    }
+}
+
+fn validate_unit(u: &str) -> napi::Result<()> {
+    match u {
+        UNIT_AU | UNIT_KM => Ok(()),
+        _ => Err(napi::Error::from_reason(format!(
+            "Unknown unit '{}'. Valid: au, km",
+            u
+        ))),
+    }
+}