Unit and Dimension Guard

Quantities that carry their unit, with arithmetic that refuses to add or compare incompatible dimensions.

THE SILENT FAILURE. A number is just a number. Adding metres to feet, seconds to milliseconds, or kilograms to pounds produces a plausible result and no error. This is the failure that destroyed the Mars Climate Orbiter, and in ordinary software it appears as a timeout set in seconds passed to an API expecting milliseconds -- firing a thousand times too early or too late -- or a distance in kilometres rendered as miles. The value stays in range, the UI renders, nothing reports a problem.

Incompatible operations fail at COMPILE time where TypeScript can see them, and at RUNTIME too, because your data crosses a JSON boundary where types are gone. Conversion factors are EXACT where the definition is exact (an inch is exactly 25.4 mm by international agreement, cited) and marked as approximations where they are not -- treating an approximate factor as exact is a smaller version of this product's own failure.

Temperature is AFFINE, so converting a temperature DIFFERENCE is not the same as converting a temperature, and getting that wrong is the classic bug. Compound units compose and cancel. Round-trip stability is tested, and where a round trip cannot be exact the README says so.

A REAL BUG FOUND BEFORE RELEASE, at the JSON boundary the product exists to defend: unit names were looked up on a plain object literal with only a truthiness check, so a unit named toString, constructor or __proto__ resolved to an Object.prototype member and crashed with a raw TypeError. A crash is not failing closed. Now refused by name.

VERIFIED: 225 tests. Every mutation was observed FAILING before the source was restored -- a test never seen to fail is a decoration. Independently reviewed by a verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function multiplyDimRuntime(a: Dim, b: Dim): Dim;
  export function negateDimRuntime(a: Dim): Dim;
  export function divideDimRuntime(a: Dim, b: Dim): Dim;
  export function dimEquals(a: Dim, b: Dim): boolean;
  export function formatDim(d: Dim): string;
  export function assertFinite(value: number, context: string): void;
  export function parseQuantityJSON<D extends Dim>( json: QuantityJSON, expectedUnit: Unit<D>, ): Quantity<D>;
  export function quantityToJSON<D extends Dim>(qty: Quantity<D>, unit: Unit<D>): QuantityJSON;
  export function mulUnit<A extends Dim, B extends Dim>( a: Unit<A>, b: Unit<B>, symbol = `${a.symbol}*${b.symbol}`, ): Unit<MultiplyDim<A, B>>;
  export function divUnit<A extends Dim, B extends Dim>( a: Unit<A>, b: Unit<B>, symbol = `${a.symbol}/${b.symbol}`, ): Unit<DivideDim<A, B>>;

  export type Exp = -4 | -3 | -2 | -1 | 0 | 1 | 2 | 3 | 4;
  export type DivideDim<A extends Dim, B extends Dim> = MultiplyDim<A, NegateDim<B>>;
  export type TemperatureUnit = "K" | "C" | "F";