siderust-js 0.1.0

package/siderust-node/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "siderust-node"
+version = "0.1.0"
+edition = "2021"
+authors = ["VPRamon <vallespuigramon@gmail.com>"]
+license = "AGPL-3.0"
+repository = "https://github.com/Siderust/siderust"
+description = "Node.js native bindings for siderust — high-precision astronomy and satellite mechanics"
+readme = "README.md"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+siderust = { version = "0.6.0", features = [] }
+siderust-binding-core = { path = "../siderust-core" }
+qtty     = "0.4.1"
+tempoch  = "0.4"
+affn     = { version = "0.4.1", features = ["astro"] }
+chrono   = "0.4.44"
+napi     = { version = "2", features = ["napi6"] }
+napi-derive = "2"
+
+[build-dependencies]
+napi-build = "2"
+
+[profile.release]
+lto = true
+strip = "symbols"

package/siderust-node/README.md

@@ -0,0 +1,109 @@
+# `@siderust/siderust`
+
+High-precision astronomy for Node.js with a strict typed boundary.
+
+Time inputs use `@siderust/tempoch`. Physical quantities use
+`@siderust/qtty`. Raw numbers are no longer accepted for domain values such
+as epochs, angles, lengths, or observer/star properties.
+
+## Install
+
+```bash
+npm install @siderust/siderust @siderust/qtty @siderust/tempoch
+```
+
+## Example
+
+```js
+const { Quantity } = require('@siderust/qtty');
+const { JulianDate, ModifiedJulianDate, Period } = require('@siderust/tempoch');
+const {
+  Observer,
+  bodyAltitudeAt,
+  bodyCrossings,
+  moonPhase,
+  vsop87Heliocentric,
+} = require('@siderust/siderust');
+
+const DEG = (value) => new Quantity(value, 'Degree');
+const M = (value) => new Quantity(value, 'Meter');
+
+const observer = new Observer(DEG(-17.8925), DEG(28.7543), M(2396));
+const jd = new JulianDate(2_451_545.0);
+const mjd = new ModifiedJulianDate(60_000.0);
+const window = new Period(mjd, new ModifiedJulianDate(60_001.0));
+
+const sunAltitude = bodyAltitudeAt('Sun', observer, mjd);
+const sunCrossings = bodyCrossings('Sun', observer, window, DEG(0));
+const moon = moonPhase(jd);
+const mars = vsop87Heliocentric('Mars', jd);
+
+console.log(sunAltitude.toString());
+console.log(sunCrossings[0].mjd.value);
+console.log(moon.phaseAngle.toString());
+console.log(mars.x.toString());
+```
+
+## Public API
+
+### Domain classes
+
+- `new Observer(lon, lat, height)`
+  `lon` / `lat` must be angle `Quantity` values and `height` must be a length `Quantity`.
+- `new Star(name, distance, mass, radius, luminosity, ra, dec)`
+  Every physical field must be a `Quantity`.
+
+### Time-aware functions
+
+- Any `jd` parameter requires a `JulianDate`.
+- Any instantaneous `mjd` parameter requires a `ModifiedJulianDate`.
+- Search windows use `Period`.
+
+### Typed outputs
+
+- Angular results return `Quantity` values in degrees.
+- Cartesian positions return `Quantity` coordinates in their documented units.
+- Event timestamps return `ModifiedJulianDate`.
+- Interval results return `Period[]`.
+
+## Main exports
+
+- `transformDirection(polar, azimuth, srcFrame, dstFrame, jd)`
+- `directionToHorizontal(polar, azimuth, srcFrame, jd, observer)`
+- `geodeticToEcef(observer)`
+- `angularSeparation(...)`
+- `cartesianDistance(...)`
+- `cartesianMagnitude(...)`
+- `directionToCartesian(polar, azimuth)`
+- `vsop87Heliocentric(body, jd)`
+- `vsop87Barycentric(body, jd)`
+- `vsop87SunBarycentric(jd)`
+- `vsop87EarthBarycentric(jd)`
+- `vsop87EarthHeliocentric(jd)`
+- `vsop87MoonGeocentric(jd)`
+- `transformPositionCenter(x, y, z, srcCenter, dstCenter, jd)`
+- `transformPositionFrame(x, y, z, srcFrame, dstFrame, jd)`
+- `orbitalPeriod(name)`
+- `bodyAltitudeAt(body, observer, mjd)`
+- `bodyAzimuthAt(body, observer, mjd)`
+- `bodyCrossings(body, observer, window, threshold)`
+- `bodyCulminations(body, observer, window)`
+- `bodyAboveThreshold(body, observer, window, threshold)`
+- `bodyBelowThreshold(body, observer, window, threshold)`
+- `bodyAzimuthCrossings(body, observer, window, bearing)`
+- `bodyAzimuthExtrema(body, observer, window)`
+- `starAltitudeAt(star, observer, mjd)`
+- `starAzimuthAt(star, observer, mjd)`
+- `starCrossings(star, observer, window, threshold)`
+- `starCulminations(star, observer, window)`
+- `starAboveThreshold(star, observer, window, threshold)`
+- `starBelowThreshold(star, observer, window, threshold)`
+- `starAzimuthCrossings(star, observer, window, bearing)`
+- `starAzimuthExtrema(star, observer, window)`
+- `intersectPeriods(periods1, periods2)`
+- `moonPhase(jd)`
+- `moonPhaseTopocentric(jd, observer)`
+- `findPhaseEvents(window)`
+- `moonIlluminationAbove(window, kMin)`
+- `moonIlluminationBelow(window, kMax)`
+- `moonIlluminationRange(window, kMin, kMax)`

package/siderust-node/__test__/index.test.mjs

@@ -0,0 +1,248 @@
+// @ts-check
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { Quantity } from '@siderust/qtty';
+import { JulianDate, ModifiedJulianDate, Period } from '@siderust/tempoch';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+const {
+  Observer,
+  Star,
+  angularSeparation,
+  bodyAltitudeAt,
+  bodyCrossings,
+  bodyCulminations,
+  directionToCartesian,
+  directionToHorizontal,
+  findPhaseEvents,
+  geodeticToEcef,
+  getPlanet,
+  intersectPeriods,
+  moonIlluminationAbove,
+  moonPhase,
+  orbitalPeriod,
+  starAltitudeAt,
+  transformDirection,
+  transformPositionCenter,
+  version,
+  vsop87Heliocentric,
+  vsop87MoonGeocentric,
+} = require(join(__dirname, '..'));
+
+const DEG = (value) => new Quantity(value, 'Degree');
+const M = (value) => new Quantity(value, 'Meter');
+const AU = (value) => new Quantity(value, 'AstronomicalUnit');
+const LY = (value) => new Quantity(value, 'LightYear');
+const SOLAR_MASS = (value) => new Quantity(value, 'SolarMass');
+const SOLAR_RADIUS = (value) => new Quantity(value, 'NominalSolarRadius');
+const SOLAR_LUMINOSITY = (value) => new Quantity(value, 'SolarLuminosity');
+
+const J2000 = new JulianDate(2_451_545.0);
+const MJD_60000 = new ModifiedJulianDate(60_000.0);
+const WINDOW = new Period(new ModifiedJulianDate(60_000.0), new ModifiedJulianDate(60_002.0));
+
+describe('version()', () => {
+  it('returns a semver-like string', () => {
+    assert.match(version(), /^\d+\.\d+\.\d+/);
+  });
+});
+
+describe('Observer', () => {
+  it('requires Quantity inputs and exposes typed getters', () => {
+    const observer = new Observer(DEG(-17.8925), DEG(28.7543), M(2396));
+    assert.equal(observer.lon.unit, 'Degree');
+    assert.equal(observer.lat.unit, 'Degree');
+    assert.equal(observer.height.unit, 'Meter');
+    assert.match(observer.format(), /Observer/);
+  });
+
+  it('rejects raw numbers', () => {
+    assert.throws(() => new Observer(-17.8925, 28.7543, 2396), /expected a Quantity/);
+  });
+});
+
+describe('Star', () => {
+  it('requires Quantity inputs and exposes typed getters', () => {
+    const star = new Star(
+      'TypedStar',
+      LY(100),
+      SOLAR_MASS(2),
+      SOLAR_RADIUS(1.5),
+      SOLAR_LUMINOSITY(8),
+      DEG(180),
+      DEG(-45),
+    );
+
+    assert.equal(star.distance.unit, 'LightYear');
+    assert.equal(star.mass.unit, 'SolarMass');
+    assert.equal(star.ra.unit, 'Degree');
+    assert.match(star.format(), /TypedStar/);
+  });
+
+  it('rejects raw numbers', () => {
+    assert.throws(() => new Star('Broken', 1, 1, 1, 1, 1, 1), /expected a Quantity/);
+  });
+});
+
+describe('typed outputs', () => {
+  it('returns typed planet metadata', () => {
+    const mars = getPlanet('Mars');
+    assert.equal(mars.mass.unit, 'Kilogram');
+    assert.equal(mars.radius.unit, 'Kilometer');
+    assert.equal(mars.semiMajorAxis.unit, 'AstronomicalUnit');
+    assert.equal(typeof mars.eccentricity, 'number');
+    assert.equal(mars.inclination.unit, 'Degree');
+  });
+
+  it('returns typed geodetic coordinates', () => {
+    const ecef = geodeticToEcef(Observer.roqueDeLasMuchachos());
+    assert.equal(ecef.x.unit, 'Meter');
+    assert.equal(ecef.y.unit, 'Meter');
+    assert.equal(ecef.z.unit, 'Meter');
+  });
+
+  it('returns typed ephemeris positions', () => {
+    const mars = vsop87Heliocentric('Mars', J2000);
+    const moon = vsop87MoonGeocentric(J2000);
+    assert.equal(mars.x.unit, 'AstronomicalUnit');
+    assert.equal(moon.x.unit, 'Kilometer');
+    assert.equal(mars.frame, 'EclipticMeanJ2000');
+  });
+
+  it('preserves input length units in center transforms', () => {
+    const transformed = transformPositionCenter(
+      AU(1),
+      AU(0),
+      AU(0),
+      'Heliocentric',
+      'Geocentric',
+      J2000,
+    );
+
+    assert.equal(transformed.x.unit, 'AstronomicalUnit');
+    assert.equal(transformed.y.unit, 'AstronomicalUnit');
+    assert.equal(transformed.z.unit, 'AstronomicalUnit');
+  });
+
+  it('returns typed direction values', () => {
+    const direction = transformDirection(
+      DEG(38.78),
+      DEG(279.23),
+      'EquatorialMeanJ2000',
+      'EclipticMeanJ2000',
+      J2000,
+    );
+
+    const horizontal = directionToHorizontal(
+      DEG(38.78),
+      DEG(279.23),
+      'ICRS',
+      J2000,
+      Observer.roqueDeLasMuchachos(),
+    );
+
+    assert.equal(direction.polar.unit, 'Degree');
+    assert.equal(direction.azimuth.unit, 'Degree');
+    assert.equal(horizontal.polar.unit, 'Degree');
+    assert.equal(horizontal.azimuth.unit, 'Degree');
+  });
+
+  it('returns typed scalar astronomy values', () => {
+    const separation = angularSeparation(DEG(10), DEG(20), DEG(11), DEG(21), 'ICRS');
+    const period = orbitalPeriod('Mars');
+    const unitVector = directionToCartesian(DEG(45), DEG(90));
+
+    assert.equal(separation.unit, 'Degree');
+    assert.equal(period.unit, 'Day');
+    assert.equal(typeof unitVector.x, 'number');
+    assert.equal(typeof unitVector.y, 'number');
+    assert.equal(typeof unitVector.z, 'number');
+  });
+});
+
+describe('event APIs', () => {
+  it('return typed instantaneous quantities', () => {
+    const observer = Observer.roqueDeLasMuchachos();
+    const star = Star.catalog('Vega');
+
+    const bodyAltitude = bodyAltitudeAt('Sun', observer, MJD_60000);
+    const stellarAltitude = starAltitudeAt(star, observer, MJD_60000);
+
+    assert.equal(bodyAltitude.unit, 'Degree');
+    assert.equal(stellarAltitude.unit, 'Degree');
+  });
+
+  it('return typed event timestamps and periods', () => {
+    const observer = Observer.roqueDeLasMuchachos();
+
+    const crossings = bodyCrossings('Sun', observer, WINDOW, DEG(0));
+    const culminations = bodyCulminations('Sun', observer, WINDOW);
+    const darkMoon = moonIlluminationAbove(WINDOW, 0.5);
+    const phaseEvents = findPhaseEvents(WINDOW);
+
+    for (const event of crossings) {
+      assert.ok(event.mjd instanceof ModifiedJulianDate);
+    }
+    for (const event of culminations) {
+      assert.ok(event.mjd instanceof ModifiedJulianDate);
+      assert.equal(event.altitude.unit, 'Degree');
+    }
+    for (const period of darkMoon) {
+      assert.ok(period instanceof Period);
+    }
+    for (const event of phaseEvents) {
+      assert.ok(event.mjd instanceof ModifiedJulianDate);
+    }
+  });
+
+  it('intersects typed periods', () => {
+    const periods = intersectPeriods(
+      [new Period(new ModifiedJulianDate(60_000.0), new ModifiedJulianDate(60_001.0))],
+      [new Period(new ModifiedJulianDate(60_000.5), new ModifiedJulianDate(60_001.5))],
+    );
+
+    assert.equal(periods.length, 1);
+    assert.ok(periods[0] instanceof Period);
+    assert.equal(periods[0].start.value, 60_000.5);
+  });
+});
+
+describe('moonPhase()', () => {
+  it('returns typed angular values', () => {
+    const phase = moonPhase(J2000);
+    assert.equal(phase.phaseAngle.unit, 'Degree');
+    assert.equal(phase.elongation.unit, 'Degree');
+    assert.equal(typeof phase.illuminatedFraction, 'number');
+  });
+});
+
+describe('strict boundary validation', () => {
+  it('rejects raw numbers for time and angle inputs', () => {
+    const observer = Observer.roqueDeLasMuchachos();
+
+    assert.throws(() => vsop87Heliocentric('Mars', 2_451_545.0), /Expected a JulianDate/);
+    assert.throws(() => bodyAltitudeAt('Sun', observer, 60_000.0), /Expected a ModifiedJulianDate/);
+    assert.throws(() => bodyCrossings('Sun', observer, MJD_60000, DEG(0)), /Expected a Period/);
+    assert.throws(
+      () => transformDirection(38.78, DEG(279.23), 'ICRS', 'ICRS', J2000),
+      /expected a Quantity/,
+    );
+  });
+
+  it('rejects structural impostors', () => {
+    assert.throws(
+      () => new Observer({ value: 1, unit: 'Degree' }, DEG(0), M(0)),
+      /expected a Quantity/,
+    );
+    assert.throws(
+      () => bodyAltitudeAt('Sun', Observer.roqueDeLasMuchachos(), { value: 60_000 }),
+      /Expected a ModifiedJulianDate/,
+    );
+  });
+});

package/siderust-node/build.rs

@@ -0,0 +1,5 @@
+extern crate napi_build;
+
+fn main() {
+    napi_build::setup();
+}

package/siderust-node/c8.config.json

@@ -0,0 +1,3 @@
+{
+  "reporter": ["text-summary", "lcov", "cobertura", "html"]
+}

package/siderust-node/eslint.config.js

@@ -0,0 +1,31 @@
+const js = require('@eslint/js');
+const globals = require('globals');
+
+const baseRules = {
+  ...js.configs.recommended.rules,
+  'no-console': 'off',
+};
+
+module.exports = [
+  {
+    ignores: ['coverage/**', 'node_modules/**', 'target/**', '*.d.ts', '*.node', 'index.js'],
+  },
+  {
+    files: ['**/*.js'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'commonjs',
+      globals: globals.node,
+    },
+    rules: baseRules,
+  },
+  {
+    files: ['**/*.mjs'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: globals.node,
+    },
+    rules: baseRules,
+  },
+];

package/siderust-node/examples/01_basic_coordinates.mjs

@@ -0,0 +1,24 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { Quantity } from '@siderust/qtty';
+import { JulianDate } from '@siderust/tempoch';
+
+const require = createRequire(import.meta.url);
+const { Observer, directionToCartesian, geodeticToEcef, transformDirection } = require(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+);
+
+const DEG = (value) => new Quantity(value, 'Degree');
+const jd = new JulianDate(2_451_545.0);
+const observer = new Observer(DEG(-17.8925), DEG(28.7543), new Quantity(2396, 'Meter'));
+
+console.log('Observer:', observer.format());
+console.log('ECEF:', geodeticToEcef(observer));
+
+const vega = transformDirection(DEG(38.7837), DEG(279.2347), 'ICRS', 'EclipticMeanJ2000', jd);
+console.log('Vega in ecliptic coordinates:', vega);
+
+const unitVector = directionToCartesian(DEG(38.7837), DEG(279.2347));
+console.log('Unit vector:', unitVector);

package/siderust-node/examples/02_coordinate_transformations.mjs

@@ -0,0 +1,25 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { Quantity } from '@siderust/qtty';
+import { JulianDate } from '@siderust/tempoch';
+
+const require = createRequire(import.meta.url);
+const { transformPositionCenter, transformPositionFrame, vsop87Heliocentric } = require(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+);
+
+const jd = new JulianDate(2_451_545.0);
+const mars = vsop87Heliocentric('Mars', jd);
+
+console.log('Mars heliocentric position:', mars);
+console.log(
+  'Mars geocentric position:',
+  transformPositionCenter(mars.x, mars.y, mars.z, 'Heliocentric', 'Geocentric', jd),
+);
+console.log(
+  'Mars equatorial position:',
+  transformPositionFrame(mars.x, mars.y, mars.z, 'EclipticMeanJ2000', 'EquatorialMeanJ2000', jd),
+);
+console.log('Reference length unit:', new Quantity(1, mars.x.unit).toString());

package/siderust-node/examples/03_all_frames_conversions.mjs

@@ -0,0 +1,26 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { Quantity } from '@siderust/qtty';
+import { JulianDate } from '@siderust/tempoch';
+
+const require = createRequire(import.meta.url);
+const { transformDirection } = require(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+);
+
+const DEG = (value) => new Quantity(value, 'Degree');
+const jd = new JulianDate(2_451_545.0);
+const frames = [
+  'ICRS',
+  'EclipticMeanJ2000',
+  'EquatorialMeanJ2000',
+  'EquatorialMeanOfDate',
+  'EquatorialTrueOfDate',
+];
+
+for (const frame of frames) {
+  const result = transformDirection(DEG(38.7837), DEG(279.2347), 'ICRS', frame, jd);
+  console.log(frame, result);
+}

package/siderust-node/examples/04_all_center_conversions.mjs

@@ -0,0 +1,24 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { JulianDate } from '@siderust/tempoch';
+
+const require = createRequire(import.meta.url);
+const { transformPositionCenter, vsop87Barycentric, vsop87EarthBarycentric } = require(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+);
+
+const jd = new JulianDate(2_451_545.0);
+const mars = vsop87Barycentric('Mars', jd);
+const earth = vsop87EarthBarycentric(jd);
+
+console.log('Mars barycentric:', mars);
+console.log(
+  'Mars geocentric:',
+  transformPositionCenter(mars.x, mars.y, mars.z, 'Barycentric', 'Geocentric', jd),
+);
+console.log(
+  'Earth heliocentric:',
+  transformPositionCenter(earth.x, earth.y, earth.z, 'Barycentric', 'Heliocentric', jd),
+);

package/siderust-node/examples/05_target_tracking.mjs

@@ -0,0 +1,22 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { Quantity } from '@siderust/qtty';
+import { JulianDate } from '@siderust/tempoch';
+
+const require = createRequire(import.meta.url);
+const { transformDirection, vsop87Heliocentric } = require(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+);
+
+const DEG = (value) => new Quantity(value, 'Degree');
+const jd0 = new JulianDate(2_451_545.0);
+const jd1 = new JulianDate(2_451_545.5);
+
+console.log('Mars at J2000:', vsop87Heliocentric('Mars', jd0));
+console.log('Mars 12h later:', vsop87Heliocentric('Mars', jd1));
+console.log(
+  'Vega of-date direction at J2000+12h:',
+  transformDirection(DEG(38.7837), DEG(279.2347), 'ICRS', 'EquatorialTrueOfDate', jd1),
+);

package/siderust-node/examples/06_night_events.mjs

@@ -0,0 +1,18 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { Quantity } from '@siderust/qtty';
+import { ModifiedJulianDate, Period } from '@siderust/tempoch';
+
+const require = createRequire(import.meta.url);
+const { Observer, bodyBelowThreshold, bodyCrossings } = require(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+);
+
+const DEG = (value) => new Quantity(value, 'Degree');
+const observer = new Observer(DEG(0), DEG(51.4769), new Quantity(0, 'Meter'));
+const week = new Period(new ModifiedJulianDate(60_000.0), new ModifiedJulianDate(60_007.0));
+
+console.log('Sunset/sunrise events:', bodyCrossings('Sun', observer, week, DEG(0)));
+console.log('Astronomical night periods:', bodyBelowThreshold('Sun', observer, week, DEG(-18)));

package/siderust-node/examples/07_moon_properties.mjs

@@ -0,0 +1,21 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { Quantity } from '@siderust/qtty';
+import { JulianDate } from '@siderust/tempoch';
+
+const require = createRequire(import.meta.url);
+const { Observer, moonPhase, moonPhaseTopocentric } = require(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+);
+
+const observer = new Observer(
+  new Quantity(-17.8925, 'Degree'),
+  new Quantity(28.7543, 'Degree'),
+  new Quantity(2396, 'Meter'),
+);
+const jd = new JulianDate(2_451_545.0);
+
+console.log('Geocentric moon phase:', moonPhase(jd));
+console.log('Topocentric moon phase:', moonPhaseTopocentric(jd, observer));

package/siderust-node/examples/08_solar_system.mjs

@@ -0,0 +1,19 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { JulianDate } from '@siderust/tempoch';
+
+const require = createRequire(import.meta.url);
+const { getPlanet, orbitalPeriod, vsop87Heliocentric } = require(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+);
+
+const jd = new JulianDate(2_451_545.0);
+for (const body of ['Mercury', 'Venus', 'Earth', 'Mars']) {
+  console.log(body, {
+    info: getPlanet(body),
+    period: orbitalPeriod(body),
+    position: vsop87Heliocentric(body, jd),
+  });
+}

package/siderust-node/examples/09_star_observability.mjs

@@ -0,0 +1,22 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { Quantity } from '@siderust/qtty';
+import { ModifiedJulianDate, Period } from '@siderust/tempoch';
+
+const require = createRequire(import.meta.url);
+const { Observer, Star, intersectPeriods, starAboveThreshold, starAzimuthCrossings } = require(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'index.js'),
+);
+
+const observer = Observer.roqueDeLasMuchachos();
+const sirius = Star.catalog('Sirius');
+const window = new Period(new ModifiedJulianDate(60_000.0), new ModifiedJulianDate(60_001.0));
+
+const highAltitude = starAboveThreshold(sirius, observer, window, new Quantity(25, 'Degree'));
+const dueSouth = starAzimuthCrossings(sirius, observer, window, new Quantity(180, 'Degree'));
+
+console.log('High-altitude periods:', highAltitude);
+console.log('South crossings:', dueSouth);
+console.log('Self-intersection check:', intersectPeriods(highAltitude, highAltitude));

package/siderust-node/examples/10_time_periods.mjs

@@ -0,0 +1,9 @@
+import { ModifiedJulianDate, Period } from '@siderust/tempoch';
+
+const window = new Period(new ModifiedJulianDate(51_544.5), new ModifiedJulianDate(51_545.5));
+const later = new ModifiedJulianDate(51_545.0);
+
+console.log('Window:', window.format());
+console.log('Duration:', window.duration().toString());
+console.log('Contains 51545.0:', window.contains(later));
+console.log('UTC bounds:', window.toUtc());