@spaceteams/weft-layer-dimensional 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spaceteams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,53 @@
+import { LayerEvaluator } from "@spaceteams/weft";
+
+//#region src/unit.d.ts
+/**
+ * A rational unit representation using sorted base-unit arrays.
+ *
+ * `num` lists the base units in the numerator, `denom` in the denominator.
+ * Both arrays are kept sorted alphabetically so structural equality works.
+ *
+ * Examples:
+ * - metres:          `{ num: ["m"], denom: [] }`
+ * - metres per second: `{ num: ["m"], denom: ["s"] }`
+ * - dimensionless:   `{ num: [], denom: [] }`
+ */
+type Unit = {
+  readonly num: readonly string[];
+  readonly denom: readonly string[];
+};
+/** Create a base unit, e.g. `unit("m")` → `{ num: ["m"], denom: [] }`. */
+declare function unit(name: string): Unit;
+/** The dimensionless unit (scalar). */
+declare function dimensionless(): Unit;
+/** Create an arbitrary compound unit from numerator and denominator base units. */
+declare function compoundUnit(num: readonly string[], denom: readonly string[]): Unit;
+/** Multiply two units: `(a·b)`. Combines numerators and denominators, cancelling common factors. */
+declare function multiplyUnits(a: Unit, b: Unit): Unit;
+/** Divide two units: `a / b`. */
+declare function divideUnits(a: Unit, b: Unit): Unit;
+/** Structural equality of two units. */
+declare function unitsEqual(a: Unit, b: Unit): boolean;
+/**
+ * Format a unit as a human-readable string.
+ *
+ * - `"m"`, `"kg"` — simple base unit
+ * - `"m/s"` — single numerator / single denominator
+ * - `"m²"` — repeated base unit uses superscript exponents
+ * - `"kg·m/s²"` — full compound unit
+ * - `"1"` — dimensionless
+ * - `"1/s"` — pure denominator
+ */
+declare function formatUnit(u: Unit): string;
+//#endregion
+//#region src/dimensional-layer.d.ts
+/**
+ * SI-style dimensional analysis layer for weft computation models.
+ *
+ * Propagates {@link Unit} values through the computation graph based on each
+ * rule's `op`. When units are incompatible (e.g. adding metres to seconds),
+ * the layer returns `undefined` — it never throws.
+ */
+declare const dimensionalLayer: LayerEvaluator<Unit>;
+//#endregion
+export { Unit, compoundUnit, dimensionalLayer, dimensionless, divideUnits, formatUnit, multiplyUnits, unit, unitsEqual };

package/dist/index.mjs

@@ -0,0 +1,180 @@
+//#region src/unit.ts
+/** Create a base unit, e.g. `unit("m")` → `{ num: ["m"], denom: [] }`. */
+function unit(name) {
+	return {
+		num: [name],
+		denom: []
+	};
+}
+/** The dimensionless unit (scalar). */
+function dimensionless() {
+	return {
+		num: [],
+		denom: []
+	};
+}
+/** Create an arbitrary compound unit from numerator and denominator base units. */
+function compoundUnit(num, denom) {
+	const result = cancelCommon([...num], [...denom]);
+	return {
+		num: result.num.sort(),
+		denom: result.denom.sort()
+	};
+}
+/** Multiply two units: `(a·b)`. Combines numerators and denominators, cancelling common factors. */
+function multiplyUnits(a, b) {
+	return compoundUnit([...a.num, ...b.num], [...a.denom, ...b.denom]);
+}
+/** Divide two units: `a / b`. */
+function divideUnits(a, b) {
+	return compoundUnit([...a.num, ...b.denom], [...a.denom, ...b.num]);
+}
+/** Structural equality of two units. */
+function unitsEqual(a, b) {
+	return arraysEqual(a.num, b.num) && arraysEqual(a.denom, b.denom);
+}
+/**
+* Format a unit as a human-readable string.
+*
+* - `"m"`, `"kg"` — simple base unit
+* - `"m/s"` — single numerator / single denominator
+* - `"m²"` — repeated base unit uses superscript exponents
+* - `"kg·m/s²"` — full compound unit
+* - `"1"` — dimensionless
+* - `"1/s"` — pure denominator
+*/
+function formatUnit(u) {
+	const numStr = formatHalf(u.num);
+	const denomStr = formatHalf(u.denom);
+	if (numStr === "" && denomStr === "") return "1";
+	if (denomStr === "") return numStr;
+	if (numStr === "") return `1/${denomStr}`;
+	return `${numStr}/${denomStr}`;
+}
+const superscripts = {
+	2: "²",
+	3: "³",
+	4: "⁴",
+	5: "⁵",
+	6: "⁶",
+	7: "⁷",
+	8: "⁸",
+	9: "⁹"
+};
+function formatHalf(units) {
+	if (units.length === 0) return "";
+	const counts = /* @__PURE__ */ new Map();
+	for (const u of units) counts.set(u, (counts.get(u) ?? 0) + 1);
+	const parts = [];
+	for (const [name, count] of [...counts.entries()].sort((a, b) => a[0].localeCompare(b[0]))) if (count === 1) parts.push(name);
+	else parts.push(`${name}${superscripts[count] ?? `^${count}`}`);
+	return parts.join("·");
+}
+function cancelCommon(num, denom) {
+	const remaining = [...denom];
+	const canceled = [];
+	for (const u of num) {
+		const idx = remaining.indexOf(u);
+		if (idx >= 0) remaining.splice(idx, 1);
+		else canceled.push(u);
+	}
+	return {
+		num: canceled,
+		denom: remaining
+	};
+}
+function arraysEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+//#endregion
+//#region src/dimensional-layer.ts
+/**
+* SI-style dimensional analysis layer for weft computation models.
+*
+* Propagates {@link Unit} values through the computation graph based on each
+* rule's `op`. When units are incompatible (e.g. adding metres to seconds),
+* the layer returns `undefined` — it never throws.
+*/
+const dimensionalLayer = {
+	name: "units",
+	version: "1",
+	eval(op, deps, spec) {
+		switch (op) {
+			case "sum":
+			case "difference":
+			case "weighted-sum":
+			case "min":
+			case "max": return requireSameUnit(deps);
+			case "ratio": {
+				const numKey = spec.numerator;
+				const denomRaw = spec.denominator;
+				const denomKey = typeof denomRaw === "string" ? denomRaw : typeof denomRaw === "object" && denomRaw !== null && "id" in denomRaw ? denomRaw.id : void 0;
+				const numUnit = numKey ? deps.get(numKey) : void 0;
+				const denomUnit = denomKey ? deps.get(denomKey) : void 0;
+				if (!numUnit || !denomUnit) return void 0;
+				return divideUnits(numUnit, denomUnit);
+			}
+			case "scale":
+			case "product": return multiplyAllUnits(deps);
+			case "negate":
+			case "abs":
+			case "clamp":
+			case "round": return firstUnit(deps);
+			case "conditional": {
+				const condKey = spec.condition;
+				for (const [id, u] of deps) if (id !== condKey) return u;
+				return;
+			}
+			case "future-value":
+			case "annuity-payment":
+			case "present-value": return financialUnit(deps, spec);
+			case "match": return firstUnit(deps);
+			case "compare":
+			case "and":
+			case "or":
+			case "not":
+			case "coerce":
+			case "format": return dimensionless();
+			case "project":
+			case "pluck":
+			case "pick":
+			case "compose":
+			case "spread": return;
+			default: return requireSameUnit(deps);
+		}
+	},
+	codec: {
+		encode: (u) => ({
+			num: [...u.num],
+			denom: [...u.denom]
+		}),
+		decode: (j) => j
+	}
+};
+function requireSameUnit(deps) {
+	let result;
+	for (const u of deps.values()) if (result === void 0) result = u;
+	else if (!unitsEqual(result, u)) return;
+	return result;
+}
+function multiplyAllUnits(deps) {
+	const values = [...deps.values()];
+	if (values.length === 0) return void 0;
+	let result = values[0];
+	for (let i = 1; i < values.length; i++) result = multiplyUnits(result, values[i]);
+	return result;
+}
+function firstUnit(deps) {
+	for (const u of deps.values()) return u;
+}
+function financialUnit(deps, spec) {
+	const monetaryOperand = spec.pv ?? spec.fv;
+	if (monetaryOperand === void 0) return void 0;
+	const monetaryKey = typeof monetaryOperand === "string" ? monetaryOperand : typeof monetaryOperand === "object" && monetaryOperand !== null && "id" in monetaryOperand ? monetaryOperand.id : void 0;
+	if (!monetaryKey) return void 0;
+	return deps.get(monetaryKey);
+}
+//#endregion
+export { compoundUnit, dimensionalLayer, dimensionless, divideUnits, formatUnit, multiplyUnits, unit, unitsEqual };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@spaceteams/weft-layer-dimensional",
+  "version": "0.2.0",
+  "description": "SI unit propagation and dimensional analysis layer for @spaceteams/weft",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spaceteams/weft.git",
+    "directory": "layers/dimensional"
+  },
+  "keywords": [
+    "weft",
+    "layer",
+    "dimensional",
+    "units",
+    "SI"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@spaceteams/weft": "0.5.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write ."
+  }
+}