siderust-js 0.1.0

package/siderust-web/Cargo.toml

@@ -0,0 +1,34 @@
+[package]
+name = "siderust-web"
+version = "0.1.0"
+edition = "2021"
+authors = ["VPRamon <vallespuigramon@gmail.com>"]
+license = "AGPL-3.0"
+repository = "https://github.com/Siderust/siderust"
+description = "Browser/WASM bindings for siderust — high-precision astronomy in the browser"
+readme = "README.md"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+siderust = { version = "0.6.0", features = [] }
+siderust-binding-core = { path = "../siderust-core" }
+qtty     = "0.4.1"
+tempoch  = "0.4"
+affn     = { version = "0.4.1", features = ["astro"] }
+chrono   = "0.4.44"
+
+wasm-bindgen            = "0.2"
+serde                   = { version = "1.0", features = ["derive"] }
+serde-wasm-bindgen      = "0.6"
+js-sys                  = "0.3"
+console_error_panic_hook = "0.1"
+
+[package.metadata.wasm-pack.profile.release]
+wasm-opt = false
+
+[profile.release]
+lto = true
+strip = true
+opt-level = "s"

package/siderust-web/README.md

@@ -0,0 +1,100 @@
+# `@siderust/siderust-web`
+
+Browser/WASM bindings for Siderust with the same strict typed API as the
+Node package.
+
+Call `init()` before constructing `Quantity`, `JulianDate`, `Observer`, or
+any other typed object used with this package. `init()` bootstraps
+`@siderust/qtty-web`, `@siderust/tempoch-web`, and the main `siderust-web`
+wasm bundle together.
+
+## Install
+
+```bash
+npm install @siderust/siderust-web @siderust/qtty-web @siderust/tempoch-web
+```
+
+## Example
+
+```js
+import { Quantity } from '@siderust/qtty-web';
+import { JulianDate, ModifiedJulianDate, Period } from '@siderust/tempoch-web';
+import {
+  init,
+  Observer,
+  bodyAltitudeAt,
+  bodyCrossings,
+  moonPhase,
+  vsop87Heliocentric,
+} from '@siderust/siderust-web';
+
+await init();
+
+const DEG = (value) => new Quantity(value, 'Degree');
+const M = (value) => new Quantity(value, 'Meter');
+
+const observer = new Observer(DEG(-17.8925), DEG(28.7543), M(2396));
+const jd = new JulianDate(2_451_545.0);
+const mjd = new ModifiedJulianDate(60_000.0);
+const window = new Period(mjd, new ModifiedJulianDate(60_001.0));
+
+console.log(bodyAltitudeAt('Sun', observer, mjd).toString());
+console.log(bodyCrossings('Sun', observer, window, DEG(0)));
+console.log(moonPhase(jd).phaseAngle.toString());
+console.log(vsop87Heliocentric('Mars', jd).x.toString());
+```
+
+## API shape
+
+- `jd` parameters require `JulianDate`.
+- Instant `mjd` parameters require `ModifiedJulianDate`.
+- Search windows use `Period`.
+- Observer/star/domain quantities require `Quantity`.
+- Event timestamps are returned as `ModifiedJulianDate`.
+- Period searches return `Period[]`.
+- Angles, lengths, and other physical outputs return `Quantity`.
+
+## Core exports
+
+- `init()`
+- `Observer`
+- `Star`
+- `transformDirection(...)`
+- `directionToHorizontal(...)`
+- `geodeticToEcef(...)`
+- `angularSeparation(...)`
+- `cartesianDistance(...)`
+- `cartesianMagnitude(...)`
+- `directionToCartesian(...)`
+- `vsop87Heliocentric(...)`
+- `vsop87Barycentric(...)`
+- `vsop87SunBarycentric(...)`
+- `vsop87EarthBarycentric(...)`
+- `vsop87EarthHeliocentric(...)`
+- `vsop87MoonGeocentric(...)`
+- `transformPositionCenter(...)`
+- `transformPositionFrame(...)`
+- `orbitalPeriod(...)`
+- `bodyAltitudeAt(...)`
+- `bodyAzimuthAt(...)`
+- `bodyCrossings(...)`
+- `bodyCulminations(...)`
+- `bodyAboveThreshold(...)`
+- `bodyBelowThreshold(...)`
+- `bodyAzimuthCrossings(...)`
+- `bodyAzimuthExtrema(...)`
+- `starAltitudeAt(...)`
+- `starAzimuthAt(...)`
+- `starCrossings(...)`
+- `starCulminations(...)`
+- `starAboveThreshold(...)`
+- `starBelowThreshold(...)`
+- `starAzimuthCrossings(...)`
+- `starAzimuthExtrema(...)`
+- `intersectPeriods(...)`
+- `moonPhase(...)`
+- `moonPhaseTopocentric(...)`
+- `findPhaseEvents(...)`
+- `moonIlluminationAbove(...)`
+- `moonIlluminationBelow(...)`
+- `moonIlluminationRange(...)`

package/siderust-web/__test__/index.test.mjs

@@ -0,0 +1,118 @@
+import { before, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+
+import { init as initQtty, Quantity } from "@siderust/qtty-web";
+import {
+  init as initTempoch,
+  JulianDate,
+  ModifiedJulianDate,
+  Period,
+} from "@siderust/tempoch-web";
+
+import {
+  init,
+  Observer,
+  Star,
+  bodyAltitudeAt,
+  bodyCrossings,
+  moonPhase,
+  transformDirection,
+  vsop87Heliocentric,
+} from "../index.js";
+
+const qttyWasm = new URL(
+  "../../../qtty-js/qtty-web/pkg/qtty_web_bg.wasm",
+  import.meta.url,
+);
+const tempochWasm = new URL(
+  "../../../tempoch-js/tempoch-web/pkg/tempoch_web_bg.wasm",
+  import.meta.url,
+);
+const siderustWasm = new URL("../pkg/siderust_web_bg.wasm", import.meta.url);
+
+const DEG = (value) => new Quantity(value, "Degree");
+const M = (value) => new Quantity(value, "Meter");
+const LY = (value) => new Quantity(value, "LightYear");
+const SOLAR_MASS = (value) => new Quantity(value, "SolarMass");
+const SOLAR_RADIUS = (value) => new Quantity(value, "NominalSolarRadius");
+const SOLAR_LUMINOSITY = (value) => new Quantity(value, "SolarLuminosity");
+
+before(async () => {
+  await initQtty(await readFile(qttyWasm));
+  await initTempoch(await readFile(tempochWasm));
+  await init(await readFile(siderustWasm));
+});
+
+describe("@siderust/siderust-web typed API", () => {
+  it("constructs typed observer and star objects", () => {
+    const observer = new Observer(DEG(-17.8925), DEG(28.7543), M(2396));
+    const star = new Star(
+      "TypedStar",
+      LY(100),
+      SOLAR_MASS(2),
+      SOLAR_RADIUS(1.5),
+      SOLAR_LUMINOSITY(8),
+      DEG(180),
+      DEG(-45),
+    );
+
+    assert.equal(observer.lon.unit, "Degree");
+    assert.equal(observer.height.unit, "Meter");
+    assert.equal(star.distance.unit, "LightYear");
+    assert.equal(star.ra.unit, "Degree");
+  });
+
+  it("rejects raw numbers", () => {
+    assert.throws(
+      () => new Observer(-17.8925, 28.7543, 2396),
+      /expected a Quantity/,
+    );
+    assert.throws(
+      () => vsop87Heliocentric("Mars", 2_451_545.0),
+      /Expected a JulianDate/,
+    );
+  });
+
+  it("returns typed direction and position results", () => {
+    const direction = transformDirection(
+      DEG(38.78),
+      DEG(279.23),
+      "EquatorialMeanJ2000",
+      "EclipticMeanJ2000",
+      new JulianDate(2_451_545.0),
+    );
+    const mars = vsop87Heliocentric("Mars", new JulianDate(2_451_545.0));
+
+    assert.equal(direction.polar.unit, "Degree");
+    assert.equal(direction.azimuth.unit, "Degree");
+    assert.equal(mars.x.unit, "AstronomicalUnit");
+    assert.equal(mars.center, "Heliocentric");
+  });
+
+  it("returns typed event values", () => {
+    const observer = Observer.roqueDeLasMuchachos();
+    const window = new Period(
+      new ModifiedJulianDate(60_000.0),
+      new ModifiedJulianDate(60_001.0),
+    );
+    const altitude = bodyAltitudeAt(
+      "Sun",
+      observer,
+      new ModifiedJulianDate(60_000.0),
+    );
+    const crossings = bodyCrossings("Sun", observer, window, DEG(0));
+
+    assert.equal(altitude.unit, "Degree");
+    for (const event of crossings) {
+      assert.ok(event.mjd instanceof ModifiedJulianDate);
+    }
+  });
+
+  it("returns typed moon phase values", () => {
+    const phase = moonPhase(new JulianDate(2_451_545.0));
+    assert.equal(phase.phaseAngle.unit, "Degree");
+    assert.equal(phase.elongation.unit, "Degree");
+    assert.equal(typeof phase.illuminatedFraction, "number");
+  });
+});

package/siderust-web/examples/github-pages/README.md

@@ -0,0 +1,31 @@
+# GitHub Pages Example
+
+This demo goes through the public `@siderust/siderust-web` API and uses
+`@siderust/qtty-web` plus `@siderust/tempoch-web` explicitly for typed
+inputs.
+
+## Build the local packages
+
+```bash
+cd ../../../qtty-js/qtty-web
+npm run build
+
+cd ../../tempoch-js/tempoch-web
+npm run build
+
+cd ../../siderust-js/siderust-web
+npm run build
+```
+
+## Serve the example
+
+From `javascript/siderust-js/siderust-web/examples/github-pages`:
+
+```bash
+python3 -m http.server 8080
+```
+
+Then open <http://localhost:8080/index.html>.
+
+The page uses an `importmap` that points at the sibling `qtty-web`,
+`tempoch-web`, and `siderust-web` packages in this workspace.

package/siderust-web/examples/github-pages/index.html

@@ -0,0 +1,135 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Siderust Typed Browser Demo</title>
+  <style>
+    :root {
+      --bg: #f6f3ec;
+      --ink: #1f2430;
+      --accent: #8b5e34;
+      --panel: #fffaf2;
+      --line: #dbcdb7;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: Georgia, "Iowan Old Style", serif;
+      background:
+        radial-gradient(circle at top left, #fff6e4 0, transparent 32%),
+        linear-gradient(180deg, #f0e7d7, var(--bg));
+      color: var(--ink);
+      min-height: 100vh;
+      padding: 2rem;
+    }
+    main {
+      max-width: 900px;
+      margin: 0 auto;
+      background: rgba(255, 250, 242, 0.92);
+      border: 1px solid var(--line);
+      border-radius: 18px;
+      padding: 1.5rem;
+      box-shadow: 0 30px 80px rgba(31, 36, 48, 0.12);
+    }
+    h1, h2 { margin: 0 0 0.75rem; color: var(--accent); }
+    p { line-height: 1.55; }
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+      gap: 1rem;
+      margin-top: 1rem;
+    }
+    .card {
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      padding: 1rem;
+    }
+    pre {
+      margin: 0;
+      white-space: pre-wrap;
+      font-family: "SFMono-Regular", Consolas, monospace;
+      font-size: 0.88rem;
+    }
+    .status { margin-bottom: 1rem; }
+  </style>
+  <script type="importmap">
+    {
+      "imports": {
+        "@siderust/qtty-web": "../../../../qtty-js/qtty-web/index.js",
+        "@siderust/tempoch-web": "../../../../tempoch-js/tempoch-web/index.js",
+        "@siderust/siderust-web": "../../index.js"
+      }
+    }
+  </script>
+</head>
+<body>
+  <main>
+    <h1>Siderust Browser Demo</h1>
+    <p class="status" id="status">Loading typed wasm packages…</p>
+
+    <div class="grid">
+      <section class="card">
+        <h2>Observer</h2>
+        <pre id="observer"></pre>
+      </section>
+      <section class="card">
+        <h2>Sun</h2>
+        <pre id="sun"></pre>
+      </section>
+      <section class="card">
+        <h2>Moon</h2>
+        <pre id="moon"></pre>
+      </section>
+      <section class="card">
+        <h2>Mars</h2>
+        <pre id="mars"></pre>
+      </section>
+    </div>
+  </main>
+
+  <script type="module">
+    import { Quantity } from '@siderust/qtty-web';
+    import { JulianDate, ModifiedJulianDate, Period } from '@siderust/tempoch-web';
+    import {
+      init,
+      Observer,
+      bodyAltitudeAt,
+      bodyCrossings,
+      moonPhase,
+      vsop87Heliocentric,
+    } from '@siderust/siderust-web';
+
+    const DEG = (value) => new Quantity(value, 'Degree');
+    const statusEl = document.getElementById('status');
+
+    try {
+      await init(new URL('../../pkg/siderust_web_bg.wasm', import.meta.url));
+
+      const observer = new Observer(DEG(-17.8925), DEG(28.7543), new Quantity(2396, 'Meter'));
+      const jd = new JulianDate(2_451_545.0);
+      const mjd = new ModifiedJulianDate(60_000.0);
+      const window = new Period(mjd, new ModifiedJulianDate(60_001.0));
+
+      const sunAltitude = bodyAltitudeAt('Sun', observer, mjd);
+      const sunCrossings = bodyCrossings('Sun', observer, window, DEG(0));
+      const phase = moonPhase(jd);
+      const mars = vsop87Heliocentric('Mars', jd);
+
+      document.getElementById('observer').textContent = observer.format();
+      document.getElementById('sun').textContent =
+        `Altitude: ${sunAltitude.toString()}\nCrossings in next day: ${sunCrossings.length}`;
+      document.getElementById('moon').textContent =
+        `Phase: ${phase.label}\nElongation: ${phase.elongation.toString()}\nIlluminated: ${(phase.illuminatedFraction * 100).toFixed(1)}%`;
+      document.getElementById('mars').textContent =
+        `X: ${mars.x.toString()}\nY: ${mars.y.toString()}\nZ: ${mars.z.toString()}`;
+
+      statusEl.textContent = 'Typed browser API loaded successfully.';
+    } catch (error) {
+      statusEl.textContent = `Failed to initialize: ${error.message}`;
+      throw error;
+    }
+  </script>
+</body>
+</html>