@smartput/duration

Nanosecond to week, canonical in seconds.

Calendar-free: a week is exactly 604800 seconds here. Months and years are not units of duration, because they are not constant lengths — those live in @smartput/datetime, which has a calendar.

Three doors, one table. The kind descriptor is for the engine, /validate is free functions over JS numbers, /class is an immutable value class — and all three read the same UnitTable, so a unit added once is added everywhere. See Validating without the engine.

Setup

npm add @smartput/duration

Example

import { parseDuration, asDuration, formatDuration } from "@smartput/duration/validate";
import { Duration } from "@smartput/duration/class";

parseDuration("90 min")                     // {"ok":true,"value":90,"unit":"min","raw":"90"}
asDuration("90 min", "s")                   // {"ok":true,"value":5400,"unit":"s","raw":"5400"}
formatDuration(parseDuration("90 min"))     // "90min"
String(Duration.parse("90 min"))            // "90min"

// …and the same table through the engine:
engine.evaluate("30 h - 30 min").formatted  // "29.5 hours"
engine.evaluate("1 wk + 2 d").formatted     // "1.2857 weeks"
engine.evaluate("90 min in h").formatted    // "1.5 hours"

parse and as never throw — they answer { ok: true, … } or { ok: false, code, input }. The value class throws on bad input and Duration.tryParse does not. All three read the one UnitTable below.

Entry points

| Import | Contents | | --- | --- | | @smartput/duration | The package root. | | @smartput/duration/units | The UnitTable: ratios and aliases, with no engine and no Decimal. | | @smartput/duration/validate | Free functions over JS numbers. Ok \| Err, never a throw. | | @smartput/duration/class | The immutable value class. | | @smartput/duration/locale/<id> | One language's words for this kind. 17 ship: en, de, fr, es, pt, it, nl, zh, ja, ar, ru, pl, tr, hi, ko, id, uk. |

Units

Read from the table itself, not typed out — a unit added to the source appears here on the next bun run docs:packages. Ratios are decimal strings, which is what lets the engine widen them to Decimal without a float in between.

DURATION_UNITS

| Unit | Ratio to s | Aliases | | --- | --- | --- | | s | 1 | s sec secs second seconds | | ms | 0.001 | ms millisecond milliseconds | | min | 60 | m min mins minute minutes | | h | 3600 | h hr hrs hour hours | | d | 86400 | d day days | | wk | 604800 | wk wks week weeks |

Runtime exports

Type-only exports are erased and do not appear here.

DURATION_UNITS · duration

Dependencies

• @smartput/kind
• @smartput/shared

What it costs

Ceilings, not measurements. bun run check-size bundles each entry with bun build --minify and fails if a row crosses its ceiling or drops more than 30 % below it — a budget that is only an upper bound reports a vanished graph as a triumph.

| Import | Minified | Gzipped | | --- | --- | --- | | duration/validate parseDuration only | ≤ 1.4 kB | ≤ 750 B |

Generated by scripts/gen-readmes.ts — run bun run docs:readmes. Every output above was produced by running the line beside it. The full page, with live demos, is docs/packages/duration.md.