JSON TransformArray
unshift
Prepend elements to the beginning of an array
unshift
Adds one or more items to the beginning of an array, preserving their order. If items is itself an array, its elements are prepended individually (spread); otherwise the value is prepended as a single element.
Options
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
items | any | Yes | — | Item or array of items to prepend. Selectors inside are resolved first. |
Example
Input
["c", "d"]Operation
{ "type": "unshift", "options": { "items": ["a", "b"] } }Output
["a", "b", "c", "d"]In a Circuit Step
{
"name": "prepend_system_prompt",
"description": "Prepend a fresh system message to the conversation",
"function": "circuit.core.transform.json",
"input": {
"source": "${{ messages }}",
"operations": [
{
"type": "unshift",
"options": {
"items": [
{ "role": "system", "content": "${{ prompts.system_prompt }}" }
]
}
}
]
},
"outputs": [
{
"name": "messages_with_system",
"description": "Messages array with system prompt at the front",
"value": "${{ prepend_system_prompt.output.transformed_result }}"
}
]
}Notes & gotchas
- Errors with
unshift: expected arrayif the input is not an array. - When
itemsis an array, the order is preserved in the result — internally each element is inserted at index 0 in reverse order to achieve that. - This is the operation used by the canonical "inject system prompt" pattern:
unshifta[{ "role": "system", "content": "..." }]array onto a filtered messages list. itemsis fully selector-evaluated, so"items": "${{ new_system_messages }}"works.