form0-core 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
@@ -8,7 +8,7 @@
   "main": "src/index.js",
   "type": "module",
   "scripts": {
-    "test": "node tests/form0-core.test.js && node tests/builtin-metadata.test.js && node tests/calculation-editor.test.js && node tests/security-test.js",
+    "test": "node tests/form0-core.test.js && node tests/builtin-metadata.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/security-test.js",
     "postinstall": "node scripts/postinstall.cjs",
     "format": "prettier --write \"**/*.{js,jsx,json,ts,tsx,md}\"",
     "format:check": "prettier --check \"**/*.{js,jsx,json,ts,tsx,md}\""

package/src/builtins/control/setresult.js

@@ -22,7 +22,7 @@ export const SETRESULT_METADATA = defineBuiltinMetadata({
   signature: 'SETRESULT(value)',
   description: 'Set the final return value for multiline calculations.',
   examples: ['SETRESULT($price * $quantity)'],
-  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION],
 });
 
 export const SETRESULT = (value) => {

package/src/builtins/event/control/off.js

@@ -1,5 +1,6 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
 import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
+import { isValidEventType } from '../../../engine/event-registry.js';
 
 /**
  * OFF builtin for form events
@@ -37,6 +38,16 @@ export const OFF_METADATA = defineBuiltinMetadata({
 });
 
 export function OFF(eventType, fieldKeyOrCallback, callback) {
+  if (typeof eventType !== 'string' || eventType.trim().length === 0) {
+    console.warn('[form0] OFF() requires a non-empty event type string');
+    return null;
+  }
+
+  if (!isValidEventType(eventType)) {
+    console.warn(`[form0] OFF() received an unknown event type: ${eventType}`);
+    return null;
+  }
+
   let fieldKey = '*';
   let actualCallback = undefined;
 

package/src/builtins/event/control/on.js

@@ -1,5 +1,6 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
 import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
+import { isValidEventType } from '../../../engine/event-registry.js';
 
 /**
  * ON builtin for form events
@@ -29,6 +30,16 @@ export const ON_METADATA = defineBuiltinMetadata({
 });
 
 export function ON(eventType, fieldKeyOrCallback, callback) {
+  if (typeof eventType !== 'string' || eventType.trim().length === 0) {
+    console.warn('[form0] ON() requires a non-empty event type string');
+    return null;
+  }
+
+  if (!isValidEventType(eventType)) {
+    console.warn(`[form0] ON() received an unknown event type: ${eventType}`);
+    return null;
+  }
+
   let fieldKey = '*';
   let actualCallback = fieldKeyOrCallback;
 
@@ -38,6 +49,11 @@ export function ON(eventType, fieldKeyOrCallback, callback) {
     actualCallback = callback;
   }
 
+  if (typeof actualCallback !== 'function') {
+    console.warn('[form0] ON() requires a callback function');
+    return null;
+  }
+
   // Create operation descriptor
   const operation = {
     type: 'EVENT_OPERATION',

package/src/builtins/registry.js

@@ -65,7 +65,7 @@ export { ON, ON_METADATA } from './event/control/on.js';
 export { OFF, OFF_METADATA } from './event/control/off.js';
 export { __consumeEventOperations } from './event/event-operations-collector.js';
 
-const CALCULATION_AND_EVENT_ENTRIES = Object.freeze([
+const COMMON_RUNTIME_ENTRIES = Object.freeze([
   { implementation: IF, definition: IF_METADATA },
   { implementation: AND, definition: AND_METADATA },
   { implementation: OR, definition: OR_METADATA },
@@ -73,7 +73,6 @@ const CALCULATION_AND_EVENT_ENTRIES = Object.freeze([
   { implementation: COUNTA, definition: COUNTA_METADATA },
   { implementation: COUNTBLANK, definition: COUNTBLANK_METADATA },
   { implementation: ARRAY, definition: ARRAY_METADATA },
-  { implementation: SETRESULT, definition: SETRESULT_METADATA },
   { implementation: EVAL, definition: EVAL_METADATA },
   { implementation: CHOICEVALUE, definition: CHOICEVALUE_METADATA },
   { implementation: CHOICELABEL, definition: CHOICELABEL_METADATA },
@@ -91,6 +90,10 @@ const CALCULATION_AND_EVENT_ENTRIES = Object.freeze([
   { implementation: UPPER, definition: UPPER_METADATA },
 ]);
 
+const CALCULATION_ONLY_ENTRIES = Object.freeze([
+  { implementation: SETRESULT, definition: SETRESULT_METADATA },
+]);
+
 const EVENT_ONLY_ENTRIES = Object.freeze([
   { implementation: ALERT, definition: ALERT_METADATA },
   { implementation: SETVALUE, definition: SETVALUE_METADATA },
@@ -110,12 +113,23 @@ function filterDefinitionsByContext(definitions, context) {
   return Object.freeze(definitions.filter((definition) => definition.contexts.includes(context)));
 }
 
-export const builtins = buildBuiltinObject(CALCULATION_AND_EVENT_ENTRIES);
+export const calculationBuiltins = buildBuiltinObject([
+  ...COMMON_RUNTIME_ENTRIES,
+  ...CALCULATION_ONLY_ENTRIES,
+]);
+
+export const eventBuiltins = buildBuiltinObject([
+  ...COMMON_RUNTIME_ENTRIES,
+  ...EVENT_ONLY_ENTRIES,
+]);
 
-export const eventBuiltins = buildBuiltinObject(EVENT_ONLY_ENTRIES);
+// Backward-compatible alias for calculation runtime helpers.
+export const builtins = calculationBuiltins;
 
 export const BUILTIN_DEFINITIONS = Object.freeze(
-  [...CALCULATION_AND_EVENT_ENTRIES, ...EVENT_ONLY_ENTRIES].map(({ definition }) => definition)
+  [...COMMON_RUNTIME_ENTRIES, ...CALCULATION_ONLY_ENTRIES, ...EVENT_ONLY_ENTRIES].map(
+    ({ definition }) => definition
+  )
 );
 
 export const CALCULATION_BUILTIN_DEFINITIONS = filterDefinitionsByContext(

package/src/engine/calculation.js

@@ -1,7 +1,12 @@
 import { runExpression } from './evaluator.js';
-import { flattenFields } from '../utilities/field-helpers.js';
 import { ContextResolver } from './context-resolver.js';
 import { WarningSystem } from './warning-system.js';
+import {
+  buildCalculationDependencyPlan,
+  buildCalculationExecutionContext,
+  extractStaticFieldReferences,
+} from '../utilities/calculation-dependencies.js';
+import { areStructuredValuesEqual } from '../utilities/value-equality.js';
 
 export function evaluateCalculatedFields(
   schema,
@@ -10,69 +15,68 @@ export function evaluateCalculatedFields(
   securityConfig,
   contextResolver = null,
   warningSystem = null,
-  runtimeDiagnostics = null
+  runtimeDiagnostics = null,
+  calculationPlan = null
 ) {
-  const fields = flattenFields(schema.elements);
-
-  // Initialize context resolver and warning system if not provided (backward compatibility)
   const resolver = contextResolver || new ContextResolver(schema);
   const warnings = warningSystem || new WarningSystem();
+  const plan = calculationPlan || buildCalculationDependencyPlan(schema, resolver);
 
-  fields.forEach((field) => {
-    if (field.type === 'CalculatedField' && field.calculate) {
-      try {
-        // Create execution context for this calculation
-        const executionContext = {
-          type: 'calculation',
-          fieldName: field.data_name,
-          parentPath: resolver.getFieldInfo(field.data_name)?.parentPath || [],
-        };
-
-        const context = buildScopedContext(
-          values,
-          helpers,
-          executionContext,
-          resolver,
-          warnings,
-          field.calculate
-        );
-        values[field.data_name] = runExpression(
-          field.calculate,
-          context,
-          securityConfig,
-          false,
-          schema,
-          {
-            suppressConsoleWarning: Array.isArray(runtimeDiagnostics),
-            onError: (error) => {
-              if (!Array.isArray(runtimeDiagnostics)) {
-                return;
-              }
-
-              runtimeDiagnostics.push({
-                fieldName: field.data_name,
-                message:
-                  error instanceof Error && error.message
-                    ? error.message
-                    : 'Unknown calculation runtime error.',
-              });
-            },
-          }
-        );
-      } catch (e) {
-        if (Array.isArray(runtimeDiagnostics)) {
-          runtimeDiagnostics.push({
-            fieldName: field.data_name,
-            message:
-              e instanceof Error && e.message
-                ? e.message
-                : 'Unknown calculation runtime error.',
-          });
-        }
-        if (!Array.isArray(runtimeDiagnostics)) {
-          console.warn(`Calculation failed for ${field.data_name}:`, e.message);
-        }
-      }
+  emitDependencyPlanWarnings(plan, warnings, runtimeDiagnostics);
+
+  if (plan.totalCalculatedFieldCount === 0) {
+    return;
+  }
+
+  if (plan.hasDynamicDependencies) {
+    evaluateFieldSequenceUntilStable(
+      plan.orderedFieldNames,
+      plan,
+      schema,
+      values,
+      helpers,
+      securityConfig,
+      resolver,
+      warnings,
+      runtimeDiagnostics
+    );
+    return;
+  }
+
+  plan.orderedComponentIds.forEach((componentId) => {
+    const component = plan.componentsById.get(componentId);
+    if (!component || component.fieldNames.length === 0) {
+      return;
+    }
+
+    if (component.isCyclic) {
+      evaluateFieldSequenceUntilStable(
+        component.fieldNames,
+        plan,
+        schema,
+        values,
+        helpers,
+        securityConfig,
+        resolver,
+        warnings,
+        runtimeDiagnostics
+      );
+      return;
+    }
+
+    const fieldName = component.fieldNames[0];
+    const node = plan.nodesByDataName.get(fieldName);
+    if (node?.field) {
+      evaluateCalculatedField(
+        node.field,
+        schema,
+        values,
+        helpers,
+        securityConfig,
+        resolver,
+        warnings,
+        runtimeDiagnostics
+      );
     }
   });
 }
@@ -87,43 +91,32 @@ function buildScopedContext(
 ) {
   const ctx = { ...helpers };
 
-  // Find which fields are actually referenced in the expression
-  const referencedFields = extractFieldReferences(expressionCode);
-
-  // Track problematic fields that are actually accessed
+  const referencedFields = extractStaticFieldReferences(expressionCode);
   const restrictedAccessedFields = [];
   const notFoundAccessedFields = [];
 
-  // Add scoped field access
   for (const [fieldName, value] of Object.entries(values)) {
     const accessLevel = contextResolver.resolveFieldAccess(executionContext, fieldName);
 
     if (accessLevel === 'accessible') {
       ctx[`$${fieldName}`] = value;
     } else if (accessLevel === 'restricted') {
-      // Only add restricted fields to context if they're actually referenced
       if (referencedFields.has(fieldName)) {
         ctx[`$${fieldName}`] = undefined;
         restrictedAccessedFields.push(fieldName);
       }
-      // If not referenced, don't add to context at all
     }
-    // 'not_found' fields are not added to context at all
   }
 
-  // Check for not_found fields that are actually referenced
   for (const fieldName of referencedFields) {
-    // Check if this field was processed above (exists in values)
     if (!(fieldName in values)) {
       const accessLevel = contextResolver.resolveFieldAccess(executionContext, fieldName);
       if (accessLevel === 'not_found') {
         notFoundAccessedFields.push(fieldName);
-        // Don't add to context - it will be undefined when accessed
       }
     }
   }
 
-  // Emit warnings for restricted fields that are actually accessed
   restrictedAccessedFields.forEach((fieldName) => {
     const warning = contextResolver.generateAccessWarning(
       executionContext,
@@ -133,7 +126,6 @@ function buildScopedContext(
     warningSystem.emitWarning(warning);
   });
 
-  // Emit warnings for not_found fields that are actually accessed
   notFoundAccessedFields.forEach((fieldName) => {
     const warning = contextResolver.generateAccessWarning(executionContext, fieldName, 'not_found');
     warningSystem.emitWarning(warning);
@@ -142,93 +134,225 @@ function buildScopedContext(
   return ctx;
 }
 
-/**
- * Extract field references from expression code (simple regex-based approach)
- * Skips field references inside EVAL() calls to avoid false positives from dynamic field construction
- * @param {string} code - The expression/code to analyze
- * @returns {Set<string>} Set of field names referenced in the code
- */
-function extractFieldReferences(code) {
-  const fieldReferences = new Set();
-
-  // Remove content inside EVAL() calls to avoid false positives
-  // This handles complex patterns like EVAL('string' + variable + 'more')
-  const cleanedCode = removeEvalContents(code);
-
-  // Simple regex to find $fieldname patterns in the cleaned code
-  // This matches $ followed by valid JavaScript identifier characters
-  const fieldRegex = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
-  let match;
-
-  while ((match = fieldRegex.exec(cleanedCode)) !== null) {
-    fieldReferences.add(match[1]); // Add the field name (without $)
+function pushRuntimeDiagnostic(
+  runtimeDiagnostics,
+  fieldName,
+  message,
+  severity = 'error',
+  dedupeKey = null
+) {
+  if (!Array.isArray(runtimeDiagnostics)) {
+    return;
   }
 
-  return fieldReferences;
+  if (
+    dedupeKey &&
+    runtimeDiagnostics.some(
+      (diagnostic) =>
+        diagnostic?.fieldName === fieldName &&
+        diagnostic?.message === message &&
+        diagnostic?.dedupeKey === dedupeKey
+    )
+  ) {
+    return;
+  }
+
+  runtimeDiagnostics.push({
+    fieldName,
+    message,
+    severity,
+    dedupeKey,
+  });
 }
 
-/**
- * Remove EVAL() function calls and their contents from code
- * Handles nested parentheses and complex expressions inside EVAL()
- * @param {string} code - The code to clean
- * @returns {string} Code with EVAL() contents removed
- */
-function removeEvalContents(code) {
-  let result = '';
-  let i = 0;
-
-  while (i < code.length) {
-    // Look for EVAL pattern
-    const evalMatch = code.substring(i).match(/^EVAL\s*\(/);
-    if (evalMatch) {
-      // Found EVAL(, add "EVAL()" to result and skip the entire call
-      result += 'EVAL()';
-      i += evalMatch[0].length;
-
-      // Skip everything until we find the matching closing parenthesis
-      let parenCount = 1;
-      let inSingleQuote = false;
-      let inDoubleQuote = false;
-      let inBacktick = false;
-
-      while (i < code.length && parenCount > 0) {
-        const char = code[i];
-
-        // Handle string literals (ignore parentheses inside strings)
-        if (char === "'" && !inDoubleQuote && !inBacktick) {
-          inSingleQuote = !inSingleQuote;
-        } else if (char === '"' && !inSingleQuote && !inBacktick) {
-          inDoubleQuote = !inDoubleQuote;
-        } else if (char === '`' && !inSingleQuote && !inDoubleQuote) {
-          inBacktick = !inBacktick;
-        }
-
-        // Only count parentheses when not inside strings
-        if (!inSingleQuote && !inDoubleQuote && !inBacktick) {
-          if (char === '(') {
-            parenCount++;
-          } else if (char === ')') {
-            parenCount--;
-          }
-        }
-
-        i++;
-      }
-    } else {
-      // Not an EVAL call, add character to result
-      result += code[i];
-      i++;
+function emitDependencyPlanWarnings(plan, warningSystem, runtimeDiagnostics) {
+  plan.dynamicFieldNames.forEach((fieldName) => {
+    const message = `CalculatedField '${fieldName}' uses dynamic field access. Runtime evaluation falls back to bounded stabilization.`;
+    warningSystem.emitWarning({
+      type: 'calculation_dependency',
+      reason: 'dynamic_dependencies',
+      message,
+      suggestion: 'Prefer direct $field references when possible to enable dependency ordering.',
+      executionContext: {
+        type: 'calculation',
+        fieldName,
+      },
+      fieldContext: {
+        fieldName,
+        dynamic: true,
+      },
+    });
+    pushRuntimeDiagnostic(
+      runtimeDiagnostics,
+      fieldName,
+      message,
+      'warning',
+      `dynamic:${fieldName}`
+    );
+  });
+
+  plan.cyclicComponentIds.forEach((componentId) => {
+    const component = plan.componentsById.get(componentId);
+    if (!component?.isCyclic) {
+      return;
     }
+
+    const fieldNames = component.fieldNames;
+    const message = `CalculatedField dependency cycle detected: ${fieldNames.join(' -> ')}. Runtime evaluation will use bounded stabilization.`;
+    warningSystem.emitWarning({
+      type: 'calculation_dependency',
+      reason: 'cyclic_dependencies',
+      message,
+      suggestion:
+        'Remove the cycle or break it with a source field so calculated values can be evaluated deterministically.',
+      executionContext: {
+        type: 'calculation',
+        fieldName: fieldNames[0] || null,
+      },
+      fieldContext: {
+        fieldNames: [...fieldNames],
+        cyclic: true,
+      },
+    });
+
+    fieldNames.forEach((fieldName) => {
+      pushRuntimeDiagnostic(
+        runtimeDiagnostics,
+        fieldName,
+        message,
+        'warning',
+        `cycle:${componentId}`
+      );
+    });
+  });
+}
+
+function evaluateCalculatedField(
+  field,
+  schema,
+  values,
+  helpers,
+  securityConfig,
+  resolver,
+  warnings,
+  runtimeDiagnostics
+) {
+  if (!field?.data_name || !field.calculate) {
+    return { changed: false, hasError: false };
   }
 
-  return result;
+  try {
+    const executionContext = buildCalculationExecutionContext(schema, field.data_name, resolver);
+    const context = buildScopedContext(
+      values,
+      helpers,
+      executionContext,
+      resolver,
+      warnings,
+      field.calculate
+    );
+    const previousValue = values[field.data_name];
+    const nextValue = runExpression(field.calculate, context, securityConfig, false, schema, {
+      suppressConsoleWarning: Array.isArray(runtimeDiagnostics),
+      onError: (error) => {
+        pushRuntimeDiagnostic(
+          runtimeDiagnostics,
+          field.data_name,
+          error instanceof Error && error.message
+            ? error.message
+            : 'Unknown calculation runtime error.'
+        );
+      },
+    });
+    values[field.data_name] = nextValue;
+
+    return {
+      changed: !areStructuredValuesEqual(previousValue, nextValue),
+      hasError: false,
+    };
+  } catch (error) {
+    pushRuntimeDiagnostic(
+      runtimeDiagnostics,
+      field.data_name,
+      error instanceof Error && error.message ? error.message : 'Unknown calculation runtime error.'
+    );
+
+    if (!Array.isArray(runtimeDiagnostics)) {
+      console.warn(`Calculation failed for ${field.data_name}:`, error?.message);
+    }
+
+    return { changed: false, hasError: true };
+  }
 }
 
-// Legacy function for backward compatibility
-function buildContext(values, helpers) {
-  const ctx = {};
-  for (const key in values) {
-    ctx[`$${key}`] = values[key];
+function evaluateFieldSequenceUntilStable(
+  fieldNames,
+  plan,
+  schema,
+  values,
+  helpers,
+  securityConfig,
+  resolver,
+  warnings,
+  runtimeDiagnostics
+) {
+  const maxPasses = Math.max(2, plan.totalCalculatedFieldCount);
+  let stillChangingFieldNames = [];
+
+  for (let pass = 0; pass < maxPasses; pass += 1) {
+    stillChangingFieldNames = [];
+
+    fieldNames.forEach((fieldName) => {
+      const node = plan.nodesByDataName.get(fieldName);
+      if (!node?.field) {
+        return;
+      }
+
+      const result = evaluateCalculatedField(
+        node.field,
+        schema,
+        values,
+        helpers,
+        securityConfig,
+        resolver,
+        warnings,
+        runtimeDiagnostics
+      );
+
+      if (result.changed) {
+        stillChangingFieldNames.push(fieldName);
+      }
+    });
+
+    if (stillChangingFieldNames.length === 0) {
+      return;
+    }
   }
-  return { ...ctx, ...helpers };
+
+  const message = `Calculated fields did not stabilize within ${maxPasses} evaluation passes: ${stillChangingFieldNames.join(', ')}.`;
+  warnings.emitWarning({
+    type: 'calculation_dependency',
+    reason: 'non_converging_runtime',
+    message,
+    suggestion:
+      'Review the involved CalculatedField expressions for dependency cycles or dynamic references that never settle.',
+    executionContext: {
+      type: 'calculation',
+      fieldName: stillChangingFieldNames[0] || null,
+    },
+    fieldContext: {
+      fieldNames: [...stillChangingFieldNames],
+      maxPasses,
+    },
+  });
+
+  stillChangingFieldNames.forEach((fieldName) => {
+    pushRuntimeDiagnostic(
+      runtimeDiagnostics,
+      fieldName,
+      message,
+      'warning',
+      `non-converging:${fieldNames.join(',')}`
+    );
+  });
 }