Core Engine Internals

This document covers the "hidden" technical details and internal logic discovered during a deep audit of the @dfbe/core source code.

1. Logic Evaluation Depth Guard

To prevent infinite recursion or performance degradation in extremely complex forms, the ConditionEvaluator implements a strict MAX_DEPTH limit.

• Limit: 5 levels of nested logic groups (and/or).
• Behavior: If the limit is exceeded, the evaluation returns false and logs an error to the console.

2. Rule Evaluation & Precedence

Rules are not just a simple list; they follow a specific precedence and default behavior:

• Precedence: If multiple rules match and affect the same property (e.g., two rules trying to set label), the last matching rule in the rules array takes precedence.
• Smart Visibility: If a field has one or more rules with a visible: true effect, but no rules with a visible: false effect, the engine automatically assumes the field should be hidden by default.
• Batch Updates: All field effects are calculated in a single pass using evaluateFieldEffects before the UI re-renders, ensuring no flickering of intermediate states.

3. The Calculation Loop Guard

The FieldRenderer implements a sophisticated protection mechanism for computedValue side-effects.

• The Problem: A field A has a computed value based on field B, and B has a computed value based on A. This creates an infinite loop.
• The Solution: A tickCounterRef tracks how many times a field value is updated in a single execution tick.
• Limit: The engine checks tickCounterRef.current > 5. This means if a value is updated 6 or more times in one tick, the engine halts the update for that field and logs an error.

4. Dot-Notation Resolution

The engine uses a recursive resolver for field paths. This allows you to bind components to deep data structures without flattening your state.

• Function: getNestedValue(obj, path)
• Example: profile.education.university.id will correctly traverse the RHF state object to find the nested value.
• Safety: If any part of the path is null or undefined, the resolver returns undefined immediately rather than throwing.

5. Dependency Tracking System

Re-renders are highly optimized via the extractFieldDependencies system. The engine only watches the fields that are actually mentioned in:

1. The visibleIf condition.
2. Any rule.condition.
3. Any rule.effects of type label, helperText, or computedValue that use string interpolation (e.g., label: "Hello {{name}}").
4. The dataSource.dependsOn property.

This ensures that typing in a "Phone Number" field doesn't trigger logic recalculations for an unrelated "Address" section.

6. Computed Value Engine

The engine supports more than just string interpolation; it includes a safe Math Evaluator.

• Syntax: computedValue: "{{price}} * {{quantity}}"
• Security: The evaluator uses a strict regex to only allow numbers and basic math operators (+, -, *, /, ., ()). It will NOT evaluate any string containing letters or potentially malicious code.
• Fail-safe: If the evaluation fails or the syntax is incomplete (during typing), it returns the raw interpolated string.

7. Dataset Compatibility

While most fields can be defined in the schema, the External Dataset feature is strictly restricted to high-performance selection components:

• Supported Types: combobox, searchable-select.
• Behavior: If a dataset is assigned to a field of any other type, the engine throws a runtime error — it will not silently pass.
• Reasoning: These components are designed to handle the ID → Object transformation and O(1) Map lookups without performance bottlenecks.