Help flow looping until the end of the specified array for processing collections of data.

array-loop Block

The array-loop block helps flow looping until the end of the specified array.

Overview

The array-loop block is designed to iterate through arrays and process each element individually. It's essential for handling collections of data, making it perfect for batch processing, data transformation, and sequential operations on array elements.

Configuration Options

Array Configuration

Array Property: The message property containing the array to loop through
Array Source: Where to get the array from (message property, context, or expression)
Element Property: The message property to store the current array element
Index Property: The message property to store the current array index

Loop Behavior

Loop Direction: Forward (0 to length-1) or backward (length-1 to 0)
Skip Empty Arrays: Whether to skip processing if the array is empty
Handle Null Arrays: What to do if the array is null or undefined
Output Behavior: What to send on each iteration and when complete

How It Works

The array-loop block:

Receives Array: Gets the array from the specified message property
Validates Array: Checks if the array is valid and not empty
Iterates: Loops through each element in the array
Outputs: Sends a message for each element with the element and index
Completes: Sends a completion message when the loop finishes

Basic Array Loop Example

// Input message
{
    payload: {
        items: ["apple", "banana", "cherry"]
    }
}

// Configuration
Array Property: msg.payload.items
Element Property: msg.payload.currentItem
Index Property: msg.payload.currentIndex

// Output messages
{ payload: { currentItem: "apple", currentIndex: 0 } }
{ payload: { currentItem: "banana", currentIndex: 1 } }
{ payload: { currentItem: "cherry", currentIndex: 2 } }
{ payload: { complete: true, totalItems: 3 } }

Use Cases

Data Processing

Process each item in a dataset:

input → array-loop → process item → output

API Calls

Make API calls for each item:

array-loop → http request → process response → next item

File Processing

Process multiple files:

array-loop → read file → process → save → next file

Data Transformation

Transform each element in an array:

array-loop → transform → collect results → final output

Common Patterns

Simple Array Processing

// Configuration
Array Property: msg.payload.users
Element Property: msg.payload.user
Index Property: msg.payload.userIndex

// Process each user
array-loop → validate user → save user → next user

Conditional Processing

// Configuration
Array Property: msg.payload.orders
Element Property: msg.payload.order
Index Property: msg.payload.orderIndex

// Process orders conditionally
array-loop → switch (order type) → different processing → next order

Nested Array Processing

// Configuration
Array Property: msg.payload.categories
Element Property: msg.payload.category
Index Property: msg.payload.categoryIndex

// Process categories and their items
array-loop → process category → array-loop (items) → process item → next category

Advanced Features

Dynamic Array Sources

Get arrays from different sources:

// From message property
Array Property: msg.payload.data

// From context
Array Property: flow.get("dataArray")

// From expression
Array Property: msg.payload.results.filter(item => item.active)

Array Validation

Handle various array scenarios:

// Skip empty arrays
if (array.length === 0) {
  return { payload: { complete: true, message: "No items to process" } };
}

// Handle null arrays
if (!array) {
  return { payload: { error: "Array is null or undefined" } };
}

Custom Indexing

Use custom index values:

// Start from 1 instead of 0
Index Property: msg.payload.itemNumber
Index Value: currentIndex + 1

// Use custom identifiers
Index Property: msg.payload.itemId
Index Value: array[currentIndex].id

Tips

Validate Arrays: Always check if the array exists and is not empty
Handle Edge Cases: Consider what happens with null, undefined, or empty arrays
Use Meaningful Properties: Store elements and indices in descriptive message properties
Consider Performance: Be mindful of array size and processing time
Test with Different Arrays: Verify behavior with various array types and sizes
Monitor Memory: Watch for memory usage with large arrays

Common Issues

Null or Undefined Arrays

Handle cases where the array doesn't exist:

// BAD: This will fail
Array Property: msg.payload.items
// If msg.payload.items is null

// GOOD: Add validation
if (!msg.payload.items || !Array.isArray(msg.payload.items)) {
    return { payload: { error: "Invalid array" } };
}

Empty Arrays

Decide how to handle empty arrays:

// BAD: Processing empty array
Array Property: msg.payload.items
// If msg.payload.items is []

// GOOD: Check for empty arrays
if (msg.payload.items.length === 0) {
    return { payload: { complete: true, message: "No items to process" } };
}

Large Arrays

Be careful with very large arrays:

// BAD: Very large array
Array Property: msg.payload.hugeArray
// If hugeArray has millions of items

// GOOD: Process in batches
Array Property: msg.payload.batch
// Process smaller batches

counter-loop - For fixed-count loops
while-loop - For conditional loops
split - For splitting data into arrays
join - For combining processed results

array-loop

On this page