@flusys/nestjs-form-builder 6.0.2 → 6.1.1

package/fesm/utils/computed-field.utils.spec.js

@@ -0,0 +1,1201 @@
+import { calculateComputedFields } from './computed-field.utils';
+function directField(overrides = {}) {
+    return {
+        id: 'cf-1',
+        name: 'Computed',
+        key: 'total',
+        valueType: 'number',
+        rules: [
+            {
+                id: 'rule-1',
+                computation: {
+                    type: 'direct',
+                    config: {
+                        type: 'direct',
+                        value: 42
+                    }
+                }
+            }
+        ],
+        ...overrides
+    };
+}
+describe('calculateComputedFields', ()=>{
+    it('returns an empty object when there are no computed fields', ()=>{
+        expect(calculateComputedFields({}, undefined)).toEqual({});
+        expect(calculateComputedFields({}, [])).toEqual({});
+    });
+    it('keys the result by the field.key property, not field.id', ()=>{
+        const field = directField({
+            id: 'cf-id',
+            key: 'my_key'
+        });
+        const result = calculateComputedFields({}, [
+            field
+        ]);
+        expect(result).toEqual({
+            my_key: 42
+        });
+    });
+    it('evaluates multiple computed fields independently', ()=>{
+        const fields = [
+            directField({
+                key: 'a'
+            }),
+            directField({
+                key: 'b',
+                rules: [
+                    {
+                        id: 'r2',
+                        computation: {
+                            type: 'direct',
+                            config: {
+                                type: 'direct',
+                                value: 'hello'
+                            }
+                        }
+                    }
+                ],
+                valueType: 'string'
+            })
+        ];
+        const result = calculateComputedFields({}, fields);
+        expect(result).toEqual({
+            a: 42,
+            b: 'hello'
+        });
+    });
+    // ==========================================================================
+    // Rule matching / condition evaluation
+    // ==========================================================================
+    describe('condition evaluation', ()=>{
+        it('uses the first matching rule and ignores subsequent rules', ()=>{
+            const field = {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'string',
+                rules: [
+                    {
+                        id: 'rule-1',
+                        condition: {
+                            operator: 'AND',
+                            conditions: [
+                                {
+                                    fieldId: 'x',
+                                    comparison: 'equals',
+                                    value: 1
+                                }
+                            ]
+                        },
+                        computation: {
+                            type: 'direct',
+                            config: {
+                                type: 'direct',
+                                value: 'first'
+                            }
+                        }
+                    },
+                    {
+                        id: 'rule-2',
+                        computation: {
+                            type: 'direct',
+                            config: {
+                                type: 'direct',
+                                value: 'second'
+                            }
+                        }
+                    }
+                ]
+            };
+            const result = calculateComputedFields({
+                x: 1
+            }, [
+                field
+            ]);
+            expect(result.total).toBe('first');
+        });
+        it('falls through to the default value when no rule matches', ()=>{
+            const field = {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'string',
+                defaultValue: 'fallback',
+                rules: [
+                    {
+                        id: 'rule-1',
+                        condition: {
+                            operator: 'AND',
+                            conditions: [
+                                {
+                                    fieldId: 'x',
+                                    comparison: 'equals',
+                                    value: 1
+                                }
+                            ]
+                        },
+                        computation: {
+                            type: 'direct',
+                            config: {
+                                type: 'direct',
+                                value: 'matched'
+                            }
+                        }
+                    }
+                ]
+            };
+            const result = calculateComputedFields({
+                x: 2
+            }, [
+                field
+            ]);
+            expect(result.total).toBe('fallback');
+        });
+        it('returns null when no rule matches and no default value is set', ()=>{
+            const field = {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'string',
+                rules: [
+                    {
+                        id: 'rule-1',
+                        condition: {
+                            operator: 'AND',
+                            conditions: [
+                                {
+                                    fieldId: 'x',
+                                    comparison: 'equals',
+                                    value: 1
+                                }
+                            ]
+                        },
+                        computation: {
+                            type: 'direct',
+                            config: {
+                                type: 'direct',
+                                value: 'matched'
+                            }
+                        }
+                    }
+                ]
+            };
+            const result = calculateComputedFields({
+                x: 2
+            }, [
+                field
+            ]);
+            expect(result.total).toBeNull();
+        });
+        it('treats a missing/empty condition group as always-true', ()=>{
+            const field = directField({
+                key: 'total'
+            });
+            delete field.rules[0].condition;
+            const result = calculateComputedFields({}, [
+                field
+            ]);
+            expect(result.total).toBe(42);
+        });
+        it('AND operator requires all conditions to match', ()=>{
+            const field = {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'string',
+                defaultValue: 'no-match',
+                rules: [
+                    {
+                        id: 'rule-1',
+                        condition: {
+                            operator: 'AND',
+                            conditions: [
+                                {
+                                    fieldId: 'a',
+                                    comparison: 'equals',
+                                    value: 1
+                                },
+                                {
+                                    fieldId: 'b',
+                                    comparison: 'equals',
+                                    value: 2
+                                }
+                            ]
+                        },
+                        computation: {
+                            type: 'direct',
+                            config: {
+                                type: 'direct',
+                                value: 'matched'
+                            }
+                        }
+                    }
+                ]
+            };
+            expect(calculateComputedFields({
+                a: 1,
+                b: 2
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                a: 1,
+                b: 99
+            }, [
+                field
+            ]).total).toBe('no-match');
+        });
+        it('OR operator matches when at least one condition matches', ()=>{
+            const field = {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'string',
+                defaultValue: 'no-match',
+                rules: [
+                    {
+                        id: 'rule-1',
+                        condition: {
+                            operator: 'OR',
+                            conditions: [
+                                {
+                                    fieldId: 'a',
+                                    comparison: 'equals',
+                                    value: 1
+                                },
+                                {
+                                    fieldId: 'b',
+                                    comparison: 'equals',
+                                    value: 2
+                                }
+                            ]
+                        },
+                        computation: {
+                            type: 'direct',
+                            config: {
+                                type: 'direct',
+                                value: 'matched'
+                            }
+                        }
+                    }
+                ]
+            };
+            expect(calculateComputedFields({
+                a: 1,
+                b: 99
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                a: 99,
+                b: 99
+            }, [
+                field
+            ]).total).toBe('no-match');
+        });
+        it('normalizes lower-case / unknown operator strings to AND by default', ()=>{
+            const field = {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'string',
+                defaultValue: 'no-match',
+                rules: [
+                    {
+                        id: 'rule-1',
+                        condition: {
+                            operator: 'unknown-operator',
+                            conditions: [
+                                {
+                                    fieldId: 'a',
+                                    comparison: 'equals',
+                                    value: 1
+                                },
+                                {
+                                    fieldId: 'b',
+                                    comparison: 'equals',
+                                    value: 2
+                                }
+                            ]
+                        },
+                        computation: {
+                            type: 'direct',
+                            config: {
+                                type: 'direct',
+                                value: 'matched'
+                            }
+                        }
+                    }
+                ]
+            };
+            // Falls back to AND semantics, so a partial match should NOT trigger the rule.
+            expect(calculateComputedFields({
+                a: 1,
+                b: 99
+            }, [
+                field
+            ]).total).toBe('no-match');
+        });
+        it('normalizes lower-case "or" to OR semantics', ()=>{
+            const field = {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'string',
+                defaultValue: 'no-match',
+                rules: [
+                    {
+                        id: 'rule-1',
+                        condition: {
+                            operator: 'or',
+                            conditions: [
+                                {
+                                    fieldId: 'a',
+                                    comparison: 'equals',
+                                    value: 1
+                                }
+                            ]
+                        },
+                        computation: {
+                            type: 'direct',
+                            config: {
+                                type: 'direct',
+                                value: 'matched'
+                            }
+                        }
+                    }
+                ]
+            };
+            expect(calculateComputedFields({
+                a: 1
+            }, [
+                field
+            ]).total).toBe('matched');
+        });
+    });
+    // ==========================================================================
+    // Comparison operators
+    // ==========================================================================
+    describe('comparison operators', ()=>{
+        function withComparison(comparison, value) {
+            const field = {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'string',
+                defaultValue: 'no-match',
+                rules: [
+                    {
+                        id: 'rule-1',
+                        condition: {
+                            operator: 'AND',
+                            conditions: [
+                                {
+                                    fieldId: 'x',
+                                    comparison,
+                                    value
+                                }
+                            ]
+                        },
+                        computation: {
+                            type: 'direct',
+                            config: {
+                                type: 'direct',
+                                value: 'matched'
+                            }
+                        }
+                    }
+                ]
+            };
+            return field;
+        }
+        it('equals matches by strict or stringified equality', ()=>{
+            const field = withComparison('equals', '5');
+            expect(calculateComputedFields({
+                x: 5
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 6
+            }, [
+                field
+            ]).total).toBe('no-match');
+        });
+        it('not_equals is the inverse of equals', ()=>{
+            const field = withComparison('not_equals', '5');
+            expect(calculateComputedFields({
+                x: 6
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 5
+            }, [
+                field
+            ]).total).toBe('no-match');
+            expect(calculateComputedFields({
+                x: '5'
+            }, [
+                field
+            ]).total).toBe('no-match');
+        });
+        it('is_empty treats null, undefined, empty string and empty array as empty', ()=>{
+            const field = withComparison('is_empty', null);
+            expect(calculateComputedFields({
+                x: null
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: undefined
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: ''
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: []
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 0
+            }, [
+                field
+            ]).total).toBe('no-match');
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe('matched');
+        });
+        it('is_not_empty is the inverse of is_empty', ()=>{
+            const field = withComparison('is_not_empty', null);
+            expect(calculateComputedFields({
+                x: 'value'
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: ''
+            }, [
+                field
+            ]).total).toBe('no-match');
+        });
+        it('contains / not_contains perform substring checks', ()=>{
+            const contains = withComparison('contains', 'ell');
+            expect(calculateComputedFields({
+                x: 'hello'
+            }, [
+                contains
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 'world'
+            }, [
+                contains
+            ]).total).toBe('no-match');
+            const notContains = withComparison('not_contains', 'ell');
+            expect(calculateComputedFields({
+                x: 'world'
+            }, [
+                notContains
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 'hello'
+            }, [
+                notContains
+            ]).total).toBe('no-match');
+        });
+        it('starts_with / ends_with perform prefix/suffix checks', ()=>{
+            const startsWith = withComparison('starts_with', 'hel');
+            expect(calculateComputedFields({
+                x: 'hello'
+            }, [
+                startsWith
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 'shell'
+            }, [
+                startsWith
+            ]).total).toBe('no-match');
+            const endsWith = withComparison('ends_with', 'llo');
+            expect(calculateComputedFields({
+                x: 'hello'
+            }, [
+                endsWith
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 'llothing'
+            }, [
+                endsWith
+            ]).total).toBe('no-match');
+        });
+        it('numeric comparisons coerce operands with Number()', ()=>{
+            expect(calculateComputedFields({
+                x: 10
+            }, [
+                withComparison('greater_than', 5)
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 3
+            }, [
+                withComparison('greater_than', 5)
+            ]).total).toBe('no-match');
+            expect(calculateComputedFields({
+                x: 3
+            }, [
+                withComparison('less_than', 5)
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: '5'
+            }, [
+                withComparison('greater_or_equal', 5)
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 5
+            }, [
+                withComparison('less_or_equal', 5)
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 6
+            }, [
+                withComparison('less_or_equal', 5)
+            ]).total).toBe('no-match');
+        });
+        it('is_before / is_after compare Date values', ()=>{
+            const before = withComparison('is_before', '2024-06-01');
+            expect(calculateComputedFields({
+                x: '2024-01-01'
+            }, [
+                before
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: '2024-12-01'
+            }, [
+                before
+            ]).total).toBe('no-match');
+            const after = withComparison('is_after', '2024-06-01');
+            expect(calculateComputedFields({
+                x: '2024-12-01'
+            }, [
+                after
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: '2024-01-01'
+            }, [
+                after
+            ]).total).toBe('no-match');
+        });
+        it('is_checked treats true, "true" and 1 as checked', ()=>{
+            const field = withComparison('is_checked', null);
+            expect(calculateComputedFields({
+                x: true
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 'true'
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 1
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: false
+            }, [
+                field
+            ]).total).toBe('no-match');
+            expect(calculateComputedFields({
+                x: 0
+            }, [
+                field
+            ]).total).toBe('no-match');
+        });
+        it('is_not_checked treats false, "false", 0 and falsy as unchecked', ()=>{
+            const field = withComparison('is_not_checked', null);
+            expect(calculateComputedFields({
+                x: false
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 'false'
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 0
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: undefined
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: true
+            }, [
+                field
+            ]).total).toBe('no-match');
+        });
+        it('is_any_of / in match against an array of allowed values', ()=>{
+            const field = withComparison('is_any_of', [
+                'a',
+                'b',
+                'c'
+            ]);
+            expect(calculateComputedFields({
+                x: 'b'
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 'z'
+            }, [
+                field
+            ]).total).toBe('no-match');
+            const inField = withComparison('in', [
+                'a',
+                'b',
+                'c'
+            ]);
+            expect(calculateComputedFields({
+                x: 'a'
+            }, [
+                inField
+            ]).total).toBe('matched');
+        });
+        it('is_any_of returns false (no match) when compareValue is not an array', ()=>{
+            const field = withComparison('is_any_of', 'not-an-array');
+            expect(calculateComputedFields({
+                x: 'not-an-array'
+            }, [
+                field
+            ]).total).toBe('no-match');
+        });
+        it('is_none_of / not_in match when value is absent from the array', ()=>{
+            const field = withComparison('is_none_of', [
+                'a',
+                'b',
+                'c'
+            ]);
+            expect(calculateComputedFields({
+                x: 'z'
+            }, [
+                field
+            ]).total).toBe('matched');
+            expect(calculateComputedFields({
+                x: 'a'
+            }, [
+                field
+            ]).total).toBe('no-match');
+            const notIn = withComparison('not_in', [
+                'a',
+                'b',
+                'c'
+            ]);
+            expect(calculateComputedFields({
+                x: 'z'
+            }, [
+                notIn
+            ]).total).toBe('matched');
+        });
+        it('is_none_of treats a non-array compareValue as always matching', ()=>{
+            const field = withComparison('is_none_of', 'not-an-array');
+            expect(calculateComputedFields({
+                x: 'anything'
+            }, [
+                field
+            ]).total).toBe('matched');
+        });
+        it('returns false for unknown comparison operators', ()=>{
+            const field = withComparison('some_unknown_operator', 1);
+            expect(calculateComputedFields({
+                x: 1
+            }, [
+                field
+            ]).total).toBe('no-match');
+        });
+    });
+    // ==========================================================================
+    // Computation types
+    // ==========================================================================
+    describe('direct computation', ()=>{
+        it('coerces the direct value to a number when valueType is number', ()=>{
+            const field = directField({
+                valueType: 'number'
+            });
+            field.rules[0].computation = {
+                type: 'direct',
+                config: {
+                    type: 'direct',
+                    value: '42'
+                }
+            };
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe(42);
+        });
+        it('coerces the direct value to a string when valueType is string', ()=>{
+            const field = directField({
+                valueType: 'string'
+            });
+            field.rules[0].computation = {
+                type: 'direct',
+                config: {
+                    type: 'direct',
+                    value: 42
+                }
+            };
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe('42');
+        });
+    });
+    describe('field_reference computation', ()=>{
+        it('reads the referenced field value and coerces per valueType', ()=>{
+            const field = directField({
+                valueType: 'number'
+            });
+            field.rules[0].computation = {
+                type: 'field_reference',
+                config: {
+                    type: 'field_reference',
+                    fieldId: 'age'
+                }
+            };
+            expect(calculateComputedFields({
+                age: '30'
+            }, [
+                field
+            ]).total).toBe(30);
+        });
+        it('returns null when the referenced field is null or undefined', ()=>{
+            const field = directField({
+                valueType: 'number'
+            });
+            field.rules[0].computation = {
+                type: 'field_reference',
+                config: {
+                    type: 'field_reference',
+                    fieldId: 'age'
+                }
+            };
+            expect(calculateComputedFields({
+                age: null
+            }, [
+                field
+            ]).total).toBeNull();
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBeNull();
+        });
+        it('coerces the referenced field to a string when valueType is string', ()=>{
+            const field = directField({
+                valueType: 'string'
+            });
+            field.rules[0].computation = {
+                type: 'field_reference',
+                config: {
+                    type: 'field_reference',
+                    fieldId: 'age'
+                }
+            };
+            expect(calculateComputedFields({
+                age: 30
+            }, [
+                field
+            ]).total).toBe('30');
+        });
+    });
+    describe('unknown / malformed computation configs', ()=>{
+        it('returns null for an unrecognized computation type', ()=>{
+            const field = directField();
+            field.rules[0].computation = {
+                type: 'not-a-real-type',
+                config: {}
+            };
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBeNull();
+        });
+        it('returns null when computation.type does not match its config shape', ()=>{
+            const field = directField();
+            // type says "direct" but config is missing the "value" property expected by the type guard
+            field.rules[0].computation = {
+                type: 'direct',
+                config: {
+                    type: 'field_reference',
+                    fieldId: 'x'
+                }
+            };
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBeNull();
+        });
+    });
+    // ==========================================================================
+    // Arithmetic computation
+    // ==========================================================================
+    describe('arithmetic computation', ()=>{
+        function arithmeticField(config) {
+            return {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'number',
+                rules: [
+                    {
+                        id: 'rule-1',
+                        computation: {
+                            type: 'arithmetic',
+                            config
+                        }
+                    }
+                ]
+            };
+        }
+        it('sum adds all operand values (fields + constants)', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'sum',
+                operands: [
+                    {
+                        type: 'field',
+                        fieldId: 'a'
+                    },
+                    {
+                        type: 'field',
+                        fieldId: 'b'
+                    },
+                    {
+                        type: 'constant',
+                        value: 10
+                    }
+                ]
+            });
+            expect(calculateComputedFields({
+                a: 5,
+                b: 3
+            }, [
+                field
+            ]).total).toBe(18);
+        });
+        it('increment behaves the same as sum', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'increment',
+                operands: [
+                    {
+                        type: 'constant',
+                        value: 1
+                    },
+                    {
+                        type: 'constant',
+                        value: 2
+                    }
+                ]
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe(3);
+        });
+        it('subtract subtracts subsequent operands from the first', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'subtract',
+                operands: [
+                    {
+                        type: 'constant',
+                        value: 10
+                    },
+                    {
+                        type: 'constant',
+                        value: 3
+                    },
+                    {
+                        type: 'constant',
+                        value: 2
+                    }
+                ]
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe(5);
+        });
+        it('decrement behaves the same as subtract', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'decrement',
+                operands: [
+                    {
+                        type: 'constant',
+                        value: 10
+                    },
+                    {
+                        type: 'constant',
+                        value: 4
+                    }
+                ]
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe(6);
+        });
+        it('multiply multiplies all operand values', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'multiply',
+                operands: [
+                    {
+                        type: 'constant',
+                        value: 2
+                    },
+                    {
+                        type: 'constant',
+                        value: 3
+                    },
+                    {
+                        type: 'constant',
+                        value: 4
+                    }
+                ]
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe(24);
+        });
+        it('divide divides the first operand by each subsequent operand in order', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'divide',
+                operands: [
+                    {
+                        type: 'constant',
+                        value: 100
+                    },
+                    {
+                        type: 'constant',
+                        value: 2
+                    },
+                    {
+                        type: 'constant',
+                        value: 5
+                    }
+                ]
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe(10);
+        });
+        it('divide safely skips division by zero operands (guards against Infinity/NaN)', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'divide',
+                operands: [
+                    {
+                        type: 'constant',
+                        value: 100
+                    },
+                    {
+                        type: 'constant',
+                        value: 0
+                    }
+                ]
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe(100);
+        });
+        it('average computes the mean of all operand values', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'average',
+                operands: [
+                    {
+                        type: 'constant',
+                        value: 2
+                    },
+                    {
+                        type: 'constant',
+                        value: 4
+                    },
+                    {
+                        type: 'constant',
+                        value: 6
+                    }
+                ]
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe(4);
+        });
+        it('min / max compute the extremes among operand values', ()=>{
+            const operands = [
+                {
+                    type: 'constant',
+                    value: 5
+                },
+                {
+                    type: 'constant',
+                    value: 1
+                },
+                {
+                    type: 'constant',
+                    value: 9
+                }
+            ];
+            expect(calculateComputedFields({}, [
+                arithmeticField({
+                    type: 'arithmetic',
+                    operation: 'min',
+                    operands
+                })
+            ]).total).toBe(1);
+            expect(calculateComputedFields({}, [
+                arithmeticField({
+                    type: 'arithmetic',
+                    operation: 'max',
+                    operands
+                })
+            ]).total).toBe(9);
+        });
+        it('treats missing field operand values as 0', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'sum',
+                operands: [
+                    {
+                        type: 'field',
+                        fieldId: 'missing'
+                    },
+                    {
+                        type: 'constant',
+                        value: 5
+                    }
+                ]
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe(5);
+        });
+        it('treats a constant operand with an undefined value as 0', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'sum',
+                operands: [
+                    {
+                        type: 'constant'
+                    },
+                    {
+                        type: 'constant',
+                        value: 5
+                    }
+                ]
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBe(5);
+        });
+        it('returns null for an unknown arithmetic operation', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'unknown-op',
+                operands: [
+                    {
+                        type: 'constant',
+                        value: 1
+                    }
+                ]
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBeNull();
+        });
+        it('returns null when operands array is empty', ()=>{
+            const field = arithmeticField({
+                type: 'arithmetic',
+                operation: 'sum',
+                operands: []
+            });
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBeNull();
+        });
+        it('does not treat an arithmetic config as valid when operands is not an array', ()=>{
+            const field = directField();
+            field.rules[0].computation = {
+                type: 'arithmetic',
+                config: {
+                    type: 'arithmetic',
+                    operation: 'sum',
+                    operands: 'not-an-array'
+                }
+            };
+            // Fails the isArithmeticConfig type guard -> falls through to "unknown computation type" -> null
+            expect(calculateComputedFields({}, [
+                field
+            ]).total).toBeNull();
+        });
+    });
+    // ==========================================================================
+    // Error handling / malformed field defensive fallback
+    // ==========================================================================
+    describe('defensive error handling', ()=>{
+        it('falls back to defaultValue when field.rules is malformed and calculation throws', ()=>{
+            const field = {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'number',
+                defaultValue: -1,
+                rules: undefined
+            };
+            const result = calculateComputedFields({}, [
+                field
+            ]);
+            expect(result.total).toBe(-1);
+        });
+        it('falls back to null when field.rules is malformed and no defaultValue is set', ()=>{
+            const field = {
+                id: 'cf-1',
+                name: 'Total',
+                key: 'total',
+                valueType: 'number',
+                rules: undefined
+            };
+            const result = calculateComputedFields({}, [
+                field
+            ]);
+            expect(result.total).toBeNull();
+        });
+        it('isolates failures per field — one bad field does not break the others', ()=>{
+            const badField = {
+                id: 'cf-bad',
+                name: 'Bad',
+                key: 'bad',
+                valueType: 'number',
+                defaultValue: 0,
+                rules: undefined
+            };
+            const goodField = directField({
+                key: 'good'
+            });
+            const result = calculateComputedFields({}, [
+                badField,
+                goodField
+            ]);
+            expect(result).toEqual({
+                bad: 0,
+                good: 42
+            });
+        });
+    });
+});