Descrizione
Operatore di iterazione enterprise — il workhorse di tutte le pipeline batch del workflow business. Itera una collezione (array di oggetti, object con key=>value, string split per character/word/line) attraverso il ramo "body" del workflow editor, applicando per ogni item la stessa sequenza di azioni configurate downstream. Equivalente concettuale del `for-each` dei linguaggi di programmazione classici ma con cinque strategie di esecuzione configurabili per coprire spettro completo dei use case da 10 item a 10M item: (1) naive — 1-at-a-time sequenziale, semplice e prevedibile, default per dataset < 100 item dove la latency totale del workflow non è blocker e ogni step può essere debugged singolarmente; (2) batch — chunk di N item alla volta (es. 50 per batch), pattern bilanciato per dataset 1k-10k item dove il throughput è importante ma vogliamo ancora controllo granular dei chunks per error handling; (3) bulk — UNA singola call downstream con l'array intero come input, pattern critico quando il nodo downstream supporta operazioni bulk (es. action_email_send_tracked_batch, db_insert bulk) — riduce overhead di N invocazioni separate; (4) queue — processing asincrono via BullMQ (Redis/Dragonfly) per dataset > 10k item, attivo SE il worker BullMQ è in esecuzione (processo `flowforge worker`); se nessun worker è attaccato, il loop ricade automaticamente su naive (con log esplicito) — nessun dato perso, solo throughput ridotto; (5) aggregate — modalità riduzione senza body (no iteration steps), equivalente a passare l'array a logic_aggregate downstream senza per-item processing; (6) auto — l'engine FlowForge sceglie automaticamente la strategy migliore basata su array size + downstream node capabilities introspection. Scope expression per ogni iteration espone variabili context al body: {{loop.item}} (l'item corrente dell'iterazione), {{loop.index}} (0-based position), {{loop.total}} (size della collezione), {{loop.first}} (boolean true per il primo item, utile per email header decoration "Ciao {{name}}!" solo la prima volta), {{loop.last}} (boolean true per l'ultimo, per email footer "fine elenco"), {{loop.percentage}} (per progress reporting). Branch outputs del nodo per error handling: "done" (success aggregato — tutti gli iter completati senza error), "error" (almeno 1 iteration ha fallito — il caller può vedere quali in failedItems). Cap configurable maxIterations (default 10000) per safety anti-runaway. Use case: process batch ordini Stripe webhook ricevuti via paginate → loop con strategy=batch per gestire 500 ordini in batch 50; parse righe CSV/Excel uploaded → loop su rows dell'output xlsx_parse con strategy=naive per debug step-by-step; enrich N lead CRM con dati esterni via action_company_search + action_lead_score (strategy=batch 10 per gestire rate-limit upstream); multi-recipient email con personalization per ogni destinatario; bulk insert in DB di analytics events con strategy=bulk per one-shot db_insert atomic.