siderust-js 0.1.0

package/tempoch-js/tempoch-node/examples/periods.mjs

@@ -0,0 +1,79 @@
+// examples/periods.mjs
+// Run: node examples/periods.mjs
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const { Period } = require(join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'));
+
+const line = (label = '') =>
+  console.log(
+    label ? `─── ${label} ${'─'.repeat(Math.max(0, 52 - label.length))}` : '─'.repeat(56),
+  );
+
+// ─── Construction ─────────────────────────────────────────────────────────
+line('Period construction');
+
+// From raw MJD values
+const J2000_MJD = 51_544.5;
+const p1 = new Period(J2000_MJD, J2000_MJD + 30);
+console.log(`p1 : ${p1.format()}`);
+console.log(`  duration : ${p1.durationDays()} d`);
+
+// From JavaScript Date objects
+const start2024 = new Date('2024-01-01T00:00:00Z');
+const end2024 = new Date('2025-01-01T00:00:00Z');
+const year2024 = Period.fromDates(start2024, end2024);
+console.log(`2024 calendar year:`);
+console.log(`  startMjd : ${year2024.startMjd.toFixed(2)}`);
+console.log(`  endMjd   : ${year2024.endMjd.toFixed(2)}`);
+console.log(`  duration : ${year2024.durationDays().toFixed(2)} d  (2024 is a leap year)`);
+
+// ─── Accessors ────────────────────────────────────────────────────────────
+line('Accessors');
+const p = new Period(J2000_MJD, J2000_MJD + 10);
+const startObj = p.start; // ModifiedJulianDate
+const endObj = p.end; // ModifiedJulianDate
+console.log(`start : MJD ${startObj.value} → ${startObj.toDate().toISOString()}`);
+console.log(`end   : MJD ${endObj.value} → ${endObj.toDate().toISOString()}`);
+
+// ─── Containment ──────────────────────────────────────────────────────────
+line('Containment [start, end)');
+const week = new Period(J2000_MJD, J2000_MJD + 7);
+const points = [
+  [J2000_MJD, 'start (included)'],
+  [J2000_MJD + 3.5, 'midpoint (included)'],
+  [J2000_MJD + 7, 'end (excluded — half-open)'],
+  [J2000_MJD - 1, 'before start (excluded)'],
+];
+for (const [mjd, label] of points) {
+  console.log(`  contains(${mjd.toFixed(1)}): ${week.contains(mjd)}  ← ${label}`);
+}
+
+// ─── Intersection ─────────────────────────────────────────────────────────
+line('Intersection');
+const a = new Period(J2000_MJD, J2000_MJD + 10);
+const b = new Period(J2000_MJD + 5, J2000_MJD + 15);
+const c = new Period(J2000_MJD + 20, J2000_MJD + 30);
+
+console.log(`a = [${a.startMjd}, ${a.endMjd})`);
+console.log(`b = [${b.startMjd}, ${b.endMjd})`);
+console.log(`c = [${c.startMjd}, ${c.endMjd})`);
+
+const ab = a.intersection(b);
+console.log(`a ∩ b = ${ab ? `[${ab.startMjd}, ${ab.endMjd}) → ${ab.durationDays()} d` : 'null'}`);
+
+const ac = a.intersection(c);
+console.log(`a ∩ c = ${ac ? `[${ac.startMjd}, ${ac.endMjd})` : 'null (no overlap)'}`);
+
+// ─── UTC round-trip ───────────────────────────────────────────────────────
+line('UTC bounds');
+const obs = Period.fromDates(new Date('2025-04-01T20:00:00Z'), new Date('2025-04-02T06:00:00Z'));
+const { startMs, endMs } = obs.toUtc();
+const startDate = new Date(startMs);
+const endDate = new Date(endMs);
+console.log(`Observation window:`);
+console.log(`  start : ${startDate.toISOString()}`);
+console.log(`  end   : ${endDate.toISOString()}`);
+console.log(`  duration : ${(obs.durationDays() * 24).toFixed(1)} h`);

package/tempoch-js/tempoch-node/examples/quickstart.mjs

@@ -0,0 +1,71 @@
+// examples/quickstart.mjs
+// Run: node examples/quickstart.mjs
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const {
+  JulianDate,
+  ModifiedJulianDate,
+  jdToMjd,
+  mjdToJd,
+  jdFromDate,
+  mjdFromDate,
+  jdToDate,
+} = require(join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'));
+
+const line = (label = '') =>
+  console.log(
+    label ? `─── ${label} ${'─'.repeat(Math.max(0, 52 - label.length))}` : '─'.repeat(56),
+  );
+
+// ─── Construction ─────────────────────────────────────────────────────────
+line('Construction');
+const J2000 = JulianDate.j2000();
+console.log(`J2000.0 JD  : ${J2000.value}`);
+console.log(`J2000.0 MJD : ${J2000.toMjd().value}`);
+
+const now = new Date();
+const jdNow = JulianDate.fromDate(now);
+console.log(`Now (JD)    : ${jdNow.value.toFixed(5)}`);
+console.log(`Now (MJD)   : ${jdNow.toMjd().value.toFixed(5)}`);
+
+// ─── UTC ↔ JD conversion ──────────────────────────────────────────────────
+line('UTC ↔ JD');
+const vernal2025 = JulianDate.fromUtc(2025, 3, 20, 9, 1, 0);
+console.log(`2025 Vernal Equinox JD  : ${vernal2025.value.toFixed(4)}`);
+const utcBack = vernal2025.toDate();
+console.log(`Back to UTC             : ${utcBack.toISOString()}`);
+
+// ─── Free conversion functions ────────────────────────────────────────────
+line('Free functions');
+const d = new Date('2025-01-01T00:00:00Z');
+console.log(`2025-01-01 JD  : ${jdFromDate(d).toFixed(4)}`);
+console.log(`2025-01-01 MJD : ${mjdFromDate(d).toFixed(4)}`);
+console.log(`jdToMjd(J2000) : ${jdToMjd(2_451_545.0)}`);
+console.log(`mjdToJd(51544.5): ${mjdToJd(51_544.5)}`);
+
+// ─── Epoch-based quantities ───────────────────────────────────────────────
+line('Epoch quantities');
+const obsDate = JulianDate.fromUtc(2025, 6, 15, 0, 0, 0);
+console.log(`JD             : ${obsDate.value.toFixed(4)}`);
+console.log(`Julian centuries (T): ${obsDate.julianCenturies().toFixed(6)}`);
+console.log(`Julian years        : ${obsDate.julianYears().toFixed(4)}`);
+
+// ─── Arithmetic ───────────────────────────────────────────────────────────
+line('Arithmetic');
+const t0 = JulianDate.fromUtc(2025, 1, 1, 0, 0, 0);
+const t1 = t0.addDays(365.25);
+console.log(`t0 : ${jdToDate(t0.value).toISOString().slice(0, 10)}`);
+console.log(`t1 = t0 + 365.25 d : ${jdToDate(t1.value).toISOString().slice(0, 10)}`);
+console.log(`t1 − t0 (days) : ${t1.difference(t0).toFixed(2)}`);
+
+// ─── MJD class ────────────────────────────────────────────────────────────
+line('ModifiedJulianDate');
+const mjd0 = new ModifiedJulianDate(51_544.5);
+console.log(`MJD 51544.5 → JD  : ${mjd0.toJd().value}`);
+console.log(`MJD 51544.5 → UTC : ${mjd0.toDate().toISOString()}`);
+const mjd1 = mjd0.addDays(1);
+console.log(`+ 1 day           : ${mjd1.value}`);
+console.log(`difference        : ${mjd1.difference(mjd0).toFixed(1)} d`);

package/tempoch-js/tempoch-node/examples/timescales.mjs

@@ -0,0 +1,92 @@
+// examples/timescales.mjs
+// Astronomical time contexts: J2000.0, centuries, epoch arithmetic.
+// Run: node examples/timescales.mjs
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const { JulianDate, ModifiedJulianDate, Period, julianCenturies, julianYears } = require(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+);
+
+const line = (label = '') =>
+  console.log(
+    label ? `─── ${label} ${'─'.repeat(Math.max(0, 52 - label.length))}` : '─'.repeat(56),
+  );
+
+// ─── The J2000.0 reference epoch ──────────────────────────────────────────
+line('J2000.0 epoch');
+const J2000 = JulianDate.j2000();
+console.log(`JD     : ${J2000.value}`);
+console.log(`MJD    : ${J2000.toMjd().value}`);
+// UTC ≈ 2000-01-01T11:58:56Z (J2000.0 is TT, not UTC; ΔT ≈ 63.8 s in 2000)
+console.log(`UTC    : ${J2000.toDate().toISOString()}  (ΔT ≈ 63.8 s offset from TT noon)`);
+
+// ─── Standard astronomical epochs ─────────────────────────────────────────
+line('Standard epochs');
+const epochs = [
+  { name: 'J1900.0', jd: 2_415_020.0 },
+  { name: 'J1950.0', jd: 2_433_282.5 },
+  { name: 'J2000.0', jd: 2_451_545.0 },
+  { name: 'J2050.0', jd: 2_469_807.5 },
+];
+
+for (const { name, jd } of epochs) {
+  const T = julianCenturies(jd);
+  const y = julianYears(jd);
+  console.log(`${name}  JD = ${jd.toFixed(1)}  T = ${T.toFixed(4)}  y = ${y.toFixed(2)}`);
+}
+
+// ─── Julian centuries as a "clock" ────────────────────────────────────────
+line('Centuries since J2000');
+const observations = [
+  new Date('1990-01-01T00:00:00Z'),
+  new Date('2000-01-01T12:00:00Z'),
+  new Date('2010-06-15T00:00:00Z'),
+  new Date('2025-01-01T00:00:00Z'),
+];
+console.log(`${'Date'.padEnd(26)} ${'T (centuries)'.padStart(15)}`);
+for (const d of observations) {
+  const jd = JulianDate.fromDate(d);
+  const T = jd.julianCenturies();
+  console.log(`${d.toISOString().slice(0, 10).padEnd(26)} ${T.toFixed(6).padStart(15)}`);
+}
+
+// ─── Epoch arithmetic ─────────────────────────────────────────────────────
+line('Epoch arithmetic');
+const JULIAN_YEAR = 365.25; // days
+const JULIAN_CENTURY = 36_525.0; // days
+
+const jd2000 = JulianDate.j2000();
+const jd2100 = jd2000.addDays(JULIAN_CENTURY);
+console.log(`J2100.0 JD   : ${jd2100.value}`);
+console.log(`J2100.0 UTC  : ${jd2100.toDate().toISOString().slice(0, 10)}`);
+console.log(`J2100 T      : ${jd2100.julianCenturies().toFixed(1)}`);
+
+const jd_minus5 = jd2000.addDays(-5 * JULIAN_YEAR);
+console.log(`J1995.0 JD   : ${jd_minus5.value.toFixed(1)}`);
+console.log(`T from J2000 : ${jd_minus5.julianCenturies().toFixed(6)}`);
+
+// ─── Observation window with T values ─────────────────────────────────────
+line('Observation window');
+const nightStart = new Date('2025-04-15T22:00:00Z');
+const nightEnd = new Date('2025-04-16T04:00:00Z');
+const night = Period.fromDates(nightStart, nightEnd);
+
+const midMjd = (night.startMjd + night.endMjd) / 2;
+const midJd = new ModifiedJulianDate(midMjd).toJd();
+
+console.log(`Start UTC  : ${nightStart.toISOString()}`);
+console.log(`End UTC    : ${nightEnd.toISOString()}`);
+console.log(`Duration   : ${(night.durationDays() * 24).toFixed(1)} h`);
+console.log(`Mid JD     : ${midJd.value.toFixed(5)}`);
+console.log(`Mid T      : ${midJd.julianCenturies().toFixed(8)}  centuries since J2000`);
+
+// ─── MJD as a compact date format ─────────────────────────────────────────
+line('MJD compact dates');
+const today = ModifiedJulianDate.fromDate(new Date());
+console.log(`Today MJD        : ${today.value.toFixed(4)}`);
+console.log(`Days since J2000 : ${(today.value - 51_544.5).toFixed(2)}`);
+const formatted = today.format();
+console.log(`Formatted        : ${formatted}`);

package/tempoch-js/tempoch-node/index.d.ts

@@ -0,0 +1,280 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export interface QuantityLike {
+  value: number
+  unit: string
+  dimension?: string
+}
+
+/**
+ * UTC bounds of a [`Period`] expressed as millisecond timestamps.
+ *
+ * Construct JS `Date` objects with `new Date(bounds.startMs)`.
+ */
+export interface UtcBounds {
+  /** Start instant in milliseconds since Unix epoch. */
+  startMs: number
+  /** End instant in milliseconds since Unix epoch. */
+  endMs: number
+}
+
+/* ------------------------------------------------------------------ */
+/*  Free functions                                                     */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Convert a Julian Date to a Modified Julian Date value.
+ *
+ * `mjd = jd − 2 400 000.5`
+ */
+export declare function jdToMjd(jd: number): number
+/**
+ * Convert a Modified Julian Date to a Julian Date value.
+ *
+ * `jd = mjd + 2 400 000.5`
+ */
+export declare function mjdToJd(mjd: number): number
+/** Compute Julian centuries since J2000.0 for a Julian Date. */
+export declare function julianCenturies(jd: number): number
+/** Compute Julian years since J2000.0 for a Julian Date. */
+export declare function julianYears(jd: number): number
+/** Convert a JavaScript `Date` to a Julian Date value. */
+export declare function jdFromDate(date: Date): number
+/** Convert a JavaScript `Date` to a Modified Julian Date value. */
+export declare function mjdFromDate(date: Date): number
+/**
+ * Convert a Julian Date value to a JavaScript `Date`.
+ *
+ * Throws if the Julian Date is outside the representable UTC range.
+ */
+export declare function jdToDate(jd: number): Date
+/**
+ * Convert a Modified Julian Date value to a JavaScript `Date`.
+ *
+ * Throws if the MJD is outside the representable UTC range.
+ */
+export declare function mjdToDate(mjd: number): Date
+/** Signed difference `jd1 − jd2` in days. */
+export declare function jdDifference(jd1: number, jd2: number): number
+/** Signed difference `mjd1 − mjd2` in days. */
+export declare function mjdDifference(mjd1: number, mjd2: number): number
+/** Return the tempoch-node version string. */
+export declare function version(): string
+
+/* ------------------------------------------------------------------ */
+/*  JulianDate                                                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * A Julian Date — continuous count of days from the Julian Period origin.
+ *
+ * The Julian Date for J2000.0 is **2 451 545.0** (2000-01-01 12:00:00 TT).
+ *
+ * ```js
+ * const { JulianDate } = require('@siderust/tempoch');
+ *
+ * // Construct from raw value
+ * const jd = new JulianDate(2_451_545.0);
+ *
+ * // Construct from a JavaScript Date
+ * const jd2 = JulianDate.fromDate(new Date('2000-01-01T12:00:00Z'));
+ * ```
+ */
+export declare class JulianDate {
+  /**
+   * Create a Julian Date from a raw scalar (days since the Julian Period).
+   *
+   * Throws if `value` is `NaN` or `±Infinity`.
+   */
+  constructor(value: number)
+  /**
+   * Create a Julian Date from a JavaScript `Date` object.
+   *
+   * The UTC timestamp is interpreted as Universal Time and the ΔT
+   * correction is applied automatically.
+   */
+  static fromDate(date: Date): JulianDate
+  /**
+   * Create a Julian Date from explicit UTC components.
+   *
+   * `second` may include a fractional part for sub-second precision.
+   * All values are in the proleptic Gregorian calendar (UTC).
+   */
+  static fromUtc(year: number, month: number, day: number, hour: number, minute: number, second: number): JulianDate
+  /** The J2000.0 epoch — JD 2 451 545.0 (2000-01-01T12:00:00 TT). */
+  static j2000(): JulianDate
+  /** Raw Julian Date value (days since the Julian Period origin). */
+  get value(): number
+  /** The JD value as a quantity-like object in Days. */
+  get days(): QuantityLike
+  /** Convert to a `ModifiedJulianDate` (`JD − 2 400 000.5`). */
+  toMjd(): ModifiedJulianDate
+  /**
+   * Convert to a JavaScript `Date` (UTC).
+   *
+   * Throws if the Julian Date falls outside the range representable by
+   * `chrono` (roughly −262 143 to +262 143 CE).
+   */
+  toDate(): Date
+  /**
+   * Julian centuries since J2000.0 (T) as a quantity-like object.
+   *
+   * Used extensively by precession, nutation, and sidereal-time formulae.
+   */
+  julianCenturies(): QuantityLike
+  /** Julian years since J2000.0 as a quantity-like object. */
+  julianYears(): QuantityLike
+  /**
+   * Add a time duration, returning a new `JulianDate`.
+   *
+   * Accepts a quantity-like object (any supported time unit) or a raw number (days).
+   */
+  add(duration: QuantityLike | number): JulianDate
+  /**
+   * Subtract a time duration, returning a new `JulianDate`.
+   *
+   * Accepts a quantity-like object (any supported time unit) or a raw number (days).
+   */
+  sub(duration: QuantityLike | number): JulianDate
+  /**
+   * Add a duration in days, returning a new `JulianDate`.
+   * @deprecated Use `add()` instead.
+   */
+  addDays(days: number): JulianDate
+  /** Signed difference `self − other` as a quantity-like object in Days. */
+  difference(other: JulianDate): QuantityLike
+  /** Human-readable representation (e.g. `"Julian Day: 2451545 d"`). */
+  format(): string
+}
+
+/* ------------------------------------------------------------------ */
+/*  ModifiedJulianDate                                                 */
+/* ------------------------------------------------------------------ */
+
+/**
+ * A Modified Julian Date — `JD − 2 400 000.5`.
+ *
+ * MJD starts at 1858-11-17T00:00:00 UTC (= JD 2 400 000.5).
+ * J2000.0 is MJD **51 544.5**.
+ *
+ * ```js
+ * const { ModifiedJulianDate } = require('@siderust/tempoch');
+ *
+ * const mjd = new ModifiedJulianDate(51_544.5);
+ * const mjd2 = ModifiedJulianDate.fromDate(new Date('2000-01-01T12:00:00Z'));
+ * ```
+ */
+export declare class ModifiedJulianDate {
+  /**
+   * Create a Modified Julian Date from a raw scalar.
+   *
+   * Throws if `value` is `NaN` or `±Infinity`.
+   */
+  constructor(value: number)
+  /** Create a Modified Julian Date from a JavaScript `Date` object. */
+  static fromDate(date: Date): ModifiedJulianDate
+  /** Create a Modified Julian Date from explicit UTC components. */
+  static fromUtc(year: number, month: number, day: number, hour: number, minute: number, second: number): ModifiedJulianDate
+  /** Raw MJD value. */
+  get value(): number
+  /** The MJD value as a quantity-like object in Days. */
+  get days(): QuantityLike
+  /** Convert to a `JulianDate`. */
+  toJd(): JulianDate
+  /**
+   * Convert to a JavaScript `Date` (UTC).
+   *
+   * Throws if the MJD falls outside the representable UTC range.
+   */
+  toDate(): Date
+  /**
+   * Add a time duration, returning a new `ModifiedJulianDate`.
+   *
+   * Accepts a quantity-like object (any supported time unit) or a raw number (days).
+   */
+  add(duration: QuantityLike | number): ModifiedJulianDate
+  /**
+   * Subtract a time duration, returning a new `ModifiedJulianDate`.
+   *
+   * Accepts a quantity-like object (any supported time unit) or a raw number (days).
+   */
+  sub(duration: QuantityLike | number): ModifiedJulianDate
+  /**
+   * Add a duration in days, returning a new `ModifiedJulianDate`.
+   * @deprecated Use `add()` instead.
+   */
+  addDays(days: number): ModifiedJulianDate
+  /** Signed difference `self − other` as a quantity-like object in Days. */
+  difference(other: ModifiedJulianDate): QuantityLike
+  /** Human-readable representation (e.g. `"MJD 51544.5 d"`). */
+  format(): string
+}
+
+/* ------------------------------------------------------------------ */
+/*  Period                                                             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * A time period (interval) defined by two MJD endpoints.
+ *
+ * Intervals are half-open `[start, end)`: `start` is included, `end` is
+ * excluded from containment tests.
+ *
+ * ```js
+ * const { Period } = require('@siderust/tempoch');
+ *
+ * const p = new Period(51_544.5, 51_545.5);  // one-day period at J2000
+ * console.log(p.durationDays());             // 1
+ * console.log(p.contains(51_545.0));         // true
+ * ```
+ */
+export declare class Period {
+  /**
+   * Create a period from two MJD values or `ModifiedJulianDate` objects.
+   *
+   * Throws if `start > end`.
+   */
+  constructor(start: number | ModifiedJulianDate, end: number | ModifiedJulianDate)
+  /**
+   * Create a period from two JavaScript `Date` objects.
+   *
+   * Throws if `start > end`.
+   */
+  static fromDates(start: Date, end: Date): Period
+  /** Start of the period as a raw MJD value. */
+  get startMjd(): number
+  /** End of the period as a raw MJD value. */
+  get endMjd(): number
+  /** Start as a `ModifiedJulianDate` object. */
+  get start(): ModifiedJulianDate
+  /** End as a `ModifiedJulianDate` object. */
+  get end(): ModifiedJulianDate
+  /** Duration of the period as a quantity-like object in Days. */
+  duration(): QuantityLike
+  /** Duration of the period in days (raw number). */
+  durationDays(): number
+  /**
+   * Return the overlapping sub-period, or `null` if they do not overlap.
+   *
+   * Periods are half-open `[start, end)`: two periods that share only an
+   * endpoint are considered non-overlapping.
+   */
+  intersection(other: Period): Period | null
+  /** Return `true` if the value falls inside `[start, end)`. */
+  contains(mjd: number | ModifiedJulianDate): boolean
+  /**
+   * Return start and end as millisecond timestamps (ms since Unix epoch).
+   *
+   * Construct JS `Date` objects with:
+   * ```js
+   * const { startMs, endMs } = period.toUtc();
+   * const startDate = new Date(startMs);
+   * ```
+   *
+   * Throws if either endpoint is outside the representable UTC range.
+   */
+  toUtc(): UtcBounds
+  /** Human-readable representation. */
+  format(): string
+}

package/tempoch-js/tempoch-node/index.js

@@ -0,0 +1,32 @@
+/**
+ * @siderust/tempoch — Astronomical time primitives for Node.js.
+ *
+ * Public entrypoint.  Exposes JS-level façade classes (`JulianDate`,
+ * `ModifiedJulianDate`, `Period`) and free functions from the native backend.
+ *
+ * @module @siderust/tempoch
+ */
+
+'use strict';
+
+const { JulianDate } = require('./lib/JulianDate.js');
+const { ModifiedJulianDate } = require('./lib/ModifiedJulianDate.js');
+const { Period } = require('./lib/Period.js');
+
+// Free functions — pass through from the native backend.
+const backend = require('./lib/backend.js');
+
+module.exports.JulianDate = JulianDate;
+module.exports.ModifiedJulianDate = ModifiedJulianDate;
+module.exports.Period = Period;
+module.exports.jdToMjd = backend.jdToMjd;
+module.exports.mjdToJd = backend.mjdToJd;
+module.exports.julianCenturies = backend.julianCenturies;
+module.exports.julianYears = backend.julianYears;
+module.exports.jdFromDate = backend.jdFromDate;
+module.exports.mjdFromDate = backend.mjdFromDate;
+module.exports.jdToDate = backend.jdToDate;
+module.exports.mjdToDate = backend.mjdToDate;
+module.exports.jdDifference = backend.jdDifference;
+module.exports.mjdDifference = backend.mjdDifference;
+module.exports.version = backend.version;