@neilberkman/sidereon 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neil Berkman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @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.
+
+The binding calls the engine's serial paths only, so no thread pool is spawned
+under wasm32.
+
+## Install / build
+
+The published package ships the prebuilt wasm. To build from source:
+
+```sh
+wasm-pack build --target web    --out-dir pkg      --out-name sidereon
+wasm-pack build --target nodejs --out-dir pkg-node --out-name 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.
+
+```js
+import init, { loadSp3, loadIonex, Tle, GroundStation } from "@neilberkman/sidereon";
+import { readFile } from "node:fs/promises";
+
+// Browser: await init();   Node: pass the wasm bytes.
+await init({ module_or_path: await readFile(new URL("./pkg/sidereon_bg.wasm", import.meta.url)) });
+
+const sp3 = loadSp3(new Uint8Array(await readFile("COD0MGXFIN.SP3")));
+console.log(sp3.epochCount, sp3.satellites);
+
+// 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));
+
+// 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);
+```
+
+For CommonJS / synchronous Node, `require("@neilberkman/sidereon")` resolves to
+the `nodejs` build, which loads the wasm at require time (no init step):
+
+```js
+const { loadSp3 } = require("@neilberkman/sidereon");
+const sp3 = loadSp3(require("fs").readFileSync("COD0MGXFIN.SP3"));
+```
+
+## IONEX slant delay
+
+```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);
+```
+
+## SGP4 propagation and look angles
+
+```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 station = new GroundStation(37.7749, -122.4194 /*, altitudeM */);
+const { azimuthDeg, elevationDeg, rangeKm } = tle.lookAngles(station, epochs);
+```
+
+## Errors
+
+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.
+
+## Data conventions
+
+- 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.
+
+## Scope
+
+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).

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@neilberkman/sidereon",
+  "version": "0.8.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",
+  "exports": {
+    ".": {
+      "types": "./pkg/sidereon.d.ts",
+      "import": "./pkg/sidereon.js",
+      "require": "./pkg-node/sidereon.js"
+    },
+    "./types": "./types/sidereon-extra.d.ts"
+  },
+  "types": "./pkg/sidereon.d.ts",
+  "files": [
+    "pkg/sidereon.js",
+    "pkg/sidereon.d.ts",
+    "pkg/sidereon_bg.wasm",
+    "pkg/sidereon_bg.wasm.d.ts",
+    "pkg-node/sidereon.js",
+    "pkg-node/sidereon.d.ts",
+    "pkg-node/sidereon_bg.wasm",
+    "pkg-node/sidereon_bg.wasm.d.ts",
+    "types/sidereon-extra.d.ts",
+    "README.md"
+  ],
+  "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",
+    "test": "node --test"
+  }
+}