@oneblink/sdk-core
    Preparing search index...

    Function evaluateExpression

    • Evaluate a OneBlink calculation expression against form submission data.

      Day-only (YYYY-MM-DD) date parsing is injected via parseDayOnlyDate so callers control timezone-aware behaviour (client vs server), matching the pattern used by conditionalLogicService. Other date strings use new Date(value).

      Expressions are mathematical / logical formulas. Form element values are referenced with {ELEMENT:<elementName>} tags (including nested paths via |, e.g. {ELEMENT:Children|Age}).

      • Numbers — e.g. 0, 5, 5.4
      • Strings — single or double quoted, e.g. "abc", 'abc'
      • Booleans — true, false
      Operator Description Example
      + Addition (also unary plus) 1 + 2 → 3
      - Subtraction (also unary minus) 1 - 2 → -1
      * Multiplication 4 * 2 → 8
      / Division 4 / 2 → 2
      % Remainder 8 % 3 → 2
      ++ Unary increment ++2 → 3
      -- Unary decrement --2 → 1

      Standard operator precedence applies. Use parentheses to override it, e.g. 3 * (2 + 1) → 9.

      Operator Description Example
      == Equal 2 == 2 → true
      != Not equal 2 != 3 → true
      > Greater than 2 > 1 → true
      >= Greater than or equal 2 >= 2 → true
      < Less than 2 < 3 → true
      <= Less than or equal 2 <= 2 → true
      Operator Description Example
      && Logical AND (returns last operand) true && false → false
      || Logical OR (returns first truthy) false || true → true
      ! Logical NOT !false → true
      • {ELEMENT:Number} — value of the root element named Number
      • {ELEMENT:Set\|Child} — value of Child within repeatable set / nested form element Set
      • Nested paths may include multiple segments: {ELEMENT:Parents\|Children\|Age}

      How values are coerced for evaluation:

      • Numbers are used as-is
      • Day-only (YYYY-MM-DD) strings are parsed via parseDayOnlyDate; other non-numeric date strings use new Date(value). Valid dates use Date#getTime(), otherwise the string is parsed as a float via parseFloat
      • Arrays of numeric strings (e.g. checkboxes) are summed
      • Repeatable set entries sum the referenced nested numeric values
      • Empty arrays yield NaN (result type MISSING_VALUES)
      • Compliance element objects use their value property
      Function Description Example
      ROUND(value, precision) Round value to precision decimal places (correct floating-point rounds) ROUND(1.255, 2) → 1.26
      ROUND_DOWN(value) Round down to the nearest integer (Math.floor) ROUND_DOWN(1.9) → 1
      ROUND_UP(value) Round up to the nearest integer (Math.ceil) ROUND_UP(1.1) → 2
      ISNULL(value, defaultValue) If value is unentered (null/undefined/""), return defaultValue or 0; otherwise return value ISNULL({ELEMENT:A}, 10)

      ROUND, ROUND_DOWN, and ROUND_UP return null when value is NaN or not finite.

      const result = calculationService.evaluateExpression({
        expression: '{ELEMENT:Quantity} * {ELEMENT:Price}',
        submission: { Quantity: 3, Price: 12.5 },
        formElements: form.elements,
        // Client: local timezone. Server: organisation timezone.
        parseDayOnlyDate: (value) => new Date(`${value}T00:00:00.000Z`),
      })
      // result === { type: 'RESULT', value: 37.5 }

      calculationService.evaluateExpression({
        expression: 'ROUND({ELEMENT:Amount} * 1.1, 2)',
        submission: { Amount: 100 },
        formElements: form.elements,
        parseDayOnlyDate: (value) => new Date(`${value}T00:00:00.000Z`),
      })
      // { type: 'RESULT', value: 110 }

      calculationService.evaluateExpression({
        expression: 'ISNULL({ELEMENT:Optional}, 0) + {ELEMENT:Required}',
        submission: { Required: 5 },
        formElements: form.elements,
        parseDayOnlyDate: (value) => new Date(`${value}T00:00:00.000Z`),
      })
      // { type: 'RESULT', value: 5 }

      Parameters

      • options: {
            expression: string;
            formElements: FormElement[];
            parseDayOnlyDate: conditionalLogicService.ParseDayOnlyDate;
            submission: { [name: string]: unknown };
        }
        • expression: string

          The calculation expression string to evaluate

        • formElements: FormElement[]

          Form elements definition. Used to resolve nested form element values referenced in the expression and to validate {ELEMENT:...} references.

        • parseDayOnlyDate: conditionalLogicService.ParseDayOnlyDate

          Parse YYYY-MM-DD strings when resolving date element values. sdk-core only calls this for day-only values; other date strings use new Date(value).

        • submission: { [name: string]: unknown }

          Form submission data used to resolve {ELEMENT:...} references

      Returns EvaluateExpressionResult

      A discriminated result describing the outcome of evaluation. Empty expressions and parse failures return { type: 'INVALID_EXPRESSION', error }. Unexpected runtime errors are rethrown.

    Settings

    Member Visibility

    On This Page

    Expression syntax