siderust-js 0.1.0

package/siderust-node/index.js

@@ -0,0 +1,79 @@
+/**
+ * @siderust/siderust — High-precision astronomy for Node.js.
+ *
+ * Public entrypoint.  Exposes JS-level façade classes (`Observer`,
+ * `Star`) and wrapped free functions from the native backend.
+ *
+ * @module @siderust/siderust
+ */
+
+'use strict';
+
+const { Observer } = require('./lib/Observer.js');
+const { Star } = require('./lib/Star.js');
+const wrappers = require('./lib/wrappers.js');
+
+// ── Classes ───────────────────────────────────────────────────────
+module.exports.Observer = Observer;
+module.exports.Star = Star;
+
+// ── Bodies / Stars ────────────────────────────────────────────────
+module.exports.getPlanet = wrappers.getPlanet;
+module.exports.listBodies = wrappers.listBodies;
+module.exports.listCatalogStars = wrappers.listCatalogStars;
+
+// ── Coordinates ───────────────────────────────────────────────────
+module.exports.transformDirection = wrappers.transformDirection;
+module.exports.directionToHorizontal = wrappers.directionToHorizontal;
+module.exports.geodeticToEcef = wrappers.geodeticToEcef;
+module.exports.angularSeparation = wrappers.angularSeparation;
+module.exports.cartesianDistance = wrappers.cartesianDistance;
+module.exports.cartesianMagnitude = wrappers.cartesianMagnitude;
+module.exports.dotProduct = wrappers.dotProduct;
+module.exports.directionToCartesian = wrappers.directionToCartesian;
+
+// ── Ephemeris ─────────────────────────────────────────────────────
+module.exports.vsop87Heliocentric = wrappers.vsop87Heliocentric;
+module.exports.vsop87Barycentric = wrappers.vsop87Barycentric;
+module.exports.vsop87SunBarycentric = wrappers.vsop87SunBarycentric;
+module.exports.vsop87EarthBarycentric = wrappers.vsop87EarthBarycentric;
+module.exports.vsop87EarthHeliocentric = wrappers.vsop87EarthHeliocentric;
+module.exports.vsop87MoonGeocentric = wrappers.vsop87MoonGeocentric;
+module.exports.transformPositionCenter = wrappers.transformPositionCenter;
+module.exports.transformPositionFrame = wrappers.transformPositionFrame;
+module.exports.orbitalPeriod = wrappers.orbitalPeriod;
+
+// ── Body events ───────────────────────────────────────────────────
+module.exports.bodyAltitudeAt = wrappers.bodyAltitudeAt;
+module.exports.bodyAzimuthAt = wrappers.bodyAzimuthAt;
+module.exports.bodyCrossings = wrappers.bodyCrossings;
+module.exports.bodyCulminations = wrappers.bodyCulminations;
+module.exports.bodyAboveThreshold = wrappers.bodyAboveThreshold;
+module.exports.bodyBelowThreshold = wrappers.bodyBelowThreshold;
+module.exports.bodyAzimuthCrossings = wrappers.bodyAzimuthCrossings;
+module.exports.bodyAzimuthExtrema = wrappers.bodyAzimuthExtrema;
+
+// ── Star events ───────────────────────────────────────────────────
+module.exports.starAltitudeAt = wrappers.starAltitudeAt;
+module.exports.starAzimuthAt = wrappers.starAzimuthAt;
+module.exports.starCrossings = wrappers.starCrossings;
+module.exports.starCulminations = wrappers.starCulminations;
+module.exports.starAboveThreshold = wrappers.starAboveThreshold;
+module.exports.starBelowThreshold = wrappers.starBelowThreshold;
+module.exports.starAzimuthCrossings = wrappers.starAzimuthCrossings;
+module.exports.starAzimuthExtrema = wrappers.starAzimuthExtrema;
+
+// ── Periods ───────────────────────────────────────────────────────
+module.exports.intersectPeriods = wrappers.intersectPeriods;
+
+// ── Moon ──────────────────────────────────────────────────────────
+module.exports.moonPhase = wrappers.moonPhase;
+module.exports.moonPhaseTopocentric = wrappers.moonPhaseTopocentric;
+module.exports.findPhaseEvents = wrappers.findPhaseEvents;
+module.exports.moonIlluminationAbove = wrappers.moonIlluminationAbove;
+module.exports.moonIlluminationBelow = wrappers.moonIlluminationBelow;
+module.exports.moonIlluminationRange = wrappers.moonIlluminationRange;
+
+// ── Meta ──────────────────────────────────────────────────────────
+module.exports.version = wrappers.version;
+

package/siderust-node/lib/Observer.js

@@ -0,0 +1,112 @@
+/**
+ * @siderust/siderust — Observer façade class.
+ *
+ * A geodetic observer location on the Earth's surface (WGS84 ellipsoid).
+ * This is a plain JS class that stores lon/lat/height as plain fields.
+ * The native Observer is only used internally for napi calls.
+ *
+ * @module @siderust/siderust/lib/Observer
+ */
+
+'use strict';
+
+const { Quantity } = require('@siderust/qtty');
+
+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 val.to(expectedUnit).value;
+}
+
+module.exports = { Observer };

package/siderust-node/lib/Star.js

@@ -0,0 +1,118 @@
+/**
+ * @siderust/siderust — Star façade class.
+ *
+ * A star with physical parameters and sky coordinates.
+ * This is a plain JS class that stores raw properties.
+ *
+ * @module @siderust/siderust/lib/Star
+ */
+
+'use strict';
+
+const { Quantity } = require('@siderust/qtty');
+const backend = require('./backend.js');
+
+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) {
+    // Delegate to native for the catalog data
+    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;
+}
+
+module.exports = { Star };

package/siderust-node/lib/backend.js

@@ -0,0 +1,63 @@
+/**
+ * @siderust/siderust — Internal native backend wrapper.
+ *
+ * Loads the NAPI-RS `.node` addon and re-exports the raw primitives
+ * that the public JS façade classes and free functions need.
+ *
+ * @module @siderust/siderust/lib/backend
+ * @private
+ */
+
+'use strict';
+
+const native = require('../native.cjs');
+
+// ── Native classes (internal only) ────────────────────────────────
+module.exports.NativeObserver = native.Observer;
+module.exports.NativeStar = native.Star;
+
+// ── Free functions (pass-through) ─────────────────────────────────
+module.exports.getPlanet = native.getPlanet;
+module.exports.listBodies = native.listBodies;
+module.exports.transformDirection = native.transformDirection;
+module.exports.directionToHorizontal = native.directionToHorizontal;
+module.exports.geodeticToEcef = native.geodeticToEcef;
+module.exports.angularSeparation = native.angularSeparation;
+module.exports.cartesianDistance = native.cartesianDistance;
+module.exports.cartesianMagnitude = native.cartesianMagnitude;
+module.exports.dotProduct = native.dotProduct;
+module.exports.directionToCartesian = native.directionToCartesian;
+module.exports.vsop87Heliocentric = native.vsop87Heliocentric;
+module.exports.vsop87Barycentric = native.vsop87Barycentric;
+module.exports.vsop87SunBarycentric = native.vsop87SunBarycentric;
+module.exports.vsop87EarthBarycentric = native.vsop87EarthBarycentric;
+module.exports.vsop87EarthHeliocentric = native.vsop87EarthHeliocentric;
+module.exports.vsop87MoonGeocentric = native.vsop87MoonGeocentric;
+module.exports.transformPositionCenter = native.transformPositionCenter;
+module.exports.transformPositionFrame = native.transformPositionFrame;
+module.exports.orbitalPeriodDays = native.orbitalPeriodDays;
+module.exports.bodyAltitudeAt = native.bodyAltitudeAt;
+module.exports.bodyAzimuthAt = native.bodyAzimuthAt;
+module.exports.bodyCrossings = native.bodyCrossings;
+module.exports.bodyCulminations = native.bodyCulminations;
+module.exports.bodyAboveThreshold = native.bodyAboveThreshold;
+module.exports.bodyBelowThreshold = native.bodyBelowThreshold;
+module.exports.bodyAzimuthCrossings = native.bodyAzimuthCrossings;
+module.exports.bodyAzimuthExtrema = native.bodyAzimuthExtrema;
+module.exports.starAltitudeAt = native.starAltitudeAt;
+module.exports.starAzimuthAt = native.starAzimuthAt;
+module.exports.starCrossings = native.starCrossings;
+module.exports.starCulminations = native.starCulminations;
+module.exports.starAboveThreshold = native.starAboveThreshold;
+module.exports.starBelowThreshold = native.starBelowThreshold;
+module.exports.starAzimuthCrossings = native.starAzimuthCrossings;
+module.exports.starAzimuthExtrema = native.starAzimuthExtrema;
+module.exports.intersectPeriods = native.intersectPeriods;
+module.exports.moonPhase = native.moonPhase;
+module.exports.moonPhaseTopocentric = native.moonPhaseTopocentric;
+module.exports.findPhaseEvents = native.findPhaseEvents;
+module.exports.moonIlluminationAbove = native.moonIlluminationAbove;
+module.exports.moonIlluminationBelow = native.moonIlluminationBelow;
+module.exports.moonIlluminationRange = native.moonIlluminationRange;
+module.exports.listCatalogStars = native.listCatalogStars;
+module.exports.version = native.version;