@coldsmirk/abacus-core 0.2.0 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@ Part of [abacus](https://github.com/coldsmirk/abacus). To edit expressions in an
 ## What you get
 
 - **Evaluate** ZEN expressions against a data context, sync or async.
-- **Compile** a structured, UI-authored condition tree into a single ZEN boolean expression, and **select** a matching branch by priority.
+- **Compile** a structured, UI-authored condition tree into a single ZEN boolean expression — and **lift** the canonical form back into a tree for round-trip editing — plus **select** a matching branch by priority.
 - **Type-analyze** an expression against a variable-context type tree — the inferred type of every span, autocomplete metadata, and positioned diagnostics that power an editor.
 - **Localize** all editor-produced text through a typed, extensible message catalog.
 - **Strong typing** end to end, dual ESM / CJS, and a single lazily-loaded WebAssembly engine instance.
@@ -44,6 +44,8 @@ ZEN has two expression flavours, selected throughout this package by a `mode: "s
 - **standard** — computes a value of any type, e.g. `amount * 1.2`, `customer.name`, `upper(code)`.
 - **unary** — a boolean _test_ against an implicit subject `$`, e.g. `$ > 1000`, `$ in ['BJ', 'SH']`. Used for conditions.
 
+The `ExpressionMode` union carries a third value, **`"template"`**, for the editor layer: literal text with `{{ expression }}` holes, each hole a standard expression. It is edited and validated hole-by-hole (`analyzeTemplateSync`, `getTemplateDiagnosticsSync`, `parseTemplateHoles` / `templateHoleAt`); the single-expression functions treat `"template"` as `"standard"`. Templates are not directly evaluable here — the ZEN wasm exposes no template renderer — so there is no `evaluateTemplate`.
+
 ### The engine loads once, lazily
 
 The multi-megabyte WebAssembly binary is fetched on first use via a dynamic `import()`, then cached as a single frozen instance for the lifetime of the page. Every helper comes in two forms:
@@ -292,6 +294,53 @@ type BranchSelection =
   | { matched: false; branchId: string | null };        // default fallback, or null if none
 ```
 
+### Condition trees
+
+The flat model above is one AND-group per branch. For a structured builder UI — arbitrarily nested AND/OR groups of typed comparison rules — the package also models a **condition tree** and compiles it to a single canonical expression, with an exact inverse:
+
+```ts
+interface ConditionTreeRule {                    // a leaf comparison
+  kind: "rule";
+  left: string;                                  // an identifier path, like `subject`
+  operator: ConditionTreeOperator;               // the compiler's full 14-operator set
+  right?: ConditionTreeValue;                    // per the operator's arity (see below)
+}
+interface ConditionTreeGroup {                   // an and/or group of rules and subgroups
+  kind: "group";
+  op: "and" | "or";
+  items: readonly ConditionTreeNode[];
+}
+type ConditionTreeNode = ConditionTreeGroup | ConditionTreeRule;
+
+function compileConditionTree(tree: ConditionTreeGroup): string;
+function liftConditionTree(expression: string): ConditionTreeGroup | null;
+function conditionOperatorArity(operator: ConditionOperator): "scalar" | "array" | "none";
+```
+
+```ts
+import { compileConditionTree, liftConditionTree } from "@coldsmirk/abacus-core";
+
+const tree = {
+  kind: "group", op: "or", items: [
+    { kind: "group", op: "and", items: [
+      { kind: "rule", left: "amount", operator: "gt", right: 1000 },
+      { kind: "rule", left: "vip", operator: "eq", right: true },
+    ] },
+    { kind: "rule", left: "region", operator: "eq", right: "CN" },
+  ],
+} as const;
+
+compileConditionTree(tree);   // → "(amount > 1000 and vip == true) or region == 'CN'"
+liftConditionTree("(amount > 1000 and vip == true) or region == 'CN'");  // → the tree above
+liftConditionTree("len(name) > 3");                                      // → null: not canonical
+```
+
+A rule's `right` follows its operator's **arity** — a single scalar (`string | number | boolean`) for the comparison and string operators, an array of scalars for `in` / `not_in`, absent for `is_empty` / `is_not_empty`. `conditionOperatorArity` classifies the operators so a condition UI can pick value editors from the same definition the compiler enforces. `CONDITION_TREE_OPERATORS` is the same runtime list as `CONDITION_OPERATORS` under the tree name.
+
+The emitted expression is **canonical**: nested groups are always parenthesized (never relying on `and`/`or` precedence), single-item groups collapse to their item, and a rule the tree cannot represent canonically — a non-path `left`, an off-arity `right`, a value with no ZEN literal — is dropped like an invalid flat condition. A tree with nothing compilable yields `""`.
+
+`liftConditionTree` recognizes exactly that canonical subset (whitespace-tolerantly), so the two functions round-trip: everything `compileConditionTree` emits lifts back to an equal tree, and anything else — a raw hand-authored expression, mixed `and`/`or` without parentheses, groups nested beyond 64 levels — returns `null` rather than guessing at structure. That `null` is a host's signal to fall back to raw-expression editing instead of a structured builder; [`@coldsmirk/abacus-mantine`](https://www.npmjs.com/package/@coldsmirk/abacus-mantine)'s `<ConditionBuilder>` is built on exactly this contract.
+
 ### Safety: subjects, values, and escaping
 
 The compiler is designed not to become an expression-injection sink:
@@ -365,10 +414,12 @@ class ExpressionNotReadyError extends ExpressionError {  // a *Sync helper calle
 - **Evaluate** — `evaluate`, `evaluateSync`, `evaluateUnary`, `evaluateUnarySync`
 - **Engine lifecycle** — `loadEngine`, `isEngineReady`, `getEngineSync`, `getEngineError`, `configureEngine`, `resetEngine`
 - **Type analysis** — `analyzeTypes` / `analyzeTypesSync`, `getDiagnostics` / `getDiagnosticsSync`, `getCompletionItems` / `getCompletionItemsSync`, `satisfiesType` / `satisfiesTypeSync`
-- **Conditions** — `compileCondition`, `compileGroup`, `compileBranch`, `selectBranch`, `selectBranchWith`, `toZenLiteral`, `CONDITION_OPERATORS`
+- **Templates** — `analyzeTemplate` / `analyzeTemplateSync`, `getTemplateDiagnostics` / `getTemplateDiagnosticsSync`, `parseTemplateHoles`, `templateHoleAt`
+- **Conditions** — `compileCondition`, `compileGroup`, `compileBranch`, `selectBranch`, `selectBranchWith`, `toZenLiteral`, `CONDITION_OPERATORS`, `conditionOperatorArity`
+- **Condition trees** — `compileConditionTree`, `liftConditionTree`, `CONDITION_TREE_OPERATORS`
 - **Localization** — `configureExpressionMessages`, `registerExpressionLocale`, `getExpressionMessages`, `enMessages`, `zhCNMessages`
 - **Errors** — `ExpressionError`, `ExpressionNotReadyError`
-- **Types** — `ExpressionType`, `ExpressionMode`, `ExpressionContext`, `ExpressionEngine`, `LoadEngineOptions`, `ExpressionAnalysis`, `ExpressionTypeSpan`, `ExpressionCompletion`, `ExpressionDiagnostic`, `ExpressionMessages`, `ExpressionLocale`, `BuiltInExpressionLocale`, `ConfigureMessagesOptions`, `ConditionInput`, `FieldConditionInput`, `ExpressionConditionInput`, `ConditionGroupInput`, `ConditionBranchInput`, `ConditionOperator`, `BranchSelection`
+- **Types** — `ExpressionType`, `ExpressionMode`, `TemplateHole`, `ExpressionContext`, `ExpressionEngine`, `LoadEngineOptions`, `ExpressionAnalysis`, `ExpressionTypeSpan`, `ExpressionCompletion`, `ExpressionDiagnostic`, `ExpressionMessages`, `ExpressionLocale`, `BuiltInExpressionLocale`, `ConfigureMessagesOptions`, `ConditionInput`, `FieldConditionInput`, `ExpressionConditionInput`, `ConditionGroupInput`, `ConditionBranchInput`, `ConditionOperator`, `ConditionOperatorArity`, `BranchSelection`, `ConditionTreeGroup`, `ConditionTreeNode`, `ConditionTreeRule`, `ConditionTreeOperator`, `ConditionTreeValue`, `ConditionScalar`
 
 ## License