siderust-js 0.1.0

package/tempoch-js/tempoch-node/README.md

@@ -0,0 +1,265 @@
+# @siderust/tempoch
+
+**Astronomical time primitives for Node.js — powered by Rust.**
+
+`@siderust/tempoch` wraps the [`tempoch`](https://github.com/Siderust/tempoch)
+Rust crate via [napi-rs](https://napi.rs) to provide:
+
+- **Julian Date** (`JulianDate`) and **Modified Julian Date** (`ModifiedJulianDate`)  
+  with precise UTC ↔ JD conversion including the ΔT (TT − UT) correction.
+- **Period** — a half-open time interval `[start, end)` with duration, containment,
+  and intersection queries.
+- **Free functions** for scalar conversions and epoch arithmetic.
+- **TypeScript declarations** (auto-generated by napi-rs).
+
+All time logic lives in Rust; the JS/TS layer is a thin ergonomic façade.
+
+---
+
+## Quick start
+
+```js
+const { JulianDate, ModifiedJulianDate, Period } = require('@siderust/tempoch');
+
+// Construct from raw value
+const jd = new JulianDate(2_451_545.0);
+console.log(jd.value); // 2451545
+console.log(jd.julianCenturies()); // 0  (J2000.0)
+
+// Construct from a JavaScript Date
+const jd2 = JulianDate.fromDate(new Date('2025-06-21T00:00:00Z'));
+console.log(jd2.toMjd().value.toFixed(2)); // ~61027.50
+
+// Round-trip to UTC
+const back = jd2.toDate();
+console.log(back.toISOString());
+
+// Free conversion functions
+const { jdToMjd, julianCenturies } = require('@siderust/tempoch');
+console.log(jdToMjd(2_451_545.0)); // 51544.5
+console.log(julianCenturies(2_451_545.0)); // 0
+```
+
+```ts
+// TypeScript
+import {
+  JulianDate,
+  ModifiedJulianDate,
+  Period,
+  jdToMjd,
+  julianCenturies,
+} from '@siderust/tempoch';
+
+const jd: JulianDate = JulianDate.j2000();
+const t: number = jd.julianCenturies(); // 0
+```
+
+---
+
+## Installation
+
+```bash
+npm install @siderust/tempoch
+```
+
+The package ships a pre-built native addon for the current platform.
+To build from source, see [Building from source](#building-from-source).
+
+---
+
+## API
+
+### `JulianDate`
+
+Continuous day count since the Julian Period origin. J2000.0 = **JD 2 451 545.0**.
+
+#### Constructors / factories
+
+| Method                                   | Description                                            |
+| ---------------------------------------- | ------------------------------------------------------ |
+| `new JulianDate(value)`                  | From raw `f64` days. Throws on `NaN`/`±Infinity`.      |
+| `JulianDate.fromDate(date)`              | From a JS `Date`. Applies ΔT correction automatically. |
+| `JulianDate.fromUtc(y, mo, d, h, mi, s)` | From explicit UTC components. `s` may be fractional.   |
+| `JulianDate.j2000()`                     | Returns the J2000.0 epoch (JD 2 451 545.0).            |
+
+#### Accessors / conversions
+
+| Member               | Type                 | Description                                          |
+| -------------------- | -------------------- | ---------------------------------------------------- |
+| `.value`             | `number`             | Raw JD scalar.                                       |
+| `.toMjd()`           | `ModifiedJulianDate` | Converts to MJD (`JD − 2 400 000.5`).                |
+| `.toDate()`          | `Date`               | Converts to JS `Date` (UTC). Throws if out of range. |
+| `.julianCenturies()` | `number`             | T = (JD − 2 451 545.0) / 36 525.                     |
+| `.julianYears()`     | `number`             | (JD − 2 451 545.0) / 365.25.                         |
+| `.format()`          | `string`             | Human-readable string.                               |
+
+#### Arithmetic
+
+| Method               | Description                                                                      |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `.addDays(days)`     | Returns a new `JulianDate` shifted by `days` (can be negative). Throws on `NaN`. |
+| `.difference(other)` | Returns `this − other` in days.                                                  |
+
+---
+
+### `ModifiedJulianDate`
+
+`MJD = JD − 2 400 000.5`. MJD epoch: 1858-11-17T00:00:00 UTC. J2000.0 = **MJD 51 544.5**.
+
+#### Constructors / factories
+
+| Method                                           | Description                                       |
+| ------------------------------------------------ | ------------------------------------------------- |
+| `new ModifiedJulianDate(value)`                  | From raw `f64` days. Throws on `NaN`/`±Infinity`. |
+| `ModifiedJulianDate.fromDate(date)`              | From a JS `Date`.                                 |
+| `ModifiedJulianDate.fromUtc(y, mo, d, h, mi, s)` | From explicit UTC components.                     |
+
+#### Accessors / conversions
+
+| Member      | Type         | Description                                          |
+| ----------- | ------------ | ---------------------------------------------------- |
+| `.value`    | `number`     | Raw MJD scalar.                                      |
+| `.toJd()`   | `JulianDate` | Converts to JD.                                      |
+| `.toDate()` | `Date`       | Converts to JS `Date` (UTC). Throws if out of range. |
+| `.format()` | `string`     | Human-readable string.                               |
+
+#### Arithmetic
+
+| Method               | Description                                           |
+| -------------------- | ----------------------------------------------------- |
+| `.addDays(days)`     | Returns a new `ModifiedJulianDate` shifted by `days`. |
+| `.difference(other)` | Returns `this − other` in days.                       |
+
+---
+
+### `Period`
+
+A half-open time interval `[start, end)` over MJD.
+
+#### Constructors / factories
+
+| Method                         | Description                                                     |
+| ------------------------------ | --------------------------------------------------------------- |
+| `new Period(startMjd, endMjd)` | From two raw MJD values. Throws if `start > end` or non-finite. |
+| `Period.fromDates(start, end)` | From two JS `Date` objects. Throws if `start > end`.            |
+
+#### Accessors
+
+| Member      | Type                 | Description                             |
+| ----------- | -------------------- | --------------------------------------- |
+| `.startMjd` | `number`             | Start raw MJD value.                    |
+| `.endMjd`   | `number`             | End raw MJD value.                      |
+| `.start`    | `ModifiedJulianDate` | Start as a `ModifiedJulianDate` object. |
+| `.end`      | `ModifiedJulianDate` | End as a `ModifiedJulianDate` object.   |
+
+#### Methods
+
+| Method                 | Return                               | Description                                                     |
+| ---------------------- | ------------------------------------ | --------------------------------------------------------------- |
+| `.durationDays()`      | `number`                             | Duration in days.                                               |
+| `.contains(mjd)`       | `boolean`                            | `true` if `start ≤ mjd < end`.                                  |
+| `.intersection(other)` | `Period \| null`                     | Overlapping sub-period, or `null` if disjoint.                  |
+| `.toUtc()`             | `{ startMs: number, endMs: number }` | Endpoints as ms-since-epoch timestamps. Throws if out of range. |
+| `.format()`            | `string`                             | Human-readable string.                                          |
+
+---
+
+### Free functions
+
+| Function                    | Returns  | Description               |
+| --------------------------- | -------- | ------------------------- |
+| `jdToMjd(jd)`               | `number` | `jd − 2 400 000.5`        |
+| `mjdToJd(mjd)`              | `number` | `mjd + 2 400 000.5`       |
+| `julianCenturies(jd)`       | `number` | T = (jd − J2000) / 36 525 |
+| `julianYears(jd)`           | `number` | (jd − J2000) / 365.25     |
+| `jdFromDate(date)`          | `number` | JS `Date` → JD scalar     |
+| `mjdFromDate(date)`         | `number` | JS `Date` → MJD scalar    |
+| `jdToDate(jd)`              | `Date`   | JD scalar → JS `Date`     |
+| `mjdToDate(mjd)`            | `Date`   | MJD scalar → JS `Date`    |
+| `jdDifference(jd1, jd2)`    | `number` | `jd1 − jd2` in days       |
+| `mjdDifference(mjd1, mjd2)` | `number` | `mjd1 − mjd2` in days     |
+| `version()`                 | `string` | Package version string    |
+
+---
+
+## UTC conversions and ΔT
+
+The mapping between a Julian Date (expressed in **Terrestrial Time**, TT) and a
+`Date` object (expressed in **UTC**) involves the **ΔT = TT − UT** correction.
+This package applies the correction automatically in both directions using the
+piecewise Meeus/IERS model from `tempoch-core`:
+
+```
+JulianDate.fromDate(jsDate)  →  internal route: UTC → UT → JD(TT)
+jd.toDate()                  →  internal route: JD(TT) → UT → UTC
+```
+
+For J2000.0 (JD 2 451 545.0, TT noon), the UTC equivalent is approximately
+**2000-01-01T11:58:56Z** (ΔT ≈ 63.8 s in the year 2000).
+
+> **Note:** this ΔT is an astronomical correction, not a leap-second offset.
+> It accounts for the irregular slowing of Earth's rotation relative to
+> dynamical (atomic) time.
+
+---
+
+## Examples
+
+| File                                               | Description                                    |
+| -------------------------------------------------- | ---------------------------------------------- |
+| [examples/quickstart.mjs](examples/quickstart.mjs) | Construction, conversions, arithmetic          |
+| [examples/periods.mjs](examples/periods.mjs)       | Period construction, containment, intersection |
+| [examples/timescales.mjs](examples/timescales.mjs) | J2000 epoch, centuries, observation windows    |
+
+Run any example directly:
+
+```bash
+node examples/quickstart.mjs
+```
+
+---
+
+## Building from source
+
+Requirements: **Rust ≥ 1.75**, **Node.js ≥ 18**, **napi-rs CLI 2.x**.
+
+```bash
+git clone https://github.com/Siderust/tempoch
+cd javascript/tempoch-js/tempoch-node
+
+# Install JS dev dependencies (includes @napi-rs/cli)
+npm install
+
+# Debug build
+npm run build:debug
+
+# Optimised release build
+npm run build
+```
+
+---
+
+## Architecture
+
+```
+@siderust/tempoch (JS/TS)
+        │
+        │  napi-rs bindings  (src/lib.rs)
+        ▼
+tempoch  (Rust façade crate)
+        │
+        ▼
+tempoch-core  (Time<S>, Period, ΔT model, scale markers)
+```
+
+The native addon is a `cdylib` Rust crate that depends on `tempoch` and
+`tempoch-core`. No C FFI layer is involved — napi-rs generates the V8 bridge
+directly without going through `tempoch-ffi`.
+
+---
+
+## License
+
+AGPL-3.0-only — see [LICENSE](LICENSE).
+
+© 2026 Vallés Puig, Ramon