@smartput/measure

Typographic units: point, pica, em, pixel.

Not in BUILTIN_KINDS: its mm and cm mean the same lengths but belong to a different kind, and registering both makes every 12 cm ambiguous. px is the one ratio in the repo that is a function rather than a constant — it reads dpi off the parse context.

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

Example

import { parseMeasure, asMeasure, formatMeasure } from "@smartput/measure/validate";
import { Measure } from "@smartput/measure/class";

parseMeasure("12 pt")                       // {"ok":true,"value":12,"unit":"pt","raw":"12"}
asMeasure("12 pt", "inch")                  // {"ok":true,"value":0.16666666666666666,"unit":"inch","raw":"0.1666666666666…
formatMeasure(parseMeasure("12 pt"))        // "12pt"
String(Measure.parse("12 pt"))              // "12pt"

// …and the same table through the engine:
engine.evaluate("12 pt in mm").formatted    // "4.2333 millimetres"
engine.evaluate("1 pc in pt").formatted     // "12 points"
engine.evaluate("72 pt in inch").formatted  // "1 inch"

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

Entry points

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

MEASURE_UNITS

| Unit | Ratio to inch | Aliases | | --- | --- | --- | | inch | 1 | inch inches | | mm | 0.0393700787401574803149606299213 | mm millimeter millimetre millimeters millimetres | | cm | 0.393700787401574803149606299213 | cm centimeter centimetre centimeters centimetres | | pt | 0.0138888888888888888888888888889 | pt point points | | pc | 0.166666666666666666666666666667 | pc pica picas | | px | f(ctx) | px pixel pixels |

Runtime exports

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

DEFAULT_DPI · MEASURE_UNITS · measure

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 | | --- | --- | --- | | measure/validate parseMeasure only | ≤ 1.6 kB | ≤ 800 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/measure.md.