form0-core 0.6.0 → 0.8.0

package/src/utilities/record-transformer.js

@@ -8,6 +8,9 @@ import { recordVersion } from './version-utils.js';
 import { buildRepeatableMetadata } from './repeatable-helpers.js';
 import { buildDatasetDescriptors, resolveDatasetRowTitle } from './dataset-descriptors.js';
 
+const resolveRecordId = (primary, fallback) =>
+  primary === 0 ? 0 : primary || (fallback === 0 ? 0 : fallback || null);
+
 const hasMeaningfulValue = (value) => {
   if (value === null || value === undefined) {
     return false;
@@ -45,40 +48,8 @@ const hasMeaningfulRecord = (record) => {
   return false;
 };
 
-/**
- * Create structured record from form engine state with support for unlimited RepeatableSection nesting
- * @param {Object} state - Form engine state {values, errors, visible, required, read_only}
- * @param {Array} [fields] - Optional flattened fields array from schema (for key mapping)
- * @param {Object} options - Additional options for record creation
- *   - mainRecordId: UUID for the main record
- *   - childRecordIds: Nested object structure for RepeatableSection child record UUIDs
- *   - originalElements: Original nested form elements (for proper RepeatableSection nesting)
- * @param {string} [id] - DEPRECATED: Use options.mainRecordId instead
- * @returns {Object} Structured record ready for submission
- *
- * @example
- * // Simple RepeatableSection:
- * options = {
- *   mainRecordId: "main-uuid",
- *   childRecordIds: {
- *     "repA": ["child-1", "child-2", "child-3"]
- *   }
- * }
- *
- * // Nested RepeatableSections:
- * options = {
- *   mainRecordId: "main-uuid",
- *   childRecordIds: {
- *     "repA": {
- *       _records: ["repA-record-1", "repA-record-2"],
- *       "repA-record-1": {
- *         "repB": ["repB-child-1", "repB-child-2"]
- *       }
- *     }
- *   }
- * }
- */
-export function createStructuredRecord(state, fields = null, options = {}, id = null) {
+/** Shared transformation steps; yielding does not change formatting or record metadata. */
+function* structuredRecordSteps(state, fields = null, options = {}, id = null) {
   // Compute final version values
   const finalVersion = options.version || 1;
   const finalChildVersion = options.childVersion || 1;
@@ -276,7 +247,11 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
   }
 
   // Enhanced recursive function to process nested RepeatableSections
-  const processRepeatableSection = (repInfo, currentPath = [], structuredInstances = null) => {
+  const processRepeatableSection = function* (
+    repInfo,
+    currentPath = [],
+    structuredInstances = null
+  ) {
     const pathKey = repInfo.preferredKey;
 
     // Get child record IDs from options using the full path
@@ -389,7 +364,7 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
             ? instanceRepeatable[childRepInfo.preferredKey]
             : [];
           const nestedInstances = Array.isArray(rawNestedInstances) ? rawNestedInstances : [];
-          const childRepeatableArray = processRepeatableSection(
+          const childRepeatableArray = yield* processRepeatableSection(
             childRepInfo,
             [...currentPath, pathKey],
             nestedInstances
@@ -405,6 +380,7 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
         if (hasMeaningfulRecord(childRecord)) {
           childRecords.push(childRecord);
         }
+        yield;
       }
 
       return childRecords;
@@ -499,7 +475,7 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
 
         // Recursively process child RepeatableSections
         for (const [childDataName, childRepInfo] of repInfo.children) {
-          const childRepeatableArray = processRepeatableSection(childRepInfo, [
+          const childRepeatableArray = yield* processRepeatableSection(childRepInfo, [
             ...currentPath,
             pathKey,
           ]);
@@ -526,6 +502,7 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
         if (hasMeaningfulRecord(childRecord)) {
           childRecords.push(childRecord);
         }
+        yield;
       }
 
       return childRecords;
@@ -549,7 +526,7 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
           : []
         : null;
 
-      const childRecords = processRepeatableSection(repInfo, [], structuredInstances);
+      const childRecords = yield* processRepeatableSection(repInfo, [], structuredInstances);
       const repeatableOutputKey = resolveRepeatableOutputKey(repInfo);
       if (hasStructuredRepeatableState) {
         // In structured mode keep explicit repeatable keys, even when empty.
@@ -614,7 +591,7 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
     ),
 
     // Ensure our specific handling isn't overridden (always set last)
-    id: options.mainRecordId || id || null,
+    id: resolveRecordId(options.mainRecordId, id),
     changeset_id: options.changeset_id || null, // Ensure changeset_id isn't overridden
     created_at: clientCreatedAt, // Ensure canonical created_at isn't overridden
     updated_at: serverUpdatedAt, // Ensure canonical updated_at isn't overridden
@@ -648,3 +625,97 @@ export function createStructuredRecord(state, fields = null, options = {}, id =
 
   return record;
 }
+
+/**
+ * Create structured record from form engine state with support for unlimited RepeatableSection nesting
+ * @param {Object} state - Form engine state {values, errors, visible, required, read_only}
+ * @param {Array} [fields] - Optional flattened fields array from schema (for key mapping)
+ * @param {Object} options - Additional options for record creation
+ *   - mainRecordId: UUID for the main record
+ *   - childRecordIds: Nested object structure for RepeatableSection child record UUIDs
+ *   - originalElements: Original nested form elements (for proper RepeatableSection nesting)
+ * @param {string} [id] - DEPRECATED: Use options.mainRecordId instead
+ * @returns {Object} Structured record ready for submission
+ *
+ * @example
+ * // Simple RepeatableSection:
+ * options = {
+ *   mainRecordId: "main-uuid",
+ *   childRecordIds: {
+ *     "repA": ["child-1", "child-2", "child-3"]
+ *   }
+ * }
+ *
+ * // Nested RepeatableSections:
+ * options = {
+ *   mainRecordId: "main-uuid",
+ *   childRecordIds: {
+ *     "repA": {
+ *       _records: ["repA-record-1", "repA-record-2"],
+ *       "repA-record-1": {
+ *         "repB": ["repB-child-1", "repB-child-2"]
+ *       }
+ *     }
+ *   }
+ * }
+ */
+export function createStructuredRecord(state, fields = null, options = {}, id = null) {
+  const work = structuredRecordSteps(state, fields, options, id);
+  let next;
+  do {
+    next = work.next();
+  } while (!next.done);
+  return next.value;
+}
+
+/**
+ * Create the same structured record with host scheduling between rows.
+ * Supply a stable evaluated snapshot; this function never evaluates or mutates it.
+ * @param {Object} state
+ * @param {Object[]} [fields]
+ * @param {Object} [options] The synchronous serializer's options; use mainRecordId for identity.
+ * @param {{signal?: AbortSignal, budgetMs?: number, yieldToHost?: Function}} [scheduling]
+ * @returns {Promise<Object>} Cancellation rejects with an AbortError; no partial record is returned.
+ */
+export async function createStructuredRecordAsync(
+  state,
+  fields = null,
+  options = {},
+  scheduling = {}
+) {
+  const clock = () => globalThis.performance?.now?.() ?? Date.now();
+  const check = () => {
+    if (scheduling.signal?.aborted)
+      throw Object.assign(new Error('Record serialization was cancelled.'), {
+        name: 'AbortError',
+        code: 'cancelled',
+      });
+  };
+  const yieldToHost =
+    scheduling.yieldToHost || (() => new Promise((resolve) => setTimeout(resolve, 0)));
+  const pause = async () => {
+    try {
+      await yieldToHost();
+    } catch (error) {
+      throw Object.assign(new Error(error?.message || 'Record serialization scheduling failed.'), {
+        code: 'record_scheduling_failed',
+      });
+    }
+  };
+  check();
+  // Finish prior editor/signature work before beginning this separate phase.
+  await pause();
+  check();
+  let started = clock();
+  const work = structuredRecordSteps(state, fields, options);
+  for (;;) {
+    const next = work.next();
+    check();
+    if (next.done) return next.value;
+    if (clock() - started >= (scheduling.budgetMs ?? 8)) {
+      await pause();
+      check();
+      started = clock();
+    }
+  }
+}

package/src/utilities/repeatable-collections.js

@@ -0,0 +1,170 @@
+import { parse } from 'acorn';
+import { ContextResolver } from '../engine/context-resolver.js';
+
+export const COLLECTION_NAMES = new Set(['REPEATABLEVALUES', 'REPEATABLESUM']);
+const VALUE_TYPES = new Set([
+  'TextField',
+  'NumericField',
+  'SingleChoiceField',
+  'MultiChoiceField',
+  'BooleanField',
+  'DateField',
+  'TimeField',
+  'CalculatedField',
+  'FormLinkField',
+]);
+
+/** Parse schema references without interpreting collection sources as scalar values. */
+export function analyzeRepeatableCollections(source, resolver = null, owner = null) {
+  const calls = [];
+  const issues = [];
+  if (!/\bREPEATABLE(?:VALUES|SUM)\b/.test(source || ''))
+    return { calls, issues, expression: source, scalarSource: source };
+  let tree;
+  try {
+    tree = parse(source, { ecmaVersion: 'latest', sourceType: 'commonjs' });
+  } catch {
+    return { calls, issues, expression: source, scalarSource: source };
+  }
+  const edits = [];
+  function visit(node, parent) {
+    if (!node || typeof node !== 'object') return;
+    if (
+      node.type === 'CallExpression' &&
+      node.callee?.name === 'EVAL' &&
+      node.arguments.some(
+        (argument) =>
+          argument.type === 'Literal' &&
+          typeof argument.value === 'string' &&
+          /\bREPEATABLE(?:VALUES|SUM)\s*\(/.test(argument.value)
+      )
+    )
+      issues.push({
+        code: 'dynamic_collection_unsupported',
+        message: 'Repeatable collection calls inside EVAL are unsupported; use direct calls.',
+        index: node.start,
+        length: node.end - node.start,
+      });
+    if (node.type === 'Identifier' && COLLECTION_NAMES.has(node.name)) {
+      if (parent?.type !== 'CallExpression' || parent.callee !== node) {
+        issues.push({
+          code: 'collection_alias_unsupported',
+          message: 'Repeatable collection builtins require direct calls.',
+          index: node.start,
+          length: node.end - node.start,
+        });
+      } else {
+        const [section, target] = parent.arguments;
+        const valid =
+          parent.arguments.length === 2 &&
+          section?.type === 'Identifier' &&
+          /^\$[a-zA-Z_][a-zA-Z0-9_]*$/.test(section.name) &&
+          target?.type === 'Literal' &&
+          typeof target.value === 'string';
+        if (!valid) {
+          issues.push({
+            code: 'invalid_collection_arguments',
+            message: `${node.name} requires a direct $repeatable_data_name and a literal target data_name.`,
+            index: parent.start,
+            length: parent.end - parent.start,
+          });
+        } else {
+          const call = {
+            name: node.name,
+            section: section.name.slice(1),
+            target: target.value,
+            index: section.start,
+            length: section.end - section.start,
+          };
+          calls.push(call);
+          edits.push({
+            start: section.start,
+            end: section.end,
+            value: JSON.stringify(call.section),
+          });
+          if (resolver) {
+            const info = resolver.repeatableSectionTree.get(call.section);
+            const fieldInfo = resolver.fieldOwnership.get(call.target);
+            const ownerPath = resolver.getFieldInfo(owner)?.parentPath || [];
+            let message = null;
+            if (!info) message = `Unknown RepeatableSection '${call.section}'.`;
+            else if (
+              !fieldInfo ||
+              !ContextResolver.pathsEqual(fieldInfo.parentPath, info.currentPath)
+            )
+              message = `Collection target '${call.target}' must belong to '${call.section}' rows.`;
+            else if (!VALUE_TYPES.has(fieldInfo.field.type))
+              message = `Collection target type ${fieldInfo.field.type} is unsupported.`;
+            else if (
+              call.name === 'REPEATABLESUM' &&
+              !['NumericField', 'CalculatedField'].includes(fieldInfo.field.type)
+            )
+              message = 'REPEATABLESUM requires a NumericField or CalculatedField target.';
+            else if (
+              !ContextResolver.isPrefix(ownerPath, info.parentPath) &&
+              !ContextResolver.isPrefix(info.parentPath, ownerPath)
+            )
+              message = `Collection source '${call.section}' is outside the calculation's record ancestry.`;
+            if (message)
+              issues.push({
+                code: 'invalid_collection_reference',
+                message,
+                index: parent.start,
+                length: parent.end - parent.start,
+              });
+          }
+        }
+      }
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key === 'start' || key === 'end') continue;
+      if (Array.isArray(value)) value.forEach((child) => visit(child, node));
+      else if (value && typeof value === 'object') visit(value, node);
+    }
+  }
+  visit(tree, null);
+  let expression = source;
+  let scalarSource = source;
+  for (const edit of edits.sort((a, b) => b.start - a.start)) {
+    expression = expression.slice(0, edit.start) + edit.value + expression.slice(edit.end);
+    scalarSource =
+      scalarSource.slice(0, edit.start) +
+      ' '.repeat(edit.end - edit.start) +
+      scalarSource.slice(edit.end);
+  }
+  return { calls, issues, expression, scalarSource };
+}
+
+export function projectCollectionValue(field, value) {
+  if (value == null) return ['MultiChoiceField', 'FormLinkField'].includes(field.type) ? [] : null;
+  const fail = () => {
+    throw new Error(`Malformed collection value for '${field.data_name}'.`);
+  };
+  if (['SingleChoiceField', 'MultiChoiceField', 'BooleanField'].includes(field.type)) {
+    if (typeof value !== 'object' || Array.isArray(value)) return fail();
+    const multiple = field.type === 'MultiChoiceField';
+    const selections = value[multiple ? 'choices' : 'choice'];
+    const others = value.other ?? (field.type === 'BooleanField' ? [] : undefined);
+    if (!Array.isArray(selections) || !Array.isArray(others)) return fail();
+    if ((field.type === 'BooleanField' || !field.allow_other) && others.length) return fail();
+    const allowed = new Set(field.choices.map((choice) => choice.value));
+    const projected = selections.map((entry) => {
+      if (!entry || !allowed.has(entry.value)) return fail();
+      return entry.value;
+    });
+    for (const entry of others) {
+      if (!entry || typeof entry.label !== 'string' || !entry.label.trim()) return fail();
+      projected.push(entry.label);
+    }
+    if (!multiple && projected.length > 1) return fail();
+    return multiple ? projected : (projected[0] ?? null);
+  }
+  if (field.type === 'FormLinkField') {
+    if (!Array.isArray(value) || (!field.allow_multiple_records && value.length > 1)) return fail();
+    return value.map((entry) => {
+      if (!entry || typeof entry.record_id !== 'string' || !entry.record_id.trim()) return fail();
+      return { record_id: entry.record_id };
+    });
+  }
+  return value;
+}

package/src/utilities/schema-revision.js

@@ -0,0 +1,30 @@
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, stableValue(value[key])])
+  );
+}
+
+function fnv1a64(input) {
+  let hash = 0xcbf29ce484222325n;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= BigInt(input.charCodeAt(index));
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return hash.toString(16).padStart(16, '0');
+}
+
+/** Return a deterministic schema revision without importing authoring/editor modules. */
+export function getFormSchemaRevision(schema) {
+  const root =
+    schema?.form && Array.isArray(schema.form.elements)
+      ? schema
+      : schema && Array.isArray(schema.elements)
+        ? { form: schema }
+        : null;
+  if (!root) throw new Error('Expected a root schema containing form.elements or a form schema');
+  return `form0-${fnv1a64(JSON.stringify(stableValue(root)))}`;
+}