@neilberkman/sidereon 0.8.1 → 0.9.1

package/README.md

@@ -1,105 +1,152 @@
 # @neilberkman/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 in the browser and in Node: propagate satellites, predict
+passes, solve precise positions (SPP / RTK / PPP), and convert between coordinate
+frames and time scales. This is the JavaScript and TypeScript interface to the
+sidereon engine.
 
-The binding calls the engine's serial paths only, so no thread pool is spawned
-under wasm32.
+The engine is written in Rust and compiled to WebAssembly, so a browser tab or a
+Node process gets the same numbers the native builds produce, with no server
+round-trip and no native add-on to install. Results are reference-validated: the
+SGP4 propagator is a bit-exact port of Vallado's reference implementation, frames
+and time are checked against Skyfield and IERS, and the positioning stack is
+checked against IGS products.
 
-## 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)
-
-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.
+The package is dual ESM/CJS and ships prebuilt wasm with bundled TypeScript
+declarations. The two entry points initialize differently:
 
-```js
-import init, { loadSp3, loadIonex, Tle, GroundStation } from "@neilberkman/sidereon";
-import { readFile } from "node:fs/promises";
+- **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, so there is no init step and everything is ready synchronously.
 
-// Browser: await init();   Node: pass the wasm bytes.
-await init({ module_or_path: await readFile(new URL("./pkg/sidereon_bg.wasm", import.meta.url)) });
+## Example: propagate a TLE
 
-const sp3 = loadSp3(new Uint8Array(await readFile("COD0MGXFIN.SP3")));
-console.log(sp3.epochCount, sp3.satellites);
+Parse a two-line element set, run SGP4, and take look angles (azimuth, elevation,
+range) from a ground station. No data files, no setup.
 
-// 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));
+```js
+import init, { Tle, GroundStation } from "@neilberkman/sidereon";
 
-// 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);
-```
+await init();
 
-For CommonJS / synchronous Node, `require("@neilberkman/sidereon")` resolves to
-the `nodejs` build, which loads the wasm at require time (no init step):
+const tle = new Tle(
+  "1 25544U 98067A   24001.50000000  .00016717  00000-0  10270-3 0  9009",
+  "2 25544  51.6400 208.8657 0002644 250.3037 109.7782 15.49560812999990",
+);
+const station = new GroundStation(51.5, -0.1, 10.0);
 
-```js
-const { loadSp3 } = require("@neilberkman/sidereon");
-const sp3 = loadSp3(require("fs").readFileSync("COD0MGXFIN.SP3"));
+// Epochs are unix microseconds as BigInt64Array.
+const t = BigInt(Date.UTC(2024, 0, 1, 12)) * 1000n;
+const look = tle.lookAngles(station, new BigInt64Array([t]));
+console.log(look.azimuthDeg[0], look.elevationDeg[0], look.rangeKm[0]);
 ```
 
-## IONEX slant delay
+`Tle` also gives you `propagate(epochs)` (TEME position/velocity over a
+`BigInt64Array` of unix-microsecond epochs) and `findPasses(station, start, end,
+minElevationDeg)` for visibility windows.
 
-```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);
-```
+### Node (CommonJS)
 
-## SGP4 propagation and look angles
+`require` resolves to the Node build, which initializes the wasm at require time:
 
 ```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]);
-
-const { positionKm, velocityKmS } = tle.propagate(epochs); // TEME, flat [x,y,z,...]
+const { Tle, GroundStation } = require("@neilberkman/sidereon");
 
-const station = new GroundStation(37.7749, -122.4194 /*, altitudeM */);
-const { azimuthDeg, elevationDeg, rangeKm } = tle.lookAngles(station, epochs);
+const tle = new Tle(line1, line2);
+const look = tle.lookAngles(new GroundStation(51.5, -0.1, 10.0), epochs);
 ```
 
-## Errors
+## Example: precise positioning
 
-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.
+Load a precise SP3 ephemeris, hand it pseudoranges, and get a least-squares fix
+back.
 
-## Data conventions
+```js
+import init, { loadSp3 } from "@neilberkman/sidereon";
 
-- 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.
+await init();
 
-## Scope
+// SP3-c precise orbits, as bytes (read from a file, fetch, or string).
+const sp3 = loadSp3(new TextEncoder().encode(sp3Text));
+
+// GPS L1 pseudoranges (m) for the satellites in view at the epoch.
+const solution = sp3.solveSpp({
+  observations: [
+    { satelliteId: "G08", pseudorangeM: 23825519.8 },
+    { satelliteId: "G10", pseudorangeM: 22717690.1 },
+    { satelliteId: "G16", pseudorangeM: 20478653.4 },
+    { satelliteId: "G18", pseudorangeM: 21768335.2 },
+    { satelliteId: "G20", pseudorangeM: 21248327.7 },
+    { satelliteId: "G21", pseudorangeM: 20808709.8 },
+  ],
+  tRxJ2000S: 646272000.0,
+  tRxSecondOfDayS: 43200.0,
+  dayOfYear: 176.5,
+  initialGuess: [4.5e6, 0.5e6, 4.5e6, 0],
+  corrections: { ionosphere: false, troposphere: false },
+  withGeodetic: true,
+});
+
+console.log(solution.positionM); // ECEF m ~ [4484128, 550582, 4487561]
+console.log(solution.rxClockS);  // receiver clock bias, seconds
+```
 
-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).
+`solveRtkFloat` / `solveRtkFixed` and `solvePppFloat` / `solvePppFixed` follow
+the same shape: an options object in, a result object with `Float64Array`
+positions and scalar attributes out.
+
+## Capabilities
+
+The wasm surface mirrors the full breadth of the engine:
+
+- **Orbit propagation:** SGP4 from TLE and OMM, numerical propagation, batch
+  constellation propagation, pass prediction, look angles, coverage.
+- **GNSS positioning:** SPP, RTK (float/fixed), PPP (float/fixed), DGNSS, RAIM/FDE,
+  DOP, velocity.
+- **Ephemeris and time:** broadcast ephemeris and SP3 (load/interpolate/merge),
+  JPL SPK (DAF/.bsp) kernels, scale-aware time (`Instant` with GMST/GAST and
+  resolved TT/UT1/TDB), Earth orientation parameters.
+- **Geometry and events:** reference frames (TEME, GCRS, ITRS, geodetic, ECEF),
+  look angles, eclipse and shadow geometry, conjunction screening with collision
+  probability, initial orbit determination, orbital elements.
+- **Atmosphere:** Klobuchar and NeQuick-G ionosphere, IONEX slant delay,
+  troposphere models.
+- **RF link budget:** free-space path loss, EIRP, C/N0, antenna gain.
+- **Format parsing and serialization:** TLE/OMM, CCSDS, RINEX, CRINEX (Hatanaka),
+  SP3, IONEX, ANTEX, RTCM.
+
+The binding adds no modeling of its own: every result is exactly what the engine
+computes. Failures surface as the JS exception you would expect (`Error` for
+engine rejections such as parse failures, non-converging solves, and 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`.
+
+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.
+
+## Live demo
+
+The interactive demo at [sidereon.dev](https://sidereon.dev) runs on this exact
+package: every computation happens client-side in your browser via this wasm
+build.
+
+## Links
+
+- **Engine and core repo:** https://github.com/neilberkman/sidereon
+- **Live demo:** https://sidereon.dev
+- **Sibling interfaces:** sidereon-python (PyPI), sidereon-c, sidereon-ex (Hex).
+  One validated engine, the same numbers in every language.
+
+## License
+
+MIT

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@neilberkman/sidereon",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "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"
   }
 }