@interstellar-tools/temporal 0.1.1

package/README.md

@@ -0,0 +1,18 @@
+# @interstellar-tools/temporal
+
+## Installation
+
+- [Node.js](https://nodejs.org/) version 22.9.0 or higher
+- npm version 11.5.1 or higher
+
+::: code-group
+
+```shell [npm]
+npm i --save @interstellar-tools/temporal
+```
+
+```shell [yarn]
+yarn add @interstellar-tools/temporal
+```
+
+:::

package/dist/__tests__/convert-temporal-unit.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=convert-temporal-unit.spec.d.ts.map

package/dist/__tests__/convert-temporal-unit.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-temporal-unit.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/convert-temporal-unit.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/convert-temporal-unit.spec.js

@@ -0,0 +1,93 @@
+import assert from 'node:assert/strict';
+import test, { describe } from 'node:test';
+import { convertTemporalUnit } from '../convert-temporal-unit';
+import { JULIAN_YEAR_SECONDS, SECONDS_PER_DAY } from '@interstellar-tools/constants';
+// Helpers
+const EPS_ABS = 1e-9;
+const EPS_REL = 1e-12;
+const approxEqual = (a, b, msg) => {
+    const diff = Math.abs(a - b);
+    const scale = Math.max(1, Math.abs(a), Math.abs(b));
+    assert.ok(diff <= Math.max(EPS_ABS, EPS_REL * scale), msg ?? `expected ~${b}, got ${a}`);
+};
+const conv = (value, unit, target) => {
+    return convertTemporalUnit({ value, unit }, target);
+};
+const CANONICAL = [
+    's',
+    'ms',
+    'μs',
+    'ns',
+    'ps',
+    'fs',
+    'as',
+    'zs',
+    'ys',
+    'min',
+    'h',
+    'd',
+    'yr',
+    'kyr',
+    'Myr',
+    'Gyr'
+];
+const roundTo3 = (v) => Math.round(v * 1000) / 1000;
+describe('convert-temporal-unit', () => {
+    test('identity: all canonical units map to themselves', () => {
+        for (const u of CANONICAL) {
+            const out = conv(123.456, u, u);
+            assert.equal(out.unit, u);
+            assert.equal(roundTo3(out.value), 123.456);
+        }
+    });
+    test('SI submultiples: seconds ↔ ms/μs/ns', () => {
+        assert.equal(conv(2, 's', 'ms').value, 2000);
+        assert.equal(conv(2, 's', 'μs').value, 2000000);
+        approxEqual(conv(2, 's', 'ns').value, 2000000000);
+        approxEqual(conv(500, 'ms', 's').value, 0.5);
+        approxEqual(conv(250000, 'μs', 's').value, 0.25);
+    });
+    test('minutes/hours/days basics', () => {
+        assert.equal(conv(90, 'min', 'h').value, 1.5);
+        assert.equal(conv(2, 'h', 'min').value, 120);
+        assert.equal(conv(1, 'd', 'h').value, 24);
+        assert.equal(conv(0.5, 'd', 's').value, SECONDS_PER_DAY / 2);
+    });
+    test('Julian year family: yr ↔ d, kyr/Myr/Gyr scaling', () => {
+        // 1 yr = 365.25 d
+        approxEqual(conv(1, 'yr', 'd').value, 365.25);
+        approxEqual(conv(365.25, 'd', 'yr').value, 1);
+        // Scaling
+        assert.equal(conv(3, 'Myr', 'kyr').value, 3000);
+        assert.equal(conv(2, 'Gyr', 'yr').value, 2000000000);
+        // Seconds linkage
+        approxEqual(conv(1, 'Myr', 's').value, JULIAN_YEAR_SECONDS * 1e6);
+        approxEqual(conv(1e3, 'yr', 's').value, JULIAN_YEAR_SECONDS * 1e3);
+    });
+    test('extremes: yoctoseconds ↔ seconds round-trip', () => {
+        const s = conv(1, 'ys', 's').value;
+        approxEqual(s, 1e-24);
+        const back = conv(s, 's', 'ys').value;
+        approxEqual(back, 1);
+    });
+    test('round-trip property across units', () => {
+        const pairs = [
+            ['h', 's', 2.75],
+            ['d', 'min', 0.125],
+            ['yr', 'd', 3.5],
+            ['kyr', 'yr', 1.234],
+            ['Myr', 'kyr', 0.00042],
+            ['Gyr', 'yr', 0.009]
+        ];
+        for (const [from, mid, val] of pairs) {
+            const midVal = conv(val, from, mid).value;
+            const back = conv(midVal, mid, from).value;
+            approxEqual(back, val, `round-trip failed for ${from}↔${mid}`);
+        }
+    });
+    test('unit labels in output are canonical', () => {
+        const out = conv(42, 'h', 'min');
+        assert.equal(out.unit, 'min');
+    });
+});
+//# sourceMappingURL=convert-temporal-unit.spec.js.map

package/dist/__tests__/convert-temporal-unit.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-temporal-unit.spec.js","sourceRoot":"","sources":["../../src/__tests__/convert-temporal-unit.spec.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/normalize-temporal-units.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=normalize-temporal-units.spec.d.ts.map

package/dist/__tests__/normalize-temporal-units.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-temporal-units.spec.d.ts","sourceRoot":"","sources":["../../src/__tests__/normalize-temporal-units.spec.ts"],"names":[],"mappings":""}

package/dist/__tests__/normalize-temporal-units.spec.js

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test, { describe } from 'node:test';
+import { normalizeTemporalUnit } from '../normalize-temporal-unit';
+const canonical = [
+    's',
+    'ms',
+    'μs',
+    'ns',
+    'ps',
+    'fs',
+    'as',
+    'zs',
+    'ys',
+    'min',
+    'h',
+    'd',
+    'yr',
+    'kyr',
+    'Myr',
+    'Gyr'
+];
+const aliasPairs = [
+    // seconds & submultiples
+    ['second', 's'],
+    ['seconds', 's'],
+    ['millisecond', 'ms'],
+    ['milliseconds', 'ms'],
+    ['microsecond', 'μs'],
+    ['microseconds', 'μs'],
+    ['us', 'μs'],
+    // clock units
+    ['minute', 'min'],
+    ['minutes', 'min'],
+    ['hour', 'h'],
+    ['hours', 'h'],
+    ['day', 'd'],
+    ['days', 'd'],
+    // years & multiples (Julian-year-based)
+    ['year', 'yr'],
+    ['years', 'yr'],
+    ['yr', 'yr'],
+    ['yrs', 'yr'],
+    ['kiloyear', 'kyr'],
+    ['kiloyears', 'kyr'],
+    ['kyr', 'kyr'],
+    // million years (geology/astro spellings)
+    ['megayear', 'Myr'],
+    ['megayears', 'Myr'],
+    ['megaannum', 'Myr'],
+    ['megaannums', 'Myr'],
+    ['Myr', 'Myr'],
+    ['Ma', 'Myr'],
+    // billion years
+    ['gigayear', 'Gyr'],
+    ['gigayears', 'Gyr'],
+    ['gigaannum', 'Gyr'],
+    ['gigaannums', 'Gyr'],
+    ['Gyr', 'Gyr'],
+    ['Ga', 'Gyr']
+];
+describe('normalizeTemporalUnit', () => {
+    test('canonical units map to themselves', () => {
+        for (const u of canonical) {
+            assert.equal(normalizeTemporalUnit(u), u, `expected '${u}' → '${u}'`);
+        }
+    });
+    test('aliases map to canonical symbols', () => {
+        for (const [input, expected] of aliasPairs) {
+            assert.equal(normalizeTemporalUnit(input), expected, `expected '${input}' → '${expected}'`);
+        }
+    });
+    test('trims surrounding whitespace', () => {
+        assert.equal(normalizeTemporalUnit(' seconds '), 's');
+        assert.equal(normalizeTemporalUnit('\tus\n'), 'μs');
+    });
+    test('case-sensitive matching', () => {
+        assert.throws(() => normalizeTemporalUnit('Seconds'), /Unsupported unit: Seconds/, 'capitalized alias should be rejected');
+        assert.throws(() => normalizeTemporalUnit('US'), /Unsupported unit: US/, 'uppercase "US" should not be treated as microseconds');
+    });
+    test('rejects unknown or empty inputs', () => {
+        assert.throws(() => normalizeTemporalUnit(''), /Unsupported unit:/);
+        assert.throws(() => normalizeTemporalUnit('   '), /Unsupported unit:\s+/);
+        assert.throws(() => normalizeTemporalUnit('lightyear'), /Unsupported unit:/);
+    });
+});
+//# sourceMappingURL=normalize-temporal-units.spec.js.map

package/dist/__tests__/normalize-temporal-units.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-temporal-units.spec.js","sourceRoot":"","sources":["../../src/__tests__/normalize-temporal-units.spec.ts"],"names":[],"mappings":"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"}

package/dist/convert-temporal-unit.d.ts

@@ -0,0 +1,67 @@
+import { TemporalInterface, TemporalUnitType } from '@interstellar-tools/types';
+/**
+ * Seconds-per-unit lookup for all canonical {@link TemporalUnitType} symbols.
+ *
+ * ### Conventions
+ * - **Base**: conversions are performed via **seconds**.
+ * - **SI day**: `d = 86 400 s` (from {@link SECONDS_PER_DAY}).
+ * - **Julian year**: `yr = 365.25 d = 31 557 600 s`
+ *   (from {@link JULIAN_YEAR_SECONDS}); `kyr/Myr/Gyr` are powers of 10 thereof.
+ * - Units are **canonical** and **case-sensitive** (e.g., `'μs'` uses the Unicode micro sign).
+ *
+ * $$
+ * \text{seconds}(u) \;=\; \text{value}\times \mathrm{SECONDS\_PER}[u]
+ * $$
+ *
+ * @example
+ * ```ts
+ * // seconds per hour:
+ * SECONDS_PER.h; // 3600
+ *
+ * // seconds in a Julian year:
+ * SECONDS_PER.yr; // 31_557_600
+ * ```
+ * @hidden
+ */
+export declare const SECONDS_PER: Record<TemporalUnitType, number>;
+/**
+ * Convert a temporal **duration** between any two canonical {@link TemporalUnitType} units.
+ *
+ * - Uses {@link SECONDS_PER} with **seconds** as the intermediate unit.
+ * - Interprets `d` as the **SI day** and `yr/kyr/Myr/Gyr` via the **Julian year** convention.
+ * - The `time.unit` is expected to be **canonical**; if you accept aliases upstream,
+ *   normalize them before calling (e.g., with `normalizeTemporalUnit`).
+ * - The `targetUnit` is normalized to a canonical symbol (idempotent for canonical input).
+ *
+ * $$
+ * \text{value}_{\text{target}}
+ * \;=\;
+ * \frac{\text{value}_{\text{in}} \cdot \mathrm{SECONDS\_PER}[u_{\text{in}}]}
+ *      {\mathrm{SECONDS\_PER}[u_{\text{out}}]}
+ * $$
+ *
+ * @param time       Input duration `{ value, unit }` in canonical units.
+ * @param targetUnit Desired canonical output unit (will be normalized).
+ * @returns          A new `{ value, unit }` where `unit` is the canonical target symbol.
+ *
+ * @example
+ * ```ts
+ * convertTemporalUnit({ value: 2, unit: 'h' }, 'min');
+ * // → { value: 120, unit: 'min' }
+ *
+ * convertTemporalUnit({ value: 1, unit: 'd' }, 's');
+ * // → { value: 86_400, unit: 's' }
+ *
+ * convertTemporalUnit({ value: 3, unit: 'Myr' }, 'kyr');
+ * // → { value: 3000, unit: 'kyr' }
+ *
+ * convertTemporalUnit({ value: 1, unit: 'yr' }, 'd');
+ * // → { value: 365.25, unit: 'd' }
+ * ```
+ *
+ * @see SECONDS_PER_DAY
+ * @see JULIAN_YEAR_SECONDS
+ * @see normalizeTemporalUnit
+ */
+export declare const convertTemporalUnit: (time: TemporalInterface, targetUnit: TemporalUnitType) => TemporalInterface;
+//# sourceMappingURL=convert-temporal-unit.d.ts.map

package/dist/convert-temporal-unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-temporal-unit.d.ts","sourceRoot":"","sources":["../src/convert-temporal-unit.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAIhF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAsBxD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,mBAAmB,GAC9B,MAAM,iBAAiB,EACvB,YAAY,gBAAgB,KAC3B,iBASF,CAAC"}

package/dist/convert-temporal-unit.js

@@ -0,0 +1,96 @@
+import { JULIAN_YEAR_SECONDS, SECONDS_PER_DAY } from '@interstellar-tools/constants';
+import { normalizeTemporalUnit } from './normalize-temporal-unit';
+/**
+ * Seconds-per-unit lookup for all canonical {@link TemporalUnitType} symbols.
+ *
+ * ### Conventions
+ * - **Base**: conversions are performed via **seconds**.
+ * - **SI day**: `d = 86 400 s` (from {@link SECONDS_PER_DAY}).
+ * - **Julian year**: `yr = 365.25 d = 31 557 600 s`
+ *   (from {@link JULIAN_YEAR_SECONDS}); `kyr/Myr/Gyr` are powers of 10 thereof.
+ * - Units are **canonical** and **case-sensitive** (e.g., `'μs'` uses the Unicode micro sign).
+ *
+ * $$
+ * \text{seconds}(u) \;=\; \text{value}\times \mathrm{SECONDS\_PER}[u]
+ * $$
+ *
+ * @example
+ * ```ts
+ * // seconds per hour:
+ * SECONDS_PER.h; // 3600
+ *
+ * // seconds in a Julian year:
+ * SECONDS_PER.yr; // 31_557_600
+ * ```
+ * @hidden
+ */
+export const SECONDS_PER = {
+    // SI base & submultiples
+    s: 1,
+    ms: 1e-3,
+    μs: 1e-6,
+    ns: 1e-9,
+    ps: 1e-12,
+    fs: 1e-15,
+    as: 1e-18,
+    zs: 1e-21,
+    ys: 1e-24,
+    // convenient larger units
+    min: 60,
+    h: 60 * 60,
+    d: SECONDS_PER_DAY,
+    // year family (Julian-year-based)
+    yr: JULIAN_YEAR_SECONDS,
+    kyr: JULIAN_YEAR_SECONDS * 1e3,
+    Myr: JULIAN_YEAR_SECONDS * 1e6,
+    Gyr: JULIAN_YEAR_SECONDS * 1e9
+};
+/**
+ * Convert a temporal **duration** between any two canonical {@link TemporalUnitType} units.
+ *
+ * - Uses {@link SECONDS_PER} with **seconds** as the intermediate unit.
+ * - Interprets `d` as the **SI day** and `yr/kyr/Myr/Gyr` via the **Julian year** convention.
+ * - The `time.unit` is expected to be **canonical**; if you accept aliases upstream,
+ *   normalize them before calling (e.g., with `normalizeTemporalUnit`).
+ * - The `targetUnit` is normalized to a canonical symbol (idempotent for canonical input).
+ *
+ * $$
+ * \text{value}_{\text{target}}
+ * \;=\;
+ * \frac{\text{value}_{\text{in}} \cdot \mathrm{SECONDS\_PER}[u_{\text{in}}]}
+ *      {\mathrm{SECONDS\_PER}[u_{\text{out}}]}
+ * $$
+ *
+ * @param time       Input duration `{ value, unit }` in canonical units.
+ * @param targetUnit Desired canonical output unit (will be normalized).
+ * @returns          A new `{ value, unit }` where `unit` is the canonical target symbol.
+ *
+ * @example
+ * ```ts
+ * convertTemporalUnit({ value: 2, unit: 'h' }, 'min');
+ * // → { value: 120, unit: 'min' }
+ *
+ * convertTemporalUnit({ value: 1, unit: 'd' }, 's');
+ * // → { value: 86_400, unit: 's' }
+ *
+ * convertTemporalUnit({ value: 3, unit: 'Myr' }, 'kyr');
+ * // → { value: 3000, unit: 'kyr' }
+ *
+ * convertTemporalUnit({ value: 1, unit: 'yr' }, 'd');
+ * // → { value: 365.25, unit: 'd' }
+ * ```
+ *
+ * @see SECONDS_PER_DAY
+ * @see JULIAN_YEAR_SECONDS
+ * @see normalizeTemporalUnit
+ */
+export const convertTemporalUnit = (time, targetUnit) => {
+    const normalizedTargetUnit = normalizeTemporalUnit(targetUnit);
+    const { value, unit } = time;
+    // Convert input to seconds
+    const inSeconds = value * SECONDS_PER[unit];
+    // Convert seconds to target
+    const convertedValue = inSeconds / SECONDS_PER[normalizedTargetUnit];
+    return { value: convertedValue, unit: normalizedTargetUnit };
+};
+//# sourceMappingURL=convert-temporal-unit.js.map

package/dist/convert-temporal-unit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-temporal-unit.js","sourceRoot":"","sources":["../src/convert-temporal-unit.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,eAAe,EAChB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAqC;IAC3D,yBAAyB;IACzB,CAAC,EAAE,CAAC;IACJ,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,KAAK;IACT,EAAE,EAAE,KAAK;IACT,EAAE,EAAE,KAAK;IACT,EAAE,EAAE,KAAK;IACT,EAAE,EAAE,KAAK;IAET,0BAA0B;IAC1B,GAAG,EAAE,EAAE;IACP,CAAC,EAAE,EAAE,GAAG,EAAE;IACV,CAAC,EAAE,eAAe;IAElB,kCAAkC;IAClC,EAAE,EAAE,mBAAmB;IACvB,GAAG,EAAE,mBAAmB,GAAG,GAAG;IAC9B,GAAG,EAAE,mBAAmB,GAAG,GAAG;IAC9B,GAAG,EAAE,mBAAmB,GAAG,GAAG;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,IAAuB,EACvB,UAA4B,EACT,EAAE;IACrB,MAAM,oBAAoB,GAAG,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC/D,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IAC7B,2BAA2B;IAC3B,MAAM,SAAS,GAAG,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC5C,4BAA4B;IAC5B,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC,oBAAoB,CAAC,CAAC;IAErE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;AAC/D,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './convert-temporal-unit';
+export * from './normalize-temporal-unit';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AAExC,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './convert-temporal-unit';
+export * from './normalize-temporal-unit';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AAExC,cAAc,2BAA2B,CAAC"}

package/dist/normalize-temporal-unit.d.ts

@@ -0,0 +1,116 @@
+import type { TemporalUnitType } from '@interstellar-tools/types';
+/**
+ * Lookup table that **normalizes user-facing time unit aliases** (and the canonical
+ * symbols themselves) to a single, canonical {@link TemporalUnitType}.
+ *
+ * ## Purpose
+ * - Centralizes all **string → symbol** normalization (e.g., `"seconds"` → `"s"`, `"us"` → `"μs"`).
+ * - Ensures downstream math uses only **canonical units** (`s`, `ms`, `μs`, `min`, `h`, `d`, `yr`, `kyr`, `Myr`, `Gyr`).
+ *
+ * ## Conventions & semantics
+ * - **Durations only** (no timestamp/"ago" meaning). Geology-style tokens (`Ma`, `Ga`, `megaannum`, `gigaannum`)
+ *   are treated as **durations** and normalized to `Myr`/`Gyr`.
+ * - **Day** is [SI](https://en.wikipedia.org/wiki/International_System_of_Units) day: exactly **86 400 s**.
+ * - **Year family** (`yr`, `kyr`, `Myr`, `Gyr`) is the **Julian year** convention: **365.25 d = 31 557 600 s**.
+ * - **Case-sensitive** and exact matching. The ASCII alias `"us"` is accepted and normalized to the Unicode `μs`.
+ *
+ * ## Usage pattern
+ * - Accept `TemporalUnitAliasType | TemporalUnitType` at your boundaries.
+ * - Normalize with this map.
+ * - Store/compute exclusively with canonical {@link TemporalUnitType}.
+ *
+ * ::: tip
+ *
+ * If you require runtime immutability, wrap with `Object.freeze(NORMALIZE_UNIT)`.
+ *
+ * :::
+ *
+ * @see https://www.bipm.org/en/publications/si-brochure  ([SI](https://en.wikipedia.org/wiki/International_System_of_Units) Brochure — second & day)
+ * @see https://en.wikipedia.org/wiki/Julian_year_(astronomy) (Julian year for yr/kyr/Myr/Gyr)
+ */
+export declare const NORMALIZE_UNIT: {
+    readonly s: "s";
+    readonly ms: "ms";
+    readonly μs: "μs";
+    readonly ns: "ns";
+    readonly ps: "ps";
+    readonly fs: "fs";
+    readonly as: "as";
+    readonly zs: "zs";
+    readonly ys: "ys";
+    readonly min: "min";
+    readonly h: "h";
+    readonly d: "d";
+    readonly yr: "yr";
+    readonly kyr: "kyr";
+    readonly Myr: "Myr";
+    readonly Gyr: "Gyr";
+    readonly second: "s";
+    readonly seconds: "s";
+    readonly millisecond: "ms";
+    readonly milliseconds: "ms";
+    readonly microsecond: "μs";
+    readonly microseconds: "μs";
+    readonly us: "μs";
+    readonly minute: "min";
+    readonly minutes: "min";
+    readonly hour: "h";
+    readonly hours: "h";
+    readonly day: "d";
+    readonly days: "d";
+    readonly year: "yr";
+    readonly years: "yr";
+    readonly yrs: "yr";
+    readonly kiloyear: "kyr";
+    readonly kiloyears: "kyr";
+    readonly megayear: "Myr";
+    readonly megayears: "Myr";
+    readonly megaannum: "Myr";
+    readonly megaannums: "Myr";
+    readonly Ma: "Myr";
+    readonly gigayear: "Gyr";
+    readonly gigayears: "Gyr";
+    readonly gigaannum: "Gyr";
+    readonly gigaannums: "Gyr";
+    readonly Ga: "Gyr";
+};
+/**
+ * Normalize a user-provided **temporal unit string** into a canonical {@link TemporalUnitType}.
+ *
+ * - Trims surrounding whitespace.
+ * - Accepts both **canonical symbols** (e.g., `"s"`, `"ms"`, `"μs"`, `"min"`, `"h"`, `"d"`, `"yr"`, `"kyr"`, `"Myr"`, `"Gyr"`)
+ *   and **aliases** (e.g., `"seconds"`, `"milliseconds"`, `"us"`, `"hours"`, `"years"`, `"Ma"`, `"Ga"`),
+ *   using {@link NORMALIZE_UNIT} as the single source of truth.
+ * - Returns a **canonical** unit suitable for arithmetic, storage, and serialization.
+ *
+ * ### Conventions
+ * - **Durations only** (no timestamp or "ago" semantics). Geology-style tokens like `"Ma"`/`"Ga"` are
+ *   interpreted as durations and normalized to `"Myr"`/`"Gyr"`.
+ * - **Case-sensitive** exact match against {@link NORMALIZE_UNIT}. For example, `"Seconds"` (capital S)
+ *   will fail; use `"seconds"` instead, or pre-normalize casing upstream if desired.
+ * - The ASCII alias `"us"` is accepted and normalized to the Unicode microsecond symbol `"μs"`.
+ *
+ * @param u - The input unit string. Leading/trailing whitespace is ignored; content is **case-sensitive**.
+ * @returns The canonical {@link TemporalUnitType} (e.g., `"s"`, `"ms"`, `"μs"`, `"min"`, `"h"`, `"d"`, `"yr"`, `"kyr"`, `"Myr"`, `"Gyr"`).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError | RangeError}  If `u` does not match any known key in {@link NORMALIZE_UNIT}.
+ *
+ * @example
+ * ```ts
+ * // Canonical conversion using the normalized unit:
+ * const unit = normalizeTemporalUnit(' seconds '); // → 's'
+ * const valueInSeconds = 2 * (unit === 's' ? 1 : NaN); // 2
+ *
+ * normalizeTemporalUnit('us');   // → 'μs'
+ * normalizeTemporalUnit('Myr');  // → 'Myr' (already canonical)
+ * normalizeTemporalUnit('Ma');   // → 'Myr' (geology-style alias)
+ * normalizeTemporalUnit('Ga');   // → 'Gyr'
+ * // normalizeTemporalUnit('Seconds'); // throws (case-sensitive)
+ * ```
+ *
+ * @see {@link NORMALIZE_UNIT} for the complete alias→canonical mapping.
+ * @see https://www.bipm.org/en/publications/si-brochure (SI Brochure — second/day)
+ * @see https://en.wikipedia.org/wiki/Julian_year_(astronomy) (Julian year for yr/kyr/Myr/Gyr)
+ */
+export declare const normalizeTemporalUnit: (u: string) => TemporalUnitType;
+//# sourceMappingURL=normalize-temporal-unit.d.ts.map

package/dist/normalize-temporal-unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-temporal-unit.d.ts","sourceRoot":"","sources":["../src/normalize-temporal-unit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoD1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,qBAAqB,GAAI,GAAG,MAAM,KAAG,gBAOjD,CAAC"}

package/dist/normalize-temporal-unit.js

@@ -0,0 +1,123 @@
+/**
+ * Lookup table that **normalizes user-facing time unit aliases** (and the canonical
+ * symbols themselves) to a single, canonical {@link TemporalUnitType}.
+ *
+ * ## Purpose
+ * - Centralizes all **string → symbol** normalization (e.g., `"seconds"` → `"s"`, `"us"` → `"μs"`).
+ * - Ensures downstream math uses only **canonical units** (`s`, `ms`, `μs`, `min`, `h`, `d`, `yr`, `kyr`, `Myr`, `Gyr`).
+ *
+ * ## Conventions & semantics
+ * - **Durations only** (no timestamp/"ago" meaning). Geology-style tokens (`Ma`, `Ga`, `megaannum`, `gigaannum`)
+ *   are treated as **durations** and normalized to `Myr`/`Gyr`.
+ * - **Day** is [SI](https://en.wikipedia.org/wiki/International_System_of_Units) day: exactly **86 400 s**.
+ * - **Year family** (`yr`, `kyr`, `Myr`, `Gyr`) is the **Julian year** convention: **365.25 d = 31 557 600 s**.
+ * - **Case-sensitive** and exact matching. The ASCII alias `"us"` is accepted and normalized to the Unicode `μs`.
+ *
+ * ## Usage pattern
+ * - Accept `TemporalUnitAliasType | TemporalUnitType` at your boundaries.
+ * - Normalize with this map.
+ * - Store/compute exclusively with canonical {@link TemporalUnitType}.
+ *
+ * ::: tip
+ *
+ * If you require runtime immutability, wrap with `Object.freeze(NORMALIZE_UNIT)`.
+ *
+ * :::
+ *
+ * @see https://www.bipm.org/en/publications/si-brochure  ([SI](https://en.wikipedia.org/wiki/International_System_of_Units) Brochure — second & day)
+ * @see https://en.wikipedia.org/wiki/Julian_year_(astronomy) (Julian year for yr/kyr/Myr/Gyr)
+ */
+export const NORMALIZE_UNIT = {
+    // canonical already map to themselves:
+    s: 's',
+    ms: 'ms',
+    μs: 'μs',
+    ns: 'ns',
+    ps: 'ps',
+    fs: 'fs',
+    as: 'as',
+    zs: 'zs',
+    ys: 'ys',
+    min: 'min',
+    h: 'h',
+    d: 'd',
+    yr: 'yr',
+    kyr: 'kyr',
+    Myr: 'Myr',
+    Gyr: 'Gyr',
+    // aliases → canonical
+    second: 's',
+    seconds: 's',
+    millisecond: 'ms',
+    milliseconds: 'ms',
+    microsecond: 'μs',
+    microseconds: 'μs',
+    us: 'μs',
+    minute: 'min',
+    minutes: 'min',
+    hour: 'h',
+    hours: 'h',
+    day: 'd',
+    days: 'd',
+    year: 'yr',
+    years: 'yr',
+    yrs: 'yr',
+    kiloyear: 'kyr',
+    kiloyears: 'kyr',
+    megayear: 'Myr',
+    megayears: 'Myr',
+    megaannum: 'Myr',
+    megaannums: 'Myr',
+    Ma: 'Myr',
+    gigayear: 'Gyr',
+    gigayears: 'Gyr',
+    gigaannum: 'Gyr',
+    gigaannums: 'Gyr',
+    Ga: 'Gyr'
+};
+/**
+ * Normalize a user-provided **temporal unit string** into a canonical {@link TemporalUnitType}.
+ *
+ * - Trims surrounding whitespace.
+ * - Accepts both **canonical symbols** (e.g., `"s"`, `"ms"`, `"μs"`, `"min"`, `"h"`, `"d"`, `"yr"`, `"kyr"`, `"Myr"`, `"Gyr"`)
+ *   and **aliases** (e.g., `"seconds"`, `"milliseconds"`, `"us"`, `"hours"`, `"years"`, `"Ma"`, `"Ga"`),
+ *   using {@link NORMALIZE_UNIT} as the single source of truth.
+ * - Returns a **canonical** unit suitable for arithmetic, storage, and serialization.
+ *
+ * ### Conventions
+ * - **Durations only** (no timestamp or "ago" semantics). Geology-style tokens like `"Ma"`/`"Ga"` are
+ *   interpreted as durations and normalized to `"Myr"`/`"Gyr"`.
+ * - **Case-sensitive** exact match against {@link NORMALIZE_UNIT}. For example, `"Seconds"` (capital S)
+ *   will fail; use `"seconds"` instead, or pre-normalize casing upstream if desired.
+ * - The ASCII alias `"us"` is accepted and normalized to the Unicode microsecond symbol `"μs"`.
+ *
+ * @param u - The input unit string. Leading/trailing whitespace is ignored; content is **case-sensitive**.
+ * @returns The canonical {@link TemporalUnitType} (e.g., `"s"`, `"ms"`, `"μs"`, `"min"`, `"h"`, `"d"`, `"yr"`, `"kyr"`, `"Myr"`, `"Gyr"`).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError | RangeError}  If `u` does not match any known key in {@link NORMALIZE_UNIT}.
+ *
+ * @example
+ * ```ts
+ * // Canonical conversion using the normalized unit:
+ * const unit = normalizeTemporalUnit(' seconds '); // → 's'
+ * const valueInSeconds = 2 * (unit === 's' ? 1 : NaN); // 2
+ *
+ * normalizeTemporalUnit('us');   // → 'μs'
+ * normalizeTemporalUnit('Myr');  // → 'Myr' (already canonical)
+ * normalizeTemporalUnit('Ma');   // → 'Myr' (geology-style alias)
+ * normalizeTemporalUnit('Ga');   // → 'Gyr'
+ * // normalizeTemporalUnit('Seconds'); // throws (case-sensitive)
+ * ```
+ *
+ * @see {@link NORMALIZE_UNIT} for the complete alias→canonical mapping.
+ * @see https://www.bipm.org/en/publications/si-brochure (SI Brochure — second/day)
+ * @see https://en.wikipedia.org/wiki/Julian_year_(astronomy) (Julian year for yr/kyr/Myr/Gyr)
+ */
+export const normalizeTemporalUnit = (u) => {
+    const k = u.trim();
+    const v = NORMALIZE_UNIT[k];
+    if (!v)
+        throw new Error(`Unsupported unit: ${u}`);
+    return v;
+};
+//# sourceMappingURL=normalize-temporal-unit.js.map

package/dist/normalize-temporal-unit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-temporal-unit.js","sourceRoot":"","sources":["../src/normalize-temporal-unit.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,uCAAuC;IACvC,CAAC,EAAE,GAAG;IACN,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,GAAG,EAAE,KAAK;IACV,CAAC,EAAE,GAAG;IACN,CAAC,EAAE,GAAG;IACN,EAAE,EAAE,IAAI;IACR,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IAEV,sBAAsB;IACtB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,GAAG;IACZ,WAAW,EAAE,IAAI;IACjB,YAAY,EAAE,IAAI;IAClB,WAAW,EAAE,IAAI;IACjB,YAAY,EAAE,IAAI;IAClB,EAAE,EAAE,IAAI;IACR,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,KAAK;IACd,IAAI,EAAE,GAAG;IACT,KAAK,EAAE,GAAG;IACV,GAAG,EAAE,GAAG;IACR,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,IAAI;IACX,GAAG,EAAE,IAAI;IAET,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,KAAK;IAChB,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;IAChB,UAAU,EAAE,KAAK;IACjB,EAAE,EAAE,KAAK;IACT,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;IAChB,UAAU,EAAE,KAAK;IACjB,EAAE,EAAE,KAAK;CAIV,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAS,EAAoB,EAAE;IACnE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACnB,MAAM,CAAC,GAAG,cAAc,CAAC,CAAgC,CAAC,CAAC;IAE3D,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC;IAElD,OAAO,CAAC,CAAC;AACX,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@interstellar-tools/temporal",
+  "version": "0.1.1",
+  "description": "temporal",
+  "keywords": [
+    "temporal"
+  ],
+  "homepage": "https://phun-ky.net/projects/interstellar-tools",
+  "bugs": {
+    "url": "https://github.com/phun-ky/interstellar-tools/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phun-ky/interstellar-tools.git"
+  },
+  "funding": "https://github.com/phun-ky/interstellar-tools?sponsor=1",
+  "license": "MIT",
+  "author": "Alexander Vassbotn Røyne-Helgesen <alexander@phun-ky.net>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "release": "release-it",
+    "test": "tsx --test **/__tests__/**/*.spec.ts",
+    "pretest:ci": "rm -rf coverage && mkdir -p coverage",
+    "test:ci": "glob -c \"node --import tsx --test --no-warnings --experimental-test-coverage --test-reporter=cobertura --test-reporter-destination=coverage/cobertura-coverage.xml --test-reporter=spec --test-reporter-destination=stdout\" \"**/__tests__/**/*.spec.ts\""
+  },
+  "dependencies": {
+    "@interstellar-tools/types": "^0.1.0",
+    "@interstellar-tools/constants": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.3",
+    "eslint": "^9.27.0",
+    "eslint-config-phun-ky": "^1.0.3",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=22.9.0",
+    "npm": ">=11.5.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}