@businessdash/sdk 0.9.60

package/src/forms-core/calculation.ts

@@ -0,0 +1,167 @@
+/**
+ * Calculation/Math form-element runtime — the bridge between a form's
+ * "calculation" field and the Business Functions engine.
+ *
+ * A calculation field computes a value from OTHER fields in the same form,
+ * either by an **inline formula** (mode "formula") or by referencing a saved
+ * **business function** (mode "function"). Input variables are bound to source
+ * fields via `inputMap` (variable name → source field id). The result is the
+ * field's submitted value; for a multi-output function, `outputKey` selects
+ * which exported variable to surface (default: the function's first output).
+ *
+ * Sensitivity: a calculation that references a `sensitive` function MUST run
+ * server-only (its formula/def is never published). This module is pure and
+ * environment-agnostic — the CALLER decides whether to run it (the client skips
+ * sensitive calcs and shows a placeholder; the server always computes the
+ * authoritative value on submit).
+ *
+ * Pure + isomorphic (no DB, no React). The SDK mirrors it.
+ */
+
+import {
+	type BusinessFunctionDef,
+	runBusinessFunction,
+} from "./business-function.js";
+import {
+	type EvalOptions,
+	type FormulaObject,
+	type FormulaValue,
+	type FormulaVars,
+	runFormula,
+} from "./formula.js";
+
+export interface CalcInputBinding {
+	/** The variable name (formula) or function input key this binding feeds. */
+	variable: string;
+	/** The source field id whose value supplies it. */
+	fieldId: string;
+}
+
+export interface CalcDisplay {
+	/** Show the computed value live in the rendered form. */
+	show?: boolean;
+	prefix?: string;
+	suffix?: string;
+	/** Fixed decimal places for a numeric result (omit = as-is). */
+	decimals?: number;
+}
+
+export interface CalculationConfig {
+	mode?: "formula" | "function";
+	/** Inline expression (mode "formula"). Non-sensitive only. */
+	formula?: string;
+	/** Referenced business function id (mode "function"). */
+	functionId?: string;
+	/** Which function output to surface as the value (default: first output). */
+	outputKey?: string;
+	/** Binds variables / function input keys to source field ids. */
+	inputMap?: CalcInputBinding[];
+	display?: CalcDisplay;
+	/** True when it references a sensitive function → compute server-only. */
+	sensitive?: boolean;
+}
+
+export interface CalcResult {
+	ok: boolean;
+	/** The surfaced value (the chosen output, or the formula result). */
+	value: FormulaValue | null;
+	/** For a function calc, the full exported object. */
+	outputs?: FormulaObject;
+	error?: string;
+}
+
+export interface CalcContext {
+	/** Saved business functions keyed by id (for mode "function"). */
+	functionsById?: Record<string, BusinessFunctionDef>;
+	/** Eval options exposing other functions for composition (by UPPERCASE slug). */
+	evalOptions?: EvalOptions;
+}
+
+/** Coerce an arbitrary source-field value into something the engine accepts. */
+function toFormulaValue(raw: unknown): FormulaValue | undefined {
+	if (raw === null || raw === undefined || raw === "") return undefined;
+	if (typeof raw === "number" || typeof raw === "boolean") return raw;
+	if (typeof raw === "string") return raw;
+	if (typeof raw === "object" && !Array.isArray(raw))
+		return raw as FormulaObject;
+	return String(raw);
+}
+
+/** Apply display formatting (prefix/suffix/decimals) for rendering. Pure. */
+export function formatCalcValue(
+	value: FormulaValue | null,
+	display?: CalcDisplay,
+): string {
+	if (value === null || value === undefined) return "";
+	let body: string;
+	if (
+		typeof value === "number" &&
+		display?.decimals !== undefined &&
+		Number.isFinite(value)
+	) {
+		body = value.toFixed(display.decimals);
+	} else if (typeof value === "object") {
+		body = JSON.stringify(value);
+	} else {
+		body = String(value);
+	}
+	return `${display?.prefix ?? ""}${body}${display?.suffix ?? ""}`;
+}
+
+/**
+ * Compute a calculation field. `resolveField(fieldId)` returns the current
+ * value of a source field. Never throws — returns `{ ok:false, error }` on a
+ * bad config or evaluation error.
+ */
+export function computeCalculation(
+	config: CalculationConfig,
+	resolveField: (fieldId: string) => unknown,
+	ctx: CalcContext = {},
+): CalcResult {
+	const bindings = config.inputMap ?? [];
+
+	if (config.mode === "function") {
+		const def = config.functionId
+			? ctx.functionsById?.[config.functionId]
+			: undefined;
+		if (!def) {
+			return {
+				ok: false,
+				value: null,
+				error: "Referenced function not found.",
+			};
+		}
+		const rawInputs: Record<string, unknown> = {};
+		for (const b of bindings) {
+			rawInputs[b.variable] = resolveField(b.fieldId);
+		}
+		const run = runBusinessFunction(def, rawInputs, ctx.evalOptions);
+		const key = config.outputKey ?? def.outputs[0]?.key;
+		const value =
+			key !== undefined && key in run.outputs ? run.outputs[key] : null;
+		const result: CalcResult = {
+			ok: run.ok,
+			value: value ?? null,
+			outputs: run.outputs,
+		};
+		if (!run.ok) {
+			result.error = run.issues
+				.map((i) => `${i.scope}/${i.key}: ${i.reason}`)
+				.join("; ");
+		}
+		return result;
+	}
+
+	// mode "formula" (default)
+	const formula = config.formula?.trim();
+	if (!formula) {
+		return { ok: false, value: null, error: "No formula." };
+	}
+	const vars: FormulaVars = {};
+	for (const b of bindings) {
+		vars[b.variable] = toFormulaValue(resolveField(b.fieldId));
+	}
+	const r = runFormula(formula, vars, ctx.evalOptions);
+	if (!r.ok) return { ok: false, value: null, error: r.error };
+	return { ok: true, value: r.value };
+}