Parameters and expressions

Parameters turn one design document into a family of evaluated variants. InvariantCAD stores formulas as immutable expression trees instead of executing arbitrary JavaScript during evaluation.

Supported dimensions

Dimension	Constructors	Base unit
Length	`mm`, `cm`, `meters`, `inch`	millimetre
Angle	`rad`, `deg`	radian
Scalar	`scalar`	unitless
Mass density	`kgPerCubicMillimeter`, `kgPerCubicMeter`, `gramsPerCubicCentimeter`	kg/mm³

const width = cad.parameter.length("width", mm(80), {
  min: mm(20),
  max: mm(200),
  label: "Width",
  description: "Overall body width",
});

const taper = cad.parameter.angle("taper", deg(3));
const scale = cad.parameter.scalar("scale", scalar(1));
const density = cad.parameter.massDensity(
  "density",
  kgPerCubicMeter(2700),
);

Defaults and bounds may themselves reference parameters that belong to the same design. Evaluation resolves the complete dependency graph and reports cycles, missing values, non-finite results, and bound violations as diagnostics.

Arithmetic

Every expression exposes immutable arithmetic methods:

const wall = cad.parameter.length("wall", mm(3));
const clearance = cad.parameter.length("clearance", mm(0.25));
const outside = cad.parameter.length("outside", mm(40));

const inside = outside.sub(wall.mul(2)).sub(clearance.mul(2));
const halfOutside = outside.div(2);
const positiveOffset = clearance.abs();

add and sub require the same dimension.
mul and div accept a scalar expression or finite number.
neg and abs preserve the dimension.
expr.min, expr.max, and trigonometric helpers construct additional serializable operations. expr.min and expr.max require one dimension, expr.sin, expr.cos, and expr.tan take an angle and return a scalar, and expr.ratio divides two values of the same dimension into a scalar.

TypeScript prevents many dimension mistakes at compile time. The same rules are also checked at runtime: arithmetic, the vector helpers, and every builder input throw TypeError for a wrong-dimensional expression from an untyped caller. Document validation applies them again to documents received from untyped or hostile sources.

Vectors

Use vector helpers to preserve component dimensions:

const size = vec3(width, mm(30), wall);
const point = vec2(width.mul(0.25), mm(0));
const scale3d = scalarVec3(scale, scalar(1), scalar(1));
const rotation = angleVec3(deg(0), taper, deg(90));

vec2 and vec3 contain lengths. scalarVec3 is used for scale and directions; angleVec3 is used for Euler rotations.

Evaluation overrides

Override values by parameter ID:

const result = await evaluator.evaluate(document, {
  parameters: {
    width: 125,
    taper: Math.PI / 36,
    density: 2.7e-6,
  },
});

Override numbers use base units, not the constructor originally used by the author. width: 125 means 125 mm, even if the default was written as inch(4.5), and taper: Math.PI / 36 means 5 degrees because angles are stored in radians. An override can also be an expression object of the parameter’s dimension:

const result = await evaluator.evaluate(document, {
  parameters: {
    width: mm(125),
    taper: deg(5),
  },
});

The evaluator checks the expression’s dimension against the parameter and fails with EXPRESSION_DIMENSION_MISMATCH when they differ, for example deg(5) for a length. A matching expression is evaluated like a configuration binding, so it may also reference other parameters of the same document.

Prefer plain numbers when overrides arrive as data, such as JSON, CLI arguments, or a worker message. Expression objects are authoring objects: a serialized or structured-cloned copy is no longer an Expression and fails with EXPRESSION_INVALID.

Configuration overrides

A named configuration can bind parameters inside the document:

const compact = cad.configuration("compact", (configuration) => {
  configuration.parameter(width, mm(60));
  configuration.parameter(wall, mm(2.5));
});

At evaluation, select it by reference during authoring or by stable ID after serialization. Explicit evaluation overrides apply within the selected configuration context. See configurations and BOMs.

Parameter ownership

Parameters are bound to the DesignBuilder that created them. Cross-design use throws immediately, including inside derived expressions, vectors, transform operations, sketch entities, topology predicates, parameter defaults and bounds, densities, configuration values, and assembly placements:

const first = design("first");
const foreignWidth = first.parameter.length("width", mm(10));

const second = design("second");
// second.box(...foreignWidth...) is rejected during authoring, even when
// second defines its own "width" parameter.

This restriction guarantees that every expression reference can be represented inside one closed document. Raw expression IR passed through fromExpressionIR refers to parameters only by ID; the builder accepts it only when that ID names a parameter it already defines, with the same dimension. Raw IR must be plain JSON records and arrays whose fields are own enumerable data properties. Accessors, inherited fields, and class instances throw TypeError without running any accessor. A record may hold no symbol or non-enumerable fields, and a min or max value array may hold nothing but its operands, because the freeze would not reach such extra data.

Getting started

Modeling

Evaluation

Analysis and interchange

Parameters and expressions

Supported dimensions

Arithmetic

Vectors

Evaluation overrides

Configuration overrides

Parameter ownership