form0-core 0.3.1 → 0.4.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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/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') {

package/src/builtins/choice/choicevalue.js

@@ -1,29 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { CHOICEVALUE_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin CHOICEVALUE
- * @description Retrieves the currently selected choice field value, preserving the type (if the value 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 value with preserved type, or null if no selection
- * @example
- * // Get the selected city value
- * CHOICEVALUE($city)
- * @example
- * // Use in conditional logic
- * IF(CHOICEVALUE($city) === "bogota", "Welcome to Bogotá!", "Welcome!")
  */
-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 CHOICEVALUE = (choiceField) => {
   // Handle null/undefined input
   if (!choiceField || typeof choiceField !== 'object') {

package/src/builtins/choice/choicevalues.js

@@ -1,26 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { CHOICEVALUES_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin CHOICEVALUES
- * @description Retrieves an array of all selected choice field values from a MultiChoiceField, preserving the type of each value. 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 values with preserved types
- * @example
- * // Get all selected color values
- * CHOICEVALUES($colors)
- * @example
- * // Check if "red" is selected
- * CHOICEVALUES($colors).includes("red")
  */
-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 CHOICEVALUES = (multiChoiceField) => {
   // Handle null/undefined input
   if (!multiChoiceField || typeof multiChoiceField !== 'object') {

package/src/builtins/choice/hasother.js

@@ -1,29 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { HASOTHER_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin HASOTHER
- * @description Returns true if user entered an other option, false otherwise. Works with both SingleChoiceField and MultiChoiceField.
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {Object} choiceField - The choice field object (SingleChoiceField with choice array or MultiChoiceField with choices array) and other array
  * @returns {boolean} True if user entered an other option, false otherwise
- * @example
- * // Check if user entered other option in single choice field
- * HASOTHER($city)
- * @example
- * // Check if user entered other option in multi choice field
- * HASOTHER($colors)
- * @example
- * // Use in conditional logic
- * IF(HASOTHER($city), "Custom city: " + OTHER($city), "Selected city: " + CHOICELABEL($city))
  */
-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 HASOTHER = (choiceField) => {
   // Handle null/undefined input
   if (!choiceField || typeof choiceField !== 'object') {

package/src/builtins/choice/other.js

@@ -1,29 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { OTHER_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin OTHER
- * @description Retrieves the other label if user entered the other option, otherwise null. Works with both SingleChoiceField and MultiChoiceField.
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {Object} choiceField - The choice field object (SingleChoiceField with choice array or MultiChoiceField with choices array) and other array
  * @returns {string|null} The other label if user entered an other option, null otherwise
- * @example
- * // Get the other value from single choice field
- * OTHER($city)
- * @example
- * // Get the other value from multi choice field
- * OTHER($colors)
- * @example
- * // Use in conditional logic
- * IF(HASOTHER($city), "Custom city: " + OTHER($city), "No custom city entered")
  */
-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 OTHER = (choiceField) => {
   // Handle null/undefined input
   if (!choiceField || typeof choiceField !== 'object') {