@smartput/angle

Degree, radian, gradian, turn — with a 30-digit π.

The ratios are decimal strings, not floats, which is what lets radians carry a thirty-digit π through the engine without drift. The micro path does Number(r) and accepts the float; the engine does new Decimal(r) and does not.

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

Example

import { parseAngle, asAngle, formatAngle } from "@smartput/angle/validate";
import { Angle } from "@smartput/angle/class";

parseAngle("30 deg")                        // {"ok":true,"value":30,"unit":"deg","raw":"30"}
asAngle("30 deg", "rad")                    // {"ok":true,"value":0.5235987755982988,"unit":"rad","raw":"0.5235987755982988"}
formatAngle(parseAngle("30 deg"))           // "30deg"
String(Angle.parse("30 deg"))               // "30deg"

// …and the same table through the engine:
engine.evaluate("30 deg in rad").formatted  // "0.5236 radians"
engine.evaluate("1 turn in deg").formatted  // "360 degrees"
engine.evaluate("90deg + 45deg").formatted  // "135 degrees"

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

Entry points

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

ANGLE_UNITS

| Unit | Ratio to rad | Aliases | | --- | --- | --- | | rad | 1 | rad radian radians | | deg | 0.0174532925199432957692369076849 | deg degree degrees | | grad | 0.0157079632679489661923132169164 | gon grad gradian gradians | | turn | 6.28318530717958647692528676656 | rev turn turns revolution revolutions |

Runtime exports

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

ANGLE_UNITS · angle

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 | | --- | --- | --- | | angle/validate parseAngle only | ≤ 1.4 kB | ≤ 800 B | | angle/validate parse + add + to | ≤ 2.4 kB | ≤ 1.1 kB | | angle/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/angle.md.