dim

Type-safe dimensional analysis and units for TypeScript.

Just want SI?@isentropic/dim-si provides ready-to-use SI units with compile-time dimension checking.

How It Works

dim treats quantities and units as separate concepts with different responsibilities. Units are layered on top of quantities to give them meaning.

A quantity encodes dimensionality. Dimensions are tracked at compile time, so the type checker catches errors like adding a length to a time before your code runs.

A unit gives meaning to a quantity. Units are views over quantities: different lenses for reading and writing the same underlying value.

dim accomplishes this by providing tools for defining quantity and unit systems, and uses those same tools to provide ready-made ISQ quantities and SI units.

End-to-End Example

Here's what that looks like in practice: a small physics system with length, time, and temperature.

1. Define a quantity system

Choose base dimensions and derive compound quantities from them:

import{defineQuantitySystem}from"@isentropic/dim-quantity";constqs=defineQuantitySystem(["L","T","Θ"]);constlength=qs.base("L");consttime=qs.base("T");consttemperature=qs.base("Θ");constvelocity=qs.factory({L: 1,T: -1});

At this point, length(100) produces a value tagged with dimension L. No units, no scale factors, just dimensionality.

For larger systems, dim-quantity supports a spec-based approach with code generation.

2. Layer a unit system on top

Units attach physical meaning to those raw quantities:

import{defineUnitSystem}from"@isentropic/dim-unit";constus=defineUnitSystem("tutorial",qs);// Base unitsconstmeter=us.unit(length);constsecond=us.unit(time);constkelvin=us.unit(temperature);// Scaled unitsconstkilometer=meter.scaled(1000);consthour=second.scaled(3600);// Affine units (arbitrary zero point)constcelsius=kelvin.offset(273.15);

3. Use the units to solve problems

Now you have type-safe arithmetic with automatic dimension tracking. Wrap any quantity with q() for fluent chaining:

import{q}from"@isentropic/dim-unit/chain";constspeed=q(kilometer(5)).div(hour(2));q(kilometer(5)).in(meter);// 5000q(kilometer(5)).in(kilometer);// 5// Same-dimension arithmetic worksq(kilometer(1)).plus(meter(500));// 1500 m// Dimension mismatches are compile errorsq(kilometer(1)).plus(hour(1));// Error: length and time dimensions don't match// Affine units enforce correct semanticsq(celsius(100)).minus(celsius(0));// 100 K (linear delta)q(celsius(0)).plus(celsius.delta(10));// 10°C (affine point)q(celsius(100)).plus(celsius(0));// Error: can't add two affine quantities

Free functions add, subtract, multiply, divide, and scale are also available from @isentropic/dim-unit/ops.

Pre-Built Systems

Defining quantity and unit systems from scratch is useful for custom domains, but most scientific and engineering work uses the same foundational systems: the ISQ (International System of Quantities) for dimensions and derived quantities, and the SI (International System of Units) for units.

Rather than make everyone define these themselves, dim uses its own tooling to provide them as ready-to-use packages.

Packages

Package	Description
dim-si	SI unit system built on dim-isq
dim-isq	ISQ quantity system
dim-unit	Define unit systems with scale factors and affine offsets for any quantity system
dim-quantity	Define quantity systems with compile-time dimension tracking

Development

deno test# Run all tests
deno lint # Lint all files
deno fmt # Format all files

License

MIT