@smartput/number

The unitless kind, and the one that accepts a bare number.

One unit, one, and the only kind whose /validate carries a mode of its own: native lets parseNumber("30") succeed where every other kind returns missing-unit. That branch lives here rather than in the shared parser precisely so that only this package's size row pays for it.

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

Example

import { numberFromWords, spellNumber } from "@smartput/number";
import { parseNumber } from "@smartput/number/validate";

numberFromWords(["one", "hundred", "and", "five"])  // {"value":"105","text":"105","consumed":4}
spellNumber(105)                                    // "one hundred and five"
parseNumber("1,500")                                // {"ok":false,"code":"nan","input":"1,500"}
engine.evaluate("(1 + 2) * 3").formatted            // "9"
engine.evaluate("twenty two + 5").formatted         // "27"

numberFromWords takes the words already split, and reports how many it consumed — it is a reader inside a larger sentence, not a whole-string parser. spellNumber is its inverse over the same table.

Entry points

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

NUMBER_UNITS

| Unit | Ratio to one | Aliases | | --- | --- | --- | | one | 1 | one |

Runtime exports

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

NUMBER_UNITS · NUMBER_WORDS · number · numberFromWords · spellNumber

Dependencies

• @smartput/kind
• @smartput/shared

Optional peers

• @smartput/core — needed only by @smartput/number and its /locale/* entries, and npm add does not fetch it. Anyone reaching those has written createEngine and installed it already; the /validate, /units and /class entries never touch it.

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 | | --- | --- | --- | | number/validate parseNumber 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/number.md.