Scoped Re-evaluation: Preventing Unnecessary FEEL Expression Evaluation in Large Forms

ent.type); }

### 2. Schema-Based Field Registry
Replace repeated component scans with a pre-built lookup structure. Initialize on `form.init` and rebuild only when the schema structure changes.

```javascript
// ✅ Build a Set of datetime field keys on init

_datetimeFieldKeys = new Set();

_buildDatetimeFieldRegistry() {
  this._datetimeFieldKeys.clear();

  if (!this._form?._state?.schema) return;

  const components = this._getAllComponents(
    this._form._state.schema.components || []
  );

  components.forEach(component => {
    if (['date', 'datetime', 'time'].includes(component.type) && component.key) {
      this._datetimeFieldKeys.add(component.key);
      // Also add by id in case events use id instead of key
      if (component.id) this._datetimeFieldKeys.add(component.id);
    }
  });
}

// ✅ O(1) lookup instead of O(n) scan
_isDatetimeField(fieldKey) {
  return this._datetimeFieldKeys.has(fieldKey);
}

Initialize on form.init and rebuild when the schema changes:

this._eventBus.on('form.init', () => {
  this._initialized = true;
  this._buildDatetimeFieldRegistry();
  setTimeout(() => this.evaluateAll(), 50);
});

this._eventBus.on('propertiesPanel.updated', () => {
  // Schema may have changed (new datetime field added or removed)
  this._buildDatetimeFieldRegistry();

  if (!this._initialized || this._evaluating) return;
  setTimeout(() => {
    if (!this._evaluating) this.evaluateAll();
  }, 50);
});

3. Context Filtering

FEEL expressions in datetime validation only reference other datetime fields and temporal helpers. Passing the entire form state pollutes the context and increases resolution overhead.

// ❌ Full context — 50+ values, most irrelevant
prepareContext(data) {
  const context = {};
  Object.keys(data).forEach(key => {
    context[key] = this._coerceValue(data[key]);
  });
  context.today = () => { ... };
  context.now = () => new Date();
  return context;
}

// ✅ Filtered context — only datetime values + date helpers
_getRelevantFormData(data) {
  const context = {};

  // Only include datetime field values
  this._datetimeFieldKeys.forEach(fieldKey => {
    if (data[fieldKey] !== undefined) {
      // ✅ Convert string dates to Date objects for FEEL comparison
      const converted = this._coerceDateValue(data[fieldKey]);
      context[fieldKey] = converted !== null ? converted : data[fieldKey];
    }
  });

  // ✅ Current field's value available as 'value'
  // (set per-component during evaluation)

  // ✅ Date/time helpers always available
  context.today = () => {
    const d = new Date();
    d.setHours(0, 0, 0, 0);
    return d;
  };
  context.now = () => new Date();
  context.tomorrow = () => {
    const d = new Date();
    d.setDate(d.getDate() + 1);
    d.setHours(0, 0, 0, 0);
    return d;
  };
  context.yesterday = () => {
    const d = new Date();
    d.setDate(d.getDate() - 1);
    d.setHours(0, 0, 0, 0);
    return d;
  };

  return context;
}

4. Date/Time Coercion

FEEL requires native Date objects for temporal comparisons. Form-JS stores dates as ISO strings. The coercion layer bridges this gap safely.

_coerceDateValue(rawValue, type = 'date') {
  if (!rawValue || typeof rawValue !== 'string') return null;

  const v = rawValue.trim();
  if (!v) return null;

  try {
    if (type === 'date' || /^\d{4}-\d{2}-\d{2}$/.test(v)) {
      // "2024-01-15" → Date at local midnight
      return new Date(v + 'T00:00:00');
    }

    if (type === 'datetime' || /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(v)) {
      // "2024-01-15 10:30:00" → Date (space to T)
      return new Date(v.replace(' ', 'T'));
    }

    if (type === 'time' || /^\d{2}:\d{

Pitfall Guide

1. Ignoring Event Payload Structure: The changed event may pass component.id instead of component.key. Always check both keys in your registry or fallback logic to avoid missed triggers.
2. O(n) Scans on Every Change: Repeatedly calling _getAllComponents() inside the changed handler creates linear performance degradation as form size grows. Always pre-build registries on form.init.
3. Full Context Pollution: Passing the entire form._state.data to FEEL increases variable resolution overhead and risks accidental key collisions (e.g., a text field named startDate overriding a datetime field). Filter context strictly to relevant keys.
4. Missing Date/Time Coercion: FEEL cannot compare ISO strings using >= or <= operators correctly. Always coerce string values to native Date objects before evaluation, and handle timezone/local midnight boundaries explicitly.
5. Stale Registry After Schema Updates: Dynamic forms or properties panel edits can add/remove datetime fields. Failing to listen to propertiesPanel.updated and rebuild the registry causes evaluators to ignore newly added fields or crash on removed ones.
6. Overlapping setTimeout Debouncing: Multiple rapid changed events can queue overlapping setTimeout calls, causing race conditions or duplicate evaluations. Always guard with an _evaluating flag and clear/replace pending timeouts when necessary.

Deliverables

• 📐 Scoped Evaluator Blueprint: A reusable class template implementing field-type gating, schema registry, context filtering, and debounce guards. Adaptable to NumberValidationEvaluator, ConditionalVisibilityEvaluator, or CrossFieldDependencyEvaluator.
• ✅ Implementation Checklist:
  • Map target field types to a Set on form.init
  • Attach changed listener with early-return gating
  • Filter evaluation context to only relevant keys + domain helpers
  • Implement type-specific coercion (Date, Number, Boolean)
  • Subscribe to propertiesPanel.updated for registry rebuilds
  • Add _evaluating guard + setTimeout debouncing
• ⚙️ Configuration Templates: Pre-configured context builders for datetime, numeric range, and cross-field dependency validation. Includes helper functions (today(), now(), min(), max()) and safe coercion pipelines ready for drop-in integration.