siderust-js 0.1.0

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

@@ -0,0 +1,176 @@
+/**
+ * @siderust/tempoch — JulianDate façade class.
+ *
+ * A Julian Date — continuous count of days from the Julian Period origin.
+ * This is a plain JS class that delegates computation to the native backend.
+ *
+ * @module @siderust/tempoch/lib/JulianDate
+ */
+
+'use strict';
+
+const { Quantity, convert, quantityDimension } = require('./qttyCompat.js');
+const backend = require('./backend.js');
+
+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) {
+    const raw = backend.jdFromDate(date);
+    return new JulianDate(raw);
+  }
+
+  /**
+   * 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) {
+    // Delegate to the native class for ΔT correction
+    const nativeJd = backend.NativeJulianDate.fromUtc(year, month, day, hour, minute, second);
+    return new JulianDate(nativeJd.value);
+  }
+
+  /**
+   * The J2000.0 epoch — JD 2 451 545.0.
+   * @returns {JulianDate}
+   */
+  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 require to break circular dependency
+    const { ModifiedJulianDate } = require('./ModifiedJulianDate.js');
+    return new ModifiedJulianDate(backend.jdToMjd(this._value));
+  }
+
+  /**
+   * Convert to a JavaScript `Date` (UTC).
+   * @returns {Date}
+   */
+  toDate() {
+    return backend.jdToDate(this._value);
+  }
+
+  /**
+   * Julian centuries since J2000.0 (T).
+   * @returns {Quantity} Quantity in JulianCentury
+   */
+  julianCenturies() {
+    return new Quantity(backend.julianCenturies(this._value), 'JulianCentury');
+  }
+
+  /**
+   * Julian years since J2000.0.
+   * @returns {Quantity} Quantity in JulianYear
+   */
+  julianYears() {
+    return new Quantity(backend.julianYears(this._value), 'JulianYear');
+  }
+
+  /**
+   * Add a time duration (Quantity or number of days).
+   * @param {Quantity | number} duration  A time `Quantity` or raw days
+   * @returns {JulianDate}
+   */
+  add(duration) {
+    const days = _toDays(duration);
+    return new JulianDate(this._value + days);
+  }
+
+  /**
+   * Subtract a time duration.
+   * @param {Quantity | number} duration  A time `Quantity` or raw days
+   * @returns {JulianDate}
+   */
+  sub(duration) {
+    const days = _toDays(duration);
+    return new JulianDate(this._value - days);
+  }
+
+  /**
+   * Add a duration in days, returning a new `JulianDate`.
+   * @param {number} days
+   * @returns {JulianDate}
+   * @deprecated Use `add(Days(n))` instead.
+   */
+  addDays(days) {
+    if (!Number.isFinite(days)) {
+      throw new Error('days must be finite');
+    }
+    return new JulianDate(this._value + days);
+  }
+
+  /**
+   * Signed difference `self − other` in days as a `Quantity`.
+   * @param {JulianDate} other
+   * @returns {Quantity} Quantity in Day
+   */
+  difference(other) {
+    return new Quantity(this._value - other._value, 'Day');
+  }
+
+  /**
+   * Human-readable representation.
+   * @returns {string}
+   */
+  format() {
+    return `Julian Day: ${this._value} d`;
+  }
+}
+
+/**
+ * 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') {
+    const dimension = quantityDimension(d);
+    if (dimension !== 'Time') {
+      throw new Error(`Expected a time Quantity, got ${dimension}`);
+    }
+    return convert(d.value, d.unit, 'Day');
+  }
+  throw new Error('Expected a Quantity or number');
+}
+
+module.exports = { JulianDate };

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

@@ -0,0 +1,156 @@
+/**
+ * @siderust/tempoch — ModifiedJulianDate façade class.
+ *
+ * A Modified Julian Date — `JD − 2 400 000.5`.
+ *
+ * @module @siderust/tempoch/lib/ModifiedJulianDate
+ */
+
+'use strict';
+
+const { Quantity, convert, quantityDimension } = require('./qttyCompat.js');
+const backend = require('./backend.js');
+
+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) {
+    const raw = backend.mjdFromDate(date);
+    return new ModifiedJulianDate(raw);
+  }
+
+  /**
+   * 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) {
+    const nativeMjd = backend.NativeModifiedJulianDate.fromUtc(
+      year,
+      month,
+      day,
+      hour,
+      minute,
+      second,
+    );
+    return new ModifiedJulianDate(nativeMjd.value);
+  }
+
+  /** 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('./JulianDate.js');
+    return new JulianDate(backend.mjdToJd(this._value));
+  }
+
+  /**
+   * Convert to a JavaScript `Date` (UTC).
+   * @returns {Date}
+   */
+  toDate() {
+    return backend.mjdToDate(this._value);
+  }
+
+  /**
+   * Add a time duration (Quantity or number of days).
+   * @param {Quantity | number} duration
+   * @returns {ModifiedJulianDate}
+   */
+  add(duration) {
+    const days = _toDays(duration);
+    return new ModifiedJulianDate(this._value + days);
+  }
+
+  /**
+   * Subtract a time duration.
+   * @param {Quantity | number} duration
+   * @returns {ModifiedJulianDate}
+   */
+  sub(duration) {
+    const days = _toDays(duration);
+    return new ModifiedJulianDate(this._value - days);
+  }
+
+  /**
+   * Add a duration in days, returning a new `ModifiedJulianDate`.
+   * @param {number} days
+   * @returns {ModifiedJulianDate}
+   * @deprecated Use `add(Days(n))` instead.
+   */
+  addDays(days) {
+    if (!Number.isFinite(days)) {
+      throw new Error('days must be finite');
+    }
+    return new ModifiedJulianDate(this._value + days);
+  }
+
+  /**
+   * Signed difference `self − other` in days as a `Quantity`.
+   * @param {ModifiedJulianDate} other
+   * @returns {Quantity} Quantity in Day
+   */
+  difference(other) {
+    return new Quantity(this._value - other._value, 'Day');
+  }
+
+  /**
+   * Human-readable representation.
+   * @returns {string}
+   */
+  format() {
+    return `MJD ${this._value} d`;
+  }
+}
+
+/**
+ * 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') {
+    const dimension = quantityDimension(d);
+    if (dimension !== 'Time') {
+      throw new Error(`Expected a time Quantity, got ${dimension}`);
+    }
+    return convert(d.value, d.unit, 'Day');
+  }
+  throw new Error('Expected a Quantity or number');
+}
+
+module.exports = { ModifiedJulianDate };

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

@@ -0,0 +1,133 @@
+/**
+ * @siderust/tempoch — Period façade class.
+ *
+ * A time period (interval) defined by two `ModifiedJulianDate` endpoints.
+ * Intervals are half-open `[start, end)`.
+ *
+ * @module @siderust/tempoch/lib/Period
+ */
+
+'use strict';
+
+const { Quantity } = require('./qttyCompat.js');
+const { ModifiedJulianDate } = require('./ModifiedJulianDate.js');
+const backend = require('./backend.js');
+
+class Period {
+  /**
+   * Create a period from two `ModifiedJulianDate` objects.
+   *
+   * @param {ModifiedJulianDate} start
+   * @param {ModifiedJulianDate} end
+   */
+  constructor(start, end) {
+    // Accept either ModifiedJulianDate objects or raw numbers (backward compat).
+    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 MJD 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.
+   * @returns {string}
+   */
+  format() {
+    return `Period(MJD ${this._startMjd.toFixed(6)} to MJD ${this._endMjd.toFixed(6)})`;
+  }
+}
+
+module.exports = { Period };

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

@@ -0,0 +1,38 @@
+/**
+ * @siderust/tempoch — Internal native backend abstraction.
+ *
+ * Loads the NAPI-RS addon and re-exports only the primitive-level helpers
+ * that the JS façade classes need.  Consumer code should never import this
+ * module directly.
+ *
+ * @module @siderust/tempoch/lib/backend
+ * @private
+ */
+
+'use strict';
+
+const native = require('../native.cjs');
+
+// The native classes are used internally for operations that are cheaper
+// to do in Rust (e.g. fromUtc with ΔT correction, Date↔JD/MJD conversion).
+// The JS façade wraps the results.
+
+module.exports = {
+  // Native classes — used internally, never exposed directly
+  NativeJulianDate: native.JulianDate,
+  NativeModifiedJulianDate: native.ModifiedJulianDate,
+  NativePeriod: native.Period,
+
+  // Free functions
+  jdToMjd: native.jdToMjd,
+  mjdToJd: native.mjdToJd,
+  julianCenturies: native.julianCenturies,
+  julianYears: native.julianYears,
+  jdFromDate: native.jdFromDate,
+  mjdFromDate: native.mjdFromDate,
+  jdToDate: native.jdToDate,
+  mjdToDate: native.mjdToDate,
+  jdDifference: native.jdDifference,
+  mjdDifference: native.mjdDifference,
+  version: native.version,
+};

package/tempoch-js/tempoch-node/lib/qttyCompat.js

@@ -0,0 +1,92 @@
+'use strict';
+
+function loadExternalQtty() {
+  try {
+    return require('@siderust/qtty');
+  } catch {
+    try {
+      return require('qtty-js/qtty-node');
+    } catch {
+      return null;
+    }
+  }
+}
+
+const externalQtty = loadExternalQtty();
+
+const TIME_UNITS_IN_DAYS = {
+  Millisecond: 1 / 86_400_000,
+  Second: 1 / 86_400,
+  Minute: 1 / 1_440,
+  Hour: 1 / 24,
+  Day: 1,
+  Week: 7,
+  JulianYear: 365.25,
+  JulianCentury: 36_525,
+};
+
+class Quantity {
+  constructor(value, unit) {
+    if (!Number.isFinite(value)) {
+      throw new Error('Quantity value must be finite');
+    }
+    if (!(unit in TIME_UNITS_IN_DAYS)) {
+      throw new Error(`Unsupported time unit: ${unit}`);
+    }
+    this._value = value;
+    this._unit = unit;
+  }
+
+  get value() {
+    return this._value;
+  }
+
+  get unit() {
+    return this._unit;
+  }
+
+  get dimension() {
+    return 'Time';
+  }
+
+  to(unit) {
+    return new Quantity(convert(this._value, this._unit, unit), unit);
+  }
+
+  toString() {
+    return `${this._value} ${this._unit}`;
+  }
+}
+
+function convert(value, fromUnit, toUnit) {
+  if (!Number.isFinite(value)) {
+    throw new Error('Quantity value must be finite');
+  }
+  if (!(fromUnit in TIME_UNITS_IN_DAYS)) {
+    throw new Error(`Unsupported time unit: ${fromUnit}`);
+  }
+  if (!(toUnit in TIME_UNITS_IN_DAYS)) {
+    throw new Error(`Unsupported time unit: ${toUnit}`);
+  }
+
+  const days = value * TIME_UNITS_IN_DAYS[fromUnit];
+  return days / TIME_UNITS_IN_DAYS[toUnit];
+}
+
+function quantityDimension(quantity) {
+  if (typeof quantity?.dimension === 'string') {
+    return quantity.dimension;
+  }
+
+  if (typeof quantity?.unit === 'string' && quantity.unit in TIME_UNITS_IN_DAYS) {
+    return 'Time';
+  }
+
+  return undefined;
+}
+
+module.exports = {
+  Quantity: externalQtty?.Quantity ?? Quantity,
+  convert: externalQtty?.convert ?? convert,
+  quantityDimension,
+};