formula

import NodeTypeBadge from '@site/src/components/DocsFeatures/node-type-badge';

# Formula

<NodeTypeBadge type="uncontrolled" />

## Overview
The Formula node evaluates mathematical expressions and performs calculations using the [mathjs](https://mathjs.org/) library. It dynamically generates input sockets based on the variables referenced in your formula expression, allowing you to create reusable calculation components that respond immediately to input changes.

When you type a formula like `a + b` or `price * quantity`, the node automatically creates corresponding input sockets (`a`, `b`, `price`, `quantity`) that can be connected to other nodes. The node evaluates the expression whenever any input value changes, making it ideal for real-time calculations, data transformations, and mathematical operations within your workflow.

### Variable Scope
The Formula node has access to three levels of variables during evaluation:
- **Node Inputs**: Values connected to the dynamically generated input sockets
- **Parent Workflow Variables**: Variables set in the immediate parent workflow scope
- **Root Workflow Variables**: Global variables available throughout the entire workflow execution

If a variable exists in multiple scopes, the node follows the standard precedence: node inputs override parent variables, which override root workflow variables.

## Inputs
| Input | Type | Description | Default |
| :--- | :--- | :--- | :--- |
| **Formula** | Text | The mathematical expression to evaluate. Supports standard math operators (+, -, *, /, ^), functions (sin, cos, sqrt, etc.), and variables. Variables automatically become input sockets. | - |
| *[Dynamic]* | Data | Dynamically generated inputs based on variables detected in the formula field. For example, typing `x * y` creates `x` and `y` inputs. | - |

## Outputs
| Output | Type | Description |
| :--- | :--- | :--- |
| **Output** | Data | The result of evaluating the formula expression. Returns `undefined` if the formula is empty or contains errors. |

## Runtime Behavior and Defaults
- **Evaluation Engine**: Uses mathjs for expression parsing and evaluation, supporting advanced mathematical functions, constants (pi, e), and complex expressions.
- **Dynamic Input Generation**: Input sockets are created or removed automatically when the formula text changes. Existing connections to removed inputs are deleted.
- **Error Handling**: If the formula contains syntax errors or references undefined variables, the node outputs `undefined` and logs the error to the console.
- **Type Coercion**: Input values are coerced to numbers where possible. Non-numeric inputs may result in `NaN` or `undefined` depending on the operation.
- **Immediate Execution**: As an uncontrolled node, it evaluates immediately whenever inputs change or the formula is modified, without requiring an event trigger.

## Example

### Basic Arithmetic
**Formula**: `price * quantity`

**Inputs**:
- `price`: 25.00
- `quantity`: 4

**Output**: `100`

### Using Workflow Variables
If you have workflow variables `taxRate` (0.08) and `discount` (5), you can reference them directly:

**Formula**: `(subtotal * (1 + taxRate)) - discount`

**Inputs**:
- `subtotal`: 100

**Output**: `103` (calculated as (100 * 1.08) - 5)

### Complex Calculations
**Formula**: `sqrt(pow(x, 2) + pow(y, 2))`

**Inputs**:
- `x`: 3
- `y`: 4

**Output**: `5` (calculates the hypotenuse of a right triangle)

:::tip[Variable Naming]
Variable names in formulas must follow JavaScript identifier rules (start with letter/underscore, contain only letters, numbers, underscores). Avoid spaces or special characters in variable names.
:::