@johnmorrisdotca/hoshi-stars 0.0.0-stage → 0.2.0

package/dist/sky.js

@@ -0,0 +1,283 @@
+// Your sky: where a star stands over your head at a place and a moment, and where it would stand over another planet's surface.
+// Pure maths, no DOM, no clock reads and no dependencies. The formulas are written from J. Meeus, "Astronomical Algorithms", 2nd ed. (Willmann-Bell, 1998):
+// chapter 12 (Greenwich mean sidereal time, the IAU 1982 expression), chapter 13 (equatorial to horizontal), chapter 16 (refraction, Saemundsson's formula) and chapter 21 (precession, the IAU 1976 constants).
+// For another planet the sky turns about that planet's pole: the pole and prime meridian are the IAU Working Group on Cartographic Coordinates and Rotational Elements (WGCCRE) quantities, passed in, so the planet data stays with the caller.
+// Azimuth runs from north through east (north 0, east 90, south 180, west 270), the compass way, not Meeus's way from south.
+import { terrestrialMinusUtc } from "./time-scale.js";
+import { J2000_MS, moment } from "./when.js";
+const RAD = Math.PI / 180;
+const DEG = 180 / Math.PI;
+const DAY_MS = 86_400_000;
+const ARCSEC = RAD / 3600;
+function finite(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new RangeError(`${name} must be a finite number, got ${String(value)}`);
+    return value;
+}
+function point(name, value) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`${name} must be an object with rightAscension and declination, got ${String(value)}`);
+    const p = value;
+    finite(`${name}.rightAscension`, p.rightAscension);
+    const declination = finite(`${name}.declination`, p.declination);
+    if (declination < -90 || declination > 90)
+        throw new RangeError(`${name}.declination must be between -90 and 90 degrees, got ${declination}`);
+    return p;
+}
+function place(name, value) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`${name} must be an object with latitude and longitude, got ${String(value)}`);
+    const o = value;
+    const latitude = finite(`${name}.latitude`, o.latitude);
+    if (latitude < -90 || latitude > 90)
+        throw new RangeError(`${name}.latitude must be between -90 and 90 degrees, got ${latitude}`);
+    finite(`${name}.longitude`, o.longitude);
+    if (o.heightM !== undefined)
+        finite(`${name}.heightM`, o.heightM);
+    return o;
+}
+/** An angle in degrees brought to 0 up to but not including 360. */
+function wrap360(angle) {
+    const a = angle % 360;
+    const r = a < 0 ? a + 360 : a;
+    return r >= 360 ? 0 : r;
+}
+/** Julian centuries since J2000.0, taking the moment as UT (the seconds between UT and the dynamical time are far below what these formulas can see). */
+function centuries(ms) {
+    return (ms - J2000_MS) / (DAY_MS * 36525);
+}
+function siderealDegrees(ms) {
+    const days = (ms - J2000_MS) / DAY_MS;
+    const T = days / 36525;
+    return 280.46061837 + 360.98564736629 * days + 0.000387933 * T * T - (T * T * T) / 38_710_000;
+}
+/**
+ * The Greenwich mean sidereal time: how far the Earth has turned against the stars, as the right ascension on the meridian of Greenwich, in degrees (Meeus 12.4, the IAU 1982 expression). It uses UT, which is UTC to under a second, and is the mean time, without the nutation term (at most about 1.1 seconds of time, 17 arc-seconds).
+ *
+ * @param when - The moment, a `Date` or milliseconds since 1970.
+ * @returns Degrees, 0 up to but not including 360. Divide by 15 for hours.
+ * @throws TypeError if `when` is not a Date or a number, RangeError if it is an invalid Date or not finite.
+ *
+ * @example
+ * ```ts
+ * import { greenwichSiderealTime } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Meeus example 12.a: 1987 April 10 at 0h UT is 13h10m46.3668s, 197.693195 degrees
+ * console.log(greenwichSiderealTime(Date.UTC(1987, 3, 10)).toFixed(6));
+ * ```
+ */
+export function greenwichSiderealTime(when) {
+    return wrap360(siderealDegrees(moment(when)));
+}
+/**
+ * The local mean sidereal time: the right ascension that is on your meridian, due south or north of you, in degrees. A star with this right ascension is crossing the meridian.
+ *
+ * @param when - The moment, a `Date` or milliseconds since 1970.
+ * @param longitude - Degrees east of Greenwich (west is negative). Any finite number.
+ * @returns Degrees, 0 up to but not including 360.
+ * @throws TypeError if `when` is not a Date or a number, RangeError if it is invalid or `longitude` is not finite.
+ *
+ * @example
+ * ```ts
+ * import { localSiderealTime } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Greenwich's 197.693195 degrees at 0h UT, 1987 April 10, and Washington is 77.07 degrees west of it
+ * console.log(localSiderealTime(Date.UTC(1987, 3, 10), -77.0656).toFixed(3)); // 120.628
+ * ```
+ */
+export function localSiderealTime(when, longitude) {
+    const ms = moment(when);
+    return wrap360(siderealDegrees(ms) + finite("longitude", longitude));
+}
+/** The three IAU 1976 precession angles zeta, z and theta, in radians, from J2000.0 to T Julian centuries after it (Meeus 21.2). */
+function precessionAngles(T) {
+    const zeta = (2306.2181 * T + 0.30188 * T * T + 0.017998 * T * T * T) * ARCSEC;
+    const z = (2306.2181 * T + 1.09468 * T * T + 0.018203 * T * T * T) * ARCSEC;
+    const theta = (2004.3109 * T - 0.42665 * T * T - 0.041833 * T * T * T) * ARCSEC;
+    return [zeta, z, theta];
+}
+/**
+ * A J2000 position carried to the mean equator and equinox of a date: the precession of the Earth's axis (Meeus chapter 21, the rigorous method with the IAU 1976 constants, good for a few centuries either side of 2000 to far under an arc-second). It leaves out the star's own proper motion (which `starPosition` adds), nutation and aberration, together under a minute of arc.
+ *
+ * @param position - A right ascension and declination in degrees at J2000.
+ * @param when - The date to carry it to.
+ * @returns The right ascension (0 up to but not including 360) and declination in degrees.
+ * @throws TypeError or RangeError, naming the argument, if `position` or `when` is not valid.
+ *
+ * @example
+ * ```ts
+ * import { precess } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Meeus example 21.b: theta Persei, carried to 2028 November 13.19 (about 15 minutes of arc east in right ascension)
+ * const there = precess({ rightAscension: 41.054063, declination: 49.227750 }, Date.UTC(2028, 10, 13, 4, 33, 36));
+ * console.log(there.rightAscension.toFixed(3), there.declination.toFixed(3)); // 41.547 49.348
+ * ```
+ */
+export function precess(position, when) {
+    point("position", position);
+    const T = centuries(moment(when));
+    const [zeta, z, theta] = precessionAngles(T);
+    const a0 = position.rightAscension * RAD + zeta;
+    const d0 = position.declination * RAD;
+    const cosD = Math.cos(d0);
+    const A = cosD * Math.sin(a0);
+    const B = Math.cos(theta) * cosD * Math.cos(a0) - Math.sin(theta) * Math.sin(d0);
+    const C = Math.sin(theta) * cosD * Math.cos(a0) + Math.cos(theta) * Math.sin(d0);
+    const declination = Math.abs(C) < 0.9999 ? Math.asin(C) : Math.sign(C) * Math.acos(Math.hypot(A, B));
+    return { rightAscension: wrap360((Math.atan2(A, B) + z) * DEG), declination: declination * DEG };
+}
+/** The east, north and up parts of a direction, from its declination and hour angle (Meeus 13.5 and 13.6, turned to measure azimuth from north through east), for an observer at latitude phi. */
+function toHorizontal(cosDcosH, cosDsinH, sinD, sinPhi, cosPhi) {
+    const east = -cosDsinH;
+    const north = sinD * cosPhi - cosDcosH * sinPhi;
+    const up = sinD * sinPhi + cosDcosH * cosPhi;
+    const across = Math.hypot(east, north);
+    return { altitude: Math.atan2(up, across) * DEG, azimuth: across < 1e-15 ? 0 : wrap360(Math.atan2(east, north) * DEG) };
+}
+/** Saemundsson's refraction (Meeus 16.4) in degrees for a true altitude in degrees, scaled for the air; 0 below -1 degree. */
+function refractionDegrees(altitude, pressureHpa, temperatureC) {
+    if (altitude < -1)
+        return 0;
+    // the +0.0019279 arc-minute makes the bending exactly 0 at the zenith, where the bare formula gives a hair under
+    const arcminutes = 1.02 / Math.tan((altitude + 10.3 / (altitude + 5.11)) * RAD) + 0.0019279;
+    return (arcminutes / 60) * (pressureHpa / 1010) * (283 / (273 + temperatureC));
+}
+/**
+ * Where a star (or any J2000 position) stands in the sky of a place on Earth at a moment: its altitude above the horizon and azimuth from north through east. The position is carried from J2000 to the equinox of the date (`precess`), the hour angle comes from the local mean sidereal time, and the horizon formulas are Meeus's (chapter 13). The result is geometric (no refraction) unless you ask for it. UTC stands for UT; nutation, aberration and parallax are left out, so it is good to about an arc-minute, far finer than the eye. The star's own proper motion is not added: pass `starPosition(star, when)` if you want it.
+ *
+ * @param position - A right ascension and declination in degrees, J2000 (the catalogue's frame), or of the date with `equinox: "date"`.
+ * @param observer - Latitude north and longitude east in degrees, and optionally `heightM`.
+ * @param when - The moment, a `Date` or milliseconds since 1970.
+ * @param options - `equinox`, and `refraction` with `pressureHpa` and `temperatureC`.
+ * @returns `{ altitude, azimuth }` in degrees.
+ * @throws TypeError or RangeError, naming the argument and the value, for a position, observer, moment or option that is not valid (a latitude or declination outside -90 to 90, a number that is not finite, a `pressureHpa` of 0 or less).
+ *
+ * @example
+ * ```ts
+ * import { starByName, starPosition } from "@johnmorrisdotca/hoshi-stars";
+ * import { horizontal } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * const polaris = starPosition(starByName("Polaris")!);
+ * const view = horizontal(polaris, { latitude: 49.28, longitude: -123.12 }, new Date("2026-11-08T06:00:00Z"));
+ * console.log(view.altitude.toFixed(1)); // 49.8: within a degree of the latitude, 49.28
+ * ```
+ */
+export function horizontal(position, observer, when, options = {}) {
+    point("position", position);
+    const o = place("observer", observer);
+    const ms = moment(when);
+    const equinox = options.equinox ?? "J2000";
+    if (equinox !== "J2000" && equinox !== "date")
+        throw new RangeError(`options.equinox must be "J2000" or "date", got ${String(equinox)}`);
+    let pressure = 1010;
+    let temperature = 10;
+    if (options.refraction === true) {
+        if (options.pressureHpa !== undefined && !(finite("options.pressureHpa", options.pressureHpa) > 0))
+            throw new RangeError(`options.pressureHpa must be greater than 0, got ${options.pressureHpa}`);
+        if (options.temperatureC !== undefined && !(finite("options.temperatureC", options.temperatureC) > -100))
+            throw new RangeError(`options.temperatureC must be above -100, got ${options.temperatureC}`);
+        pressure = options.pressureHpa ?? pressure;
+        temperature = options.temperatureC ?? temperature;
+    }
+    const of = equinox === "date" ? position : precess(position, ms);
+    const hourAngle = (siderealDegrees(ms) + o.longitude - of.rightAscension) * RAD;
+    const dec = of.declination * RAD;
+    const phi = o.latitude * RAD;
+    const cosD = Math.cos(dec);
+    const view = toHorizontal(cosD * Math.cos(hourAngle), cosD * Math.sin(hourAngle), Math.sin(dec), Math.sin(phi), Math.cos(phi));
+    if (options.refraction === true)
+        view.altitude += refractionDegrees(view.altitude, pressure, temperature);
+    return view;
+}
+/**
+ * Whether a position is above the horizon of a place at a moment (altitude greater than 0). With `refraction: true` it counts the bending of the light, so a star can be seen a little below the geometric horizon.
+ *
+ * @param position - A right ascension and declination in degrees, J2000 or (with `equinox: "date"`) of the date.
+ * @param observer - Latitude north and longitude east in degrees.
+ * @param when - The moment, a `Date` or milliseconds since 1970.
+ * @param options - The same as `horizontal`.
+ * @returns True when it is up.
+ * @throws TypeError or RangeError, as `horizontal` does.
+ *
+ * @example
+ * ```ts
+ * import { starByName, starPosition } from "@johnmorrisdotca/hoshi-stars";
+ * import { isAboveHorizon } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Polaris never sets for anyone in the northern hemisphere
+ * const polaris = starPosition(starByName("Polaris")!);
+ * console.log(isAboveHorizon(polaris, { latitude: 49.28, longitude: -123.12 }, Date.now()));
+ * ```
+ */
+export function isAboveHorizon(position, observer, when, options = {}) {
+    return horizontal(position, observer, when, options).altitude > 0;
+}
+/**
+ * Where a star stands in the sky of a place on ANOTHER planet: the sky turns about that planet's pole (the IAU WGCCRE pole and prime meridian, passed in as `spin`), so the star is rotated into the planet's own equatorial frame, its hour angle is the prime meridian plus the observer's east longitude minus its right ascension there, and the horizon formulas are the same as for Earth.
+ *
+ * The stars look the same from every planet: the nearest star, Proxima Centauri, shifts only about 40 arc-seconds seen from Pluto (annual parallax 0.77 arc-seconds times Pluto's 49 AU at its farthest), and a typical star far less, so a star's J2000 position serves anywhere in the solar system. Only the pole and the turning change.
+ *
+ * Limits: the latitude is used as the angle from the planet's equator on a sphere (the difference between planetographic and planetocentric latitude, up to a fifth of a degree on Mars, is ignored); the pole's slow drift is the caller's to add in if wanted (`spin.pole` is read as given); there is no atmosphere, and no precession of the pole is applied. `when` is UTC, like every moment in the package: it is turned into Terrestrial Time inside, the scale the IAU rates are in (69.184 s ahead of UTC since 2017, by the leap-second table back to 1972 and by Espenak and Meeus's delta T before it; a leap second announced after 2017 is not known until the table gets its row). TDB differs from TT by under 2 milliseconds, which is ignored. Without the conversion Mars would be turned 0.28 degrees out.
+ *
+ * @param position - A right ascension and declination in degrees at J2000.
+ * @param spin - The planet's `pole` (right ascension and declination, degrees) and `primeMeridian` (`w0` degrees at J2000 and `rate` degrees a day).
+ * @param observer - Latitude north and longitude east on that planet, in degrees (north being the side of the pole).
+ * @param when - The moment, a `Date` or milliseconds since 1970.
+ * @returns `{ altitude, azimuth }` in degrees, the azimuth from north through east.
+ * @throws TypeError or RangeError, naming the argument and the value, for a position, spin, observer or moment that is not valid.
+ *
+ * @example
+ * ```ts
+ * import { starByName, starPosition } from "@johnmorrisdotca/hoshi-stars";
+ * import { horizontalFrom } from "@johnmorrisdotca/hoshi-stars/sky";
+ *
+ * // Mars, IAU 2015 values: its north celestial pole is only 10 degrees from Deneb, so from the pole Deneb stands almost overhead
+ * const mars = { pole: { rightAscension: 317.269202, declination: 54.432516 }, primeMeridian: { w0: 176.049863, rate: 350.891982443297 } };
+ * const deneb = starPosition(starByName("Deneb")!);
+ * console.log(horizontalFrom(deneb, mars, { latitude: 90, longitude: 0 }, Date.UTC(2026, 10, 8)).altitude.toFixed(1)); // 79.8
+ * ```
+ */
+export function horizontalFrom(position, spin, observer, when) {
+    point("position", position);
+    if (typeof spin !== "object" || spin === null)
+        throw new TypeError(`spin must be an object with a pole and a primeMeridian, got ${String(spin)}`);
+    point("spin.pole", spin.pole);
+    const meridian = spin.primeMeridian;
+    if (typeof meridian !== "object" || meridian === null)
+        throw new TypeError(`spin.primeMeridian must be an object with w0 and rate, got ${String(meridian)}`);
+    const w0 = finite("spin.primeMeridian.w0", meridian.w0);
+    const rate = finite("spin.primeMeridian.rate", meridian.rate);
+    const o = place("observer", observer);
+    const utc = moment(when);
+    const days = (utc + terrestrialMinusUtc(utc) * 1000 - J2000_MS) / DAY_MS;
+    const turned = (w0 + rate * days + o.longitude) * RAD;
+    // The planet's frame: z toward its pole, x toward the node where its equator crosses the ICRF equator (right ascension of the pole + 90 degrees), y = z cross x.
+    const a0 = spin.pole.rightAscension * RAD;
+    const d0 = spin.pole.declination * RAD;
+    const sinA = Math.sin(a0);
+    const cosA = Math.cos(a0);
+    const sinD0 = Math.sin(d0);
+    const cosD0 = Math.cos(d0);
+    const zx = cosD0 * cosA;
+    const zy = cosD0 * sinA;
+    const zz = sinD0;
+    const xx = -sinA;
+    const xy = cosA;
+    const yx = -zz * xy;
+    const yy = zz * xx;
+    const yz = zx * xy - zy * xx;
+    const dec = position.declination * RAD;
+    const ra = position.rightAscension * RAD;
+    const cosD = Math.cos(dec);
+    const sx = cosD * Math.cos(ra);
+    const sy = cosD * Math.sin(ra);
+    const sz = Math.sin(dec);
+    const px = sx * xx + sy * xy;
+    const py = sx * yx + sy * yy + sz * yz;
+    const pz = sx * zx + sy * zy + sz * zz;
+    // cos(dec') cos(H) and cos(dec') sin(H), with H = turned - alpha'
+    const sinT = Math.sin(turned);
+    const cosT = Math.cos(turned);
+    const phi = o.latitude * RAD;
+    return toHorizontal(px * cosT + py * sinT, px * sinT - py * cosT, pz, Math.sin(phi), Math.cos(phi));
+}

package/dist/stars.d.ts

@@ -0,0 +1,162 @@
+import { type When } from "./when.ts";
+/**
+ * One star, as the Yale Bright Star Catalogue gives it. Positions are J2000 (equator and equinox of 2000, the FK5 frame, which is the ICRS to a fraction of an arc-second).
+ *
+ * @example
+ * ```ts
+ * import { starByName, type Star } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * const sirius: Star = starByName("Sirius")!;
+ * console.log(sirius.designation, sirius.magnitude);
+ * ```
+ */
+export interface Star {
+    /** The Bright Star Catalogue (Harvard Revised) number: stable, and the key for `starByHr`. */
+    hr: number;
+    /** The common name where the star has one (the IAU Working Group on Star Names' spelling), else `undefined`. */
+    name: string | undefined;
+    /** The name in katakana (`シリウス`) for every star that has a `name`, else `undefined`. */
+    nameJa: string | undefined;
+    /** The Bayer letter and constellation (`α CMa`), else the Flamsteed number and constellation (`9 CMa`), else `undefined`. */
+    designation: string | undefined;
+    /** The IAU three-letter constellation abbreviation (`CMa`) the star lies in, for every star: the catalogue's where the star has a Bayer letter or Flamsteed number, else the one the boundaries give. */
+    constellation: string;
+    /** Right ascension in degrees at J2000, 0 up to 360. The catalogue gives it to a tenth of a second of time (1.5 arc-seconds at the equator). */
+    rightAscension: number;
+    /** Declination in degrees at J2000, -90 to 90. The catalogue gives it to an arc-second. */
+    declination: number;
+    /** Visual magnitude: smaller is brighter, and Sirius is -1.46. */
+    magnitude: number;
+    /** The colour index B-V in magnitudes, or `undefined` where the catalogue has none. Hot blue stars are about -0.3, the Sun 0.65, cool red stars above 1.5. */
+    colourIndex: number | undefined;
+    /** The spectral class and subclass (`A1`, `K1`), or an empty string where the catalogue gives none we read. */
+    spectralClass: string;
+    /** Proper motion in right ascension, in milliarcseconds a year, already multiplied by cos(declination) (a true angle on the sky). */
+    properMotionRaMas: number;
+    /** Proper motion in declination, in milliarcseconds a year. */
+    properMotionDecMas: number;
+    /** The annual parallax in milliarcseconds; 0 where the catalogue has none (the distance is then unknown). */
+    parallaxMas: number;
+}
+/**
+ * The stars to a magnitude, brightest first. The catalogue stops at magnitude 6.0, so the default is all 5,080.
+ *
+ * @param options - `magnitude`: the faintest to include (a star of exactly that magnitude is in). Brighter limits give shorter lists: 1 is 15 stars, 4 is 518, 5 is 1,630.
+ * @returns A fresh array of the shared, frozen stars.
+ *
+ * @example
+ * ```ts
+ * import { stars } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(stars().length, stars({ magnitude: 2 }).map((s) => s.name ?? s.designation).slice(0, 3));
+ * ```
+ */
+export declare function stars(options?: {
+    magnitude?: number;
+}): Star[];
+/**
+ * A star by its Bright Star Catalogue number.
+ *
+ * @param hr - The HR number (Sirius is 2491).
+ * @returns The star, or `undefined` if that number is not in this table (the table holds the stars to magnitude 6.0 only).
+ *
+ * @example
+ * ```ts
+ * import { starByHr } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(starByHr(2491)?.name);
+ * ```
+ */
+export declare function starByHr(hr: number): Star | undefined;
+/**
+ * A star by its common name (`Sirius`), its name in katakana (`シリウス`) or its designation (`α CMa`, `9 CMa`), ignoring case.
+ *
+ * @param text - The name or designation.
+ * @returns The star, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { starByName } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(starByName("betelgeuse")?.designation, starByName("α Lyr")?.name, starByName("シリウス")?.hr);
+ * ```
+ */
+export declare function starByName(text: string): Star | undefined;
+/**
+ * Where a star is at a moment: its J2000 position carried forward (or back) by its proper motion in a straight line. The frame stays J2000, so precession to the date is not applied: use
+ * the result with J2000 coordinates, or convert it to the date with `/coordinates`. A straight line is good to a fraction of an arc-second for centuries for nearly every star here; it is
+ * not good for the few with large motion over millennia.
+ *
+ * @param star - A star.
+ * @param when - The moment as a `Date` or milliseconds since 1970 (UTC); J2000 when left out.
+ * @returns Right ascension and declination in degrees, J2000 frame, at that moment.
+ *
+ * @example
+ * ```ts
+ * import { starByName, starPosition } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * const now = starPosition(starByName("Arcturus")!, Date.UTC(2026, 10, 7));
+ * console.log(now.declination.toFixed(3));
+ * ```
+ */
+export declare function starPosition(star: Star, when?: When): {
+    rightAscension: number;
+    declination: number;
+};
+/**
+ * A star's distance from its parallax, in light-years.
+ *
+ * @param star - A star.
+ * @returns Light-years, or `undefined` where the catalogue has no parallax (or a non-positive one).
+ *
+ * @example
+ * ```ts
+ * import { starByName, starDistanceLightYears } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(starDistanceLightYears(starByName("Sirius")!)?.toFixed(1));
+ * ```
+ */
+export declare function starDistanceLightYears(star: Star): number | undefined;
+/**
+ * The surface temperature a colour index implies, in kelvin, by Ballesteros's relation between B-V and a black body. It is an estimate to a few hundred kelvin for most stars, and it runs cool for the hottest (about 16,600 K at -0.3).
+ *
+ * @param colourIndex - B-V in magnitudes.
+ * @returns Kelvin.
+ *
+ * @example
+ * ```ts
+ * import { starTemperatureK } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(Math.round(starTemperatureK(0.65)));
+ * ```
+ */
+export declare function starTemperatureK(colourIndex: number): number;
+/**
+ * The colour of a black body at a temperature, as a `#rrggbb` string, for drawing a star. It is the colour a camera would show, not a measurement, and it uses an approximation of the
+ * black-body locus (good to a few percent between 1,000 and 40,000 K).
+ *
+ * @param kelvin - Temperature in kelvin.
+ * @returns A colour like `#a4bdff`.
+ *
+ * @example
+ * ```ts
+ * import { blackBodyColour } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(blackBodyColour(10000), blackBodyColour(3500));
+ * ```
+ */
+export declare function blackBodyColour(kelvin: number): string;
+/**
+ * The colour to draw a star: from its B-V index, or a plain white where the catalogue has none.
+ *
+ * @param star - A star.
+ * @returns A `#rrggbb` string.
+ *
+ * @example
+ * ```ts
+ * import { starByName, starColour } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(starColour(starByName("Betelgeuse")!), starColour(starByName("Rigel")!));
+ * ```
+ */
+export declare function starColour(star: Star): string;

package/dist/stars.js

@@ -0,0 +1,195 @@
+// The stars you can see without a telescope: the 5,080 of the Yale Bright Star Catalogue to visual magnitude 6.0, with their names, positions, proper motion, brightness and colour.
+// The bright-star tier (`@johnmorrisdotca/hoshi-stars`): the table is about 100 kB gzipped and nothing else imports it. Pure: no DOM, no three.js, no state beyond the parsed table.
+import { J2000_MS } from "./when.js";
+import { STAR_NAMES, STAR_ROWS } from "./data/stars.js";
+import { STAR_NAMES_JA } from "./data/star-names-ja.js";
+import { moment } from "./when.js";
+const stored = [];
+const byHr = new Map();
+const byText = new Map();
+function load() {
+    if (stored.length > 0)
+        return;
+    for (const row of STAR_ROWS.split("\n")) {
+        const p = row.split("|");
+        const hr = Number(p[0]);
+        const letter = p[1];
+        const flamsteed = p[2];
+        const constellation = p[3];
+        const designation = constellation === "" ? undefined : `${letter !== "" ? letter : flamsteed} ${constellation}`;
+        const star = Object.freeze({
+            hr,
+            name: STAR_NAMES[hr],
+            nameJa: STAR_NAMES_JA[hr],
+            designation: letter === "" && flamsteed === "" ? undefined : designation,
+            constellation,
+            rightAscension: (Number(p[4]) / 2400),
+            declination: Number(p[5]) / 3600,
+            magnitude: Number(p[8]) / 100,
+            colourIndex: p[9] === "" ? undefined : Number(p[9]) / 100,
+            spectralClass: p[10],
+            properMotionRaMas: Number(p[6]),
+            properMotionDecMas: Number(p[7]),
+            parallaxMas: Number(p[11]),
+        });
+        stored.push(star);
+        byHr.set(hr, star);
+        for (const text of [star.name, star.nameJa, star.designation])
+            if (text !== undefined)
+                byText.set(text.toLowerCase(), star);
+    }
+}
+/**
+ * The stars to a magnitude, brightest first. The catalogue stops at magnitude 6.0, so the default is all 5,080.
+ *
+ * @param options - `magnitude`: the faintest to include (a star of exactly that magnitude is in). Brighter limits give shorter lists: 1 is 15 stars, 4 is 518, 5 is 1,630.
+ * @returns A fresh array of the shared, frozen stars.
+ *
+ * @example
+ * ```ts
+ * import { stars } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(stars().length, stars({ magnitude: 2 }).map((s) => s.name ?? s.designation).slice(0, 3));
+ * ```
+ */
+export function stars(options = {}) {
+    load();
+    const limit = options.magnitude ?? Number.POSITIVE_INFINITY;
+    if (typeof limit !== "number" || Number.isNaN(limit))
+        throw new TypeError(`magnitude must be a number, got ${String(limit)}`);
+    return stored.filter((star) => star.magnitude <= limit);
+}
+/**
+ * A star by its Bright Star Catalogue number.
+ *
+ * @param hr - The HR number (Sirius is 2491).
+ * @returns The star, or `undefined` if that number is not in this table (the table holds the stars to magnitude 6.0 only).
+ *
+ * @example
+ * ```ts
+ * import { starByHr } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(starByHr(2491)?.name);
+ * ```
+ */
+export function starByHr(hr) {
+    load();
+    return byHr.get(hr);
+}
+/**
+ * A star by its common name (`Sirius`), its name in katakana (`シリウス`) or its designation (`α CMa`, `9 CMa`), ignoring case.
+ *
+ * @param text - The name or designation.
+ * @returns The star, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { starByName } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(starByName("betelgeuse")?.designation, starByName("α Lyr")?.name, starByName("シリウス")?.hr);
+ * ```
+ */
+export function starByName(text) {
+    load();
+    return byText.get(text.trim().toLowerCase());
+}
+const JULIAN_YEAR_MS = 365.25 * 86_400_000;
+/**
+ * Where a star is at a moment: its J2000 position carried forward (or back) by its proper motion in a straight line. The frame stays J2000, so precession to the date is not applied: use
+ * the result with J2000 coordinates, or convert it to the date with `/coordinates`. A straight line is good to a fraction of an arc-second for centuries for nearly every star here; it is
+ * not good for the few with large motion over millennia.
+ *
+ * @param star - A star.
+ * @param when - The moment as a `Date` or milliseconds since 1970 (UTC); J2000 when left out.
+ * @returns Right ascension and declination in degrees, J2000 frame, at that moment.
+ *
+ * @example
+ * ```ts
+ * import { starByName, starPosition } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * const now = starPosition(starByName("Arcturus")!, Date.UTC(2026, 10, 7));
+ * console.log(now.declination.toFixed(3));
+ * ```
+ */
+export function starPosition(star, when) {
+    const years = (moment(when ?? J2000_MS) - J2000_MS) / JULIAN_YEAR_MS;
+    const declination = star.declination + (star.properMotionDecMas * years) / 3_600_000;
+    const cosine = Math.cos((star.declination * Math.PI) / 180);
+    // The motion is a true angle on the sky: it stretches by 1 / cos(declination) in right ascension. At the poles the division is kept finite.
+    const rightAscension = star.rightAscension + (star.properMotionRaMas * years) / 3_600_000 / Math.max(Math.abs(cosine), 1e-6);
+    return { rightAscension: ((rightAscension % 360) + 360) % 360, declination: Math.max(-90, Math.min(90, declination)) };
+}
+/**
+ * A star's distance from its parallax, in light-years.
+ *
+ * @param star - A star.
+ * @returns Light-years, or `undefined` where the catalogue has no parallax (or a non-positive one).
+ *
+ * @example
+ * ```ts
+ * import { starByName, starDistanceLightYears } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(starDistanceLightYears(starByName("Sirius")!)?.toFixed(1));
+ * ```
+ */
+export function starDistanceLightYears(star) {
+    return star.parallaxMas > 0 ? 3261.563777 / star.parallaxMas : undefined;
+}
+/**
+ * The surface temperature a colour index implies, in kelvin, by Ballesteros's relation between B-V and a black body. It is an estimate to a few hundred kelvin for most stars, and it runs cool for the hottest (about 16,600 K at -0.3).
+ *
+ * @param colourIndex - B-V in magnitudes.
+ * @returns Kelvin.
+ *
+ * @example
+ * ```ts
+ * import { starTemperatureK } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(Math.round(starTemperatureK(0.65)));
+ * ```
+ */
+export function starTemperatureK(colourIndex) {
+    if (!Number.isFinite(colourIndex))
+        throw new RangeError(`colourIndex must be a finite number, got ${colourIndex}`);
+    return 4600 * (1 / (0.92 * colourIndex + 1.7) + 1 / (0.92 * colourIndex + 0.62));
+}
+/**
+ * The colour of a black body at a temperature, as a `#rrggbb` string, for drawing a star. It is the colour a camera would show, not a measurement, and it uses an approximation of the
+ * black-body locus (good to a few percent between 1,000 and 40,000 K).
+ *
+ * @param kelvin - Temperature in kelvin.
+ * @returns A colour like `#a4bdff`.
+ *
+ * @example
+ * ```ts
+ * import { blackBodyColour } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(blackBodyColour(10000), blackBodyColour(3500));
+ * ```
+ */
+export function blackBodyColour(kelvin) {
+    if (!Number.isFinite(kelvin) || kelvin <= 0)
+        throw new RangeError(`kelvin must be a positive number, got ${kelvin}`);
+    const t = Math.min(40_000, Math.max(1_000, kelvin)) / 100;
+    const red = t <= 66 ? 255 : 329.698727446 * (t - 60) ** -0.1332047592;
+    const green = t <= 66 ? 99.4708025861 * Math.log(t) - 161.1195681661 : 288.1221695283 * (t - 60) ** -0.0755148492;
+    const blue = t >= 66 ? 255 : t <= 19 ? 0 : 138.5177312231 * Math.log(t - 10) - 305.0447927307;
+    const byte = (v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, "0");
+    return `#${byte(red)}${byte(green)}${byte(blue)}`;
+}
+/**
+ * The colour to draw a star: from its B-V index, or a plain white where the catalogue has none.
+ *
+ * @param star - A star.
+ * @returns A `#rrggbb` string.
+ *
+ * @example
+ * ```ts
+ * import { starByName, starColour } from "@johnmorrisdotca/hoshi-stars";
+ *
+ * console.log(starColour(starByName("Betelgeuse")!), starColour(starByName("Rigel")!));
+ * ```
+ */
+export function starColour(star) {
+    return star.colourIndex === undefined ? "#ffffff" : blackBodyColour(starTemperatureK(star.colourIndex));
+}

package/dist/time-scale.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The offset TT - UTC in seconds at a moment given in UTC: 42.184 s at the start of 1972 and 69.184 s from 2017 on; before 1972, delta T (TT - UT) from the Espenak and Meeus fit.
+ *
+ * @param utcMs - Milliseconds since 1970 (UTC), finite.
+ * @returns Seconds to add to UTC to get Terrestrial Time.
+ *
+ * @example
+ * ```ts
+ * import { terrestrialMinusUtc } from "./time-scale.ts";
+ *
+ * console.log(terrestrialMinusUtc(Date.UTC(2026, 10, 8)), terrestrialMinusUtc(Date.UTC(2000, 0, 1)));
+ * ```
+ */
+export declare function terrestrialMinusUtc(utcMs: number): number;