Docs
Fast path to Unit conversion, parsing, opt-in localization, and API reference.
Unit docs
Unit is TypeScript measurement toolkit for converting, parsing, formatting, validating, and inspecting units in real app flows.
Core idea:
- canonical units inside app
- opt-in localization at input and output edges
- explicit conversion traces when precision matters
- schema helpers when forms and imports need enforcement
Start here
| Need | Go to |
|---|---|
| Install package | Getting Started |
| Convert values | Conversion |
| Use Bangla names | Localization |
| Check API surface | Reference |
Common tasks
| Task | API |
|---|---|
Convert 1 km to meters | convert(1, "km", "m") |
| Parse Bangla measurement | parseMeasurement("১২.৫০ কেজি") |
| Limit decimal places | parseMeasurement(input, { maxDecimalPlaces: 2 }) |
| Format Bangla output | formatMeasurement(12, "kg", { locale: "bn-BD", localizeUnits: true }) |
| Run perf bench | bun run bench --json --repeats 9 |
Choose right API
| Situation | Use |
|---|---|
| One compatible conversion | convert |
| Need warnings, rounding state, trace | convertDetailed |
| Need many targets from one source | convertMany |
Parse 12.5 kg | parseMeasurement |
Parse 5 ft 7 in | parseMixedMeasurement |
| Normalize mixed input to one unit | normalizeMixedMeasurement |
| Pick readable display unit | bestUnit or formatBest |
| Enforce form or import rules | createMeasurementSchema |
| Recover from misspelled unit input | suggestUnit |
| Resolve alias or localized label to canonical | resolveUnit |
Recommended architecture
For most teams:
- Accept user input in many shapes.
- Parse and validate at boundary.
- Store canonical value + canonical unit.
- Convert only when view or export needs it.
- Add localization only where product needs localized labels or digits.
Also built in
- clearer validation and parse error messages for users
- regional conversion warnings for units like
bighaandseer - bench CLI for before/after perf comparison