@johnmorrisdotca/uchusen-rockets 0.9.0 → 0.11.0

package/dist/journey/trip.js

@@ -0,0 +1,447 @@
+import { AU_KM, C, DAY_S, G0, GM_KM3_S2, PARKING_ALTITUDE_KM, PERIOD_DAYS } from "./constants.js";
+import { accelerating, circularSpeed, escapeBurn, flipAndBurn, hohmann, transferPoint, wrapPi } from "./physics.js";
+const SCREEN = { preheat: 6, ignition: 3, ascent: 7, burn: 6, coast: 22, flip: 4, brake: 7, accelerate: 22, decelerate: 22, arrival: 3 };
+const ARRIVAL_S = 5;
+const stopOf = (source, id) => {
+    const stop = source.stops.find((one) => one.id === id);
+    if (!stop)
+        throw new Error(`No such place: ${id}`);
+    return stop;
+};
+const muOf = (source, id) => stopOf(source, id).muKm3s2 ?? GM_KM3_S2[id] ?? NaN;
+const periodOf = (source, id) => stopOf(source, id).periodDays ?? PERIOD_DAYS[id] ?? NaN;
+/** A place's position in a frame, km: round the Sun for a planet, round the Earth for the Moon (and the Earth's own is the origin of the Earth's frame). */
+export function positionKm(source, id, ms, frame) {
+    if (frame === "earth") {
+        if (id === "earth")
+            return [0, 0, 0];
+        return source.offsetKm(id, ms);
+    }
+    const au = source.positionAu(id, ms);
+    return [au[0] * AU_KM, au[1] * AU_KM, au[2] * AU_KM];
+}
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const len = (a) => Math.hypot(a[0], a[1], a[2]);
+const flat = (a) => Math.hypot(a[0], a[1]);
+const lon = (a) => Math.atan2(a[1], a[0]);
+const quantity = (q, name, estimated) => {
+    if (!q)
+        return null;
+    if (q.estimate !== undefined)
+        estimated.push(name);
+    return q.value;
+};
+/** Parking orbit radius round a body, km. */
+const parkRadius = (source, id) => stopOf(source, id).radiusKm + (id === "earth" ? PARKING_ALTITUDE_KM.earth : id === "moon" ? PARKING_ALTITUDE_KM.moon : PARKING_ALTITUDE_KM.other);
+/** The transfer from a planet to another that leaves at a time: the radii at the two ends, the flight time (two passes, since the end moves), and how far short of 180 degrees the arrival is. */
+function transferAt(source, from, to, t0) {
+    const p1 = positionKm(source, from, t0, "sun");
+    const r1 = flat(p1);
+    const mu = GM_KM3_S2.sun;
+    let p2 = positionKm(source, to, t0, "sun");
+    let seconds = hohmann(mu, r1, flat(p2)).seconds;
+    for (let i = 0; i < 4; i += 1) {
+        p2 = positionKm(source, to, t0 + seconds * 1000, "sun");
+        seconds = hohmann(mu, r1, flat(p2)).seconds;
+    }
+    const r2 = flat(p2);
+    const h = hohmann(mu, r1, r2);
+    return { r1, r2, seconds, theta0: lon(p1), f: wrapPi(lon(p2) - lon(p1) - Math.PI), dv1: h.dv1, dv2: h.dv2 };
+}
+/**
+ * The next dates a craft can leave one planet for another on a Hohmann transfer: the days on which the destination will be where the craft arrives. Found by scanning day by day and bisecting each crossing, from the planets' real positions.
+ * @param source Where the planets are.
+ * @param from The starting planet's id.
+ * @param to The destination planet's id.
+ * @param afterMs The earliest date, milliseconds since 1970.
+ * @param count How many windows.
+ * @returns The windows, soonest first.
+ * @example
+ * ```ts no-run
+ * import { windows, type BodySource } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const source: BodySource;
+ * console.log(windows(source, "earth", "mars", Date.UTC(2026, 10, 4), 2).map((one) => new Date(one.dateMs).toISOString().slice(0, 10)));
+ * ```
+ */
+export function windows(source, from, to, afterMs, count) {
+    const synodic = 1 / Math.abs(1 / periodOf(source, from) - 1 / periodOf(source, to));
+    const end = afterMs + (count + 1) * synodic * DAY_S * 1000;
+    const found = [];
+    let t = afterMs;
+    let previous = transferAt(source, from, to, t);
+    while (t < end && found.length < count) {
+        const next = t + DAY_S * 1000;
+        const current = transferAt(source, from, to, next);
+        if (previous.f * current.f < 0 && Math.abs(previous.f) < 1.5 && Math.abs(current.f) < 1.5) {
+            let lo = t;
+            let hi = next;
+            let flo = previous.f;
+            for (let i = 0; i < 24; i += 1) {
+                const mid = (lo + hi) / 2;
+                const fm = transferAt(source, from, to, mid).f;
+                if (flo * fm <= 0)
+                    hi = mid;
+                else {
+                    lo = mid;
+                    flo = fm;
+                }
+            }
+            const at = transferAt(source, from, to, hi);
+            if (hi >= afterMs)
+                found.push({ dateMs: Math.round(hi / 60_000) * 60_000, days: at.seconds / DAY_S, dv1: at.dv1, dv2: at.dv2 });
+        }
+        previous = current;
+        t = next;
+    }
+    return found;
+}
+/** The energy (km^2/s^2, the speed squared at infinity) each kind of payload figure is for. Lower is easier. */
+export function c3Of(source, kind) {
+    const mu = muOf(source, "earth");
+    const r = parkRadius(source, "earth");
+    if (kind === "leo")
+        return -mu / r;
+    if (kind === "gto")
+        return -mu / ((r + 42_164) / 2);
+    const moon = 384_400;
+    const h = hohmann(mu, r, moon);
+    if (kind === "tli")
+        return (circularSpeed(mu, r) + h.dv1) ** 2 - (2 * mu) / r;
+    const sun = hohmann(GM_KM3_S2.sun, AU_KM, 1.52371034 * AU_KM);
+    return sun.dv1 ** 2;
+}
+const KIND_OF = { moon: "tli", mars: "mars" };
+const WORDS = { leo: "low Earth orbit", gto: "geostationary transfer orbit", tli: "the Moon", mars: "Mars" };
+const tonnes = (kg) => `${(kg / 1000).toLocaleString("en-US", { maximumFractionDigits: 1 })} t`;
+/** What a ballistic craft can carry on a path of this energy: a published figure for it, or for a harder one (at least), or none. */
+function capacityVerdict(source, craft, to, c3) {
+    const kind = KIND_OF[to];
+    const direct = kind ? craft.capacityKg[kind] : undefined;
+    if (kind && direct)
+        return { level: "rated", kg: direct.value, line: `Rated: ${tonnes(direct.value)} to ${WORDS[kind]}.` };
+    let best = null;
+    for (const [name, figure] of Object.entries(craft.capacityKg)) {
+        const energy = c3Of(source, name);
+        if (energy >= c3 - 0.01 && (best === null || energy < best.c3))
+            best = { kind: name, kg: figure.value, c3: energy };
+    }
+    if (best && best.kind !== "leo" && best.kind !== "gto")
+        return { level: "at-least", kg: best.kg, line: `Can do it: at least ${tonnes(best.kg)}, because it can send that much to ${WORDS[best.kind]}, which takes more energy.` };
+    return { level: "not-rated", line: `Not rated: no published payload figure covers a trip to ${stopName(source, to)}.` };
+}
+const stopName = (source, id) => stopOf(source, id).name.en;
+const phase = (id, startS, endS, screenS) => ({ id, startS, endS, screenS });
+const unavailable = (craft, from, to, departMs, line, because) => ({
+    from,
+    to,
+    craftId: craft.id,
+    drive: craft.drive,
+    frame: to === "moon" ? "earth" : "sun",
+    departMs,
+    liftoffBeforeS: 0,
+    phases: [],
+    totalS: 0,
+    verdict: { level: "cannot", line, because, playable: false },
+    estimated: [],
+    fuel: { usedT: null, carriedT: null, note: "No trip." },
+    payload: { kg: null, atLeast: false, note: "No trip." },
+    straightKm: 0,
+    pathKm: 0,
+    dv: { departure: 0, arrival: 0, total: 0 },
+    peakG: 0,
+    peakSpeed: 0,
+    peakGamma: 1,
+    shipS: 0,
+    frameS: 0,
+});
+/**
+ * Plans a trip: the transfer or the flip and burn, the burns, the times, and what the craft can and cannot do. A craft that cannot make the trip comes back with a verdict that says why in one line and no phases.
+ * @param source Where the places are.
+ * @param craft The craft.
+ * @param from The starting place's id.
+ * @param to The destination's id.
+ * @param departMs When the departure burn begins, milliseconds since 1970 (for a ballistic trip to a planet, one of `windows`).
+ * @returns The planned trip.
+ * @example
+ * ```ts no-run
+ * import { craftOf, planTrip, type BodySource } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const source: BodySource;
+ * const trip = planTrip(source, craftOf("saturn-v")!, "earth", "moon", Date.UTC(2026, 10, 5));
+ * console.log(trip.verdict.line, Math.round(trip.dv.departure));
+ * ```
+ */
+export function planTrip(source, craft, from, to, departMs) {
+    if (from === to)
+        return unavailable(craft, from, to, departMs, "Pick two different places.", []);
+    return craft.drive === "ballistic" ? planBallistic(source, craft, from, to, departMs) : planContinuous(source, craft, from, to, departMs);
+}
+function planBallistic(source, craft, from, to, departMs) {
+    if (from !== "earth")
+        return unavailable(craft, from, to, departMs, "Rockets in this version lift off from the Earth only.", ["A rocket's payload figures are for launches from the Earth."]);
+    if (to === "sun")
+        return unavailable(craft, from, to, departMs, "No transfer is planned to the Sun.", []);
+    const estimated = [];
+    const toMoon = to === "moon";
+    const frame = toMoon ? "earth" : "sun";
+    const muEarth = muOf(source, "earth");
+    const rPark = parkRadius(source, "earth");
+    const parkSpeed = circularSpeed(muEarth, rPark);
+    let mu;
+    let r1;
+    let r2;
+    let transitS;
+    let theta0;
+    let vInf1;
+    let vInf2;
+    let burnEndSpeed;
+    let c3;
+    let straightKm;
+    if (toMoon) {
+        mu = muEarth;
+        r1 = rPark;
+        transitS = 0;
+        let moon = positionKm(source, "moon", departMs, "earth");
+        r2 = flat(moon);
+        for (let i = 0; i < 4; i += 1) {
+            transitS = hohmann(mu, r1, r2).seconds;
+            moon = positionKm(source, "moon", departMs + transitS * 1000, "earth");
+            r2 = flat(moon);
+        }
+        transitS = hohmann(mu, r1, r2).seconds;
+        theta0 = lon(moon) - Math.PI;
+        const h = hohmann(mu, r1, r2);
+        burnEndSpeed = parkSpeed + h.dv1;
+        c3 = burnEndSpeed ** 2 - (2 * mu) / r1;
+        vInf1 = Math.sqrt(Math.max(0, c3));
+        vInf2 = Math.abs(circularSpeed(mu, r2) - Math.sqrt(mu * (2 / r2 - 2 / (r1 + r2))));
+        straightKm = len(positionKm(source, "moon", departMs, "earth"));
+    }
+    else {
+        mu = GM_KM3_S2.sun;
+        const t = transferAt(source, from, to, departMs);
+        r1 = t.r1;
+        r2 = t.r2;
+        transitS = t.seconds;
+        theta0 = t.theta0;
+        vInf1 = t.dv1;
+        vInf2 = t.dv2;
+        burnEndSpeed = Math.sqrt(vInf1 ** 2 + (2 * muEarth) / rPark);
+        c3 = vInf1 ** 2;
+        straightKm = len(sub(positionKm(source, to, departMs, "sun"), positionKm(source, "earth", departMs, "sun")));
+    }
+    const dv1 = burnEndSpeed - parkSpeed;
+    const captureKm = parkRadius(source, to);
+    const muTo = muOf(source, to);
+    const captureSpeedIn = Math.sqrt(vInf2 ** 2 + (2 * muTo) / captureKm);
+    const captureSpeedOut = circularSpeed(muTo, captureKm);
+    const dv2 = escapeBurn(muTo, captureKm, vInf2);
+    const verdictCap = capacityVerdict(source, craft, to, c3);
+    const payload = craft.payload;
+    const thrust = quantity(payload.thrustN, "braking engine thrust", estimated);
+    const mass = quantity(payload.massKg, "payload mass", estimated);
+    const brakeG = thrust !== null && mass !== null ? thrust / mass / G0 : quantity(payload.brakeG, "braking acceleration", estimated) ?? 0.2;
+    const dvAvailable = payload.dvMs?.value ?? null;
+    const flyby = dvAvailable !== null && dvAvailable < dv2 * 1000;
+    const ascentS = quantity(craft.ascentS, "time to orbit", estimated) ?? 540;
+    let burnS = quantity(craft.departureBurnS, "departure burn length", estimated);
+    if (burnS === null) {
+        burnS = (dv1 * 1000) / (0.6 * G0);
+        estimated.push("departure burn length");
+    }
+    const flipS = quantity(craft.flipS, "turn-round time", estimated) ?? 120;
+    const brakeS = flyby ? 0 : (dv2 * 1000) / (brakeG * G0);
+    const arcSteps = 360;
+    const arc = [0];
+    let last = transferPoint(mu, r1, r2, theta0, 0);
+    for (let i = 1; i <= arcSteps; i += 1) {
+        const p = transferPoint(mu, r1, r2, theta0, (transitS * i) / arcSteps);
+        arc.push(arc[i - 1] + Math.hypot(p.r * Math.cos(p.theta) - last.r * Math.cos(last.theta), p.r * Math.sin(p.theta) - last.r * Math.sin(last.theta)));
+        last = p;
+    }
+    const pathKm = arc[arcSteps];
+    const t = { ascent: 0, burn: ascentS, coast: ascentS + burnS, flip: ascentS + burnS + transitS - flipS, brake: ascentS + burnS + transitS };
+    const phases = [
+        phase("preheat", -13, -3, SCREEN.preheat),
+        phase("ignition", -3, 0, SCREEN.ignition),
+        phase("ascent", t.ascent, t.burn, SCREEN.ascent),
+        phase("burn", t.burn, t.coast, SCREEN.burn),
+        phase("coast", t.coast, t.flip, SCREEN.coast),
+        phase("flip", t.flip, t.brake, SCREEN.flip),
+    ];
+    let end = t.brake;
+    if (!flyby) {
+        phases.push(phase("brake", end, end + brakeS, SCREEN.brake));
+        end += brakeS;
+    }
+    else
+        phases.push(phase("flyby", end, end + 60, SCREEN.brake));
+    if (flyby)
+        end += 60;
+    phases.push(phase("arrival", end, end + ARRIVAL_S, SCREEN.arrival));
+    end += ARRIVAL_S;
+    const peakSpeed = Math.max(burnEndSpeed, captureSpeedIn) * 1000;
+    const peakG = Math.max((dv1 * 1000) / burnS / G0, flyby ? 0 : brakeG);
+    let verdict;
+    const because = [verdictCap.line];
+    if (flyby) {
+        because.push(`${payload.name} can change its speed by ${Math.round(dvAvailable).toLocaleString("en-US")} m/s; stopping at ${stopName(source, to)} needs ${Math.round(dv2 * 1000).toLocaleString("en-US")} m/s.`);
+        verdict = { level: "flyby", line: `Flyby only: not enough fuel on board to stop at ${stopName(source, to)} (${Math.round(dv2 * 1000).toLocaleString("en-US")} m/s needed, ${Math.round(dvAvailable).toLocaleString("en-US")} m/s on board).`, because, playable: true };
+    }
+    else {
+        verdict = { level: verdictCap.level, line: verdictCap.line, because, playable: true };
+        if (verdictCap.level === "not-rated")
+            because.push("The burns below are worked from the physics; nothing says this craft can lift them.");
+    }
+    if (estimated.length > 0)
+        because.push(`Estimated, not from a source: ${[...new Set(estimated)].join(", ")}.`);
+    const isp = payload.ispS?.value ?? null;
+    const braking = flyby ? 0 : dv2 * 1000;
+    const fuel = isp !== null && mass !== null && !flyby
+        ? { usedT: (mass * (1 - Math.exp(-braking / (isp * G0)))) / 1000, carriedT: null, note: "the braking burn only, from the engine's specific impulse and the payload's mass" }
+        : { usedT: null, carriedT: null, note: flyby ? "it does not brake, so it burns no propellant at the far end" : "no source gives the specific impulse of this payload's engine" };
+    const toName = stopName(source, to);
+    const carries = verdictCap.kg !== undefined
+        ? { kg: verdictCap.kg, atLeast: verdictCap.level === "at-least", note: `Payload to ${toName}` }
+        : { kg: null, atLeast: false, note: `no published payload figure covers a trip to ${toName}` };
+    return {
+        from,
+        to,
+        craftId: craft.id,
+        drive: "ballistic",
+        frame,
+        departMs,
+        liftoffBeforeS: ascentS,
+        phases,
+        totalS: end,
+        verdict,
+        estimated: [...new Set(estimated)],
+        straightKm,
+        pathKm,
+        fuel,
+        payload: carries,
+        dv: { departure: dv1 * 1000, arrival: flyby ? 0 : dv2 * 1000, total: (dv1 + (flyby ? 0 : dv2)) * 1000 },
+        peakG,
+        peakSpeed,
+        peakGamma: 1,
+        shipS: end,
+        frameS: end,
+        ballistic: { mu, r1, r2, theta0, transitS, parkKm: rPark, parkSpeed, burnEndSpeed, captureKm, captureSpeedIn, captureSpeedOut, burnS, brakeS, flipS, ascentS, vInfDeparture: vInf1, vInfArrival: vInf2, arc, c3 },
+    };
+}
+function planContinuous(source, craft, from, to, departMs) {
+    const estimated = [];
+    const frame = from === "moon" || to === "moon" ? "earth" : "sun";
+    if ((from === "moon" || to === "moon") && from !== "earth" && to !== "earth")
+        return unavailable(craft, from, to, departMs, "The Moon can be reached from the Earth only, for now.", []);
+    const a = craft.g.value * G0;
+    const flipS = quantity(craft.flipS, "turn-round time", estimated) ?? 600;
+    const startAt = positionKm(source, from, departMs, frame);
+    let seconds = 2 * Math.sqrt((len(sub(positionKm(source, to, departMs, frame), startAt)) * 1000) / a);
+    let from3 = startAt;
+    let to3 = positionKm(source, to, departMs, frame);
+    let distanceM = 0;
+    let plan = flipAndBurn(1, a, 0);
+    for (let i = 0; i < 6; i += 1) {
+        to3 = positionKm(source, to, departMs + seconds * 1000, frame);
+        const line = sub(to3, startAt);
+        const d = len(line);
+        const unit = [line[0] / d, line[1] / d, line[2] / d];
+        const startRadius = parkRadius(source, from);
+        const endRadius = parkRadius(source, to);
+        from3 = [startAt[0] + unit[0] * startRadius, startAt[1] + unit[1] * startRadius, startAt[2] + unit[2] * startRadius];
+        const arrive = [to3[0] - unit[0] * endRadius, to3[1] - unit[1] * endRadius, to3[2] - unit[2] * endRadius];
+        to3 = arrive;
+        distanceM = len(sub(arrive, from3)) * 1000;
+        plan = flipAndBurn(distanceM, a, flipS);
+        seconds = plan.frameSeconds;
+    }
+    // The straight path must stay clear of the Sun.
+    let blockedBySun = false;
+    if (frame === "sun") {
+        const ab = sub(to3, from3);
+        const t = Math.max(0, Math.min(1, -(from3[0] * ab[0] + from3[1] * ab[1] + from3[2] * ab[2]) / (ab[0] ** 2 + ab[1] ** 2 + ab[2] ** 2)));
+        const closest = len([from3[0] + ab[0] * t, from3[1] + ab[1] * t, from3[2] + ab[2] * t]);
+        blockedBySun = closest < 0.1 * AU_KM;
+    }
+    const fullT = craft.dryT.value + craft.payloadT.value + craft.propellantT.value;
+    const ratio = Math.exp((2 * plan.rapidity) / craft.exhaustOfC.value);
+    const usedT = fullT - fullT / ratio;
+    const carried = craft.propellantT.value;
+    const tb = plan.burnSeconds;
+    const phases = [
+        phase("preheat", -13, -3, SCREEN.preheat),
+        phase("ignition", -3, 0, SCREEN.ignition),
+        phase("accelerate", 0, tb, SCREEN.accelerate),
+        phase("flip", tb, tb + flipS, SCREEN.flip),
+        phase("decelerate", tb + flipS, plan.frameSeconds, SCREEN.decelerate),
+        phase("arrival", plan.frameSeconds, plan.frameSeconds + ARRIVAL_S, SCREEN.arrival),
+    ];
+    const because = [`Needs ${Math.round(usedT).toLocaleString("en-US")} t of propellant; the ship carries ${Math.round(carried).toLocaleString("en-US")} t.`];
+    let verdict;
+    if (blockedBySun)
+        verdict = { level: "cannot", line: `The straight path passes too close to the Sun: pick another date.`, because, playable: false };
+    else if (usedT > carried)
+        verdict = { level: "cannot", line: `Not enough fuel: this trip needs ${Math.round(usedT).toLocaleString("en-US")} t of propellant and the ship carries ${Math.round(carried).toLocaleString("en-US")} t.`, because, playable: false };
+    else
+        verdict = { level: "ok", line: `Can do it: ${(usedT / carried * 100) >= 1 ? (usedT / carried * 100).toFixed(0) : (usedT / carried * 100).toPrecision(2)} per cent of the propellant, at ${craft.g.value} g.`, because, playable: true };
+    if (estimated.length > 0)
+        because.push(`Estimated, not from a source: ${[...new Set(estimated)].join(", ")}.`);
+    const peak = accelerating(a, tb);
+    return {
+        from,
+        to,
+        craftId: craft.id,
+        drive: "continuous",
+        frame,
+        departMs,
+        liftoffBeforeS: 0,
+        phases,
+        totalS: plan.frameSeconds + ARRIVAL_S,
+        verdict,
+        estimated: [...new Set(estimated)],
+        straightKm: len(sub(positionKm(source, to, departMs, frame), startAt)),
+        pathKm: distanceM / 1000,
+        dv: { departure: C * plan.rapidity, arrival: C * plan.rapidity, total: 2 * C * plan.rapidity },
+        peakG: craft.g.value,
+        peakSpeed: peak.v,
+        peakGamma: peak.gamma,
+        shipS: plan.properSeconds,
+        frameS: plan.frameSeconds,
+        propellantUsedT: usedT,
+        propellantCarriedT: carried,
+        fuel: { usedT, carriedT: carried, note: "the whole trip, from the exhaust speed" },
+        payload: { kg: craft.payloadT.value * 1000, atLeast: false, note: `Payload to ${stopName(source, to)}` },
+        continuous: { from: from3, to: to3, a, burnS: tb, flipS, peakRapidity: plan.rapidity, blockedBySun },
+    };
+}
+/**
+ * The departure date, for a craft that burns all the way, with the shortest trip in the next two years.
+ * @param source Where the places are.
+ * @param craft The craft.
+ * @param from The starting place's id.
+ * @param to The destination's id.
+ * @param afterMs The earliest date.
+ * @returns The date, milliseconds since 1970.
+ * @example
+ * ```ts no-run
+ * import { bestDate, craftOf, type BodySource } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const source: BodySource;
+ * console.log(new Date(bestDate(source, craftOf("kaminari")!, "earth", "mars", Date.UTC(2026, 10, 4))).toISOString());
+ * ```
+ */
+export function bestDate(source, craft, from, to, afterMs) {
+    let best = afterMs;
+    let bestS = Infinity;
+    for (let day = 0; day <= 800; day += 4) {
+        const at = afterMs + day * DAY_S * 1000;
+        const trip = planTrip(source, craft, from, to, at);
+        if (trip.verdict.playable && trip.frameS < bestS) {
+            bestS = trip.frameS;
+            best = at;
+        }
+    }
+    return best;
+}

package/dist/journey/words.d.ts

@@ -0,0 +1,96 @@
+/**
+ * A distance in kilometres, with groups of three digits.
+ * @param km Kilometres.
+ * @returns For example `149 597 871 km`.
+ * @example
+ * ```ts
+ * import { kilometres } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(kilometres(149_597_870.7));
+ * ```
+ */
+export declare const kilometres: (km: number) => string;
+/**
+ * A distance in astronomical units.
+ * @param km Kilometres.
+ * @returns For example `1.000 AU`, or `0.00257 AU` for a small one.
+ * @example
+ * ```ts
+ * import { astronomicalUnits } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(astronomicalUnits(149_597_870.7));
+ * ```
+ */
+export declare const astronomicalUnits: (km: number) => string;
+/**
+ * The time light takes to cross a distance, in the unit that reads best.
+ * @param km Kilometres.
+ * @returns For example `1.28 light-seconds`, `8.3 light-minutes` or `4.37 light-years`.
+ * @example
+ * ```ts
+ * import { lightTime } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(lightTime(384_400), lightTime(149_597_870.7));
+ * ```
+ */
+export declare function lightTime(km: number): string;
+/**
+ * A length of time, in the units that read best.
+ * @param seconds Seconds.
+ * @returns For example `11 min 40 s`, `5 d 2 h` or `258 d 20 h`.
+ * @example
+ * ```ts
+ * import { duration } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(duration(700), duration(258.8 * 86400));
+ * ```
+ */
+export declare function duration(seconds: number): string;
+/**
+ * A speed in metres a second as metres, kilometres or kilometres a second.
+ * @param ms Metres a second.
+ * @returns For example `7.79 km/s` or `340 m/s`.
+ * @example
+ * ```ts
+ * import { speedWords } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(speedWords(7790), speedWords(340));
+ * ```
+ */
+export declare function speedWords(ms: number): string;
+/**
+ * The share of the speed of light, with enough digits that it is never rounded up to 100: `99.999 999 99 %` for a speed a hair under c.
+ * @param ms Metres a second.
+ * @returns The percent, in groups of three digits.
+ * @example
+ * ```ts
+ * import { percentOfLight } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(percentOfLight(29_780), percentOfLight(299_792_457.9999));
+ * ```
+ */
+export declare function percentOfLight(ms: number): string;
+/**
+ * An acceleration in g.
+ * @param g Standard gravities (positive or negative).
+ * @returns For example `0.21 g`, `1.13 g`, `0.015 g`.
+ * @example
+ * ```ts
+ * import { gWords } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(gWords(0.2138), gWords(0.015));
+ * ```
+ */
+export declare function gWords(g: number): string;
+/**
+ * A mass in tonnes.
+ * @param tonnes Tonnes.
+ * @returns For example `43.5 t`, `6.35 million t`.
+ * @example
+ * ```ts
+ * import { tonnesWords } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(tonnesWords(43.5), tonnesWords(6_350_000));
+ * ```
+ */
+export declare const tonnesWords: (tonnes: number) => string;

package/dist/journey/words.js

@@ -0,0 +1,144 @@
+// Numbers as words for the panel: distances in kilometres, astronomical units and light time, times, speeds, and the share of the speed of light with as many digits as it needs. Pure; no language in it but the numbers.
+import { AU_KM, C } from "./constants.js";
+const GROUP = " ";
+/** Whole digits in groups of three, with a narrow space between: 150 000 000. */
+function group(digits) {
+    const [whole = "", fraction] = digits.split(".");
+    const spaced = whole.replace(/\B(?=(\d{3})+(?!\d))/g, GROUP);
+    if (fraction === undefined)
+        return spaced;
+    return `${spaced}.${fraction.length >= 6 ? fraction.replace(/(\d{3})(?=\d)/g, `$1${GROUP}`) : fraction}`;
+}
+/**
+ * A distance in kilometres, with groups of three digits.
+ * @param km Kilometres.
+ * @returns For example `149 597 871 km`.
+ * @example
+ * ```ts
+ * import { kilometres } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(kilometres(149_597_870.7));
+ * ```
+ */
+export const kilometres = (km) => `${group(Math.round(km).toString())} km`;
+/**
+ * A distance in astronomical units.
+ * @param km Kilometres.
+ * @returns For example `1.000 AU`, or `0.00257 AU` for a small one.
+ * @example
+ * ```ts
+ * import { astronomicalUnits } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(astronomicalUnits(149_597_870.7));
+ * ```
+ */
+export const astronomicalUnits = (km) => {
+    const au = km / AU_KM;
+    return `${au >= 0.1 ? au.toFixed(3) : au.toPrecision(3)} AU`;
+};
+/**
+ * The time light takes to cross a distance, in the unit that reads best.
+ * @param km Kilometres.
+ * @returns For example `1.28 light-seconds`, `8.3 light-minutes` or `4.37 light-years`.
+ * @example
+ * ```ts
+ * import { lightTime } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(lightTime(384_400), lightTime(149_597_870.7));
+ * ```
+ */
+export function lightTime(km) {
+    const s = (km * 1000) / C;
+    if (s < 120)
+        return `${s.toFixed(2)} light-seconds`;
+    if (s < 7200)
+        return `${(s / 60).toFixed(1)} light-minutes`;
+    if (s < 172_800)
+        return `${(s / 3600).toFixed(1)} light-hours`;
+    if (s < 31_557_600)
+        return `${(s / 86_400).toFixed(1)} light-days`;
+    return `${(s / 31_557_600).toFixed(2)} light-years`;
+}
+/**
+ * A length of time, in the units that read best.
+ * @param seconds Seconds.
+ * @returns For example `11 min 40 s`, `5 d 2 h` or `258 d 20 h`.
+ * @example
+ * ```ts
+ * import { duration } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(duration(700), duration(258.8 * 86400));
+ * ```
+ */
+export function duration(seconds) {
+    const s = Math.max(0, seconds);
+    if (s < 60)
+        return `${s < 10 ? s.toFixed(1) : Math.round(s)} s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)} min ${Math.round(s % 60)} s`;
+    if (s < 172_800)
+        return `${Math.floor(s / 3600)} h ${Math.round((s % 3600) / 60)} min`;
+    if (s < 63_115_200)
+        return `${Math.floor(s / 86_400)} d ${Math.round((s % 86_400) / 3600)} h`;
+    return `${(s / 31_557_600).toFixed(2)} years`;
+}
+/**
+ * A speed in metres a second as metres, kilometres or kilometres a second.
+ * @param ms Metres a second.
+ * @returns For example `7.79 km/s` or `340 m/s`.
+ * @example
+ * ```ts
+ * import { speedWords } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(speedWords(7790), speedWords(340));
+ * ```
+ */
+export function speedWords(ms) {
+    if (Math.abs(ms) < 1000)
+        return `${Math.round(ms)} m/s`;
+    return `${group((ms / 1000).toFixed(ms < 100_000 ? 2 : 0))} km/s`;
+}
+/**
+ * The share of the speed of light, with enough digits that it is never rounded up to 100: `99.999 999 99 %` for a speed a hair under c.
+ * @param ms Metres a second.
+ * @returns The percent, in groups of three digits.
+ * @example
+ * ```ts
+ * import { percentOfLight } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(percentOfLight(29_780), percentOfLight(299_792_457.9999));
+ * ```
+ */
+export function percentOfLight(ms) {
+    const beta = ms / C;
+    const behind = 1 - beta;
+    const digits = behind > 0 && behind < 0.01 ? Math.min(14, Math.ceil(-Math.log10(behind)) + 1) : beta < 0.001 ? 4 : 3;
+    return `${group((beta * 100).toFixed(Math.max(2, digits)))} %`;
+}
+/**
+ * An acceleration in g.
+ * @param g Standard gravities (positive or negative).
+ * @returns For example `0.21 g`, `1.13 g`, `0.015 g`.
+ * @example
+ * ```ts
+ * import { gWords } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(gWords(0.2138), gWords(0.015));
+ * ```
+ */
+export function gWords(g) {
+    const a = Math.abs(g);
+    return `${a >= 1 ? a.toFixed(2) : a >= 0.1 ? a.toFixed(2) : a.toPrecision(2)} g`;
+}
+/**
+ * A mass in tonnes.
+ * @param tonnes Tonnes.
+ * @returns For example `43.5 t`, `6.35 million t`.
+ * @example
+ * ```ts
+ * import { tonnesWords } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(tonnesWords(43.5), tonnesWords(6_350_000));
+ * ```
+ */
+export const tonnesWords = (tonnes) => (tonnes >= 1e6 ? `${(tonnes / 1e6).toFixed(2)} million t` : `${group(tonnes >= 100 ? Math.round(tonnes).toString() : tonnes.toFixed(1))} t`);