form0-core 0.3.0 → 0.4.0

package/src/builtins/logical/countblank.js

@@ -1,29 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { COUNTBLANK_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin COUNTBLANK
- * @description Returns the number of blank values in a dataset
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {Array} values - An array of items to check
  * @returns {number} The count of blank items in the array
- * @example
- * // Returns 3
- * COUNTBLANK([null, null, '', 1])
- * @example
- * // Returns 2
- * COUNTBLANK([undefined, '', 'a', 0])
- * @example
- * // Returns 0 (no blank values)
- * COUNTBLANK([1, 2, 'a', true])
  */
-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 COUNTBLANK = (values) => {
   // Handle null/undefined input
   if (!Array.isArray(values)) {

package/src/builtins/logical/if.js

@@ -1,29 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { IF_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin IF
- * @description Conditional logic function that returns one of two values based on a condition
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {boolean} condition - The condition to evaluate
  * @param {*} trueValue - Value returned if condition is true
  * @param {*} falseValue - Value returned if condition is false
  * @returns {*} Either trueValue or falseValue
- * @example
- * // Returns "Yes" if age >= 18, otherwise "No"
- * IF(age >= 18, "Yes", "No")
- * @example
- * // Nested conditions for shipping cost
- * IF(country === "US", IF(state === "CA", 8.99, 5.99), 15.99)
  */
-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 IF = (cond, a, b) => (cond ? a : b);

package/src/builtins/logical/or.js

@@ -1,24 +1,9 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { OR_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin OR
- * @description Logical OR operation that returns true if at least one argument is truthy
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {...*} args - Any number of arguments to evaluate
  * @returns {boolean} True if at least one argument is truthy, false otherwise
- * @example
- * // Check if user has any premium feature
- * OR(user.isPremium, user.isVip, user.hasSubscription)
- * @example
- * // Validation - either email or phone is required
- * OR(email.length > 0, phone.length > 0)
  */
-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 OR = (...args) => args.some(Boolean);

package/src/builtins/math/abs.js

@@ -1,27 +1,9 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { ABS_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin ABS
- * @description Returns the absolute value of a number
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {number} value - The number of which to return the absolute value
  * @returns {number} The absolute value of the input number
- * @example
- * // Returns 1
- * ABS(-1)
- * @example
- * // Returns 42
- * ABS(42)
- * @example
- * // Returns 3.14
- * ABS(-3.14)
  */
-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 ABS = (value) => Math.abs(value);

package/src/builtins/math/ceiling.js

@@ -1,30 +1,12 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { CEILING_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin CEILING
- * @description Rounds a value up to the nearest integer multiple of factor
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {number} value - The value to round up to the nearest integer multiple of factor
  * @param {number} [factor=1] - The number to whose multiples value will be rounded
  * @returns {number} The value rounded up to the nearest multiple of factor
- * @example
- * // Returns 139.9
- * CEILING(139.85, 0.1)
- * @example
- * // Returns 140
- * CEILING(139.001)
- * @example
- * // Returns 15
- * CEILING(12.3, 5)
  */
-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 CEILING = (value, factor = 1) => {
   if (factor === 0) {
     throw new Error('CEILING factor cannot be zero');

package/src/builtins/math/cos.js

@@ -1,27 +1,9 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { COS_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin COS
- * @description Returns the cosine of a value, in radians
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {number} value - The value for which to calculate the cosine
  * @returns {number} The cosine of the input value
- * @example
- * // Returns 0.15425144988758405
- * COS(30)
- * @example
- * // Returns 1
- * COS(0)
- * @example
- * // Returns -1
- * COS(Math.PI)
  */
-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 COS = (value) => Math.cos(value);

package/src/builtins/math/round.js

@@ -1,33 +1,12 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { ROUND_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin ROUND
- * @description Rounds a number to a specified number of decimal places according to standard rounding rules
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {number} value - The numeric value to be rounded
  * @param {number} places - The number of decimal places to round to
  * @returns {number} The value rounded to the specified number of decimal places
- * @example
- * // Returns 179.8
- * ROUND(179.848, 1)
- * @example
- * // Returns 900
- * ROUND(918.268, -2)
- * @example
- * // Returns 3
- * ROUND(3.14159, 0)
- * @example
- * // Returns 3.14
- * ROUND(3.14159, 2)
  */
-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 ROUND = (value, places) => {
   if (typeof value !== 'number' || typeof places !== 'number') {
     throw new Error('ROUND requires two numeric arguments');

package/src/builtins/math/sin.js

@@ -1,27 +1,9 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { SIN_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin SIN
- * @description Returns the sine of a value, in radians
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {number} value - The value for which to calculate the sine
  * @returns {number} The sine of the input value
- * @example
- * // Returns -0.9880316240928618
- * SIN(30)
- * @example
- * // Returns 0
- * SIN(0)
- * @example
- * // Returns 1
- * SIN(Math.PI / 2)
  */
-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 SIN = (value) => Math.sin(value);

package/src/builtins/registry.js

@@ -1,4 +1,12 @@
 import { cloneBuiltinMetadata, BUILTIN_CONTEXTS } from './builtin-metadata.js';
+import { BUILTIN_DEFINITIONS } from './builtin-definitions.js';
+
+export {
+  BUILTIN_DEFINITIONS,
+  CALCULATION_BUILTIN_DEFINITIONS,
+  EVENT_BUILTIN_DEFINITIONS,
+  BUILTIN_DEFINITION_BY_NAME,
+} from './builtin-definitions.js';
 
 import { IF, IF_METADATA } from './logical/if.js';
 import { AND, AND_METADATA } from './logical/and.js';
@@ -10,6 +18,7 @@ import { ARRAY, ARRAY_METADATA } from './logical/array.js';
 import {
   SETRESULT,
   SETRESULT_METADATA,
+  __beginResultScope,
   __consumeResult,
   __resetResult,
 } from './control/setresult.js';
@@ -27,13 +36,14 @@ import { CEILING, CEILING_METADATA } from './math/ceiling.js';
 import { COS, COS_METADATA } from './math/cos.js';
 import { SIN, SIN_METADATA } from './math/sin.js';
 import { ROUND, ROUND_METADATA } from './math/round.js';
+import { DATEADD, DATEADD_METADATA } from './date/dateadd.js';
+import { DAYS, DAYS_METADATA } from './date/days.js';
 import { UPPER, UPPER_METADATA } from './string/upper.js';
 
 import { ALERT, ALERT_METADATA } from './event/ui/alert.js';
 import { SETVALUE, SETVALUE_METADATA } from './event/field/setvalue.js';
 import { ON, ON_METADATA } from './event/control/on.js';
 import { OFF, OFF_METADATA } from './event/control/off.js';
-import { __consumeEventOperations } from './event/event-operations-collector.js';
 
 export { IF, IF_METADATA } from './logical/if.js';
 export { AND, AND_METADATA } from './logical/and.js';
@@ -45,6 +55,7 @@ export { ARRAY, ARRAY_METADATA } from './logical/array.js';
 export {
   SETRESULT,
   SETRESULT_METADATA,
+  __beginResultScope,
   __consumeResult,
   __resetResult,
 } from './control/setresult.js';
@@ -67,15 +78,16 @@ export { CEILING, CEILING_METADATA } from './math/ceiling.js';
 export { COS, COS_METADATA } from './math/cos.js';
 export { SIN, SIN_METADATA } from './math/sin.js';
 export { ROUND, ROUND_METADATA } from './math/round.js';
+export { DATEADD, DATEADD_METADATA } from './date/dateadd.js';
+export { DAYS, DAYS_METADATA } from './date/days.js';
 export { UPPER, UPPER_METADATA } from './string/upper.js';
 
 export { ALERT, ALERT_METADATA } from './event/ui/alert.js';
 export { SETVALUE, SETVALUE_METADATA } from './event/field/setvalue.js';
 export { ON, ON_METADATA } from './event/control/on.js';
 export { OFF, OFF_METADATA } from './event/control/off.js';
-export { __consumeEventOperations } from './event/event-operations-collector.js';
 
-const COMMON_RUNTIME_ENTRIES = Object.freeze([
+const RUNTIME_ENTRIES = Object.freeze([
   { implementation: IF, definition: IF_METADATA },
   { implementation: AND, definition: AND_METADATA },
   { implementation: OR, definition: OR_METADATA },
@@ -97,62 +109,33 @@ const COMMON_RUNTIME_ENTRIES = Object.freeze([
   { implementation: COS, definition: COS_METADATA },
   { implementation: SIN, definition: SIN_METADATA },
   { implementation: ROUND, definition: ROUND_METADATA },
+  { implementation: DATEADD, definition: DATEADD_METADATA },
+  { implementation: DAYS, definition: DAYS_METADATA },
   { implementation: UPPER, definition: UPPER_METADATA },
-]);
-
-const CALCULATION_ONLY_ENTRIES = Object.freeze([
   { implementation: SETRESULT, definition: SETRESULT_METADATA },
-]);
-
-const EVENT_ONLY_ENTRIES = Object.freeze([
   { implementation: ALERT, definition: ALERT_METADATA },
   { implementation: SETVALUE, definition: SETVALUE_METADATA },
   { implementation: ON, definition: ON_METADATA },
   { implementation: OFF, definition: OFF_METADATA },
 ]);
 
-function buildBuiltinObject(entries) {
+function buildBuiltinObject(context) {
   return Object.freeze(
     Object.fromEntries(
-      entries.map(({ implementation, definition }) => [definition.name, implementation])
+      RUNTIME_ENTRIES.filter(({ definition }) => definition.contexts.includes(context)).map(
+        ({ implementation, definition }) => [definition.name, implementation]
+      )
     )
   );
 }
 
-function filterDefinitionsByContext(definitions, context) {
-  return Object.freeze(definitions.filter((definition) => definition.contexts.includes(context)));
-}
-
-export const calculationBuiltins = buildBuiltinObject([
-  ...COMMON_RUNTIME_ENTRIES,
-  ...CALCULATION_ONLY_ENTRIES,
-]);
+export const calculationBuiltins = buildBuiltinObject(BUILTIN_CONTEXTS.CALCULATION);
 
-export const eventBuiltins = buildBuiltinObject([...COMMON_RUNTIME_ENTRIES, ...EVENT_ONLY_ENTRIES]);
+export const eventBuiltins = buildBuiltinObject(BUILTIN_CONTEXTS.EVENT);
 
 // Backward-compatible alias for calculation runtime helpers.
 export const builtins = calculationBuiltins;
 
-export const BUILTIN_DEFINITIONS = Object.freeze(
-  [...COMMON_RUNTIME_ENTRIES, ...CALCULATION_ONLY_ENTRIES, ...EVENT_ONLY_ENTRIES].map(
-    ({ definition }) => definition
-  )
-);
-
-export const CALCULATION_BUILTIN_DEFINITIONS = filterDefinitionsByContext(
-  BUILTIN_DEFINITIONS,
-  BUILTIN_CONTEXTS.CALCULATION
-);
-
-export const EVENT_BUILTIN_DEFINITIONS = filterDefinitionsByContext(
-  BUILTIN_DEFINITIONS,
-  BUILTIN_CONTEXTS.EVENT
-);
-
-export const BUILTIN_DEFINITION_BY_NAME = new Map(
-  BUILTIN_DEFINITIONS.map((definition) => [definition.name, definition])
-);
-
 export function getBuiltinDefinitions() {
   return BUILTIN_DEFINITIONS.map(cloneBuiltinMetadata);
 }

package/src/builtins/schema/datanames.js

@@ -1,29 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { DATANAMES_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin DATANAMES
- * @description Returns the data names of form fields, optionally filtered by field type
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {string} type - Optional field type to filter by (e.g., 'TextField', 'RepeatableSection', etc.). Defaults to 'any' (all fields)
  * @returns {Array<string>} Array of field data names
- * @example
- * // Get all field data names
- * DATANAMES()
- * @example
- * // Get only RepeatableSection data names
- * DATANAMES('RepeatableSection')
- * @example
- * // Get only TextField data names
- * DATANAMES('TextField')
  */
-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],
-});
-
 // Global schema context for DATANAMES() - set during expression evaluation
 let _dataNamesSchema = null;
 
@@ -32,7 +14,14 @@ let _dataNamesSchema = null;
  * Called internally by the expression evaluator
  */
 export function __setDataNamesContext(schema) {
+  const previousSchema = _dataNamesSchema;
   _dataNamesSchema = schema;
+  let restored = false;
+  return () => {
+    if (restored) return;
+    restored = true;
+    _dataNamesSchema = previousSchema;
+  };
 }
 
 /**

package/src/builtins/schema/form.js

@@ -1,28 +1,10 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { FORM_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin FORM
- * @description Access to the nested JSON form definition (future implementation)
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @returns {Object} The form schema object
- * @example
- * // Get form title
- * FORM().title
- * @example
- * // Access field definitions
- * FORM().elements[0].label
- * @example
- * // Check if form has RepeatableSections
- * FORM().elements.some(el => el.type === 'RepeatableSection')
  */
-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 function FORM() {
   // Placeholder for future implementation
   // Will provide access to nested JSON form definition

package/src/builtins/string/upper.js

@@ -1,29 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { UPPER_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin UPPER
- * @description Returns the uppercase version of a string
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {string} value - The string to convert to uppercase
  * @returns {string} The uppercase version of the input string
- * @example
- * // Returns "HELLO WORLD"
- * UPPER("hello world")
- * @example
- * // Returns "FORM0"
- * UPPER("form0")
- * @example
- * // Returns "ABC123"
- * UPPER("abc123")
  */
-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 UPPER = (value) => {
   if (value == null) {
     return '';

package/src/engine/calculation-diagnostics.js

@@ -0,0 +1,107 @@
+/**
+ * Engine-private, evaluation-scoped calculation reporting. Legacy warning handlers
+ * and throttling remain independent of this snapshot.
+ */
+export function createCalculationDiagnostics(options, observer, resolver, warningSystem) {
+  const consoleOverride = typeof options?.console === 'boolean' ? options.console : undefined;
+  const frames = [];
+  let snapshot = [];
+  const copy = (items) => JSON.parse(JSON.stringify(items));
+
+  function reportObserverFailure() {
+    if (consoleOverride ?? warningSystem.enableConsoleWarnings) {
+      console.warn('[form0] onDiagnostics observer failed.');
+    }
+  }
+
+  function record(fieldName, diagnostic) {
+    const frame = frames.at(-1);
+    if (!frame) return;
+    const item = {
+      code: diagnostic.code,
+      severity: diagnostic.severity || 'error',
+      message:
+        typeof diagnostic.message === 'string'
+          ? diagnostic.message
+          : 'Unknown calculation runtime error.',
+      fieldName,
+      phase: diagnostic.phase,
+      suggestion: diagnostic.suggestion || null,
+      context: {
+        source: 'expression',
+        parentPath: [...(resolver.getFieldInfo(fieldName)?.parentPath || [])],
+        ...diagnostic.context,
+      },
+    };
+    const key = JSON.stringify(item);
+    if (!frame.keys.has(key)) {
+      frame.keys.add(key);
+      frame.items.push(copy([item])[0]);
+    }
+  }
+
+  function emitWarning(warning, fieldNames = [warning.executionContext.fieldName]) {
+    const isScope = warning.type === 'FIELD_ACCESS_WARNING';
+    for (const fieldName of fieldNames) {
+      record(fieldName, {
+        code: isScope
+          ? warning.reason === 'not_found'
+            ? 'missing_reference'
+            : 'restricted_reference'
+          : warning.reason,
+        severity: warning.severity || 'warning',
+        phase: isScope ? 'scope' : 'dependency',
+        message: warning.message,
+        suggestion: warning.suggestion,
+        context: isScope
+          ? { referencedFieldName: warning.fieldName }
+          : {
+              ...(warning.fieldContext.fieldNames
+                ? { fieldNames: [...warning.fieldContext.fieldNames] }
+                : {}),
+              ...(warning.fieldContext.maxPasses
+                ? { maxPasses: warning.fieldContext.maxPasses }
+                : {}),
+            },
+      });
+    }
+    warningSystem.emitWarning(
+      warning,
+      consoleOverride === undefined ? undefined : { console: false }
+    );
+  }
+
+  return {
+    consoleOverride,
+    record,
+    emitWarning,
+    begin() {
+      const frame = { items: [], keys: new Set() };
+      frames.push(frame);
+      return frame;
+    },
+    abort(frame) {
+      frames.splice(frames.indexOf(frame), 1);
+    },
+    complete(frame) {
+      frames.splice(frames.indexOf(frame), 1);
+      snapshot = copy(frame.items);
+      if (consoleOverride === true) {
+        for (const item of frame.items) {
+          console.warn(`[form0] ${item.code} (${item.fieldName}): ${item.message}`);
+        }
+      }
+      if (typeof observer === 'function') {
+        try {
+          const result = observer(copy(frame.items));
+          if (result && typeof result.then === 'function') {
+            Promise.resolve(result).catch(reportObserverFailure);
+          }
+        } catch {
+          reportObserverFailure();
+        }
+      }
+    },
+    getSnapshot: () => copy(snapshot),
+  };
+}