@sladg/apex-state 4.6.0 → 4.7.0

package/dist/index.d.ts

@@ -986,6 +986,10 @@ type ClearPathInput = {
     triggers: Array<string>;
     targets: Array<string>;
 };
+type MathExprRegistration = {
+    target: string;
+    expr_json: string;
+};
 type SideEffectsRegistration = {
     registration_id: string;
     sync_pairs: Array<[string, string]>;
@@ -995,6 +999,7 @@ type SideEffectsRegistration = {
     clear_paths: Array<ClearPathInput>;
     computation_pairs: Array<unknown>;
     listeners: Array<ListenerRegistration$1>;
+    math_exprs: Array<MathExprRegistration>;
     anchor_path: string | null;
 };
 type ListenerRegistration$1 = {
@@ -1711,6 +1716,21 @@ interface SideEffects<DATA extends object, META extends GenericMeta = GenericMet
      * Accepts direct `ListenerRegistration<T>[]` or pre-validated result from `listeners()`.
      */
     listeners?: ListenerRegistration<DATA, META>[];
+    /**
+     * Math expressions - arbitrary numeric computations
+     * Format: { target: path, expr: MathExpr JSON }
+     * Evaluates reactively when source paths change.
+     *
+     * @example
+     * ```typescript
+     * math: [
+     *   { target: 'total', expr: { MUL: ['price', 'quantity'] } },
+     *   { target: 'discounted', expr: { SUB: [{ MUL: ['price', 'qty'] }, 'discount'] } },
+     *   { target: 'average', expr: { AVG: ['score1', 'score2', 'score3'] } },
+     * ]
+     * ```
+     */
+    math?: MathRegistration<DATA, Depth>[];
     /**
      * Anchor path - guard for all resources in this registration.
      * When the anchor path is structurally absent from shadow state, all listeners,
@@ -1719,6 +1739,59 @@ interface SideEffects<DATA extends object, META extends GenericMeta = GenericMet
      */
     anchorPath?: DeepKey<DATA, Depth>;
 }
+/**
+ * Numeric computation DSL — type-safe expression tree.
+ *
+ * Leaf nodes:
+ * - `number`: inline literal (`42`, `1.21`)
+ * - `string`: path reference (constrained to numeric paths in DATA)
+ *
+ * Operators:
+ * - Arithmetic: `{ ADD: [...] }`, `{ MUL: [...] }` (n-ary), `{ SUB: [a, b] }`, `{ DIV: [a, b] }`, `{ MOD: [a, b] }` (binary)
+ * - Reductions: `{ SUM: [...] }`, `{ AVG: [...] }`, `{ MIN: [...] }`, `{ MAX: [...] }`, `{ COUNT: [...] }` (n-ary)
+ * - Utilities: `{ ABS: expr }`, `{ NEGATE: expr }`, `{ ROUND: [expr, precision?] }`
+ * - Explicit ref: `{ REF: path }` (equivalent to bare string)
+ *
+ * @example
+ * ```typescript
+ * type State = { price: number; quantity: number; discount: number; total: number }
+ * const expr: MathExpr<State> = { SUB: [{ MUL: ['price', 'quantity'] }, 'discount'] }
+ * ```
+ */
+type MathExpr<DATA extends object, Depth extends number = DefaultDepth> = number | DeepKeyFiltered<DATA, number, Depth> | {
+    REF: DeepKeyFiltered<DATA, number, Depth>;
+} | {
+    ADD: MathExpr<DATA, Depth>[];
+} | {
+    SUB: [MathExpr<DATA, Depth>, MathExpr<DATA, Depth>];
+} | {
+    MUL: MathExpr<DATA, Depth>[];
+} | {
+    DIV: [MathExpr<DATA, Depth>, MathExpr<DATA, Depth>];
+} | {
+    MOD: [MathExpr<DATA, Depth>, MathExpr<DATA, Depth>];
+} | {
+    ABS: MathExpr<DATA, Depth>;
+} | {
+    NEGATE: MathExpr<DATA, Depth>;
+} | {
+    ROUND: [MathExpr<DATA, Depth>, number?];
+} | {
+    SUM: MathExpr<DATA, Depth>[];
+} | {
+    AVG: MathExpr<DATA, Depth>[];
+} | {
+    MIN: MathExpr<DATA, Depth>[];
+} | {
+    MAX: MathExpr<DATA, Depth>[];
+} | {
+    COUNT: MathExpr<DATA, Depth>[];
+};
+/** Math expression registration — type-safe target + expression tree. */
+interface MathRegistration<DATA extends object, Depth extends number = DefaultDepth> {
+    target: DeepKeyFiltered<DATA, number, Depth>;
+    expr: MathExpr<DATA, Depth>;
+}
 
 /**
  * Explicit return type of createGenericStore.