> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frontic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Value Composer

The Value Composer transforms data by chaining together operations. Below is the full catalogue of available operations, grouped by category.

![Value Composer](https://mintcdn.com/frontic/34vlQbUxJTTktEkF/images/essentials/value-composer/composer-sync-merge-light.png?fit=max\&auto=format\&n=34vlQbUxJTTktEkF\&q=85\&s=b82e9c2c0c2735c96805829d64191db2)

Value Composer in the Data Feed merge step

## How operations are configured

A composer slot is a JSON object with a `source` discriminator. There are three sources you'll work with:

| Source | Shape | Use for |
| - | - | - |
| `static` | `{ "source": "static", "value": <literal>, "outputType": "<type>" }` | A fixed value baked into the configuration. |
| `data-field` | `{ "source": "data-field", "field": "path.to.field" }` | A reference to a field on the incoming feed record. Use `$item` / `$parent` inside iterations. |
| `composed` | `{ "source": "composed", "composition": { "type": "<op>", "<param>": <slot>, ... } }` | An operation. Each parameter is itself a slot, so operations nest arbitrarily. |

Putting it together - a `concat` of `vendor.name` + `-` + `name`, the JSON the admin UI emits:

```json theme={"theme":"css-variables"}
{
  "source": "composed",
  "composition": {
    "type": "concat",
    "value1": { "source": "data-field", "field": "vendor.name" },
    "value2": { "source": "data-field", "field": "name" },
    "separator": { "source": "static", "value": " - " }
  }
}
```

The same recursion shows up everywhere: an `if` whose `then` is a `concat` of two static values, a `map` whose `mapFunction` is a `get` on `$item`, and so on. The catalogue below documents the parameter names and types each operation expects.

## Type compatibility

Every slot has a known output type, and operations declare what they accept:

* **Concrete types** (`number`, `string`, `boolean`, `array`, `object`) - the input slot must produce that exact type, or the configuration is invalid.
* **Type markers** (`T`, `K`, `V`) - polymorphic placeholders. The first input that fills a marker fixes the type for every other slot using the same marker. For example, `equals(value: T, compare: T)` accepts any type as long as `value` and `compare` agree - fill `value` with a string and `compare` is constrained to strings too.

The admin UI surfaces type mismatches in the slot's validation state - slots that can't yet produce the required type stay highlighted as invalid and the configuration won't save. There's no implicit coercion at runtime: a string flowing into a number slot raises an explicit type error rather than getting cast silently. When you actually want a cast, use `toString` / `toNumber` / `toBoolean` so the conversion is part of the chain. See [Error handling](#error-handling) for what happens when something does slip through.

## Operations

### Array Operations

#### `count`

Returns the number of elements in an array.

**Inputs**

**array** `array`

The array to count elements in.

**output** `number`

#### `filter`

Returns an array of all elements that satisfy a condition. Access each element of the array with the `$item` variable.

**Inputs**

**array** `array`

The array to filter.

**filterFunction** `boolean`

The function to determine if the element should be included in the result.

**output** `array\<T\>`

#### `findFirst`

Finds and returns the first element of an array that satisfies a condition. Access each element of the array with the `$item` variable.

**Inputs**

**array** `array`

The array to find the first element of.

**filterFunction** `boolean`

The function to determine if the element should be returned.

**output** `T`

#### `first`

Returns the first element of an array.

**Inputs**

**array** `array`

The array to get the first element from.

**output** `T`

#### `flatMap`

Applies a function to each element of an array, flattens and returns the resulting array. Access each element of the array with the `$item` variable.

**Inputs**

**array** `array`

The array to map over.

**mapFunction** `array`

The function to apply to each element.

**output** `array`

#### `join`

Joins an array of strings into a single string.

**Inputs**

**array** `array`

The array of strings to join.

**separator** `string`

An optional separator to insert between the strings.

**output** `string`

#### `map`

Applies a function to each element of an array and returns the resulting array. Access each element of the array with the `$item` variable.

**Inputs**

**array** `array`

The array to map over.

**mapFunction** `T`

The function to apply to each element.

**output** `array`

#### `merge`

Merges an array of scalar values together.

**Inputs**

**base** `array`

The base array of values.

**additional** `array`

An array of additional values to add to the base array.

**output** `array`

#### `slice`

Extracts a portion of an array.

**Inputs**

**array** `array`

The array to slice.

**start** `number`

The starting position (zero-based index).

**length** `number`

The number of elements to extract.

**output** `array`

#### `split`

Splits a string into an array of strings given a separator.

**Inputs**

**value** `string`

The string to split.

**separator** `string`

The separator to use for splitting.

**output** `array`

#### `unique`

Removes duplicate values from a scalar array.

**Inputs**

**array** `array`

The array with duplicate values.

**output** `array`

### Comparison Operations

#### `equals`

Compares two values.

**Inputs**

**value** `T`

The first value to compare.

**compare** `T`

The second value to compare.

**output** `boolean`

#### `greaterThan`

Compares two values and returns true if the first is greater than the second.

**Inputs**

**value** `number`

The first value to compare.

**compare** `number`

The second value to compare against.

**output** `boolean`

#### `isEmpty`

Returns whether a value is empty.

**Inputs**

**value** `T`

The value to check for emptiness.

**output** `boolean`

#### `isNull`

Returns whether a value is NULL.

**Inputs**

**value** `T`

The value to check for NULL.

**output** `boolean`

#### `isScalar`

Returns whether a value is a scalar (i.e. not an object or array).

**Inputs**

**value** `T`

The possibly scalar value.

**output** `boolean`

### Logic Operations

#### `and`

Returns true if all values are true.

**Inputs**

**value1** `boolean`

The first value to compare.

**value2** `boolean`

The second value to compare.

**output** `boolean`

#### `if`

Splits the execution flow based on a condition.

**Inputs**

**condition** `boolean`

The condition to evaluate.

**then** `T`

The value to return if the condition is true.

**else** `T`

The value to return if the condition is false.

**output** `T`

**Details**

##### Overview

The `if` handler is a logic component that splits the execution flow based on a boolean condition. It evaluates a `condition` and returns the result of either the `then` or `else` branch, depending on whether the condition is `true` or `false`.

##### Schema

| Property | Type | Required | Description |
| - | - | - | - |
| type | string | Yes | Must be `'if'` |
| condition | value | Yes | The condition to evaluate (must resolve to bool) |
| then | value | Yes | Value to return if condition is `true` |
| else | value | Yes | Value to return if condition is `false` |

##### Example

```yaml theme={"theme":"css-variables"}
- type: if
  condition:
    source: static
    value: true
  then:
    source: static
    value: "Condition is true"
  else:
    source: static
    value: "Condition is false"
```

##### Behavior Table

| `condition` Value | Result Returned | Notes |
| - | - | - |
| `true` | Result of `then` value | Evaluates and returns `then` branch |
| `false` | Result of `else` value | Evaluates and returns `else` branch |
| not boolean | Exception thrown | Must resolve to boolean, else error |

##### Edge Cases

* **Non-boolean condition**: If the resolved `condition` is not a boolean (`true` or `false`), a `CompositionParameterTypeException` is thrown.
* **Missing required fields**: If any of `condition`, `then`, or `else` are missing, schema validation will fail.
* **Side effects in branches**: Only the selected branch (`then` or `else`) is resolved and executed. The other branch is not evaluated, so any side effects or errors in the non-selected branch are ignored.
* **Nested handlers**: Both `then` and `else` can themselves be handlers, including nested `if` handlers, allowing for complex conditional logic.

##### Usage Notes

* Use the `if` handler to implement conditional logic in your composition flows.
* Ensure that the `condition` resolves to a boolean value; otherwise, execution will fail with a type exception.
* Both `then` and `else` branches must be provided, even if one is a placeholder or a no-op.

##### Example with Nested If

```yaml theme={"theme":"css-variables"}
- type: if
  condition:
    source: static
    value: false
  then:
    type: if
    condition:
      source: static
      value: true
    then:
      source: static
      value: "Nested true"
    else:
      source: static
      value: "Nested false"
  else:
    source: static
    value: "Outer false"
```

#### `not`

Returns the negation of the value.

**Inputs**

**value** `boolean`

The value to negate.

**output** `boolean`

**Details**

##### Not Handler

Returns the negation of the provided boolean value.

###### Schema

```json theme={"theme":"css-variables"}
{
  "type": "object",
  "properties": {
    "type": { "const": "not" },
    "value": { "$ref": "#/definitions/value" }
  },
  "required": ["type", "value"]
}
```

###### Example

```json theme={"theme":"css-variables"}
{
  "type": "not",
  "value": { "source": "static", "value": true }
}
```

###### Description

Evaluates to `true` if `value` is false, and to `false` if `value` is true.

#### `or`

Returns true if at least one value is true.

**Inputs**

**value1** `boolean`

The first value to compare.

**value2** `boolean`

The second value to compare.

**output** `boolean`

**Details**

##### Or Handler

Returns true if at least one of the provided boolean values is true.

###### Schema

```json theme={"theme":"css-variables"}
{
  "type": "object",
  "properties": {
    "type": { "const": "or" },
    "value1": { "$ref": "#/definitions/value" },
    "value2": { "$ref": "#/definitions/value" }
  },
  "required": ["type", "value1", "value2"]
}
```

###### Example

```json theme={"theme":"css-variables"}
{
  "type": "or",
  "value1": { "source": "static", "value": true },
  "value2": { "source": "static", "value": false }
}
```

###### Description

Evaluates to `true` if either `value1` or `value2` is true. Otherwise, returns `false`.

#### `xor`

Returns true if exactly one value is true.

**Inputs**

**value1** `boolean`

The first value to compare.

**value2** `boolean`

The second value to compare.

**output** `boolean`

**Details**

##### Xor Handler

Returns true if exactly one of the provided boolean values is true.

###### Schema

```json theme={"theme":"css-variables"}
{
  "type": "object",
  "properties": {
    "type": { "const": "xor" },
    "value1": { "$ref": "#/definitions/value" },
    "value2": { "$ref": "#/definitions/value" }
  },
  "required": ["type", "value1", "value2"]
}
```

###### Example

```json theme={"theme":"css-variables"}
{
  "type": "xor",
  "value1": { "source": "static", "value": true },
  "value2": { "source": "static", "value": false }
}
```

###### Description

Evaluates to `true` if either `value1` or `value2` is true, but not both. Returns `false` if both are true or both are false.

### Math Operations

#### `divide`

Divides two numbers (i.e. `$numerator / $denominator`).

**Inputs**

**numerator** `number`

The numerator for the division.

**denominator** `number`

The denominator for the division.

**output** `number`

#### `exponent`

Calculates the exponentiation of a number by another number (base^exponent).

**Inputs**

**base** `number`

The base number.

**exponent** `number`

The exponent number.

**output** `number`

#### `multiply`

Multiplies two numbers.

**Inputs**

**value1** `number`

The first number to multiply.

**value2** `number`

The second number to multiply.

**output** `number`

#### `round`

Rounds a number with given significant decimal places.

**Inputs**

**value** `number`

The number to round.

**precision** `number`

The number of significant decimal places to round to.

**output** `number`

### Object Operations

#### `get`

Accesses a value of an object field with the given key.

**Inputs**

**key** `string`

The key of the field to access.

**object** `object`

The object containing the field.

**output** `T`

#### `object`

Handles an object composition by resolving its properties.

**Inputs**

**properties** `object`

The properties of the object to resolve.

**output** `object`

### Text Operations

#### `concat`

Concatenates two strings.

**Inputs**

**value1** `string`

The first string to concatenate.

**value2** `string`

The second string to concatenate.

**separator** `string`

An optional separator to insert between the concatenated strings.

**output** `string`

#### `contains`

Checks if a string contains another string with optional case sensitivity.

**Inputs**

**value** `string`

The string to search in.

**reference** `string`

The string to search for.

**caseInsensitive** `boolean`

Whether to perform case-insensitive search (defaults to false).

**output** `boolean`

#### `length`

Returns the number of characters in a string.

**Inputs**

**value** `string`

The string to measure length of.

**output** `number`

#### `md5`

Hashes a string with the MD5 algorithm.

**Inputs**

**value** `string`

The string to hash with MD5.

**output** `string`

#### `padLeft`

Pads a string to the left.

**Inputs**

**value** `string`

The original string.

**length** `number`

The length to pad to. If the length is negative, no padding takes place.

**char** `string`

The character to pad with.

**output** `string`

#### `padRight`

Pads a string to the right.

**Inputs**

**value** `string`

The original string.

**length** `number`

The length to pad to. If the length is negative, no padding takes place.

**char** `string`

The character to pad with.

**output** `string`

#### `replace`

Replaces a value in a string.

**Inputs**

**value** `string`

The original string.

**searchValue** `string`

The substring to search for.

**replaceValue** `string`

The substring to replace with.

**caseSensitive** `boolean`

Should the search be case sensitive?

**output** `string`

#### `slugify`

Converts a string to a slug with no spaces or special characters.

**Inputs**

**value** `string`

The string to convert to a slug.

**separator** `string`

The separator to use in the slug. It will be used to replace spaces and special characters.

**output** `string`

#### `substring`

Extracts a substring from a string.

**Inputs**

**value** `string`

The string to extract from.

**start** `number`

The starting position.

**length** `number`

Length of the substring.

**output** `string`

#### `toLower`

Converts a string to lowercase.

**Inputs**

**value** `string`

The string to convert to lowercase.

**output** `string`

#### `toUpper`

Converts a string to uppercase.

**Inputs**

**value** `string`

The string to convert to uppercase.

**output** `string`

#### `trim`

Trims whitespace from the beginning and end of a string.

**Inputs**

**value** `string`

The string to trim.

**output** `string`

#### `urlEncode`

Encodes a string for usage inside of a URL.

**Inputs**

**value** `string`

The string to encode.

**output** `string`

### Transform Operations

#### `toBoolean`

Converts a value to a boolean.

**Inputs**

**value** `T`

The value to convert to a boolean, e.g. "false", "0", and \[] will all be converted to false.

**output** `boolean`

#### `toNumber`

Converts a value to a number. NULL is converted to 0.

**Inputs**

**value** `T`

The value to convert to a number.

**output** `number`

#### `toString`

Converts a value to a string. NULL is converted to an empty string.

**Inputs**

**value** `T`

The value to convert to a string.

**output** `string`

### Utilities Operations

#### `randomBoolean`

Returns a random boolean. Set probability (0-100) to control how often true is returned.

**Inputs**

**probability** `number`

Chance of returning true, from 0 (never) to 100 (always).

**output** `boolean`

#### `randomNumber`

Returns a random number between min and max. Set precision to 0 for integers, or higher for decimals (e.g. 2 produces values like 3.14).

**Inputs**

**min** `number`

Minimum value (inclusive).

**max** `number`

Maximum value (inclusive).

**precision** `number`

Decimal places: 0 for integers, 2 for values like 3.14.

**output** `number`

## Error handling

The composer is strict about types and forgiving about absence:

* **Missing fields and keys resolve to `null`.** A `data-field` slot pointing at a path that doesn't exist on the current record returns `null`. `get` against a missing key returns `null`. The chain continues with `null` flowing through.
* **`null` inputs are absorbed where it makes sense.** Per-operation handling, not a global rule:
  * `concat` coalesces `null` inputs to empty strings.
  * `filter`, `map`, and other array operations coalesce a `null` array input to `[]` and return an empty array.
  * `get` against a `null` object returns `null`.
  * `findFirst` against an empty array returns `null`.
* **Type mismatches throw.** Operations don't implicitly coerce - passing a number into a string slot, or a non-array into `filter`'s `array` parameter, raises a runtime error and fails the sync. Use explicit `toString` / `toNumber` / `toBoolean` when you need a cast, so the conversion is visible in the chain.
* **Math has guard rails.** `divide` raises a runtime error on a zero denominator instead of producing `Infinity` or `NaN`.
* **Iteration context has a limit.** `filter` and `map` populate `$item` (and `$parent` when nested one level). Three or more nesting levels aren't supported and raise a runtime error - flatten with `flatMap` instead.

The [field-level debugger](https://docs.frontic.com/data-integration/value-composer.md#field-level-debugger) shows node-wise output for the configuration: when a chain produces an unexpected `null` or fails outright, the debugger pinpoints which operation introduced it. Use it before the configuration runs against real sync data.

Configuration errors that the type system can catch - an invalid operation type, a slot whose output can't satisfy the parent's expected type, a missing required parameter - show as inline validation on the affected slot in the admin UI; the configuration won't save until they're resolved. Backend resolution carries equivalent runtime checks as a backstop, raising explicit exceptions if an invalid configuration somehow reaches it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.