@neilberkman/sidereon 0.8.1 → 0.9.0

package/README.md

@@ -1,105 +1,161 @@
-# @neilberkman/sidereon
+# sidereon
 
-A WebAssembly / JavaScript interface over the [sidereon](https://github.com/neilberkman/sidereon)
-GNSS + astrodynamics engine. It loads SP3 precise ephemerides, runs single-point
-positioning (SPP), queries IONEX slant ionospheric delay, and propagates SGP4 /
-TLE orbits with ground-station look angles. The numbers come straight from
-`sidereon-core`; this package only marshals across the wasm boundary.
+GNSS and astrodynamics for JavaScript and TypeScript: propagate satellites,
+predict passes, solve precise positions (SPP / RTK / PPP), and convert between
+coordinate frames and time — the real engine, compiled to WebAssembly, running
+in the browser or Node — checked against the references the field trusts
+(Vallado, Skyfield, IGS, IERS).
 
-The binding calls the engine's serial paths only, so no thread pool is spawned
-under wasm32.
+This isn't a reimplementation in JavaScript. It's the same Rust engine that
+backs the Python, C, and Elixir interfaces, compiled to WebAssembly — so a
+browser tab gets bit-for-bit the same numbers as the native builds, with no
+server round-trip and no native add-on to install.
 
-## Install / build
-
-The published package ships the prebuilt wasm. To build from source:
+## Install
 
 ```sh
-wasm-pack build --target web    --out-dir pkg      --out-name sidereon
-wasm-pack build --target nodejs --out-dir pkg-node --out-name sidereon
+npm install @neilberkman/sidereon
 ```
 
-## Usage (ESM, async init)
+It's a dual ESM/CJS package shipping prebuilt wasm — works in bundlers,
+browsers, and Node. TypeScript declarations are bundled. There are two entry
+points and they init differently:
+
+- **Browser / bundler (ESM):** import the default `init`, `await` it once, then
+  call the API. `init()` fetches the `.wasm` for you.
+- **Node (CommonJS):** `require(...)` loads and initializes the wasm at require
+  time — there is no init step.
+
+## Quickstart: when does the ISS fly over you?
 
-The `web` build follows the standard wasm-pack pattern: import the default
-`init`, await it once, then call the API. In the browser `init()` fetches the
-`.wasm` for you; in Node, hand it the bytes.
+No data files, no setup — give it a two-line element set and a ground station,
+and ask when the satellite is above the horizon.
 
 ```js
-import init, { loadSp3, loadIonex, Tle, GroundStation } from "@neilberkman/sidereon";
-import { readFile } from "node:fs/promises";
+import init, { Tle, GroundStation } from "@neilberkman/sidereon";
 
-// Browser: await init();   Node: pass the wasm bytes.
-await init({ module_or_path: await readFile(new URL("./pkg/sidereon_bg.wasm", import.meta.url)) });
+await init(); // browser/bundler: fetches the wasm. (Node CJS: see below — no init.)
 
-const sp3 = loadSp3(new Uint8Array(await readFile("COD0MGXFIN.SP3")));
-console.log(sp3.epochCount, sp3.satellites);
+// Real orbital elements (grab fresh ones from CelesTrak any time).
+const iss = new Tle(
+  "1 25544U 98067A   26178.50947090  .00006280  00000+0  12016-3 0  9996",
+  "2 25544  51.6322 248.9966 0004278 238.4942 121.5629 15.49454046573359",
+);
 
-// Positions come back as Float64Array; epochs as plain numbers (seconds J2000).
-const epochs = sp3.epochsJ2000Seconds();
-const { positionM, clockS } = sp3.interpolate("G01", epochs.slice(0, 1));
+// A ground station: latitude, longitude in degrees (altitude in metres, optional).
+const berkeley = new GroundStation(37.87, -122.27);
+
+// Epochs are UTC unix microseconds and cross as BigInt.
+const us = (ms) => BigInt(ms) * 1000n;
+const now = Date.now();
+
+// Every pass above 10° over the next 24 hours.
+const passes = iss.findPasses(berkeley, us(now), us(now + 24 * 3600 * 1000), 10.0);
+
+const at = (uus) => new Date(Number(uus / 1000n)).toISOString().slice(11, 16);
+for (const p of passes) {
+  console.log(`${at(p.aosUnixUs)} UTC · ${(p.durationS / 60).toFixed(1)} min · peak ${p.maxElevationDeg.toFixed(0)}°`);
+}
+```
 
-// Single-point positioning. Pass one options object (see the SppRequest type).
-const solution = sp3.solveSpp({
-  observations: [{ satelliteId: "G01", pseudorangeM: 22853110.4 }, /* ... */],
-  tRxJ2000S: 649728000,
-  tRxSecondOfDayS: 86400,
-  dayOfYear: 176,
-  corrections: { ionosphere: false, troposphere: false },
-});
-console.log(solution.positionM, solution.rxClockS, solution.usedSats);
 ```
+08:30 UTC · 6.8 min · peak 88°
+10:09 UTC · 4.3 min · peak 16°
+13:25 UTC · 3.2 min · peak 13°
+15:01 UTC · 6.6 min · peak 56°
+16:39 UTC · 3.5 min · peak 14°
+```
+
+`Tle` also gives you `propagate(epochs)` (TEME position/velocity over a
+`BigInt64Array` of unix-microsecond epochs) and `lookAngles(station, epochs)`
+(azimuth / elevation / range over a time grid).
 
-For CommonJS / synchronous Node, `require("@neilberkman/sidereon")` resolves to
-the `nodejs` build, which loads the wasm at require time (no init step):
+### Node (CommonJS)
+
+`require` resolves to the Node build, which loads the wasm at require time — no
+init call, everything is ready synchronously:
 
 ```js
-const { loadSp3 } = require("@neilberkman/sidereon");
-const sp3 = loadSp3(require("fs").readFileSync("COD0MGXFIN.SP3"));
+const { Tle, GroundStation } = require("@neilberkman/sidereon");
+
+const iss = new Tle(line1, line2);
+const passes = iss.findPasses(new GroundStation(37.87, -122.27), startUs, endUs, 10.0);
 ```
 
-## IONEX slant delay
+(Node ESM resolves the same default-`init` build as the browser; `await init()`
+needs the wasm bytes there — `await init({ module_or_path: await readFile(new
+URL("...sidereon_bg.wasm", import.meta.url)) })`. If you're not sure, `require`
+is the simplest path in Node.)
+
+## Precise positioning
+
+The positioning engine is the other half of the library: load a precise
+ephemeris, hand it pseudoranges, and get a least-squares fix back.
 
 ```js
-const ionex = loadIonex(new Uint8Array(await readFile("igsg.20i")));
-const epochs = ionex.mapEpochsJ2000S; // Float64Array, seconds since J2000
-// receiver lat/lon deg, satellite az/el deg, epoch, carrier Hz -> metres
-const delayM = ionex.slantDelay(37.4, -122.1, 135, 30, epochs[0], 1575.42e6);
+import { loadSp3 } from "@neilberkman/sidereon"; // (after init)
+import type { SppRequest } from "@neilberkman/sidereon/types";
+
+const sp3 = loadSp3(new Uint8Array(sp3FileBytes));
+
+const fix = sp3.solveSpp({
+  observations: [
+    { satelliteId: "G01", pseudorangeM: 21_000_123.4 },
+    { satelliteId: "G08", pseudorangeM: 22_517_889.1 },
+    // ...more satellites
+  ],
+  tRxJ2000S: 649_728_000,    // receive epoch, seconds since J2000
+  tRxSecondOfDayS: 86_400,
+  dayOfYear: 176,
+  corrections: { ionosphere: true, troposphere: true },
+  withGeodetic: true,
+});
+
+console.log(fix.positionM); // Float64Array [x, y, z] ECEF metres
+console.log(fix.geodetic);  // Float64Array [latRad, lonRad, heightM]
+console.log(fix.usedSats);  // satellites that contributed
 ```
 
-## SGP4 propagation and look angles
+`solveRtkFloat` / `solveRtkFixed` and `solvePppFloat` / `solvePppFixed` follow
+the same shape — an options object in, a result object with `Float64Array`
+positions and scalar attributes out.
 
-```js
-const tle = new Tle(line1, line2 /*, "improved" | "afspc" */);
-const t0 = BigInt(Date.now()) * 1000n; // unix microseconds
-const epochs = new BigInt64Array([t0, t0 + 600n * 1_000_000n]);
+## What's in the box
 
-const { positionKm, velocityKmS } = tle.propagate(epochs); // TEME, flat [x,y,z,...]
+The wasm surface is broad — the same domains the native engine exposes:
 
-const station = new GroundStation(37.7749, -122.4194 /*, altitudeM */);
-const { azimuthDeg, elevationDeg, rangeKm } = tle.lookAngles(station, epochs);
-```
+- **Orbits** — SGP4/TLE and OMM, numerical propagation, passes, look angles, visibility
+- **Frames & time** — TEME ↔ GCRS ↔ ITRS, geodetic ↔ ECEF, `Instant` with GMST/GAST and the resolved TT/UT1/TDB scales
+- **Bodies** — Sun/Moon positions, eclipse / shadow geometry, plus JPL SPK (DAF/.bsp) kernels
+- **Positioning** — SPP, RTK (float/fixed), PPP (float/fixed), DGNSS, DOP, velocity, RAIM/FDE
+- **GNSS data** — SP3 (load/interpolate/merge), RINEX (obs/nav/clock), CRINEX (Hatanaka), ANTEX, IONEX slant delay, broadcast ephemeris
+- **Space situational awareness** — conjunction/TCA screening, collision probability, CDM, covariance transforms
+- **RF / signal** — link budget (FSPL, EIRP, C/N0, antenna gain), C/A code, acquisition/correlation
+
+The binding adds no modeling of its own: every result is exactly what the engine
+computes. Failures surface as the JS exception you'd expect — `Error` for engine
+rejections (parse failures, non-converging solves, SGP4 error codes), `TypeError`
+for malformed input, `RangeError` for out-of-domain numbers. Full signatures
+live in the bundled TypeScript declarations (`sidereon.d.ts`), with the
+plain-object request shapes in `@neilberkman/sidereon/types`.
 
-## Errors
+A few conventions worth knowing: positions and state arrays cross as
+`Float64Array` (multi-epoch arrays are flat row-major, `3 * epochCount`); SGP4
+epoch grids are `BigInt64Array` of unix microseconds; SP3 query epochs are plain
+numbers in seconds since J2000.
 
-Engine failures (parse rejections, non-converging solves, SGP4 error codes)
-throw a JS `Error` carrying the engine's own message. Bad input throws
-`TypeError` (wrong shape or an unparseable satellite token) or `RangeError`
-(non-finite or out-of-domain numbers). Nothing traps or panics across the
-boundary.
+## Other languages
 
-## Data conventions
+sidereon is one validated engine with first-class interfaces in **Rust**,
+**Python**, **C**, **Elixir**, and **WebAssembly** — same numbers everywhere.
+See the live demo and docs at [sidereon.dev](https://sidereon.dev).
 
-- Positions and vectors cross as `Float64Array`. Multi-epoch arrays are flat,
-  row-major: `[x0, y0, z0, x1, y1, z1, ...]`, length `3 * epochCount`.
-- Epochs are plain numbers (seconds since J2000) except SGP4 epoch grids, which
-  are `BigInt64Array` of unix microseconds.
-- SPP positions are ECEF metres; geodetic output is `[latRad, lonRad, heightM]`.
-- SGP4 states are TEME, kilometres and km/s.
+## How it's validated
 
-## Scope
+The SGP4 propagator is a Rust port of David Vallado's reference implementation,
+bit-exact to it. Frames and time are checked against Skyfield and IERS; the
+positioning stack is checked against IGS products. The published package ships
+the prebuilt wasm, so there's nothing to compile to use it.
 
-Exposed: SP3 load/query, SPP solve, IONEX slant delay, SGP4 propagate /
-look angles. Not yet exposed: RTK, PPP, RINEX OBS/NAV/clock, velocity, and the
-broader astro event/conjunction surface. The rayon-parallel batch solves are
-intentionally omitted (wasm32 is single-threaded; the serial paths produce the
-same numbers).
+*Building from source (for contributors): `npm run build` (runs `wasm-pack
+build` for the `web` and `nodejs` targets). Tests: `npm test`.*

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@neilberkman/sidereon",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "WebAssembly / JavaScript interface over the sidereon GNSS + astrodynamics engine: SP3 loading and multi-product merge, SPP / RTK (float + fixed) / PPP (float + fixed) positioning, IONEX slant delay, SGP4 and numerical orbit propagation, RINEX observation/navigation/clock parsing, CRINEX (Hatanaka) decoding, observable-domain math (carrier combinations, cycle slips, Hatch smoothing, weighting, velocity, GPS C/A signal), and the astro domain (scale-tagged time, frame transforms, Sun/Moon ephemerides, eclipse / body angles, DOP, passes / visibility, conjunction + collision probability, CDM / OMM / ANTEX parsing, RF link budget)",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neilberkman/sidereon-wasm.git"
+  },
+  "homepage": "https://github.com/neilberkman/sidereon-wasm#readme",
+  "bugs": "https://github.com/neilberkman/sidereon-wasm/issues",
   "exports": {
     ".": {
       "types": "./pkg/sidereon.d.ts",
@@ -28,6 +34,16 @@
   ],
   "scripts": {
     "build": "wasm-pack build --target web --out-dir pkg --out-name sidereon && wasm-pack build --target nodejs --out-dir pkg-node --out-name sidereon && node scripts/postbuild.mjs",
-    "test": "node --test"
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . && prettier --check \"test/**/*.mjs\" \"scripts/**/*.mjs\" \"*.json\" \"eslint.config.js\"",
+    "format": "prettier --write \"test/**/*.mjs\" \"scripts/**/*.mjs\" \"*.json\" \"eslint.config.js\""
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.6.0",
+    "globals": "^17.7.0",
+    "prettier": "^3.9.1",
+    "typescript": "^6.0.3"
   }
 }