# Loops & State Nodes (StateGraph)

Nodes for iteration and state management. These require the `flowdrop_stategraph` module and the **StateGraph** orchestrator.

---

## ForEach

Iterates over an array, executing downstream nodes once for each item. Collects results from all iterations into an output array.

**Category:** Loops & State

### Input Ports

| Port | Type | Required | Description |
|------|------|----------|-------------|
| **items** | Array | Yes | The array to iterate over |
| **item_result** | Mixed | No | Result from the current iteration (for collecting results) |

### Output Ports

| Port | Type | Description |
|------|------|-------------|
| **current_item** | Mixed | The current item in the iteration |
| **current_index** | Number | Zero-based index of the current item |
| **is_first** | Boolean | Whether this is the first iteration |
| **is_last** | Boolean | Whether this is the last iteration |
| **has_more** | Boolean | Whether there are more items after the current one |
| **total_count** | Number | Total number of items |
| **loop_active** | Boolean | Whether the loop is still running |
| **collected_results** | Array | All results collected across iterations |

### Usage

1. Connect an array source (e.g., Range, Entity Query) to the **items** input.
2. Connect the **current_item** output to the nodes that should process each item.
3. To collect results, connect the processing output back to the **item_result** input.
4. After all iterations complete, the **collected_results** output contains an array of all results.

---

## Iterator Start

Initializes an iterator over an array. Use this for more manual control over iteration compared to ForEach.

**Category:** Loops & State

### Input Ports

| Port | Type | Required | Description |
|------|------|----------|-------------|
| **items** | Array | Yes | The array to iterate over |

### Output Ports

| Port | Type | Description |
|------|------|-------------|
| **current_item** | Mixed | The first item |
| **current_index** | Number | Always 0 for the start |
| **has_more** | Boolean | Whether there are more items |
| **total_count** | Number | Total number of items |

---

## Approval Gate

Pauses workflow execution at a designated point and waits for human approval before continuing. Works similarly to the Confirmation interrupt node but is designed for formal approval workflows with the StateGraph orchestrator.

**Category:** Loops & State

### Configuration

| Parameter | Type | Description |
|-----------|------|-------------|
| **message** | String | The approval request message |
| **timeout_seconds** | Number | Optional timeout — auto-reject if not approved in time |

### Output Ports

| Port | Type | Description |
|------|------|-------------|
| **approved** | Boolean | Whether the request was approved |
| **approval_notes** | String | Notes from the approver |
| **rejection_reason** | String | Reason for rejection (if rejected) |
| **approved_by** | String | Who approved/rejected |
| **approved_at** | String | Timestamp of the decision |

### Permissions

The `manage approval gates` permission is required to approve or reject requests.

---

## State Storage

Reads and writes key-value data to the StateGraph execution state. This allows nodes to share persistent state across loop iterations and workflow steps.

**Category:** Loops & State

### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **operation** | String | Yes | Operation: `set`, `get`, `append`, `increment`, `delete`, `clear` |
| **key** | String | Varies | The state key to operate on |
| **value** | Mixed | For `set` | The value to store |
| **default** | Mixed | For `get` | Default value if key doesn't exist |
| **amount** | Number | For `increment` | Amount to increment by |

### Output Ports

| Port | Type | Description |
|------|------|-------------|
| **value** | Mixed | The current value of the key |
| **key** | String | The key that was operated on |
| **operation** | String | The operation performed |
| **exists** | Boolean | Whether the key exists in state |
