siderust-js 0.1.0

package/siderust-web/index.d.ts

@@ -0,0 +1,311 @@
+/* eslint-disable */
+
+import { Quantity } from '@siderust/qtty-web'
+import { JulianDate, ModifiedJulianDate, Period } from '@siderust/tempoch-web'
+
+export function init(
+  module_or_path?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module
+): Promise<void>
+
+export interface PlanetInfo {
+  name: string
+  mass: Quantity
+  radius: Quantity
+  semiMajorAxis: Quantity
+  eccentricity: number
+  inclination: Quantity
+}
+
+export interface SphericalDirection {
+  polar: Quantity
+  azimuth: Quantity
+  frame: string
+}
+
+export interface CartesianEcef {
+  x: Quantity
+  y: Quantity
+  z: Quantity
+}
+
+export interface CartesianUnitVector {
+  x: number
+  y: number
+  z: number
+}
+
+export interface CartesianPosition {
+  x: Quantity
+  y: Quantity
+  z: Quantity
+  frame: string
+  center: string
+}
+
+export interface CrossingEvent {
+  mjd: ModifiedJulianDate
+  direction: string
+}
+
+export interface CulminationEvent {
+  mjd: ModifiedJulianDate
+  altitude: Quantity
+  kind: string
+}
+
+export interface AzimuthCrossingEvent {
+  mjd: ModifiedJulianDate
+  direction: string
+}
+
+export interface AzimuthExtremum {
+  mjd: ModifiedJulianDate
+  azimuth: Quantity
+  kind: string
+}
+
+export interface MoonPhase {
+  phaseAngle: Quantity
+  illuminatedFraction: number
+  elongation: Quantity
+  waxing: boolean
+  label: string
+}
+
+export interface PhaseEvent {
+  mjd: ModifiedJulianDate
+  kind: string
+}
+
+export class Observer {
+  constructor(lon: Quantity, lat: Quantity, height: Quantity)
+  static roqueDeLasMuchachos(): Observer
+  static elParanal(): Observer
+  static maunaKea(): Observer
+  static laSilla(): Observer
+  get lon(): Quantity
+  get lat(): Quantity
+  get height(): Quantity
+  format(): string
+}
+
+export class Star {
+  constructor(
+    name: string,
+    distance: Quantity,
+    mass: Quantity,
+    radius: Quantity,
+    luminosity: Quantity,
+    ra: Quantity,
+    dec: Quantity
+  )
+  static catalog(name: string): Star
+  get name(): string
+  get distance(): Quantity
+  get mass(): Quantity
+  get radius(): Quantity
+  get luminosity(): Quantity
+  get ra(): Quantity
+  get dec(): Quantity
+  format(): string
+}
+
+export function getPlanet(name: string): PlanetInfo
+export function listBodies(): Array<string>
+export function listCatalogStars(): Array<string>
+
+export function transformDirection(
+  polar: Quantity,
+  azimuth: Quantity,
+  srcFrame: string,
+  dstFrame: string,
+  jd: JulianDate
+): SphericalDirection
+
+export function directionToHorizontal(
+  polar: Quantity,
+  azimuth: Quantity,
+  srcFrame: string,
+  jd: JulianDate,
+  observer: Observer
+): SphericalDirection
+
+export function geodeticToEcef(observer: Observer): CartesianEcef
+
+export function angularSeparation(
+  polar1: Quantity,
+  azimuth1: Quantity,
+  polar2: Quantity,
+  azimuth2: Quantity,
+  frame: string
+): Quantity
+
+export function cartesianDistance(
+  x1: Quantity,
+  y1: Quantity,
+  z1: Quantity,
+  x2: Quantity,
+  y2: Quantity,
+  z2: Quantity
+): Quantity
+
+export function cartesianMagnitude(x: Quantity, y: Quantity, z: Quantity): Quantity
+
+export function dotProduct(
+  x1: number,
+  y1: number,
+  z1: number,
+  x2: number,
+  y2: number,
+  z2: number
+): number
+
+export function directionToCartesian(
+  polar: Quantity,
+  azimuth: Quantity
+): CartesianUnitVector
+
+export function vsop87Heliocentric(body: string, jd: JulianDate): CartesianPosition
+export function vsop87Barycentric(body: string, jd: JulianDate): CartesianPosition
+export function vsop87SunBarycentric(jd: JulianDate): CartesianPosition
+export function vsop87EarthBarycentric(jd: JulianDate): CartesianPosition
+export function vsop87EarthHeliocentric(jd: JulianDate): CartesianPosition
+export function vsop87MoonGeocentric(jd: JulianDate): CartesianPosition
+
+export function transformPositionCenter(
+  x: Quantity,
+  y: Quantity,
+  z: Quantity,
+  srcCenter: string,
+  dstCenter: string,
+  jd: JulianDate
+): CartesianPosition
+
+export function transformPositionFrame(
+  x: Quantity,
+  y: Quantity,
+  z: Quantity,
+  srcFrame: string,
+  dstFrame: string,
+  jd: JulianDate
+): CartesianPosition
+
+export function orbitalPeriod(name: string): Quantity
+
+export function bodyAltitudeAt(
+  body: string,
+  observer: Observer,
+  mjd: ModifiedJulianDate
+): Quantity
+
+export function bodyAzimuthAt(
+  body: string,
+  observer: Observer,
+  mjd: ModifiedJulianDate
+): Quantity
+
+export function bodyCrossings(
+  body: string,
+  observer: Observer,
+  window: Period,
+  threshold: Quantity
+): Array<CrossingEvent>
+
+export function bodyCulminations(
+  body: string,
+  observer: Observer,
+  window: Period
+): Array<CulminationEvent>
+
+export function bodyAboveThreshold(
+  body: string,
+  observer: Observer,
+  window: Period,
+  threshold: Quantity
+): Array<Period>
+
+export function bodyBelowThreshold(
+  body: string,
+  observer: Observer,
+  window: Period,
+  threshold: Quantity
+): Array<Period>
+
+export function bodyAzimuthCrossings(
+  body: string,
+  observer: Observer,
+  window: Period,
+  bearing: Quantity
+): Array<AzimuthCrossingEvent>
+
+export function bodyAzimuthExtrema(
+  body: string,
+  observer: Observer,
+  window: Period
+): Array<AzimuthExtremum>
+
+export function starAltitudeAt(
+  star: Star,
+  observer: Observer,
+  mjd: ModifiedJulianDate
+): Quantity
+
+export function starAzimuthAt(
+  star: Star,
+  observer: Observer,
+  mjd: ModifiedJulianDate
+): Quantity
+
+export function starCrossings(
+  star: Star,
+  observer: Observer,
+  window: Period,
+  threshold: Quantity
+): Array<CrossingEvent>
+
+export function starCulminations(
+  star: Star,
+  observer: Observer,
+  window: Period
+): Array<CulminationEvent>
+
+export function starAboveThreshold(
+  star: Star,
+  observer: Observer,
+  window: Period,
+  threshold: Quantity
+): Array<Period>
+
+export function starBelowThreshold(
+  star: Star,
+  observer: Observer,
+  window: Period,
+  threshold: Quantity
+): Array<Period>
+
+export function starAzimuthCrossings(
+  star: Star,
+  observer: Observer,
+  window: Period,
+  bearing: Quantity
+): Array<AzimuthCrossingEvent>
+
+export function starAzimuthExtrema(
+  star: Star,
+  observer: Observer,
+  window: Period
+): Array<AzimuthExtremum>
+
+export function intersectPeriods(
+  periods1: Array<Period>,
+  periods2: Array<Period>
+): Array<Period>
+
+export function moonPhase(jd: JulianDate): MoonPhase
+export function moonPhaseTopocentric(jd: JulianDate, observer: Observer): MoonPhase
+export function findPhaseEvents(window: Period): Array<PhaseEvent>
+export function moonIlluminationAbove(window: Period, kMin: number): Array<Period>
+export function moonIlluminationBelow(window: Period, kMax: number): Array<Period>
+export function moonIlluminationRange(window: Period, kMin: number, kMax: number): Array<Period>
+
+export function version(): string

package/siderust-web/index.js

@@ -0,0 +1,66 @@
+/**
+ * @siderust/siderust-web — High-precision astronomy for the browser.
+ *
+ * Call `init()` (and `await` it) before using any other export.
+ *
+ * @module @siderust/siderust-web
+ */
+
+export { init } from './lib/backend.js';
+export { Observer } from './lib/Observer.js';
+export { Star } from './lib/Star.js';
+
+export {
+  // Bodies / Stars
+  getPlanet,
+  listBodies,
+  listCatalogStars,
+  // Coordinates
+  transformDirection,
+  directionToHorizontal,
+  geodeticToEcef,
+  angularSeparation,
+  cartesianDistance,
+  cartesianMagnitude,
+  dotProduct,
+  directionToCartesian,
+  // Ephemeris
+  vsop87Heliocentric,
+  vsop87Barycentric,
+  vsop87SunBarycentric,
+  vsop87EarthBarycentric,
+  vsop87EarthHeliocentric,
+  vsop87MoonGeocentric,
+  transformPositionCenter,
+  transformPositionFrame,
+  orbitalPeriod,
+  // Body events
+  bodyAltitudeAt,
+  bodyAzimuthAt,
+  bodyCrossings,
+  bodyCulminations,
+  bodyAboveThreshold,
+  bodyBelowThreshold,
+  bodyAzimuthCrossings,
+  bodyAzimuthExtrema,
+  // Star events
+  starAltitudeAt,
+  starAzimuthAt,
+  starCrossings,
+  starCulminations,
+  starAboveThreshold,
+  starBelowThreshold,
+  starAzimuthCrossings,
+  starAzimuthExtrema,
+  // Periods
+  intersectPeriods,
+  // Moon
+  moonPhase,
+  moonPhaseTopocentric,
+  findPhaseEvents,
+  moonIlluminationAbove,
+  moonIlluminationBelow,
+  moonIlluminationRange,
+  // Meta
+  version,
+} from './lib/wrappers.js';

package/siderust-web/lib/Observer.js

@@ -0,0 +1,103 @@
+/**
+ * @siderust/siderust-web — Observer façade class.
+ *
+ * A geodetic observer location on the Earth's surface (WGS84 ellipsoid).
+ * This is a plain JS class; the WASM Observer is only used internally.
+ *
+ * @module @siderust/siderust-web/lib/Observer
+ */
+
+import { Quantity, convert } from '@siderust/qtty-web';
+
+export class Observer {
+  /**
+   * Create an observer at a geodetic position.
+   *
+   * @param {Quantity} lon Longitude, convertible to Degree.
+   * @param {Quantity} lat Latitude, convertible to Degree.
+   * @param {Quantity} height Height, convertible to Meter.
+   */
+  constructor(lon, lat, height) {
+    this._lonDeg = _extractQuantityValue(lon, 'Degree', 'lon');
+    this._latDeg = _extractQuantityValue(lat, 'Degree', 'lat');
+    this._heightM = _extractQuantityValue(height, 'Meter', 'height');
+
+    if (!Number.isFinite(this._lonDeg) || !Number.isFinite(this._latDeg) || !Number.isFinite(this._heightM)) {
+      throw new Error('Observer coordinates must be finite (not NaN or ±infinity)');
+    }
+  }
+
+  // ── preset observatories ───────────────────────────────────────
+
+  /** Roque de los Muchachos Observatory (La Palma, Spain). */
+  static roqueDeLasMuchachos() {
+    return new Observer(
+      new Quantity(-17.8925, 'Degree'),
+      new Quantity(28.7543, 'Degree'),
+      new Quantity(2396, 'Meter'),
+    );
+  }
+
+  /** Paranal Observatory (ESO, Chile). */
+  static elParanal() {
+    return new Observer(
+      new Quantity(-70.4043, 'Degree'),
+      new Quantity(-24.6272, 'Degree'),
+      new Quantity(2635, 'Meter'),
+    );
+  }
+
+  /** Mauna Kea Observatory (Hawaiʻi, USA). */
+  static maunaKea() {
+    return new Observer(
+      new Quantity(-155.4681, 'Degree'),
+      new Quantity(19.8207, 'Degree'),
+      new Quantity(4207, 'Meter'),
+    );
+  }
+
+  /** La Silla Observatory (ESO, Chile). */
+  static laSilla() {
+    return new Observer(
+      new Quantity(-70.7346, 'Degree'),
+      new Quantity(-29.2584, 'Degree'),
+      new Quantity(2400, 'Meter'),
+    );
+  }
+
+  // ── typed accessors ────────────────────────────────────────────
+
+  /** Longitude as a `Quantity` in Degree. */
+  get lon() {
+    return new Quantity(this._lonDeg, 'Degree');
+  }
+
+  /** Latitude as a `Quantity` in Degree. */
+  get lat() {
+    return new Quantity(this._latDeg, 'Degree');
+  }
+
+  /** Height as a `Quantity` in Meter. */
+  get height() {
+    return new Quantity(this._heightM, 'Meter');
+  }
+
+  /** Human-readable string representation. */
+  format() {
+    return `Observer(lon=${this._lonDeg.toFixed(4)}°, lat=${this._latDeg.toFixed(4)}°, h=${this._heightM.toFixed(1)} m)`;
+  }
+}
+
+/**
+ * Extract a canonical scalar value from a `Quantity`.
+ * @param {unknown} val
+ * @param {string} expectedUnit
+ * @param {string} label
+ * @returns {number}
+ */
+function _extractQuantityValue(val, expectedUnit, label) {
+  if (!(val instanceof Quantity)) {
+    throw new Error(`${label}: expected a Quantity`);
+  }
+  return convert(val.value, val.unit, expectedUnit);
+}

package/siderust-web/lib/Star.js

@@ -0,0 +1,116 @@
+/**
+ * @siderust/siderust-web — Star façade class.
+ *
+ * A star with physical parameters and sky coordinates.
+ * This is a plain JS class; the WASM Star is only used internally.
+ *
+ * @module @siderust/siderust-web/lib/Star
+ */
+
+import { Quantity } from "@siderust/qtty-web";
+import * as backend from "./backend.js";
+
+export class Star {
+  /**
+   * Create a custom star.
+   *
+   * @param {string} name         Display name
+   * @param {Quantity} distance   Distance, convertible to LightYear
+   * @param {Quantity} mass       Mass, convertible to SolarMass
+   * @param {Quantity} radius     Radius, convertible to NominalSolarRadius
+   * @param {Quantity} luminosity Luminosity, convertible to SolarLuminosity
+   * @param {Quantity} ra         Right ascension, convertible to Degree
+   * @param {Quantity} dec        Declination, convertible to Degree
+   */
+  constructor(name, distance, mass, radius, luminosity, ra, dec) {
+    this._distanceLy = _extractQuantityValue(distance, "LightYear", "distance");
+    this._massSolar = _extractQuantityValue(mass, "SolarMass", "mass");
+    this._radiusSolar = _extractQuantityValue(
+      radius,
+      "NominalSolarRadius",
+      "radius",
+    );
+    this._luminositySolar = _extractQuantityValue(
+      luminosity,
+      "SolarLuminosity",
+      "luminosity",
+    );
+    this._raDeg = _extractQuantityValue(ra, "Degree", "ra");
+    this._decDeg = _extractQuantityValue(dec, "Degree", "dec");
+
+    this._name = name;
+  }
+
+  /**
+   * Look up a star from the built-in catalog by name.
+   * @param {string} name
+   * @returns {Star}
+   */
+  static catalog(name) {
+    const native = backend.NativeStar.catalog(name);
+    return new Star(
+      native.name,
+      new Quantity(native.distanceLy, "LightYear"),
+      new Quantity(native.massSolar, "SolarMass"),
+      new Quantity(native.radiusSolar, "NominalSolarRadius"),
+      new Quantity(native.luminositySolar, "SolarLuminosity"),
+      new Quantity(native.raDeg, "Degree"),
+      new Quantity(native.decDeg, "Degree"),
+    );
+  }
+
+  /** Star name. */
+  get name() {
+    return this._name;
+  }
+
+  // ── typed accessors ────────────────────────────────────────────
+
+  /** Distance as a `Quantity` in LightYear. */
+  get distance() {
+    return new Quantity(this._distanceLy, "LightYear");
+  }
+  /** Mass as a `Quantity` in SolarMass. */
+  get mass() {
+    return new Quantity(this._massSolar, "SolarMass");
+  }
+  /** Radius as a `Quantity` in NominalSolarRadius. */
+  get radius() {
+    return new Quantity(this._radiusSolar, "NominalSolarRadius");
+  }
+  /** Luminosity as a `Quantity` in SolarLuminosity. */
+  get luminosity() {
+    return new Quantity(this._luminositySolar, "SolarLuminosity");
+  }
+  /** Right ascension as a `Quantity` in Degree. */
+  get ra() {
+    return new Quantity(this._raDeg, "Degree");
+  }
+  /** Declination as a `Quantity` in Degree. */
+  get dec() {
+    return new Quantity(this._decDeg, "Degree");
+  }
+
+  /** Human-readable representation. */
+  format() {
+    return `Star(${this._name}, d=${this._distanceLy.toFixed(1)} ly, RA=${this._raDeg.toFixed(4)}°, Dec=${this._decDeg.toFixed(4)}°)`;
+  }
+}
+
+/**
+ * Extract a canonical scalar value from a `Quantity`.
+ * @param {unknown} value
+ * @param {string} unit
+ * @param {string} label
+ * @returns {number}
+ */
+function _extractQuantityValue(value, unit, label) {
+  if (!(value instanceof Quantity)) {
+    throw new Error(`${label}: expected a Quantity`);
+  }
+  const converted = value.to(unit).value;
+  if (!Number.isFinite(converted)) {
+    throw new Error(`${label} must be finite (not NaN or ±infinity)`);
+  }
+  return converted;
+}