# Morpher: string manipulation & templating

Use Morpher templates to read context values in workflow configuration. A field containing only one template preserves the value's type. Templates embedded in text produce a string.

## Template syntax

Use `{{ }}` templates in workflow fields that support templating. Workflows use Morpher v2.

### String interpolation

A template surrounded by text produces a string:

```text
Template: "Hello {{ user.name }}!"
Context: { "user": { "name": "Alice" } }
Result: "Hello Alice!"
```

Objects and arrays embedded in text are serialized as JSON. Missing values and `null` become empty text.

### Typed values

When the entire field is a single template, its value keeps its original type:

```text
Template: "{{ user.isAdmin }}"
Context: { "user": { "isAdmin": true } }
Result: true (boolean)

Template: "{{ product.price }}"
Context: { "product": { "price": 19.99 } }
Result: 19.99 (number)

Template: "{{ items }}"
Context: { "items": [{ "id": 1 }] }
Result: [{ "id": 1 }] (array)
```

The legacy `<< >>` syntax is no longer evaluated. It remains literal text, so replace it with supported `{{ }}` templates.

## Accessing context data

Use dot notation, array indexes, or quoted bracket keys:

```text
{{ user.name }}
{{ user.profile.bio }}
{{ items[0].name }}
{{ headers["x-request-id"] }}
```

## Helpers

Chain helpers with `|`. Helpers with arguments use parentheses:

```text
{{ user.name | trim | capitalize }}
{{ items | pluck('name') | join(', ') }}
{{ user.nickname | default('Guest') }}
```

Common helpers include:

| Helper                         | Effect                                                                          |
| ------------------------------ | ------------------------------------------------------------------------------- |
| `upper`, `lower`               | Convert text to upper or lower case                                             |
| `capitalize`                   | Uppercase the first letter and lowercase the rest                               |
| `trim`                         | Remove leading and trailing whitespace                                          |
| `get('path')`                  | Read a nested path on the current value                                         |
| `find('field', value)`         | Find the first matching array item                                              |
| `where('field', value)`        | Keep array items whose field strictly equals the value                          |
| `pluck('path')`                | Read a field from every array item                                              |
| `join(', ')`                   | Join array values into text                                                     |
| `count`                        | Count array items or string length                                              |
| `default(value)`               | Replace only `null` or missing values; preserve `false`, `0`, and empty strings |
| `lookup(table, fallback)`      | Look up the current value in an object                                          |
| `number`, `integer`, `boolean` | Convert values to the requested type                                            |
| `date('yyyy-MM-dd')`           | Parse and format a supported date value                                         |
| `json(2)`                      | Serialize a value as JSON text                                                  |

Helpers such as `trim` and `upper` apply to each item when their input is an array. Collection helpers such as `join`, `count`, and `where` operate on the whole array.

## Examples

### String interpolation with helpers

```text
Template: "Welcome {{ user.name | upper }}!"
Context: { "user": { "name": "alice" } }
Result: "Welcome ALICE!"
```

### Collection processing

```text
Template: "{{ users | where('active', true) | pluck('name') | join(', ') }}"
Context: { "users": [{ "name": "Alice", "active": true }, { "name": "Bob", "active": false }] }
Result: "Alice"
```

### Conditional text

```text
Template: "{{ user.isPremium | lookup({'true': 'Premium'}, 'Standard') }}"
Context: { "user": { "isPremium": true } }
Result: "Premium"
```

### Nested properties with a fallback

```text
Template: "Bio: {{ user.profile.bio | default('Not provided') | trim }}"
Context: { "user": { "profile": {} } }
Result: "Bio: Not provided"
```

Morpher does not evaluate JavaScript operators, ternaries, arrow functions, or method calls such as `items.map(...)`. Use the supported helpers for transformations and a [Rule step](/docs/rules) for comparisons and branching. Supply calculated values in context when a transformation has no supported helper.

## Security

Expressions are parsed as paths and helper pipelines, with no arbitrary JavaScript evaluation. Path access to `constructor`, `__proto__`, and `prototype` returns `undefined`. Morpher does not mutate the context.

## Error handling

| Case | Result |
| --- | --- |
| Missing property | A sole template returns `undefined`; an embedded template becomes empty text. Use `default(...)` for a fallback. |
| Object field renders as `undefined` | The field is omitted from the processed object. |
| Invalid syntax or unknown helper | Rendering throws an error. Workflow template errors return HTTP 400 with code `TEMPLATE_ERROR`. |
| Invalid non-empty input to a conversion helper | Conversion throws an error. `default(...)` handles missing values, not conversion failures. |
