siderust-js 0.1.0

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

@@ -0,0 +1,95 @@
+/* tslint:disable */
+/* eslint-disable */
+
+import { Quantity } from '@siderust/qtty-web'
+
+// ── Initialization ──────────────────────────────────────────────────
+/**
+ * Initialise the WASM module.  Must be awaited before calling any other
+ * function in this package.
+ *
+ * ```ts
+ * import { init } from '@siderust/tempoch-web';
+ * await init();  // or init(wasmUrl)
+ * ```
+ */
+export declare function init(
+  module_or_path?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module
+): Promise<void>
+
+// ── Interfaces ──────────────────────────────────────────────────────
+
+export interface UtcBounds {
+  startMs: number
+  endMs: number
+}
+
+// ── Free functions ──────────────────────────────────────────────────
+
+export declare function jdToMjd(jd: number): number
+export declare function mjdToJd(mjd: number): number
+export declare function julianCenturies(jd: number): number
+export declare function julianYears(jd: number): number
+export declare function jdFromDate(date: Date): number
+export declare function mjdFromDate(date: Date): number
+export declare function jdToDate(jd: number): Date
+export declare function mjdToDate(mjd: number): Date
+export declare function jdDifference(jd1: number, jd2: number): number
+export declare function mjdDifference(mjd1: number, mjd2: number): number
+export declare function version(): string
+
+// ── JulianDate ──────────────────────────────────────────────────────
+
+export declare class JulianDate {
+  constructor(value: number)
+  static fromDate(date: Date): JulianDate
+  static fromUtc(year: number, month: number, day: number, hour: number, minute: number, second: number): JulianDate
+  static j2000(): JulianDate
+  get value(): number
+  get days(): Quantity
+  toMjd(): ModifiedJulianDate
+  toDate(): Date
+  julianCenturies(): Quantity
+  julianYears(): Quantity
+  add(duration: Quantity | number): JulianDate
+  sub(duration: Quantity | number): JulianDate
+  /** @deprecated Use `add()` instead. */
+  addDays(days: number): JulianDate
+  difference(other: JulianDate): Quantity
+  format(): string
+}
+
+// ── ModifiedJulianDate ──────────────────────────────────────────────
+
+export declare class ModifiedJulianDate {
+  constructor(value: number)
+  static fromDate(date: Date): ModifiedJulianDate
+  static fromUtc(year: number, month: number, day: number, hour: number, minute: number, second: number): ModifiedJulianDate
+  get value(): number
+  get days(): Quantity
+  toJd(): JulianDate
+  toDate(): Date
+  add(duration: Quantity | number): ModifiedJulianDate
+  sub(duration: Quantity | number): ModifiedJulianDate
+  /** @deprecated Use `add()` instead. */
+  addDays(days: number): ModifiedJulianDate
+  difference(other: ModifiedJulianDate): Quantity
+  format(): string
+}
+
+// ── Period ───────────────────────────────────────────────────────────
+
+export declare class Period {
+  constructor(start: number | ModifiedJulianDate, end: number | ModifiedJulianDate)
+  static fromDates(start: Date, end: Date): Period
+  get startMjd(): number
+  get endMjd(): number
+  get start(): ModifiedJulianDate
+  get end(): ModifiedJulianDate
+  duration(): Quantity
+  durationDays(): number
+  intersection(other: Period): Period | null
+  contains(mjd: number | ModifiedJulianDate): boolean
+  toUtc(): UtcBounds
+  format(): string
+}

package/tempoch-js/tempoch-web/index.js

@@ -0,0 +1,27 @@
+/**
+ * @siderust/tempoch-web — Astronomical time primitives for the browser.
+ *
+ * Call `init()` before using any other function.
+ *
+ * @module @siderust/tempoch-web
+ */
+
+export { init } from './lib/backend.js';
+export { JulianDate } from './lib/JulianDate.js';
+export { ModifiedJulianDate } from './lib/ModifiedJulianDate.js';
+export { Period } from './lib/Period.js';
+
+// Free functions re-exported from the backend
+export {
+  jdToMjd,
+  mjdToJd,
+  julianCenturies,
+  julianYears,
+  jdFromDate,
+  mjdFromDate,
+  jdToDate,
+  mjdToDate,
+  jdDifference,
+  mjdDifference,
+  version,
+} from './lib/backend.js';

package/tempoch-js/tempoch-web/lib/JulianDate.js

@@ -0,0 +1,170 @@
+/**
+ * @siderust/tempoch-web — JulianDate façade class (ESM/browser).
+ *
+ * @module @siderust/tempoch-web/lib/JulianDate
+ */
+
+import { Quantity, convert } from '@siderust/qtty-web';
+import * as backend from './backend.js';
+
+export class JulianDate {
+  /**
+   * Create a Julian Date from a raw scalar (days since the Julian Period).
+   * @param {number} value
+   */
+  constructor(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new Error('Julian date value must be finite (not NaN or ±infinity)');
+    }
+    this._value = value;
+  }
+
+  /**
+   * Create a Julian Date from a JavaScript `Date` object.
+   * @param {Date} date
+   * @returns {JulianDate}
+   */
+  static fromDate(date) {
+    return new JulianDate(backend.jdFromDate(date));
+  }
+
+  /**
+   * Create a Julian Date from explicit UTC components.
+   * @param {number} year
+   * @param {number} month
+   * @param {number} day
+   * @param {number} hour
+   * @param {number} minute
+   * @param {number} second
+   * @returns {JulianDate}
+   */
+  static fromUtc(year, month, day, hour, minute, second) {
+    return new JulianDate(backend.jdFromUtc(year, month, day, hour, minute, second));
+  }
+
+  /** The J2000.0 epoch — JD 2 451 545.0. */
+  static j2000() {
+    return new JulianDate(2_451_545.0);
+  }
+
+  /** Raw Julian Date value. */
+  get value() {
+    return this._value;
+  }
+
+  /** The JD value as a `Quantity` in Days. */
+  get days() {
+    return new Quantity(this._value, 'Day');
+  }
+
+  /**
+   * Convert to a `ModifiedJulianDate`.
+   * @returns {import('./ModifiedJulianDate.js').ModifiedJulianDate}
+   */
+  toMjd() {
+    // Lazy import to break circular dependency (ESM live bindings
+    // are resolved by the time this method is actually called).
+    const { ModifiedJulianDate } = require_mjd();
+    return new ModifiedJulianDate(backend.jdToMjd(this._value));
+  }
+
+  /** Convert to a JavaScript `Date` (UTC). */
+  toDate() {
+    return backend.jdToDate(this._value);
+  }
+
+  /**
+   * Julian centuries since J2000.0 (T).
+   * @returns {Quantity}
+   */
+  julianCenturies() {
+    return new Quantity(backend.julianCenturies(this._value), 'JulianCentury');
+  }
+
+  /**
+   * Julian years since J2000.0.
+   * @returns {Quantity}
+   */
+  julianYears() {
+    return new Quantity(backend.julianYears(this._value), 'JulianYear');
+  }
+
+  /**
+   * Add a time duration (Quantity or number of days).
+   * @param {Quantity | number} duration
+   * @returns {JulianDate}
+   */
+  add(duration) {
+    return new JulianDate(this._value + _toDays(duration));
+  }
+
+  /**
+   * Subtract a time duration.
+   * @param {Quantity | number} duration
+   * @returns {JulianDate}
+   */
+  sub(duration) {
+    return new JulianDate(this._value - _toDays(duration));
+  }
+
+  /**
+   * Add a duration in days.
+   * @param {number} days
+   * @returns {JulianDate}
+   * @deprecated Use `add()` instead.
+   */
+  addDays(days) {
+    if (!Number.isFinite(days)) throw new Error('days must be finite');
+    return new JulianDate(this._value + days);
+  }
+
+  /**
+   * Signed difference `self − other` as a Quantity in Days.
+   * @param {JulianDate} other
+   * @returns {Quantity}
+   */
+  difference(other) {
+    return new Quantity(this._value - other._value, 'Day');
+  }
+
+  /** Human-readable representation. */
+  format() {
+    return `Julian Day: ${this._value} d`;
+  }
+}
+
+// Deferred module reference for breaking circular import
+let _mjdModule = null;
+function require_mjd() {
+  if (!_mjdModule) {
+    // By the time toMjd() is called both modules are fully loaded,
+    // so the circular reference is already resolved.
+    _mjdModule = { ModifiedJulianDate: null };
+    import('./ModifiedJulianDate.js').then(m => { _mjdModule.ModifiedJulianDate = m.ModifiedJulianDate; });
+  }
+  return _mjdModule;
+}
+
+// Eagerly resolve the deferred import (runs after this module's body)
+import('./ModifiedJulianDate.js').then(m => {
+  _mjdModule = { ModifiedJulianDate: m.ModifiedJulianDate };
+});
+
+/**
+ * Convert a duration argument to days (number).
+ * @param {Quantity | number} d
+ * @returns {number}
+ */
+function _toDays(d) {
+  if (typeof d === 'number') {
+    if (!Number.isFinite(d)) throw new Error('Duration must be finite');
+    return d;
+  }
+  if (d && typeof d.value === 'number' && typeof d.unit === 'string') {
+    if (d.dimension !== 'Time') {
+      throw new Error(`Expected a time Quantity, got ${d.dimension}`);
+    }
+    return convert(d.value, d.unit, 'Day');
+  }
+  throw new Error('Expected a Quantity or number');
+}

package/tempoch-js/tempoch-web/lib/ModifiedJulianDate.js

@@ -0,0 +1,145 @@
+/**
+ * @siderust/tempoch-web — ModifiedJulianDate façade class (ESM/browser).
+ *
+ * @module @siderust/tempoch-web/lib/ModifiedJulianDate
+ */
+
+import { Quantity, convert } from '@siderust/qtty-web';
+import * as backend from './backend.js';
+
+export class ModifiedJulianDate {
+  /**
+   * Create a Modified Julian Date from a raw scalar.
+   * @param {number} value
+   */
+  constructor(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new Error('MJD value must be finite (not NaN or ±infinity)');
+    }
+    this._value = value;
+  }
+
+  /**
+   * Create a Modified Julian Date from a JavaScript `Date` object.
+   * @param {Date} date
+   * @returns {ModifiedJulianDate}
+   */
+  static fromDate(date) {
+    return new ModifiedJulianDate(backend.mjdFromDate(date));
+  }
+
+  /**
+   * Create a Modified Julian Date from explicit UTC components.
+   * @param {number} year
+   * @param {number} month
+   * @param {number} day
+   * @param {number} hour
+   * @param {number} minute
+   * @param {number} second
+   * @returns {ModifiedJulianDate}
+   */
+  static fromUtc(year, month, day, hour, minute, second) {
+    return new ModifiedJulianDate(backend.mjdFromUtc(year, month, day, hour, minute, second));
+  }
+
+  /** Raw MJD value. */
+  get value() {
+    return this._value;
+  }
+
+  /** The MJD value as a `Quantity` in Days. */
+  get days() {
+    return new Quantity(this._value, 'Day');
+  }
+
+  /**
+   * Convert to a `JulianDate`.
+   * @returns {import('./JulianDate.js').JulianDate}
+   */
+  toJd() {
+    const { JulianDate } = require_jd();
+    return new JulianDate(backend.mjdToJd(this._value));
+  }
+
+  /** Convert to a JavaScript `Date` (UTC). */
+  toDate() {
+    return backend.mjdToDate(this._value);
+  }
+
+  /**
+   * Add a time duration (Quantity or number of days).
+   * @param {Quantity | number} duration
+   * @returns {ModifiedJulianDate}
+   */
+  add(duration) {
+    return new ModifiedJulianDate(this._value + _toDays(duration));
+  }
+
+  /**
+   * Subtract a time duration.
+   * @param {Quantity | number} duration
+   * @returns {ModifiedJulianDate}
+   */
+  sub(duration) {
+    return new ModifiedJulianDate(this._value - _toDays(duration));
+  }
+
+  /**
+   * Add a duration in days.
+   * @param {number} days
+   * @returns {ModifiedJulianDate}
+   * @deprecated Use `add()` instead.
+   */
+  addDays(days) {
+    if (!Number.isFinite(days)) throw new Error('days must be finite');
+    return new ModifiedJulianDate(this._value + days);
+  }
+
+  /**
+   * Signed difference `self − other` as a Quantity in Days.
+   * @param {ModifiedJulianDate} other
+   * @returns {Quantity}
+   */
+  difference(other) {
+    return new Quantity(this._value - other._value, 'Day');
+  }
+
+  /** Human-readable representation. */
+  format() {
+    return `MJD ${this._value} d`;
+  }
+}
+
+// Deferred module reference for breaking circular import
+let _jdModule = null;
+function require_jd() {
+  if (!_jdModule) {
+    _jdModule = { JulianDate: null };
+    import('./JulianDate.js').then(m => { _jdModule.JulianDate = m.JulianDate; });
+  }
+  return _jdModule;
+}
+
+// Eagerly resolve the deferred import
+import('./JulianDate.js').then(m => {
+  _jdModule = { JulianDate: m.JulianDate };
+});
+
+/**
+ * Convert a duration argument to days (number).
+ * @param {Quantity | number} d
+ * @returns {number}
+ */
+function _toDays(d) {
+  if (typeof d === 'number') {
+    if (!Number.isFinite(d)) throw new Error('Duration must be finite');
+    return d;
+  }
+  if (d && typeof d.value === 'number' && typeof d.unit === 'string') {
+    if (d.dimension !== 'Time') {
+      throw new Error(`Expected a time Quantity, got ${d.dimension}`);
+    }
+    return convert(d.value, d.unit, 'Day');
+  }
+  throw new Error('Expected a Quantity or number');
+}

package/tempoch-js/tempoch-web/lib/Period.js

@@ -0,0 +1,121 @@
+/**
+ * @siderust/tempoch-web — Period façade class (ESM/browser).
+ *
+ * @module @siderust/tempoch-web/lib/Period
+ */
+
+import { Quantity } from '@siderust/qtty-web';
+import { ModifiedJulianDate } from './ModifiedJulianDate.js';
+import * as backend from './backend.js';
+
+export class Period {
+  /**
+   * Create a period from two `ModifiedJulianDate` objects or raw MJD numbers.
+   * @param {ModifiedJulianDate | number} start
+   * @param {ModifiedJulianDate | number} end
+   */
+  constructor(start, end) {
+    const startVal = typeof start === 'number' ? start : start._value;
+    const endVal = typeof end === 'number' ? end : end._value;
+
+    if (!Number.isFinite(startVal) || !Number.isFinite(endVal)) {
+      throw new Error('Period endpoints must be finite');
+    }
+    if (startVal > endVal) {
+      throw new Error('Period start must not be after end');
+    }
+    this._startMjd = startVal;
+    this._endMjd = endVal;
+  }
+
+  /**
+   * Create a period from two JavaScript `Date` objects.
+   * @param {Date} start
+   * @param {Date} end
+   * @returns {Period}
+   */
+  static fromDates(start, end) {
+    const startMjd = backend.mjdFromDate(start);
+    const endMjd = backend.mjdFromDate(end);
+    if (startMjd > endMjd) {
+      throw new Error('Period start must not be after end');
+    }
+    return new Period(startMjd, endMjd);
+  }
+
+  /** Start of the period as a raw MJD value. */
+  get startMjd() {
+    return this._startMjd;
+  }
+
+  /** End of the period as a raw MJD value. */
+  get endMjd() {
+    return this._endMjd;
+  }
+
+  /** Start as a `ModifiedJulianDate` object. */
+  get start() {
+    return new ModifiedJulianDate(this._startMjd);
+  }
+
+  /** End as a `ModifiedJulianDate` object. */
+  get end() {
+    return new ModifiedJulianDate(this._endMjd);
+  }
+
+  /**
+   * Duration of the period as a `Quantity` in Days.
+   * @returns {Quantity}
+   */
+  duration() {
+    return new Quantity(this._endMjd - this._startMjd, 'Day');
+  }
+
+  /**
+   * Duration of the period in days (raw number).
+   * @returns {number}
+   */
+  durationDays() {
+    return this._endMjd - this._startMjd;
+  }
+
+  /**
+   * Return the overlapping sub-period, or `null` if they do not overlap.
+   * @param {Period} other
+   * @returns {Period | null}
+   */
+  intersection(other) {
+    const s = Math.max(this._startMjd, other._startMjd);
+    const e = Math.min(this._endMjd, other._endMjd);
+    if (s >= e) return null;
+    return new Period(s, e);
+  }
+
+  /**
+   * Return `true` if the value falls inside `[start, end)`.
+   * @param {number | ModifiedJulianDate} mjd
+   * @returns {boolean}
+   */
+  contains(mjd) {
+    const val = typeof mjd === 'number' ? mjd : mjd._value;
+    return val >= this._startMjd && val < this._endMjd;
+  }
+
+  /**
+   * Return start and end as millisecond timestamps.
+   * @returns {{ startMs: number, endMs: number }}
+   */
+  toUtc() {
+    const startDate = backend.mjdToDate(this._startMjd);
+    const endDate = backend.mjdToDate(this._endMjd);
+    return {
+      startMs: startDate.getTime(),
+      endMs: endDate.getTime(),
+    };
+  }
+
+  /** Human-readable representation. */
+  format() {
+    return `Period(MJD ${this._startMjd.toFixed(6)} to MJD ${this._endMjd.toFixed(6)})`;
+  }
+}

package/tempoch-js/tempoch-web/lib/backend.js

@@ -0,0 +1,118 @@
+/**
+ * @siderust/tempoch-web — Internal WASM backend abstraction.
+ *
+ * Loads the wasm-bindgen generated module and re-exports the primitive
+ * free functions that the shared JS façade classes need.
+ *
+ * @module @siderust/tempoch-web/lib/backend
+ * @private
+ */
+
+let wasm = null;
+
+/**
+ * Initialise the WASM module. Must be called before any other function.
+ * @param {RequestInfo | URL | Response | BufferSource | WebAssembly.Module} [module_or_path]
+ */
+export async function init(module_or_path) {
+  const mod = await import('../pkg/tempoch_web.js');
+  await mod.default(module_or_path);
+  wasm = mod;
+}
+
+export function ensureInit() {
+  if (!wasm) {
+    throw new Error('@siderust/tempoch-web: call init() before using any function');
+  }
+}
+
+// ── JD / MJD conversion ────────────────────────────────────────────
+
+export function jdToMjd(jd) {
+  ensureInit();
+  return wasm.jdToMjd(jd);
+}
+
+export function mjdToJd(mjd) {
+  ensureInit();
+  return wasm.mjdToJd(mjd);
+}
+
+// ── Epoch-based quantities ─────────────────────────────────────────
+
+export function julianCenturies(jd) {
+  ensureInit();
+  return wasm.julianCenturies(jd);
+}
+
+export function julianYears(jd) {
+  ensureInit();
+  return wasm.julianYears(jd);
+}
+
+// ── Date ↔ JD/MJD ─────────────────────────────────────────────────
+// WASM can't access JS Date directly, so we pass millisecond
+// timestamps and wrap/unwrap in the JS layer.
+
+export function jdFromDate(date) {
+  ensureInit();
+  return wasm.jdFromMs(date.getTime());
+}
+
+export function mjdFromDate(date) {
+  ensureInit();
+  return wasm.mjdFromMs(date.getTime());
+}
+
+export function jdToDate(jd) {
+  ensureInit();
+  const ms = wasm.jdToMs(jd);
+  return new Date(ms);
+}
+
+export function mjdToDate(mjd) {
+  ensureInit();
+  const ms = wasm.mjdToMs(mjd);
+  return new Date(ms);
+}
+
+// ── UTC components → JD/MJD ───────────────────────────────────────
+
+export function jdFromUtc(year, month, day, hour, minute, second) {
+  ensureInit();
+  return wasm.jdFromUtc(year, month, day, hour, minute, second);
+}
+
+export function mjdFromUtc(year, month, day, hour, minute, second) {
+  ensureInit();
+  return wasm.mjdFromUtc(year, month, day, hour, minute, second);
+}
+
+// ── Arithmetic ────────────────────────────────────────────────────
+
+export function jdAddDays(jd, days) {
+  ensureInit();
+  return wasm.jdAddDays(jd, days);
+}
+
+export function mjdAddDays(mjd, days) {
+  ensureInit();
+  return wasm.mjdAddDays(mjd, days);
+}
+
+export function jdDifference(jd1, jd2) {
+  ensureInit();
+  return wasm.jdDifference(jd1, jd2);
+}
+
+export function mjdDifference(mjd1, mjd2) {
+  ensureInit();
+  return wasm.mjdDifference(mjd1, mjd2);
+}
+
+// ── Version ───────────────────────────────────────────────────────
+
+export function version() {
+  ensureInit();
+  return wasm.version();
+}