form0-core 0.3.1 → 0.4.1

package/README.md

@@ -81,6 +81,69 @@ console.log(engine.getState());
 The engine API exposes `eval()` for calculations, conditions, and validation; `trigger()` for form
 events; and `getState()` for current values and evaluated field state.
 
+Schema event callbacks retain their authored source, so ordinary functions and arrows defined in
+`form.events.code` also work on Hermes. Each dispatch uses current scoped field values; initialization
+runs once. Local initialization variables are not captured. Callbacks supplied by host helpers still
+require executable `toString()` output; unavailable source produces an event warning.
+
+## Calculation diagnostics
+
+Diagnostics are collected automatically, including when console reporting is disabled:
+
+```js
+const engine = createFormEngine({ schema });
+console.log(engine.getDiagnostics()); // [] before the first evaluation
+engine.eval();
+console.log(engine.getDiagnostics()); // latest evaluation, returned as a defensive copy
+```
+
+Configure reporting in application code:
+
+```js
+const engine = createFormEngine({
+  schema,
+  diagnostics: { console: false },
+  onDiagnostics(snapshot) {
+    for (const diagnostic of snapshot) {
+      reportCalculationDiagnostic(diagnostic);
+    }
+  },
+});
+
+engine.eval();
+// For a schema calculating quotient from divisor, correct the input and evaluate again:
+engine.getState().values.divisor = 4;
+engine.eval(); // replaces the snapshot; recovered failures disappear
+```
+
+`onDiagnostics` runs once after every completed evaluation, including identical snapshots and
+`[]`. Observer exceptions cannot interrupt evaluation and are reported according to the console
+policy. Each diagnostic has `code`, `severity`, `message`, `fieldName`, `phase`, `suggestion`, and
+`context`. Context identifies the schema parent path, related/referenced fields, and `expression`
+versus `EVAL` origin. The engine adds no expression source, field values, or stack traces.
+
+Identical diagnostics are deduplicated within an evaluation. Distinct failures are retained,
+including failures observed in intermediate stabilization passes even if a later pass succeeds.
+The snapshot records that evaluation; it is not a history or just the final unresolved errors.
+Legitimate `null`, `undefined`, `NaN`, and `Infinity` results do not produce errors by themselves.
+Diagnostics stay separate from `state.errors` and do not change submission validity.
+
+Omit `diagnostics.console` to preserve existing defaults and supplied `WarningSystem` settings.
+`false` silences calculation-owned reporting, including `EVAL()` warnings and debug logs; `true`
+prints diagnostic reporting in development and production. Event reporting retains its existing
+behavior. `WarningSystem` remains compatible.
+
+The append-only `runtimeDiagnostics` option is deprecated but remains supported for compatibility.
+For new integrations, omit that option and use `engine.getDiagnostics()` for the latest evaluation,
+or `onDiagnostics(snapshot)` to receive every completed evaluation, including recovery (`[]`).
+This is not a drop-in replacement for the legacy array: snapshots use the structured diagnostic
+contract above and replace prior results rather than accumulating them. If you need a history,
+store snapshots in application code. No removal version is scheduled.
+
+See [calculation diagnostics](https://docs.form0.dev/core/engine/calculations-dependencies#seeing-errors-and-warnings)
+for stable codes and the reporting contract. CLI and renderer diagnostics adoption is separate
+from this core API.
+
 ## Schema and record ownership
 
 `form0-core` owns behavioral schema concerns such as fields, conditions, calculations, events, and
@@ -109,6 +172,18 @@ Record utilities follow this contract:
 
 Record status remains top-level as `@status`; it is not stored inside `form_values`.
 
+## Authoring mutation validation
+
+`getFormAuthoringContext({ schema })` includes `mutationOperationCatalog`: the installed operation
+formats, required parameters, and examples. `mutationOperations` remains the list of supported names.
+Use these formats with `applyFormMutationBatch`; for example, a rename uses
+`{ op: 'updateForm', changes: { name: 'Renamed form' } }`, not a `patch` parameter.
+
+Malformed operations, unknown operation parameters, and empty change objects are rejected atomically
+with diagnostics, rather than silently ignored. Clearing a title/status field, calculation, or event
+code requires its explicit parameter (for example, `field: null`), not an omitted value. Valid
+idempotent batches remain valid in core; consumers should check actual changes before offering to save.
+
 ## ✅ Requirements
 
 - Node.js 22 or newer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
@@ -12,7 +12,7 @@
     "SECURITY.md"
   ],
   "scripts": {
-    "test": "node tests/form0-core.test.js && node tests/conditions.test.js && node tests/numeric-field-schema.test.js && node tests/dataset-descriptors.test.js && node tests/structured-record.test.js && node tests/title-fields.test.js && node tests/builtin-metadata.test.js && node tests/calculation-expression-utils.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/form-authoring.test.js && node tests/security-test.js",
+    "test": "node tests/form0-core.test.js && node tests/conditions.test.js && node tests/numeric-field-schema.test.js && node tests/dataset-descriptors.test.js && node tests/structured-record.test.js && node tests/title-fields.test.js && node tests/builtin-metadata.test.js && node tests/builtin-import-isolation.test.js && node tests/builtin-catalog-examples.test.js && node tests/date-builtins.test.js && node tests/calculation-expression-utils.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/form-authoring.test.js && node tests/calculation-dependency-engine.test.js && node tests/calculation-diagnostics.characterization.test.js && node tests/calculation-diagnostics.test.js && node tests/calculation-missing-result.test.js && node tests/evaluator-reentry.test.js && node tests/event-compatibility.characterization.test.js && node tests/event-hermes.test.js && node tests/event-async-isolation.test.js && node tests/security-test.js",
     "format": "prettier --write \"src/**/*.{js,jsx}\" \"tests/**/*.{js,jsx}\" \"scripts/**/*.{js,mjs}\" package.json README.md SECURITY.md SUPPORT.md CONTRIBUTING.md eslint.config.js .github/workflows/ci.yml .github/workflows/publish.yml",
     "format:check": "prettier --check \"src/**/*.{js,jsx}\" \"tests/**/*.{js,jsx}\" \"scripts/**/*.{js,mjs}\" package.json README.md SECURITY.md SUPPORT.md CONTRIBUTING.md eslint.config.js .github/workflows/ci.yml .github/workflows/publish.yml",
     "lint:check": "eslint src tests",
@@ -63,5 +63,8 @@
     "globals": "^17.12.0",
     "ignore": "^7.0.5",
     "prettier": "^3.5.3"
+  },
+  "dependencies": {
+    "acorn": "8.18.0"
   }
 }

package/src/authoring/form-authoring.js

@@ -16,17 +16,77 @@ import {
 } from '../utilities/form-event-editor.js';
 
 const CONTAINER_TYPES = new Set(['Section', 'RepeatableSection', 'BuildingPlanSection']);
-const MUTATION_OPERATIONS = Object.freeze([
-  'updateForm',
-  'addField',
-  'updateField',
-  'moveField',
-  'removeField',
-  'setTitleField',
-  'setStatusField',
-  'setCalculation',
-  'setFormEventCode',
+const FIELD_KEY_PARAMETER = Object.freeze({ type: 'string', minLength: 1 });
+const CHANGES_PARAMETER = Object.freeze({ type: 'object', minProperties: 1 });
+const PLACEMENT_PARAMETERS = Object.freeze({
+  parentKey: { type: ['string', 'null'], minLength: 1 },
+  position: {
+    type: ['object', 'null'],
+    properties: { beforeKey: FIELD_KEY_PARAMETER, afterKey: FIELD_KEY_PARAMETER },
+    maxProperties: 1,
+    description: 'Use one sibling key, or omit position to append in the target container.',
+  },
+});
+const MUTATION_OPERATION_CATALOG = Object.freeze([
+  {
+    op: 'updateForm',
+    description:
+      'Update form attributes; elements, events, title_field and status_field use dedicated operations.',
+    required: ['changes'],
+    parameters: { changes: CHANGES_PARAMETER },
+    example: { op: 'updateForm', changes: { name: 'Renamed form' } },
+  },
+  {
+    op: 'addField',
+    description: 'Add a complete field matching fieldSpecs; missing keys are generated.',
+    required: ['field'],
+    parameters: { field: { type: 'object', minProperties: 1 }, ...PLACEMENT_PARAMETERS },
+  },
+  {
+    op: 'updateField',
+    description: 'Update an existing field by key; type changes require remove/add.',
+    required: ['fieldKey', 'changes'],
+    parameters: { fieldKey: FIELD_KEY_PARAMETER, changes: CHANGES_PARAMETER },
+    example: { op: 'updateField', fieldKey: 'existing-field-key', changes: { label: 'New label' } },
+  },
+  {
+    op: 'moveField',
+    description: 'Move an existing field by key to a container/sibling position.',
+    required: ['fieldKey'],
+    parameters: { fieldKey: FIELD_KEY_PARAMETER, ...PLACEMENT_PARAMETERS },
+  },
+  {
+    op: 'removeField',
+    description: 'Remove an existing field by key only if it is unreferenced.',
+    required: ['fieldKey'],
+    parameters: { fieldKey: FIELD_KEY_PARAMETER },
+  },
+  {
+    op: 'setTitleField',
+    description: 'Set a complete title field, or explicitly pass field: null to clear it.',
+    required: ['field'],
+    parameters: { field: { type: ['object', 'null'] } },
+  },
+  {
+    op: 'setStatusField',
+    description: 'Set a complete status field, or explicitly pass field: null to clear it.',
+    required: ['field'],
+    parameters: { field: { type: ['object', 'null'] } },
+  },
+  {
+    op: 'setCalculation',
+    description: 'Set a CalculatedField expression by key; null explicitly clears it.',
+    required: ['fieldKey', 'expression'],
+    parameters: { fieldKey: FIELD_KEY_PARAMETER, expression: { type: ['string', 'null'] } },
+  },
+  {
+    op: 'setFormEventCode',
+    description: 'Set form event code; an empty string or null explicitly clears it.',
+    required: ['code'],
+    parameters: { code: { type: ['string', 'null'] } },
+  },
 ]);
+const MUTATION_OPERATIONS = Object.freeze(MUTATION_OPERATION_CATALOG.map(({ op }) => op));
 
 const CALCULATION_GUIDANCE = Object.freeze({
   version: 1,
@@ -306,16 +366,66 @@ function mutationError(index, operation, error) {
   };
 }
 
+function validateMutationParameter(value, spec, path) {
+  const type = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+  const types = Array.isArray(spec.type) ? spec.type : [spec.type];
+  if (!types.includes(type)) throw new Error(`${path} must be ${types.join(' or ')}`);
+  if (value === null) return;
+  if (spec.minLength && value.length < spec.minLength) {
+    throw new Error(`${path} must not be empty`);
+  }
+  if (spec.minProperties && Object.keys(value).length < spec.minProperties) {
+    throw new Error(`${path} must be a non-empty object`);
+  }
+  if (spec.maxProperties && Object.keys(value).length > spec.maxProperties) {
+    throw new Error(`${path} must specify at most one property`);
+  }
+  if (spec.properties) {
+    for (const key of Object.keys(value)) {
+      if (!Object.hasOwn(spec.properties, key)) {
+        throw new Error(`Unexpected mutation parameter '${path}.${key}'`);
+      }
+      validateMutationParameter(value[key], spec.properties[key], `${path}.${key}`);
+    }
+  }
+}
+
+function validateMutationOperation(operation) {
+  if (!operation || typeof operation !== 'object' || Array.isArray(operation)) {
+    throw new Error('A mutation operation must be an object with an op property');
+  }
+  const definition = MUTATION_OPERATION_CATALOG.find(({ op }) => op === operation.op);
+  if (!definition) throw new Error(`Unsupported mutation operation '${operation.op}'`);
+  for (const name of definition.required) {
+    if (!Object.hasOwn(operation, name) || operation[name] === undefined) {
+      const example = definition.example ? ` Example: ${JSON.stringify(definition.example)}` : '';
+      throw new Error(`${operation.op} requires '${name}'.${example}`);
+    }
+  }
+  for (const name of Object.keys(operation)) {
+    if (name === 'op') continue;
+    if (!Object.hasOwn(definition.parameters, name)) {
+      throw new Error(`Unexpected ${operation.op} parameter '${name}'`);
+    }
+    validateMutationParameter(
+      operation[name],
+      definition.parameters[name],
+      `${operation.op}.${name}`
+    );
+  }
+}
+
 function applyMutation(root, operation) {
+  validateMutationOperation(operation);
   const form = root.form;
   const fields = indexFields(form.elements);
   switch (operation.op) {
     case 'updateForm': {
       const forbidden = new Set(['elements', 'events', 'title_field', 'status_field']);
-      for (const key of Object.keys(operation.changes || {})) {
+      for (const key of Object.keys(operation.changes)) {
         if (forbidden.has(key)) throw new Error(`updateForm cannot change '${key}'`);
       }
-      Object.assign(form, deepClone(operation.changes || {}));
+      Object.assign(form, deepClone(operation.changes));
       return `Updated form attributes`;
     }
     case 'addField': {
@@ -340,7 +450,7 @@ function applyMutation(root, operation) {
       }
       const original = deepClone(target.field);
       const children = target.field.elements;
-      Object.assign(target.field, deepClone(operation.changes || {}));
+      Object.assign(target.field, deepClone(operation.changes));
       if (
         target.field.data_name !== original.data_name &&
         [...fields.values()].some(
@@ -473,6 +583,7 @@ export function getFormAuthoringContext({ schema, coreVersion = null }) {
     revision: getFormSchemaRevision(root),
     schema: deepClone(root),
     mutationOperations: [...MUTATION_OPERATIONS],
+    mutationOperationCatalog: deepClone(MUTATION_OPERATION_CATALOG),
     fieldSpecs,
     operators,
     eventTypes: getAllEventTypes(),

package/src/builtins/builtin-definitions.js

@@ -0,0 +1,320 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from './builtin-metadata.js';
+
+// Authoritative builtin metadata. Keep this catalog independent of implementations
+// so security validation can inspect names and contexts without loading EVAL().
+
+export const IF_METADATA = defineBuiltinMetadata({
+  name: 'IF',
+  category: 'logical',
+  signature: 'IF(condition, trueValue, falseValue)',
+  description: 'Return one of two values based on a condition.',
+  examples: [
+    'IF($age >= 18, "adult", "minor")',
+    'IF($country === "US", IF($state === "CA", 8.99, 5.99), 15.99)',
+  ],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const AND_METADATA = defineBuiltinMetadata({
+  name: 'AND',
+  category: 'logical',
+  signature: 'AND(...conditions)',
+  description: 'Return true only when all arguments are truthy.',
+  examples: ['AND($age >= 18, $country === "it")'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const OR_METADATA = defineBuiltinMetadata({
+  name: 'OR',
+  category: 'logical',
+  signature: 'OR(...conditions)',
+  description: 'Return true when at least one argument is truthy.',
+  examples: ['OR($email, $phone)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const COUNT_METADATA = defineBuiltinMetadata({
+  name: 'COUNT',
+  category: 'logical',
+  signature: 'COUNT(values)',
+  description: 'Count numeric values.',
+  examples: ['COUNT(ARRAY($score_1, $score_2, $score_3))'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const COUNTA_METADATA = defineBuiltinMetadata({
+  name: 'COUNTA',
+  category: 'logical',
+  signature: 'COUNTA(values)',
+  description: 'Count non-empty values.',
+  examples: ['COUNTA(ARRAY($first_name, $last_name, $email))'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const COUNTBLANK_METADATA = defineBuiltinMetadata({
+  name: 'COUNTBLANK',
+  category: 'logical',
+  signature: 'COUNTBLANK(values)',
+  description: 'Count blank values.',
+  examples: ['COUNTBLANK(ARRAY($first_name, $last_name, $email))'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const ARRAY_METADATA = defineBuiltinMetadata({
+  name: 'ARRAY',
+  category: 'logical',
+  signature: 'ARRAY(...values)',
+  description: 'Build an array from individual arguments.',
+  examples: ['ARRAY($city, $country)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const EVAL_METADATA = defineBuiltinMetadata({
+  name: 'EVAL',
+  category: 'control',
+  signature: 'EVAL(expression)',
+  description: 'Evaluate a dynamically built expression string in a restricted context.',
+  examples: ['EVAL("$" + dynamicFieldName)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const CHOICEVALUE_METADATA = defineBuiltinMetadata({
+  name: 'CHOICEVALUE',
+  category: 'choice',
+  signature: 'CHOICEVALUE(fieldValue)',
+  description: 'Return the selected choice value from a choice field.',
+  examples: [
+    'CHOICEVALUE($city)',
+    'IF(CHOICEVALUE($city) === "bogota", "Welcome to Bogota!", "Welcome!")',
+  ],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const CHOICELABEL_METADATA = defineBuiltinMetadata({
+  name: 'CHOICELABEL',
+  category: 'choice',
+  signature: 'CHOICELABEL(fieldValue)',
+  description: 'Return the selected choice label from a choice field.',
+  examples: ['CHOICELABEL($city)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const HASOTHER_METADATA = defineBuiltinMetadata({
+  name: 'HASOTHER',
+  category: 'choice',
+  signature: 'HASOTHER(fieldValue)',
+  description: 'Return true when the field has an "other" value.',
+  examples: ['HASOTHER($city)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const OTHER_METADATA = defineBuiltinMetadata({
+  name: 'OTHER',
+  category: 'choice',
+  signature: 'OTHER(fieldValue)',
+  description: 'Return the "other" label from a choice field.',
+  examples: ['OTHER($city)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const CHOICEVALUES_METADATA = defineBuiltinMetadata({
+  name: 'CHOICEVALUES',
+  category: 'choice',
+  signature: 'CHOICEVALUES(fieldValue)',
+  description: 'Return all selected values from a MultiChoiceField.',
+  examples: ['CHOICEVALUES($colors)', 'CHOICEVALUES($colors).includes("red")'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const CHOICELABELS_METADATA = defineBuiltinMetadata({
+  name: 'CHOICELABELS',
+  category: 'choice',
+  signature: 'CHOICELABELS(fieldValue)',
+  description: 'Return all selected labels from a MultiChoiceField.',
+  examples: ['CHOICELABELS($colors)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const FORM_METADATA = defineBuiltinMetadata({
+  name: 'FORM',
+  category: 'schema',
+  signature: 'FORM()',
+  description: 'Access the form definition. Reserved for a future implementation.',
+  examples: ['FORM()'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const DATANAMES_METADATA = defineBuiltinMetadata({
+  name: 'DATANAMES',
+  category: 'schema',
+  signature: "DATANAMES(type = 'any')",
+  description: 'Return form field data names, optionally filtered by field type.',
+  examples: ["DATANAMES('NumericField')"],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const ABS_METADATA = defineBuiltinMetadata({
+  name: 'ABS',
+  category: 'math',
+  signature: 'ABS(value)',
+  description: 'Return the absolute value of a number.',
+  examples: ['ABS($variance)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const CEILING_METADATA = defineBuiltinMetadata({
+  name: 'CEILING',
+  category: 'math',
+  signature: 'CEILING(value, factor)',
+  description: 'Round a number up to the nearest multiple.',
+  examples: ['CEILING($amount, 5)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const COS_METADATA = defineBuiltinMetadata({
+  name: 'COS',
+  category: 'math',
+  signature: 'COS(value)',
+  description: 'Return the cosine of a value in radians.',
+  examples: ['COS($angle_radians)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const SIN_METADATA = defineBuiltinMetadata({
+  name: 'SIN',
+  category: 'math',
+  signature: 'SIN(value)',
+  description: 'Return the sine of a value in radians.',
+  examples: ['SIN($angle_radians)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const ROUND_METADATA = defineBuiltinMetadata({
+  name: 'ROUND',
+  category: 'math',
+  signature: 'ROUND(value, places)',
+  description: 'Round a number to a fixed number of decimal places.',
+  examples: ['ROUND($total, 2)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const DATEADD_METADATA = defineBuiltinMetadata({
+  name: 'DATEADD',
+  category: 'date',
+  signature: 'DATEADD(date, days)',
+  description:
+    'Add whole days to a YYYY-MM-DD date from 0001-01-01 through 9999-12-31. Returns null when an argument is blank.',
+  examples: ['DATEADD($start_date, 30)', 'DATEADD($due_date, -7)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const DAYS_METADATA = defineBuiltinMetadata({
+  name: 'DAYS',
+  category: 'date',
+  signature: 'DAYS(endDate, startDate)',
+  description:
+    'Return the days between YYYY-MM-DD dates from 0001-01-01 through 9999-12-31. Returns null when an argument is blank.',
+  examples: ['DAYS($end_date, $start_date)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const UPPER_METADATA = defineBuiltinMetadata({
+  name: 'UPPER',
+  category: 'string',
+  signature: 'UPPER(value)',
+  description: 'Convert a string to uppercase.',
+  examples: ['UPPER($city_name)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
+export const SETRESULT_METADATA = defineBuiltinMetadata({
+  name: 'SETRESULT',
+  category: 'control',
+  signature: 'SETRESULT(value)',
+  description: 'Set the final return value for multiline calculations.',
+  examples: ['SETRESULT($price * $quantity)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION],
+});
+
+export const ALERT_METADATA = defineBuiltinMetadata({
+  name: 'ALERT',
+  category: 'event',
+  signature: "ALERT(title, message = '')",
+  description: 'Display an alert from a form event handler.',
+  examples: ["ALERT('Saved', 'The record was saved successfully.')"],
+  contexts: [BUILTIN_CONTEXTS.EVENT],
+});
+
+export const SETVALUE_METADATA = defineBuiltinMetadata({
+  name: 'SETVALUE',
+  category: 'event',
+  signature: 'SETVALUE(fieldDataName, valueToSet)',
+  description: 'Set a field value from a form event handler.',
+  examples: ["SETVALUE('field_dataname', 'value_to_set')"],
+  contexts: [BUILTIN_CONTEXTS.EVENT],
+});
+
+export const ON_METADATA = defineBuiltinMetadata({
+  name: 'ON',
+  category: 'event',
+  signature: 'ON(eventType, fieldKeyOrCallback, callback)',
+  description: 'Register an event handler within form event code.',
+  examples: ["ON('change', 'city', function(event) { ALERT('City changed!'); })"],
+  contexts: [BUILTIN_CONTEXTS.EVENT],
+});
+
+export const OFF_METADATA = defineBuiltinMetadata({
+  name: 'OFF',
+  category: 'event',
+  signature: 'OFF(eventType, fieldKeyOrCallback, callback)',
+  description: 'Remove event handlers within form event code.',
+  examples: ["OFF('change', 'city', specificCallback)"],
+  contexts: [BUILTIN_CONTEXTS.EVENT],
+});
+
+export const BUILTIN_DEFINITIONS = Object.freeze([
+  IF_METADATA,
+  AND_METADATA,
+  OR_METADATA,
+  COUNT_METADATA,
+  COUNTA_METADATA,
+  COUNTBLANK_METADATA,
+  ARRAY_METADATA,
+  EVAL_METADATA,
+  CHOICEVALUE_METADATA,
+  CHOICELABEL_METADATA,
+  HASOTHER_METADATA,
+  OTHER_METADATA,
+  CHOICEVALUES_METADATA,
+  CHOICELABELS_METADATA,
+  FORM_METADATA,
+  DATANAMES_METADATA,
+  ABS_METADATA,
+  CEILING_METADATA,
+  COS_METADATA,
+  SIN_METADATA,
+  ROUND_METADATA,
+  DATEADD_METADATA,
+  DAYS_METADATA,
+  UPPER_METADATA,
+  SETRESULT_METADATA,
+  ALERT_METADATA,
+  SETVALUE_METADATA,
+  ON_METADATA,
+  OFF_METADATA,
+]);
+
+function filterDefinitionsByContext(context) {
+  return Object.freeze(
+    BUILTIN_DEFINITIONS.filter((definition) => definition.contexts.includes(context))
+  );
+}
+
+export const CALCULATION_BUILTIN_DEFINITIONS = filterDefinitionsByContext(
+  BUILTIN_CONTEXTS.CALCULATION
+);
+export const EVENT_BUILTIN_DEFINITIONS = filterDefinitionsByContext(BUILTIN_CONTEXTS.EVENT);
+
+export const BUILTIN_DEFINITION_BY_NAME = new Map(
+  BUILTIN_DEFINITIONS.map((definition) => [definition.name, definition])
+);

package/src/builtins/choice/choicelabel.js

@@ -1,26 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { CHOICELABEL_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin CHOICELABEL
- * @description Retrieves the currently selected choice field label, preserving the type (if the label is a number preserves the number type, otherwise string). If no selection it returns null.
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {Object} choiceField - The choice field object with choice and other arrays
  * @returns {*} The selected choice label with preserved type, or null if no selection
- * @example
- * // Get the selected city label
- * CHOICELABEL($city)
- * @example
- * // Use in display logic
- * "You selected: " + CHOICELABEL($city)
  */
-export const CHOICELABEL_METADATA = defineBuiltinMetadata({
-  name: 'CHOICELABEL',
-  category: 'choice',
-  signature: 'CHOICELABEL(fieldValue)',
-  description: 'Return the selected choice label from a choice field.',
-  examples: ['CHOICELABEL($city)'],
-  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
-});
-
 export const CHOICELABEL = (choiceField) => {
   // Handle null/undefined input
   if (!choiceField || typeof choiceField !== 'object') {

package/src/builtins/choice/choicelabels.js

@@ -1,26 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { CHOICELABELS_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin CHOICELABELS
- * @description Retrieves an array of all selected choice field labels from a MultiChoiceField, preserving the type of each label. Returns an empty array if no selections.
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {Object} multiChoiceField - The multi choice field object with choices and other arrays
  * @returns {Array} Array of selected choice labels with preserved types
- * @example
- * // Get all selected color labels
- * CHOICELABELS($colors)
- * @example
- * // Display selected colors
- * "Selected colors: " + CHOICELABELS($colors).join(", ")
  */
-export const CHOICELABELS_METADATA = defineBuiltinMetadata({
-  name: 'CHOICELABELS',
-  category: 'choice',
-  signature: 'CHOICELABELS(fieldValue)',
-  description: 'Return all selected labels from a MultiChoiceField.',
-  examples: ['CHOICELABELS($colors)'],
-  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
-});
-
 export const CHOICELABELS = (multiChoiceField) => {
   // Handle null/undefined input
   if (!multiChoiceField || typeof multiChoiceField !== 'object') {