Documentation / @interstellar-tools/temporal / convertTemporalUnit

Function: convertTemporalUnit()

function convertTemporalUnit(
  time: TemporalInterface,
  targetUnit:
    | 'second'
    | 'seconds'
    | 'millisecond'
    | 'milliseconds'
    | 'microsecond'
    | 'microseconds'
    | 'us'
    | 'minute'
    | 'minutes'
    | 'hour'
    | 'hours'
    | 'day'
    | 'days'
    | 'year'
    | 'years'
    | 'yr'
    | 'yrs'
    | 'kiloyear'
    | 'kiloyears'
    | 'kyr'
    | 'megayear'
    | 'megayears'
    | 'megaannum'
    | 'megaannums'
    | 'Myr'
    | 'Ma'
    | 'gigayear'
    | 'gigayears'
    | 'gigaannum'
    | 'gigaannums'
    | 'Gyr'
    | 'Ga'
    | 's'
    | 'ms'
    | 'μs'
    | 'ns'
    | 'ps'
    | 'fs'
    | 'as'
    | 'zs'
    | 'ys'
    | 'min'
    | 'h'
    | 'd'
): TemporalInterface;

Defined in: convert-temporal-unit.ts:103

Convert a temporal duration between any two canonical TemporalUnitType units.

• Uses 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 may be a canonical unit or an alias such as 'days'; it is normalized to a canonical symbol.

$${\text{value}}_{\text{target}}=\frac{{\text{value}}_{\text{in}}\cdot \mathrm{SECONDS}\mathrm{\_}\mathrm{PER}[u_{\text{in}}]}{\mathrm{SECONDS}\mathrm{\_}\mathrm{PER}[u_{\text{out}}]}$$

Parameters

Parameter	Type	Description
time	TemporalInterface	Input duration { value, unit } in canonical units.
targetUnit		"second"

Returns

TemporalInterface

A new { value, unit } where unit is the canonical target symbol.

Example

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' }

Throws

If targetUnit is not a known unit or alias.

See

• SECONDS_PER_DAY
• JULIAN_YEAR_SECONDS
• normalizeTemporalUnit