@smartput/energy

Joule, calorie, watt-hour, electronvolt.

Canonical in joules.

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

Example

import { parseEnergy, asEnergy, formatEnergy } from "@smartput/energy/validate";
import { Energy } from "@smartput/energy/class";

parseEnergy("2 kWh")                           // {"ok":true,"value":2,"unit":"kwh","raw":"2"}
asEnergy("2 kWh", "j")                         // {"ok":true,"value":7200000,"unit":"j","raw":"7200000"}
formatEnergy(parseEnergy("2 kWh"))             // "2kwh"
String(Energy.parse("2 kWh"))                  // "2kwh"

// …and the same table through the engine:
engine.evaluate("1 kWh in J").formatted        // "3,600,000 joules"
engine.evaluate("2000 cal in kcal").formatted  // "2 kilocalories"
engine.evaluate("1 kJ + 500 J").formatted      // "1.5 kilojoules"

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

Entry points

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

ENERGY_UNITS

| Unit | Ratio to j | Aliases | | --- | --- | --- | | j | 1 | j joule joules | | kj | 1000 | kj kilojoule kilojoules | | mj | 1000000 | mj megajoule megajoules | | wh | 3600 | wh | | kwh | 3600000 | kwh | | mwh | 3600000000 | mwh | | cal | 4.184 | cal calorie calories | | kcal | 4184 | kcal kilocalorie kilocalories | | btu | 1055.05585262 | btu btus |

Runtime exports

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

ENERGY_UNITS · energy

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 | | --- | --- | --- | | energy/validate parseEnergy only | ≤ 1.4 kB | ≤ 750 B | | energy/class | ≤ 4.8 kB | ≤ 1.9 kB |

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/energy.md.