form0-core 0.1.6 → 0.1.7

package/package.json

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

package/src/index.js

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

package/src/utilities/calculation-editor.js

@@ -296,6 +296,33 @@ function sanitizeCollectedWarnings(warnings) {
   }));
 }
 
+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
  *
@@ -615,30 +642,34 @@ export function analyzeCalculationExpression({
 }
 
 /**
- * Simulate a CalculatedField expression against form0-core's real evaluation engine.
+ * 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.values]
  * @param {Object} [options.security]
  * @returns {{
- *   result: unknown,
- *   runtimeError: string | null,
- *   warnings: Array<{
- *     message: string,
- *     suggestion: string | null,
- *     context: Object | null,
- *     fieldContext: Object | null,
- *   }>,
+ *   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 simulateCalculationExpression({
+export function createCalculationPreviewSession({
   schema,
   fieldDataName,
   expression,
-  values = {},
   security = DEFAULT_SECURITY_CONFIG,
 }) {
   const simulationSchema = cloneSimulationSchema(schema);
@@ -647,17 +678,19 @@ export function simulateCalculationExpression({
 
   if (!targetField) {
     return {
-      result: null,
-      runtimeError: `Field '${fieldDataName}' does not exist in the form schema.`,
-      warnings: [],
+      run: () =>
+        createSimulationErrorResult(
+          `Field '${fieldDataName}' does not exist in the form schema.`
+        ),
+      dispose: () => {},
     };
   }
 
   if (targetField.type !== 'CalculatedField') {
     return {
-      result: null,
-      runtimeError: `Field '${fieldDataName}' is not a CalculatedField.`,
-      warnings: [],
+      run: () =>
+        createSimulationErrorResult(`Field '${fieldDataName}' is not a CalculatedField.`),
+      dispose: () => {},
     };
   }
 
@@ -666,41 +699,113 @@ export function simulateCalculationExpression({
   const warningSystem = new WarningSystem({
     enableCollection: true,
     enableConsoleWarnings: false,
+    throttleMs: 0,
   });
   const runtimeDiagnostics = [];
+  const engine = createFormEngine({
+    schema: simulationSchema,
+    initialValues: {},
+    security,
+    warningSystem,
+    runtimeDiagnostics,
+  });
 
-  try {
-    const engine = createFormEngine({
-      schema: simulationSchema,
-      initialValues:
-        values && typeof values === 'object' && !Array.isArray(values) ? values : {},
-      security,
-      warningSystem,
-      runtimeDiagnostics,
-    });
+  engine.eval();
 
-    engine.eval();
+  const engineState = engine.getState();
+  const baselineValues = deepClone(engineState.values);
+  let currentExpression = targetField.calculate;
+  let disposed = false;
 
-    const engineState = engine.getState();
-    const simulatedResult = engineState.values[fieldDataName];
-    const runtimeError =
-      runtimeDiagnostics.find((diagnostic) => diagnostic.fieldName === fieldDataName)?.message ||
-      runtimeDiagnostics[0]?.message ||
-      null;
+  return {
+    run: ({ expression: nextExpression, values = {} } = {}) => {
+      if (disposed) {
+        return createSimulationErrorResult('Calculation preview session has been disposed.');
+      }
 
-    return {
-      result: simulatedResult === undefined ? null : simulatedResult,
-      runtimeError,
-      warnings: sanitizeCollectedWarnings(warningSystem.getCollectedWarnings()),
-    };
-  } catch (error) {
-    return {
-      result: null,
-      runtimeError:
-        error instanceof Error && error.message
-          ? error.message
-          : 'Unknown calculation simulation error.',
-      warnings: sanitizeCollectedWarnings(warningSystem.getCollectedWarnings()),
-    };
+      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();
   }
 }