Units and Dimensions
Race Platform ships a units catalogue with 25 dimensions and
their canonical unit options. The dimension list lives in
packages/shared-types/src/definitions.ts (the Zod
dimensionSchema enum) and the per-unit conversion table lives
in packages/shared-types/src/units.ts. Both the TypeScript and
Dart engines consume the same table.
The 25 dimensions
length mass temperature pressure
time angle speed force
energy power voltage current
resistance frequency percentage count
ratio volume area acceleration
angular-velocity torque fuel-economy
heat-flux dimensionless
dimensionless is the no-op dimension for pure ratios that have
no SI unit. angular-velocity, fuel-economy, and heat-flux
ship in the enum but currently have a single base unit each;
extending them is a one-PR change to units.ts.
Conversion model
Every unit has a factor and an offset against the dimension's
base unit. Conversion is:
value_in_base = value × factor + offset
Temperature uses the offset for Celsius / Fahrenheit / Kelvin
correctness — everything else is offset: 0.
Common unit options per dimension
The table below lists the units you'll see in the Definitions editor and CID cell pickers. The catalogue is canonical; if you need a unit that isn't here, file a request.
| Dimension | Base | Other units |
|---|---|---|
| length | m | mm, cm, km, in, ft, mi |
| mass | kg | g, lb, oz |
| temperature | K | °C, °F |
| pressure | Pa | kPa, bar, psi, mbar, atm |
| time | s | ms, min, hr |
| angle | rad | deg |
| speed | m/s | km/h, mph |
| force | N | kgf, lbf |
| energy | J | kJ, kWh, cal |
| power | W | kW, hp, PS |
| voltage | V | mV, kV |
| current | A | mA |
| resistance | Ω | kΩ, mΩ |
| frequency | Hz | kHz, rpm |
| percentage | % | (no others — already a ratio in [0,1] scaled to display %) |
| count | # | (no others) |
| ratio | (none) | |
| volume | L | mL, gal (US), gal (UK) |
| area | m² | mm², cm², in² |
| acceleration | m/s² | g (9.80665 m/s²) |
| torque | N·m | lbf·ft, kgf·m |
| dimensionless | (none) |
The full canonical table with exact factors is in
packages/shared-types/src/units.ts.
Functions you can use
From the units module:
| Function | Description |
|---|---|
convert(value, from, to) | Convert between two units of the same dimension |
unitsForDimension(dim) | List all unit names for a dimension |
baseUnitOf(dim) | Return the base unit name |
findDimensionForUnit(unit) | Reverse-lookup dimension given a unit name |
Unit-aware math
A numeric parameter declares its dimension + defaultUnit in
its Definition. When the math engine reads the parameter, it can
attach unit metadata to the value. In v0.1.0 this is opt-in —
the caller has to pass __unit__ on the scope value. Wiring this
to happen automatically is on the roadmap.
What's coming
- Auto-attached units on scope values
- Per-user / per-team unit preferences (metric vs imperial)
- Configurable display precision per dimension
- Custom unit definitions — for non-standard units a customer uses internally