Reference
Public API, unit categories, and metadata helpers.
Reference
This page is API map. Use it when deciding which fn belongs in parse layer, conversion layer, validation layer, or display layer.
Core API
| API | Purpose |
|---|---|
convert(value, from, to, options?) | Convert between compatible units |
convertDetailed(value, from, to, options?) | Convert with trace, status, and warnings |
convertMany(value, from, units, options?) | Convert to several target units |
parseMeasurement(input, options?) | Parse numeric string + unit |
parseMixedMeasurement(input) | Parse mixed values like 5 ft 7 in |
normalizeMixedMeasurement(input, to) | Normalize mixed values to one target unit |
bestUnit(value, unit, options?) | Pick a human-friendly target unit |
formatBest(value, unit, options?) | Format with the best target unit |
createMeasurementSchema(options) | Build form-ready measurement validation |
suggestUnit(input, limit?) | Suggest units for typos or partial aliases |
formatMeasurement(value, unit, options?) | Format value with canonical or localized unit |
resolveUnit(unit) | Resolve alias/name/symbol to canonical id |
getUnit(unit) | Read unit metadata |
listUnits() | List all units |
listUnitsByCategory(category) | List units in one category |
isKnownUnit(unit) | Check if unit can resolve |
Typical flow by layer
| Layer | Good APIs |
|---|---|
| User input | parseMeasurement, parseMixedMeasurement, suggestUnit |
| Validation | createMeasurementSchema, resolveUnit, isKnownUnit |
| Domain normalization | convert, normalizeMixedMeasurement, convertDetailed |
| Presentation | bestUnit, formatBest, formatMeasurement |
| Metadata and tooling | getUnit, listUnits, listUnitsByCategory |
Unit categories
- Length:
mm,cm,m,km,in,ft,yd,mi - Mass:
mg,g,kg,tonne,oz,lb,seer,mon - Area:
sq_m,sq_km,sq_ft,acre,hectare,katha,bigha - Volume:
ml,l,cu_m,tsp,tbsp,cup,pt,qt,gal - Temperature:
c,f,k - Data:
b,kb,mb,gb,tb,kib,mib,gib,tib - Time:
ms,s,min,h,day,week
Options
| Option | API | Purpose |
|---|---|---|
precision | convert, convertMany | Output decimal places |
roundingMode | convert, convertMany | Rounding strategy |
maxDecimalPlaces | parseMeasurement | Input decimal-place limit |
locale | formatMeasurement | Locale-aware number output |
digitStyle | formatMeasurement | auto, latin, or native digits |
unitDisplay | formatMeasurement | symbol, label, or id |
localizeUnits | formatMeasurement | Opt into localized unit labels/symbols |
category | parseMeasurement, schema | Require a measurement category |
allowedUnits | parseMeasurement, schema | Limit accepted units |
unitDisplay | formatMeasurement | Choose canonical id, symbol, label |
maximumFractionDigits | formatMeasurement | Limit formatted decimals |
minimumFractionDigits | formatMeasurement | Force formatted decimals |
Error model
Main runtime errors:
UnknownUnitErrorwhen source or target unit cannot resolveIncompatibleUnitErrorwhen units belong to different categoriesInvalidMeasurementErrorwhen input shape or decimal rules fail
Use these explicitly in forms, APIs, CSV imports, and admin tools.
Typical messages are actionable:
parseMeasurement("12.345 kg", { maxDecimalPlaces: 2 })
// InvalidMeasurementError:
// Too many decimal places in "12.345 kg". Use at most 2 decimal places.
parseMixedMeasurement("5 ft nope 7 in")
// InvalidMeasurementError:
// Could not read "5 ft nope 7 in" as mixed measurement. Use format like "5 ft 7 in" or "1 kg 250 g".Bench CLI
Package includes repeatable micro-bench harness:
bun run bench
bun run bench --json
bun run bench --csv
bun run bench --json --repeats 9 --sample-ms 1200--json and --csv are intended for CI artifacts and diffing perf changes over time.
Canonical IDs vs aliases
Unit always resolves toward canonical ids like:
kgsq_ftkmbigha
Aliases, labels, and localized names are input conveniences. Canonical ids are safer for storage, validation, and internal logic.