@smartput/volume

Litres, millilitres, cubic metres, and the two gallons.

Canonical in litres. US and imperial gallons are separate units, never aliases.

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

Example

import { parseVolume, asVolume, formatVolume } from "@smartput/volume/validate";
import { Volume } from "@smartput/volume/class";

parseVolume("1.5 l")                       // {"ok":true,"value":1.5,"unit":"l","raw":"1.5"}
asVolume("1.5 l", "ml")                    // {"ok":true,"value":1500,"unit":"ml","raw":"1500"}
formatVolume(parseVolume("1.5 l"))         // "1.5l"
String(Volume.parse("1.5 l"))              // "1.5l"

// …and the same table through the engine:
engine.evaluate("1 m3 in l").formatted     // "1,000 litres"
engine.evaluate("500 ml + 1 l").formatted  // "1,500 millilitres"
engine.evaluate("2 gal in l").formatted    // "7.5708 litres"

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

Entry points

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

VOLUME_UNITS

| Unit | Ratio to l | Aliases | | --- | --- | --- | | l | 1 | l liter litre liters litres | | ml | 0.001 | ml milliliter millilitre milliliters millilitres | | m3 | 1000 | m3 m³ | | gal | 3.785411784 | gal gallon gallons | | pint | 0.473176473 | pint pints |

Runtime exports

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

VOLUME_UNITS · volume

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 | | --- | --- | --- | | volume/validate parseVolume 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/volume.md.