canonical_id: "foreach_control"
display_name: "迴圈控制"
category: "logic"
version: "v1"
wasi_target: "preview1"
stability: "floating"
runtime_compat:
  - "cf-workers"
  - "workerd"
  - "wazero"
constraints:
  max_size_kb: 2048
  max_cold_start_ms: 50
  no_network_syscall: true
  no_filesystem_syscall: true
  io_model: "stdin_stdout_json"
input_schema:
  type: object
  required: [items]
  properties:
    items:
      type: array
      description: 要迭代的陣列
    item_key:
      type: string
      description: 每個元素注入的變數名，預設 item
output_schema:
  type: object
  properties:
    success:
      type: boolean
    data:
      type: object
      properties:
        items:
          type: array
        count:
          type: number
        current_index:
          type: number
        current_item: {}
        item_key:
          type: string
gherkin_tests:
  - scenario: "正常迭代"
    given: '{"items":[1,2,3],"item_key":"item"}'
    then_contains: '"current_index":0'
  - scenario: "空陣列"
    given: '{"items":[]}'
    then_contains: '{"success":false'
tags: [builtin, control, foreach, loop, iteration]
description: "輸出第一個元素供 Cypher Executor 迭代，current_index 從 0 開始。"
config_example: |
  my_loop:                         # 節點名稱（可自訂）
    items: "{{upstream.results}}"  # 要迭代的陣列（必填）
    item_key: item                 # 每個元素注入的變數名，預設 item（選填）