Compile-time dimension safety for TypeScript. Prevents invalid operations like meters + seconds at compile time. Catches unit mismatches before your code ever runs.

import { m, km, s, add, div, to, valueOf } from 'unitsafe';

const speed = div(m(100), s(10));      // OK: m/s
const total = add(km(10), km(32));     // OK: same unit
const converted = to(m, km(1.5));      // OK: 1500 m

add(m(1), s(2));   // Compile error: cannot add length and time
to(s, km(1));      // Compile error: cannot convert length to time
add(1, m(2));      // Compile error: raw number rejected

• Motivation
• Installation
• Quick Start
• API Reference
  • Unit Factories
  • Arithmetic Operations
  • Unit Conversion
  • Comparisons
  • Helpers
  • parse()
  • Checked Mode
• Worked Examples
• Unit Reference
• How the Type System Works
  • Dimension Vectors
  • Type-Level Arithmetic
  • Branding and Type Safety
  • Runtime Representation
• Performance
  • Benchmark Methodology
  • Benchmark Results
  • Why the Overhead Exists
  • When It Matters (and When It Doesn't)
  • V8 Optimization Notes
  • Running Benchmarks Yourself
• Testing
  • Test Architecture
  • Runtime Tests
  • Type-Level Tests
  • Running Tests
• Bundle Size
• Design Decisions
• Limitations
• Requirements
• Project Structure
• Development
• Contributing
• License

Physical quantities have dimensions. Meters measure length. Seconds measure time. You can't add them — it's physically meaningless. Yet most programs represent both as plain number, and the compiler can't help you catch the mistake.

unitsafe encodes dimensional information into TypeScript's type system. The compiler rejects invalid operations at build time, and the library provides ergonomic unit conversions with runtime metadata for display and formatting.

Why not just use plain numbers with naming conventions?

• distanceMeters + timeSeconds compiles and runs silently, producing garbage
• Naming conventions don't compose: what type should distanceMeters / timeSeconds have?
• Off-by-one scale errors (forgetting to convert km to m) are invisible until production

unitsafe gives you:

• Compile-time errors for dimension mismatches (add/sub/compare)
• Automatic dimension composition for multiply/divide (m/s, m^2, kg*m/s^2)
• Type-safe conversions between compatible units (km <-> m, s <-> ms, C <-> F)
• Branded types that prevent accidental mixing of raw numbers with quantities
• Tiny runtime — each quantity is a 4-property object; no classes, no prototypes

# npm
npm install unitsafe

# pnpm
pnpm add unitsafe

# yarn
yarn add unitsafe

Requirements: TypeScript 5.5+ and Node.js 20+. See Requirements for details.

import {
  m, km, cm, mm,           // metric length
  inch, ft, yd, mi,        // US/English length
  s, ms, min, h,            // time units
  kg, g,                     // metric mass
  lb, oz,                    // US/English mass
  C, K, F,                   // temperature
  J, kWh,                    // energy
  Pa, atm,                   // pressure
  B, GB,                     // digital storage
  scalar,                    // dimensionless
  add, sub, mul, div,        // arithmetic
  to,                        // conversion
  eq, lt, lte, gt, gte,      // comparisons
  valueOf, format,           // extraction
} from 'unitsafe';

// Create quantities using unit factories
const distance = km(42.195);    // marathon distance
const time = h(2);              // 2 hours

// Divide to get speed (dimension: length/time)
const speed = div(distance, time);

// Convert to different units
const distanceInMeters = to(m, distance);
console.log(valueOf(distanceInMeters));   // 42195
console.log(format(distanceInMeters));    // "42195 m"

// Add same-unit quantities
const totalDistance = add(km(10), km(32.195));
console.log(format(totalDistance));        // "42.195 km"

// Scale a quantity
const doubled = mul(scalar(2), km(5));
console.log(format(doubled));             // "10 km"

// Compare quantities
console.log(lt(m(1), m(2)));   // true
console.log(gte(kg(5), kg(5))); // true

// Temperature conversion (affine — uses offset internally)
const boiling = to(K, C(100));
console.log(valueOf(boiling));             // 373.15

Each factory creates a Quantity value branded with the corresponding dimension and unit label. The returned quantity stores the numeric value alongside the unit's SI scale factor, label, and SI offset.

110 built-in unit factories organized by dimension:

Temperature conversions use an affine formula (SI = value × scale + offset) rather than pure scaling. See Unit Conversion.

Binary convention: 1 KB = 1024 B, 1 MB = 1024 KB, etc.

Note: The inch factory produces quantities with label 'in'. The export name is inch because in is a reserved keyword in JavaScript. Similarly, dalton produces label 'Da'.

Signature:

function m(value: number | string): Quantity<DimLength, 'm'>
function km(value: number | string): Quantity<DimLength, 'km'>
function inch(value: number | string): Quantity<DimLength, 'in'>
function ft(value: number | string): Quantity<DimLength, 'ft'>
// ... etc.

All 110 factories accept either a number or a numeric string. String values are trimmed of whitespace before parsing. Scientific notation is supported. Non-numeric strings throw a TypeError.

m(5)         // number input
m('5')       // string input — same result
m('3.14')    // float string
m('-10')     // negative string
m('1e3')     // scientific notation → 1000
m('  42  ')  // whitespace trimmed → 42

m('abc')     // TypeError: "abc" is not a number
m('')        // TypeError: empty string
m('5 m')     // TypeError: "5 m" is not a number (use parse() instead)

Each factory is also a UnitFactory object with metadata properties:

m._scale   // 1
m._label   // 'm'
m._dim     // [1, 0, 0, 0, 0, 0, 0, 0]
m._offset  // 0

C._scale   // 1
C._offset  // 273.15  (K offset for Celsius)

Adds two quantities. Both operands must have the same dimension and unit label. Returns a quantity of the same type.

add(m(1), m(2))     // OK: Quantity<DimLength, 'm'> — value 3
add(km(5), km(3))   // OK: Quantity<DimLength, 'km'> — value 8

add(m(1), s(2))     // COMPILE ERROR: different dimensions
add(m(1), km(2))    // COMPILE ERROR: different labels (convert first)
add(1, m(2))        // COMPILE ERROR: raw number rejected

To add quantities in different units of the same dimension, convert first:

add(m(500), to(m, km(1)))  // OK: 500 + 1000 = 1500 m

Subtracts two quantities. Same constraints as add.

sub(m(5), m(2))     // OK: value 3
sub(m(1), s(2))     // COMPILE ERROR

Multiplies two quantities. Dimensions are composed (exponents added). Accepts any combination of dimensions.

mul(m(3), m(4))         // Area:     Quantity<[2,0,0,...], 'm*m'> — value 12
mul(kg(10), m(5))       // kg*m:     Quantity<[1,1,0,...], 'kg*m'>
mul(scalar(2), km(5))   // Scaling:  Quantity<[1,0,0,...], 'scalar*km'> — value 10

Divides two quantities. Dimensions are composed (exponents subtracted).

div(m(10), s(2))        // Velocity: Quantity<[1,0,-1,...], 'm/s'> — value 5
div(m(6), scalar(2))    // Scaling:  Quantity<[1,0,0,...], 'm/scalar'> — value 3

Converts a quantity to a different unit of the same dimension. The first argument is the target unit factory; the second is the source quantity.

Conversion formula (general, supports affine offsets):

result = (sourceValue × sourceScale + sourceOffset − targetOffset) / targetScale

For most units sourceOffset and targetOffset are both 0, reducing to the familiar sourceValue × sourceScale / targetScale. Temperature units (Celsius, Fahrenheit) carry non-zero offsets.

to(m, km(1))         // 1000 m  (1 × 1000 / 1)
to(km, m(1500))      // 1.5 km  (1500 × 1 / 1000)
to(cm, m(2.5))       // 250 cm  (2.5 × 1 / 0.01)
to(g, kg(1))         // 1000 g  (1 × 1 / 0.001)
to(min, h(1))        // 60 min  (1 × 3600 / 60)
to(ms, s(1))         // 1000 ms (1 × 1 / 0.001)

// US/English ↔ Metric conversions
to(m, ft(1))         // 0.3048 m
to(km, mi(1))        // 1.609344 km
to(kg, lb(1))        // 0.45359237 kg
to(ft, mi(1))        // 5280 ft

// Temperature (affine — uses offset)
to(K, C(100))        // 373.15 K
to(C, K(373.15))     // 100 C
to(F, C(100))        // 212 F
to(C, F(32))         // 0 C

// Digital storage
to(B, KB(1))         // 1024 B

to(s, km(1))         // COMPILE ERROR: length ≠ time
to(lb, ft(1))        // COMPILE ERROR: mass ≠ length

All comparisons require both operands to have the same dimension and unit label.

lt(m(1), m(2))     // OK: true
lt(m(1), s(2))     // COMPILE ERROR: different dimensions

To compare quantities in different units, convert first:

lt(to(m, km(1)), m(500))   // true: 1000 m > 500 m → false actually. lt(1000, 500) → false
gt(to(m, km(1)), m(500))   // true: 1000 > 500

Returns the numeric value stored in the quantity, in the quantity's own unit.

valueOf(m(42))        // 42
valueOf(km(1.5))      // 1.5
valueOf(to(m, km(1))) // 1000
typeof valueOf(m(5))  // 'number'

Returns a human-readable string with the value and unit label.

format(m(5))                       // "5 m"
format(km(1.5))                    // "1.5 km"
format(m(3.14159), { precision: 2 })  // "3.14 m"
format(div(m(10), s(2)))           // "5 m/s"
format(mul(m(3), m(4)))            // "12 m*m"

Options:

Parses a string in the format "<value> <unit>" and returns a typed Quantity. Useful when consuming quantities from external input — API responses, user-entered strings, configuration files, etc.

Supported units: m, km, cm, mm, nm, um, dm, nmi, mil, au, ly, pc, pl, in, ft, yd, mi, s, ms, ns, us, min, h, d, week, month, yr, decade, century, plt, kg, g, ug, mg, t, st, ton, lton, Da, plm, lb, oz, K, C, F, R, pT, mm2, cm2, m2, ha, km2, in2, ft2, yd2, ac, mi2, pla, ml, cl, l, m3, tsp, tbsp, floz, cup, pt, qt, gal, plv, m/s, km/h, ft/s, mph, kn, c, N, kN, lbf, dyn, pfo, J, kJ, cal, kcal, Wh, kWh, eV, BTU, pene, W, kW, MW, hp, ppow, Pa, kPa, bar, psi, atm, mmHg, ppre, b, B, KB, MB, GB, TB, PB, scalar

parse('5 m')        // equivalent to m(5)
parse('1.5 km')     // equivalent to km(1.5)
parse('-10 s')      // equivalent to s(-10)
parse('1e3 g')      // equivalent to g(1000)
parse('  5   m  ')  // whitespace trimmed and collapsed
parse('100 C')      // equivalent to C(100)
parse('4 GB')       // equivalent to GB(4)

parse('5 miles')    // TypeError: unknown unit "miles"
parse('abc m')      // TypeError: "abc" is not a number
parse('5')          // TypeError: missing unit
parse('')           // TypeError: empty string

Because the unit is resolved at runtime, the return type is the base Quantity (with unresolved dimension and label type parameters). For static usage where the unit is known at compile time, prefer the typed factories directly — they produce narrower types.

import { parse, valueOf } from 'unitsafe';

// Dynamic input from an API:
const userInput = '42.5 km';
const distance = parse(userInput);
console.log(valueOf(distance));   // 42.5
console.log(distance._l);         // "km"

parse is also available through createChecked(), giving it access to the same checked-mode API:

const checked = createChecked();
const q = checked.parse('5 m');   // Quantity

The default API relies entirely on compile-time checks. For development and testing, createChecked() returns a mirror of the full API that adds runtime validation — it throws descriptive errors when dimension or unit mismatches are detected.

import { createChecked } from 'unitsafe';

const {
  m, km, s,            // same factories (accept number | string)
  add, sub, mul, div,  // checked operations
  to,                  // checked conversion
  eq, lt, lte, gt, gte,
  valueOf, format,
  parse,               // also available in checked mode
} = createChecked();

// Works normally for valid operations
add(m(1), m(2));         // OK: 3 m

// Throws at runtime for invalid operations (that type casts might hide)
add(m(1) as any, s(1) as any);
// Error: "Unit mismatch in add: cannot add "m" and "s" — convert first"

to(s as any, km(1) as any);
// Error: "Dimension mismatch in to: cannot convert "km" to "s""

When to use checked mode:

• During development, when any casts or complex generics might bypass compile-time checks
• In test suites, to verify that dimension constraints hold at runtime
• When consuming data from external sources (APIs, user input) where types may not be reliable

What it checks:

Calculate distance traveled under constant acceleration: d = v₀t + ½at²

import { m, s, scalar, mul, add, div, valueOf } from 'unitsafe';

// v₀ = 10 m/s, a = 2 m/s², t = 5 s
const v0 = div(m(10), s(1));              // 10 m/s
const a = div(m(2), mul(s(1), s(1)));     // 2 m/s²
const t = s(5);                            // 5 s

// v₀t: (m/s) * s = m
const v0t = mul(v0, t);

// ½at²: scalar * (m/s²) * s * s = m
const halfAt2 = mul(scalar(0.5), mul(a, mul(t, t)));

// d = v₀t + ½at²
// Both terms have dimension Length — this compiles
const d = add(v0t, halfAt2);
console.log(valueOf(d));  // 75 (meters)

import { C, K, F, to, valueOf, format } from 'unitsafe';

// Water boils at 100°C
const boiling = C(100);

console.log(format(to(K, boiling)));     // "373.15 K"
console.log(format(to(F, boiling)));     // "212 F"

// Body temperature
const body = F(98.6);
console.log(format(to(C, body)));        // "37 C"
console.log(format(to(K, body)));        // "310.15 K"

import { km, m, cm, to, valueOf, format } from 'unitsafe';

const marathon = km(42.195);

console.log(format(to(m, marathon)));    // "42195 m"
console.log(format(to(cm, marathon)));   // "4219500 cm"
console.log(format(marathon));           // "42.195 km"

import { m, km, to, gt } from 'unitsafe';

// Is 1.5 km greater than 1000 m?
const result = gt(to(m, km(1.5)), m(1000));
console.log(result);  // true (1500 > 1000)

import { B, KB, MB, GB, to, valueOf, format } from 'unitsafe';

const fileSize = MB(512);

console.log(format(to(GB, fileSize)));   // "0.5 GB"
console.log(format(to(KB, fileSize)));   // "524288 KB"

Complete list of all built-in units, organized by dimension, with their SI conversion relationships.

Base SI unit: meter (m). SI_value = value × scale.

Base SI unit: kilogram (kg). SI_value = value × scale.

Base SI unit: second (s). SI_value = value × scale.

Base SI unit: kelvin (K). SI_value = value × scale + offset.

Example: 100°C → K: 100 × 1 + 273.15 = 373.15 K

Base SI unit: square meter (m²). SI_value = value × scale.

Base SI unit: cubic meter (m³). SI_value = value × scale.

Dimension: [1, 0, -1, 0, 0, 0, 0, 0] (L¹T⁻¹). SI_value = value × scale.

Dimension: [1, 1, -2, 0, 0, 0, 0, 0] (L¹M¹T⁻²). SI_value = value × scale.

Dimension: [2, 1, -2, 0, 0, 0, 0, 0] (L²M¹T⁻²). SI_value = value × scale.

Dimension: [2, 1, -3, 0, 0, 0, 0, 0] (L²M¹T⁻³). SI_value = value × scale.

Dimension: [-1, 1, -2, 0, 0, 0, 0, 0] (L⁻¹M¹T⁻²). SI_value = value × scale.

Dimension: [0, 0, 0, 0, 0, 0, 0, 1] (Data¹). Binary convention: 1 KB = 1024 B. SI_value = value × scale.

Every physical quantity has a dimension — a combination of the eight base quantities. unitsafe represents dimensions as 8-element tuples of integer exponents:

[Length, Mass, Time, Current, Temperature, Amount, LuminousIntensity, Data]

Examples:

TypeScript cannot perform arithmetic on type-level integers natively. unitsafe works around this with pre-computed lookup tables for addition and subtraction on a bounded integer range of [-8, +8].

// Bounded integer type
type Int = -8 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;

// Lookup: AddMap[A][B] gives A + B (clamped to [-8, 8])
type IntAdd<A extends Int, B extends Int> = AddMap[A][B];

// Dimension composition for multiplication: add exponent vectors element-wise
type DimMul<A extends Dim, B extends Dim> = [
  IntAdd<A[0], B[0]>,  // Length exponents
  IntAdd<A[1], B[1]>,  // Mass exponents
  // ... 6 more
];

When you write mul(m(3), m(4)):

• m has dimension [1, 0, 0, 0, 0, 0, 0, 0]
• DimMul adds exponents: [1+1, 0+0, 0+0, ...] = [2, 0, 0, 0, 0, 0, 0, 0]
• The result type is Quantity<[2, 0, 0, 0, 0, 0, 0, 0], "m*m"> (area)

When you write div(m(10), s(2)):

• DimDiv subtracts exponents: [1-0, 0-0, 0-1, ...] = [1, 0, -1, 0, 0, 0, 0, 0]
• The result type is Quantity<[1, 0, -1, 0, 0, 0, 0, 0], "m/s"> (velocity)

The exponent range [-8, +8] supports up to 8th-power compositions (e.g., L⁸), which is more than sufficient for any real-world physics formula. Values outside this range are clamped to the boundary.

Quantity<D, L> is an interface with two phantom type parameters:

interface Quantity<D extends Dim, L extends string> {
  readonly _v: number;         // numeric value
  readonly _s: number;         // SI scale factor
  readonly _l: string;         // unit label
  readonly _o: number;         // SI offset (0 for all non-temperature units)
  readonly __phantom_dim?: D;  // phantom: dimension (never set at runtime)
  readonly __phantom_label?: L; // phantom: label (never set at runtime)
}

TypeScript's structural typing ensures:

1. Dimension safety: add(m(1), s(2)) fails because Quantity<[1,0,0,...], 'm'> and Quantity<[0,0,1,...], 's'> cannot unify on the D parameter.

2. Unit safety: add(m(1), km(2)) fails because the labels 'm' and 'km' don't match, even though both have the same dimension.

3. No raw number leaks: add(1, m(2)) fails because number lacks the _v, _s, _l, _o properties required by Quantity.

Each quantity is a plain JavaScript object with exactly four properties:

// m(5) at runtime:
{ _v: 5, _s: 1, _l: 'm', _o: 0 }

// km(1) at runtime:
{ _v: 1, _s: 1000, _l: 'km', _o: 0 }

// C(100) at runtime (Celsius — has non-zero offset):
{ _v: 100, _s: 1, _l: 'C', _o: 273.15 }

All quantity objects share the same hidden class in V8 (same properties, same order, same types), enabling optimized property access.

The benchmark compares three operations (add, multiply, divide) across 1,000,000 iterations using random data from pre-allocated Float64Array buffers. Random data prevents V8 from constant-folding or eliminating the computation.

Benchmark structure:

Plain numbers:  a + b, a * b, a / b  (raw arithmetic)
unitsafe:       add(m(a), m(b)), mul(m(a), m(b)), div(m(a), scalar(b))

Each round is timed with performance.now(). Seven rounds are run; the best and worst are dropped and the remaining five are averaged (trimmed mean) to reduce variance from GC pauses and CPU scheduling.

Source: bench/index.ts

Measured on Apple Silicon (M-series), Node.js 20+, V8:

Iterations: 1,000,000

Results (7 rounds, trimmed mean):
  Plain numbers: 0.66 ms  (~1,500 M ops/s)
  unitsafe:      14.14 ms (~70 M ops/s)
  Ratio:         0.047 (unitsafe / plain)
  Overhead:      ~95%

The overhead comes from object allocation, not from the arithmetic itself. Each factory call and each operation creates a new { _v, _s, _l, _o } object on the heap. The plain-number baseline performs zero allocations — all values live in CPU registers.

This is a fundamental trade-off: carrying unit metadata (_s for scale, _l for label, _o for offset) enables the ergonomic to(km, m(1500)) conversion API (including affine temperature conversions), but requires an object rather than a plain primitive.

Breakdown of per-operation cost:

It does NOT matter for:

• Application code (I/O-bound, rendering, business logic)
• Moderate-frequency calculations (< 100K ops/s)
• Any code path where a single operation is followed by non-trivial work
• Most scientific computing (bottleneck is usually matrix operations, not scalar arithmetic)

At ~14 ns per operation, you can perform 70 million operations per second. That's faster than:

• A single network round-trip (~1 ms = 70,000 unitsafe operations)
• A single DOM paint (~16 ms = 1.1 million operations)
• A database query (~5 ms = 350,000 operations)

It MIGHT matter for:

• Tight inner loops performing billions of arithmetic operations on scalar values
• Real-time physics simulations at microsecond granularity
• Performance-critical numerical kernels

For these cases, use valueOf() to extract plain numbers for the hot loop, and re-wrap with unit factories at the boundaries.

unitsafe is designed to be V8-friendly:

• Monomorphic objects: All quantities have the same 4-property shape {_v, _s, _l, _o}, always created in the same order. V8 assigns a single hidden class and uses fast inline-cached property access.
• No polymorphic dispatch: Each operation function (add, mul, etc.) always receives the same object shape, avoiding megamorphic deoptimization.
• No prototype chain: Quantities are plain objects created with object literals — no class instantiation, no __proto__ lookup.
• Small functions: All operations are small enough for V8's inliner.

pnpm bench

The benchmark prints ops/s, overhead percentage, and a pass/warn/note verdict. Results will vary by hardware and Node.js version.

unitsafe has three layers of testing:

486 tests across acceptance and parse test suites covering the full public API.

Example test output:

 ✓ test/acceptance.test.ts (198 tests) 12ms
 ✓ test/parse.test.ts (288 tests) 15ms

 Test Files  2 passed (2)
      Tests  486 passed (486)
   Duration  ~150ms

80+ type assertions using tsd, verifying both positive and negative cases.

Positive assertions (should compile):

Negative assertions (must NOT compile):

# All runtime tests
pnpm test

# Watch mode (re-run on file changes)
pnpm test:watch

# Type checking (catches errors in src/)
pnpm typecheck

# Type-level assertions (requires build first)
pnpm build && pnpm type-tests

# Full validation pipeline
pnpm test && pnpm typecheck && pnpm build && pnpm type-tests && pnpm bench

The declaration files are large due to the lookup tables (AddMap, SubMap) that encode type-level arithmetic. These are stripped at build time and have zero runtime cost.

The ESM bundle is 28.19 KB unminified with no dependencies. Tree-shaking further reduces the size if you only import a subset of units.

The ideal zero-cost representation would be a plain number with phantom type brands:

type Quantity<D> = number & { readonly __dim: D };

This gives typeof q === 'number' and zero allocation overhead. However, it makes the to(target, quantity) conversion API impossible — you can't read the source unit's scale factor (or offset, for temperature) from a plain number at runtime.

Alternatives considered:

The chosen approach trades ~14 ns/op overhead for an ergonomic, correct API.

add(m(1), km(2)) is a compile error even though both are lengths. This is intentional:

1. Correctness: 1 + 2 = 3, but 3 of what? Meters? Kilometers? The answer is ambiguous.
2. No hidden conversions: Implicit conversions are a common source of bugs.
3. Explicit is better: add(m(1), to(m, km(2))) makes the intent clear: "add 1 meter and 2 km, converting km to m first."

TypeScript can express integer arithmetic through recursive conditional types:

type Add<A, B> = A extends 0 ? B : Add<Prev<A>, Succ<B>>;

This causes exponential type instantiation depth for compositions like mul(mul(mul(a, b), c), d). Lookup tables are O(1) at the type level — a single indexed access regardless of nesting depth.

• Derived units show composed labels. div(m(10), s(2)) formats as "5 m/s", and mul(m(3), m(4)) formats as "12 m*m". There is no automatic simplification to named units like "m²" or "N".

• Same-label requirement for add/sub. You must convert to a common unit before adding: add(m(1), to(m, km(2))) instead of add(m(1), km(2)).

• Exponent range [-8, +8]. Dimension exponents are bounded to this range. Values outside are clamped. This is sufficient for virtually all real-world physics formulas.

• No custom unit definition API. Only the built-in units are provided. A user-facing defineUnit() API is a candidate for v0.2.

Runtime dependencies: none (zero dependencies).

unitsafe/
├── src/
│   └── index.ts          # Entire library: types, units, operations, parse, checked mode (~2000 lines)
├── test/
│   ├── acceptance.test.ts # Runtime tests (Vitest) — unit factories, arithmetic, conversions
│   └── parse.test.ts      # Runtime tests (Vitest) — parse(), all unit labels
├── type-tests/
│   └── index.test-d.ts   # Type-level assertions (tsd)
├── bench/
│   └── index.ts          # Performance benchmark harness
├── dist/                  # Build output (ESM + CJS + .d.ts)
├── package.json
├── tsconfig.json          # Strict TypeScript config
├── tsup.config.ts         # Build configuration
├── vitest.config.ts       # Test runner configuration
├── LICENSE                # MIT
└── README.md

The entire library is a single source file (src/index.ts). This is intentional — the codebase is large in line count due to the lookup tables and unit definitions, but architecturally flat and easy to navigate.

# Install dependencies
pnpm install

# Run runtime tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Type-check the source
pnpm typecheck

# Build the library (ESM + CJS + declarations)
pnpm build

# Run type-level tests (requires build)
pnpm type-tests

# Run performance benchmarks
pnpm bench

# Full validation (run before committing)
pnpm test && pnpm typecheck && pnpm build && pnpm type-tests && pnpm bench

See CONTRIBUTING.md for development setup, coding standards, and contribution guidelines.

MIT