form0-core 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },

package/src/engine/calculation.js

@@ -9,7 +9,8 @@ export function evaluateCalculatedFields(
   helpers,
   securityConfig,
   contextResolver = null,
-  warningSystem = null
+  warningSystem = null,
+  runtimeDiagnostics = null
 ) {
   const fields = flattenFields(schema.elements);
 
@@ -40,10 +41,37 @@ export function evaluateCalculatedFields(
           context,
           securityConfig,
           false,
-          schema
+          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) {
-        console.warn(`Calculation failed for ${field.data_name}:`, e.message);
+        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);
+        }
       }
     }
   });

package/src/engine/evaluator.js

@@ -13,13 +13,16 @@ export function runExpression(
   context = {},
   securityConfig = DEFAULT_SECURITY_CONFIG,
   includeEventBuiltins = false,
-  schema = null
+  schema = null,
+  options = {}
 ) {
   try {
     // Validate expression based on security mode
     const validation = validateExpression(expr, securityConfig, includeEventBuiltins);
     if (!validation.valid) {
-      console.warn('[form0] Expression validation failed:', validation.reason);
+      if (!options.suppressConsoleWarning) {
+        console.warn('[form0] Expression validation failed:', validation.reason);
+      }
       return null;
     }
 
@@ -73,7 +76,12 @@ export function runExpression(
 
     return executeExpression();
   } catch (e) {
-    console.warn('[form0] Expression evaluation failed:', e.message);
+    if (typeof options.onError === 'function') {
+      options.onError(e);
+    }
+    if (!options.suppressConsoleWarning) {
+      console.warn('[form0] Expression evaluation failed:', e.message);
+    }
     return null;
   }
 }

package/src/engine/form-engine.js

@@ -19,6 +19,7 @@ export function createFormEngine({
   helpers = {},
   security = DEFAULT_SECURITY_CONFIG,
   warningSystem = null,
+  runtimeDiagnostics = null,
 }) {
   const { schema: preparedSchema, buildingPlanMeta } = expandBuildingPlanSchema(schema);
 
@@ -126,7 +127,8 @@ export function createFormEngine({
       allHelpers,
       security,
       contextResolver,
-      sharedWarningSystem
+      sharedWarningSystem,
+      runtimeDiagnostics
     );
     evaluateRequirement(form, values, required);
     evaluateVisibility(form, values, visible);

package/src/index.js

@@ -35,6 +35,8 @@ export {
   getCalculationBuiltinCatalog,
   getCalculationReferenceCatalog,
   analyzeCalculationExpression,
+  createCalculationPreviewSession,
+  simulateCalculationExpression,
 } from './utilities/calculation-editor.js';
 export {
   getFormAIMetadata,

package/src/utilities/calculation-editor.js

@@ -4,6 +4,8 @@ import {
   CALCULATION_BUILTIN_DEFINITIONS,
 } from '../builtins/registry.js';
 import { ContextResolver } from '../engine/context-resolver.js';
+import { createFormEngine } from '../engine/form-engine.js';
+import { WarningSystem } from '../engine/warning-system.js';
 import { DEFAULT_SECURITY_CONFIG } from '../security/config.js';
 import { validateExpression } from '../security/validation.js';
 import {
@@ -238,6 +240,89 @@ function createSchemaFilteredSecurityConfig(securityConfig) {
   };
 }
 
+function deepClone(value) {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(value);
+  }
+
+  return JSON.parse(JSON.stringify(value));
+}
+
+function cloneSimulationSchema(schema) {
+  if (schema && schema.form && Array.isArray(schema.form.elements)) {
+    return deepClone(schema);
+  }
+
+  return {
+    form: deepClone(normalizeFormSchema(schema)),
+  };
+}
+
+function findFieldByDataName(elements, fieldDataName) {
+  if (!Array.isArray(elements)) {
+    return null;
+  }
+
+  for (const element of elements) {
+    if (!element || typeof element !== 'object') {
+      continue;
+    }
+
+    if (element.data_name === fieldDataName) {
+      return element;
+    }
+
+    if (Array.isArray(element.elements)) {
+      const nestedMatch = findFieldByDataName(element.elements, fieldDataName);
+      if (nestedMatch) {
+        return nestedMatch;
+      }
+    }
+  }
+
+  return null;
+}
+
+function sanitizeCollectedWarnings(warnings) {
+  if (!Array.isArray(warnings)) {
+    return [];
+  }
+
+  return warnings.map((warning) => ({
+    message: warning?.message || '',
+    suggestion: warning?.suggestion || null,
+    context: warning?.context || null,
+    fieldContext: warning?.fieldContext || null,
+  }));
+}
+
+function clearRecord(record) {
+  if (!record || typeof record !== 'object') {
+    return;
+  }
+
+  Object.keys(record).forEach((key) => {
+    delete record[key];
+  });
+}
+
+function resetEngineValues(targetValues, sourceValues) {
+  clearRecord(targetValues);
+  Object.assign(targetValues, deepClone(sourceValues));
+}
+
+function normalizeSimulationValues(values) {
+  return values && typeof values === 'object' && !Array.isArray(values) ? values : {};
+}
+
+function createSimulationErrorResult(runtimeError, warnings = []) {
+  return {
+    result: null,
+    runtimeError,
+    warnings,
+  };
+}
+
 /**
  * @typedef {'stable' | 'advanced' | 'unavailable'} CalculationBuiltinStatus
  *
@@ -555,3 +640,172 @@ export function analyzeCalculationExpression({
     referencedFields,
   };
 }
+
+/**
+ * Create a reusable preview session for CalculatedField authoring.
+ *
+ * @param {Object} options
+ * @param {Object} options.schema
+ * @param {string} options.fieldDataName
+ * @param {string} options.expression
+ * @param {Object} [options.security]
+ * @returns {{
+ *   run: (options?: {
+ *     expression?: string,
+ *     values?: Object,
+ *   }) => {
+ *     result: unknown,
+ *     runtimeError: string | null,
+ *     warnings: Array<{
+ *       message: string,
+ *       suggestion: string | null,
+ *       context: Object | null,
+ *       fieldContext: Object | null,
+ *     }>,
+ *   },
+ *   dispose: () => void,
+ * }}
+ */
+export function createCalculationPreviewSession({
+  schema,
+  fieldDataName,
+  expression,
+  security = DEFAULT_SECURITY_CONFIG,
+}) {
+  const simulationSchema = cloneSimulationSchema(schema);
+  const form = normalizeFormSchema(simulationSchema);
+  const targetField = findFieldByDataName(form.elements, fieldDataName);
+
+  if (!targetField) {
+    return {
+      run: () =>
+        createSimulationErrorResult(
+          `Field '${fieldDataName}' does not exist in the form schema.`
+        ),
+      dispose: () => {},
+    };
+  }
+
+  if (targetField.type !== 'CalculatedField') {
+    return {
+      run: () =>
+        createSimulationErrorResult(`Field '${fieldDataName}' is not a CalculatedField.`),
+      dispose: () => {},
+    };
+  }
+
+  targetField.calculate = typeof expression === 'string' ? expression : '';
+
+  const warningSystem = new WarningSystem({
+    enableCollection: true,
+    enableConsoleWarnings: false,
+    throttleMs: 0,
+  });
+  const runtimeDiagnostics = [];
+  const engine = createFormEngine({
+    schema: simulationSchema,
+    initialValues: {},
+    security,
+    warningSystem,
+    runtimeDiagnostics,
+  });
+
+  engine.eval();
+
+  const engineState = engine.getState();
+  const baselineValues = deepClone(engineState.values);
+  let currentExpression = targetField.calculate;
+  let disposed = false;
+
+  return {
+    run: ({ expression: nextExpression, values = {} } = {}) => {
+      if (disposed) {
+        return createSimulationErrorResult('Calculation preview session has been disposed.');
+      }
+
+      warningSystem.clearCollectedWarnings();
+      runtimeDiagnostics.length = 0;
+
+      if (typeof nextExpression === 'string' && nextExpression !== currentExpression) {
+        targetField.calculate = nextExpression;
+        currentExpression = nextExpression;
+      }
+
+      resetEngineValues(engineState.values, baselineValues);
+      Object.assign(engineState.values, normalizeSimulationValues(values));
+
+      try {
+        engine.eval();
+
+        const simulatedResult = engineState.values[fieldDataName];
+        const runtimeError =
+          runtimeDiagnostics.find((diagnostic) => diagnostic.fieldName === fieldDataName)
+            ?.message ||
+          runtimeDiagnostics[0]?.message ||
+          null;
+
+        return {
+          result: simulatedResult === undefined ? null : simulatedResult,
+          runtimeError,
+          warnings: sanitizeCollectedWarnings(warningSystem.getCollectedWarnings()),
+        };
+      } catch (error) {
+        return createSimulationErrorResult(
+          error instanceof Error && error.message
+            ? error.message
+            : 'Unknown calculation simulation error.',
+          sanitizeCollectedWarnings(warningSystem.getCollectedWarnings())
+        );
+      }
+    },
+    dispose: () => {
+      disposed = true;
+      warningSystem.clearCollectedWarnings();
+      runtimeDiagnostics.length = 0;
+      clearRecord(engineState.values);
+    },
+  };
+}
+
+/**
+ * Simulate a CalculatedField expression against form0-core's real evaluation engine.
+ *
+ * @param {Object} options
+ * @param {Object} options.schema
+ * @param {string} options.fieldDataName
+ * @param {string} options.expression
+ * @param {Object} [options.values]
+ * @param {Object} [options.security]
+ * @returns {{
+ *   result: unknown,
+ *   runtimeError: string | null,
+ *   warnings: Array<{
+ *     message: string,
+ *     suggestion: string | null,
+ *     context: Object | null,
+ *     fieldContext: Object | null,
+ *   }>,
+ * }}
+ */
+export function simulateCalculationExpression({
+  schema,
+  fieldDataName,
+  expression,
+  values = {},
+  security = DEFAULT_SECURITY_CONFIG,
+}) {
+  const session = createCalculationPreviewSession({
+    schema,
+    fieldDataName,
+    expression,
+    security,
+  });
+  try {
+    return session.run({
+      expression,
+      values,
+    });
+  } finally {
+    session.dispose();
+  }
+}