@smartput/length

Millimetre to mile, exact in decimal.

Eight units and thirty-two aliases. Every ratio is exact in decimal — the imperial ones by definition of the international yard and pound agreement — so no conversion in this table rounds.

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/length

Example

import { parseLength, asLength, formatLength } from "@smartput/length/validate";
import { Length } from "@smartput/length/class";

parseLength("12 cm")                       // {"ok":true,"value":12,"unit":"cm","raw":"12"}
asLength("12 cm", "m")                     // {"ok":true,"value":0.12,"unit":"m","raw":"0.12"}
formatLength(parseLength("12 cm"))         // "12cm"
String(Length.parse("12 cm"))              // "12cm"

// …and the same table through the engine:
engine.evaluate("2 km in m").formatted     // "2,000 metres"
engine.evaluate("12 inch").formatted       // "12 inches"
engine.evaluate("1 mi + 500 m").formatted  // "1.3107 miles"

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

Entry points

| Import | Contents | | --- | --- | | @smartput/length | The package root. | | @smartput/length/units | The UnitTable: ratios and aliases, with no engine and no Decimal. | | @smartput/length/validate | Free functions over JS numbers. Ok \| Err, never a throw. | | @smartput/length/class | The immutable value class. | | @smartput/length/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.

LENGTH_UNITS

| Unit | Ratio to m | Aliases | | --- | --- | --- | | m | 1 | m meter metre meters metres | | mm | 0.001 | mm millimeter millimetre millimeters millimetres | | cm | 0.01 | cm centimeter centimetre centimeters centimetres | | km | 1000 | km kilometer kilometre kilometers kilometres | | in | 0.0254 | in inch inches | | ft | 0.3048 | ft feet foot | | yd | 0.9144 | yd yard yards | | mi | 1609.344 | mi mile miles |

Runtime exports

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

LENGTH_UNITS · length

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 | | --- | --- | --- | | length/validate parseLength only | ≤ 1.6 kB | ≤ 800 B | | length/locale/en (a kind's words, no arithmetic) | ≤ 1.6 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/length.md.