form0-core 0.1.1 → 0.1.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 paqu.io
+Copyright (c) 2025-present paqu.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -35,3 +35,17 @@ npm install form0-core
 ## Security
 
 See `SECURITY.md` for security modes and configuration.
+
+## Requirements
+
+- Node.js 18+
+
+## Related repositories
+
+- [form0-cli](https://github.com/paqu-io/form0-cli) - Command-line interface
+- [form0-react](https://github.com/paqu-io/form0-react) - React components
+- [form0-react-native](https://github.com/paqu-io/form0-react-native) - React Native components
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit [issues](https://github.com/paqu-io/form0-core/issues) and [pull requests](https://github.com/paqu-io/form0-core/pulls).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
@@ -8,7 +8,7 @@
   "main": "src/index.js",
   "type": "module",
   "scripts": {
-    "test": "node tests/form0-core.test.js && node tests/security-test.js",
+    "test": "node tests/form0-core.test.js && node tests/builtin-metadata.test.js && node tests/calculation-editor.test.js && node tests/security-test.js",
     "postinstall": "node scripts/postinstall.cjs",
     "format": "prettier --write \"**/*.{js,jsx,json,ts,tsx,md}\"",
     "format:check": "prettier --check \"**/*.{js,jsx,json,ts,tsx,md}\""

package/src/builtins/builtin-metadata.js

@@ -0,0 +1,44 @@
+/**
+ * @typedef {'calculation' | 'event'} BuiltinContext
+ *
+ * @typedef {Object} BuiltinMetadata
+ * @property {string} name
+ * @property {string} category
+ * @property {string} signature
+ * @property {string} description
+ * @property {string[]} examples
+ * @property {BuiltinContext[]} contexts
+ */
+
+export const BUILTIN_CONTEXTS = Object.freeze({
+  CALCULATION: 'calculation',
+  EVENT: 'event',
+});
+
+/**
+ * Create immutable metadata for a builtin implementation.
+ *
+ * @param {BuiltinMetadata} definition
+ * @returns {BuiltinMetadata}
+ */
+export function defineBuiltinMetadata(definition) {
+  return Object.freeze({
+    ...definition,
+    examples: Object.freeze([...(definition.examples ?? [])]),
+    contexts: Object.freeze([...(definition.contexts ?? [])]),
+  });
+}
+
+/**
+ * Return a mutable clone of builtin metadata for external consumers.
+ *
+ * @param {BuiltinMetadata} definition
+ * @returns {BuiltinMetadata}
+ */
+export function cloneBuiltinMetadata(definition) {
+  return {
+    ...definition,
+    examples: [...definition.examples],
+    contexts: [...definition.contexts],
+  };
+}

package/src/builtins/choice/choicelabel.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.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.
@@ -10,6 +12,15 @@
  * // 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,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.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.
@@ -10,6 +12,15 @@
  * // 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,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.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.
@@ -10,6 +12,15 @@
  * // 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)'],
+  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,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.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.
@@ -10,6 +12,15 @@
  * // 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)'],
+  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,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin HASOTHER
  * @description Returns true if user entered an other option, false otherwise. Works with both SingleChoiceField and MultiChoiceField.
@@ -13,6 +15,15 @@
  * // 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,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin OTHER
  * @description Retrieves the other label if user entered the other option, otherwise null. Works with both SingleChoiceField and MultiChoiceField.
@@ -13,6 +15,15 @@
  * // 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') {

package/src/builtins/control/eval.js

@@ -1,5 +1,6 @@
 import { validateExpression } from '../../security/validation.js';
 import { SAFE_SECURITY_CONFIG } from '../../security/config.js';
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
 
 /**
  * @builtin EVAL
@@ -16,6 +17,15 @@ import { SAFE_SECURITY_CONFIG } from '../../security/config.js';
  * // Computed field references
  * EVAL('$city' + '_suffix')
  */
+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],
+});
+
 // Global context for EVAL() - set during expression evaluation
 let _evalContext = null;
 

package/src/builtins/control/setresult.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 // Global state for result management
 let _resultSet = false;
 let _resultValue;
@@ -14,6 +16,15 @@ let _resultValue;
  * // Set a conditional result
  * SETRESULT(IF(isEligible, discount, 0))
  */
+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, BUILTIN_CONTEXTS.EVENT],
+});
+
 export const SETRESULT = (value) => {
   _resultSet = true;
   _resultValue = value;

package/src/builtins/event/control/off.js

@@ -1,4 +1,5 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
 
 /**
  * OFF builtin for form events
@@ -26,6 +27,15 @@ import { __collectEventOperation } from '../event-operations-collector.js';
  * // Remove all field event handlers
  * OFF('change', 'city');
  */
+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 function OFF(eventType, fieldKeyOrCallback, callback) {
   let fieldKey = '*';
   let actualCallback = undefined;

package/src/builtins/event/control/on.js

@@ -1,4 +1,5 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
 
 /**
  * ON builtin for form events
@@ -18,6 +19,15 @@ import { __collectEventOperation } from '../event-operations-collector.js';
  * // Register field-specific event handler
  * ON('change', 'city', function(event) { ALERT('City changed!'); });
  */
+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 function ON(eventType, fieldKeyOrCallback, callback) {
   let fieldKey = '*';
   let actualCallback = fieldKeyOrCallback;

package/src/builtins/event/field/setvalue.js

@@ -1,4 +1,5 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
 
 /**
  * SETVALUE builtin for form events
@@ -30,6 +31,15 @@ import { __collectEventOperation } from '../event-operations-collector.js';
  * // Set MultiChoiceField value
  * SETVALUE('field_dataname', ['value1', 'value2', 'value3'])
  */
+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 function SETVALUE(fieldDataName, valueToSet) {
   // Create operation descriptor
   const operation = {

package/src/builtins/event/ui/alert.js

@@ -1,4 +1,5 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
 
 /**
  * ALERT builtin for form events
@@ -7,6 +8,15 @@ import { __collectEventOperation } from '../event-operations-collector.js';
  * @param {string} message - The message to display in the alert (optional)
  * @returns {Object} Operation descriptor for platform execution (for backward compatibility)
  */
+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 function ALERT(title, message = '') {
   // Create operation descriptor
   const operation = {

package/src/builtins/logical/and.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin AND
  * @description Logical AND operation that returns true only if all arguments are truthy
@@ -10,4 +12,13 @@
  * // Multiple conditions
  * AND(name.length > 0, email.includes("@"), age >= 13)
  */
+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 AND = (...args) => args.every(Boolean);

package/src/builtins/logical/array.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin ARRAY
  * @description Returns an array from its arguments. Can parse string representations of arrays (with single or double quotes) and comma-separated values.
@@ -28,6 +30,15 @@
  * // For complex parsing, JSON.parse() can be used:
  * // EVAL('JSON.parse("[1,2,3]")')
  */
+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 ARRAY = (...args) => {
   // Handle empty arguments
   if (args.length === 0) {

package/src/builtins/logical/count.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin COUNT
  * @description Returns a count of the number of numeric values in a dataset
@@ -13,6 +15,15 @@
  * // Returns 3 (mixed array)
  * COUNT([1, 'a', 2, null, 3])
  */
+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 COUNT = (values) => {
   // Handle null/undefined input
   if (!Array.isArray(values)) {

package/src/builtins/logical/counta.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin COUNTA
  * @description Returns a count of values in a dataset
@@ -13,6 +15,15 @@
  * // Returns 4 (counts all items including null)
  * COUNTA([1, 'a', null, true])
  */
+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 COUNTA = (values) => {
   // Handle null/undefined input
   if (!Array.isArray(values)) {

package/src/builtins/logical/countblank.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin COUNTBLANK
  * @description Returns the number of blank values in a dataset
@@ -13,6 +15,15 @@
  * // 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)) {
@@ -20,7 +31,5 @@ export const COUNTBLANK = (values) => {
   }
 
   // Count null, undefined, and empty strings as blank
-  return values.filter(
-    (value) => value === null || value === undefined || value === ''
-  ).length;
+  return values.filter((value) => value === null || value === undefined || value === '').length;
 };

package/src/builtins/logical/if.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin IF
  * @description Conditional logic function that returns one of two values based on a condition
@@ -12,4 +14,13 @@
  * // 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")'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
 export const IF = (cond, a, b) => (cond ? a : b);

package/src/builtins/logical/or.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin OR
  * @description Logical OR operation that returns true if at least one argument is truthy
@@ -10,4 +12,13 @@
  * // 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,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin ABS
  * @description Returns the absolute value of a number
@@ -13,4 +15,13 @@
  * // 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,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin CEILING
  * @description Rounds a value up to the nearest integer multiple of factor
@@ -14,6 +16,15 @@
  * // 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,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin COS
  * @description Returns the cosine of a value, in radians
@@ -13,4 +15,13 @@
  * // Returns -1
  * COS(Math.PI)
  */
-export const COS = (value) => Math.cos(value);
+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,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin ROUND
  * @description Rounds a number to a specified number of decimal places according to standard rounding rules
@@ -17,11 +19,20 @@
  * // 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');
   }
-  
+
   const multiplier = Math.pow(10, places);
   return Math.round(value * multiplier) / multiplier;
-};
+};

package/src/builtins/math/sin.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin SIN
  * @description Returns the sine of a value, in radians
@@ -13,4 +15,13 @@
  * // Returns 1
  * SIN(Math.PI / 2)
  */
-export const SIN = (value) => Math.sin(value);
+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);