Interstellar Tools

Appearance

Documentation / @interstellar-tools/temporal / normalizeTemporalUnit

Function: normalizeTemporalUnit() ​

ts
function normalizeTemporalUnit(u: string): TemporalUnitType;

Defined in: normalize-temporal-unit.ts:127

Normalize a user-provided temporal unit string into a canonical 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 NORMALIZE_TEMPORAL_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 NORMALIZE_TEMPORAL_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".

Parameters ​

ParameterTypeDescription
ustringThe input unit string. Leading/trailing whitespace is ignored; content is case-sensitive.

Returns ​

TemporalUnitType

The canonical TemporalUnitType (e.g., "s", "ms", "μs", "min", "h", "d", "yr", "kyr", "Myr", "Gyr").

Throws ​

RangeError If u does not match any known key in NORMALIZE_TEMPORAL_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 ​