Loop Action Guide

The loop action is the core component for implementing repetitive execution logic in task scripts. It supports not only traditional array iteration and conditional loops but also event-driven web page monitoring loops.

1. Basic Structure

The basic JSON structure of the loop action is as follows:

{
  "action": "loop",
  "description": "Description of the loop",
  "steps": [ ... ],       // (Required) Array of steps to execute within the loop
  "items": [ ... ],       // (Optional) Data source to iterate over
  "loopVar": "item",      // (Optional) Variable name for the current item
  "while": "...",         // (Optional) Condition expression for the loop to continue
  "loopWait": 1000,       // (Optional) Wait time after each iteration (ms)
  "monitor": { ... }      // (Optional) Web page monitoring configuration
}

---

2. Loop Modes

2.1 Iterate over Items

Suitable for processing a known list of data (e.g., a product list obtained from scrape).

• items: Specifies the array to iterate over. Usually references a variable in state, such as {{state.products}}.
• loopVar: Defines the variable name for the current item. Inside the loop body, you can access the current item's data via {{state.loopVar}}.

Example:

{
  "action": "loop",
  "description": "Iterate through scraped product links and visit",
  "items": "{{state.products}}",
  "loopVar": "product",
  "steps": [
    {
      "action": "openTab",
      "url": "{{state.product.link}}"
    },
    {
      "action": "scrape",
      "description": "Scrape details",
      "outputVar": "details",
      "schema": { ... }
    },
    {
      "action": "closeTab"
    }
  ]
}

2.2 Conditional Loop

Suitable for scenarios where the number of iterations is unknown and the loop stops only when a specific condition is met (e.g., pagination, retry waiting).

• while: A JavaScript boolean expression. Evaluated before each iteration; if true, execution continues; if false, the loop exits.

Example:

{
  "action": "loop",
  "description": "Loop through pages until there is no next page",
  "while": "state.hasNextPage === true",
  "steps": [
    {
      "action": "scrape",
      "outputVar": "currentPageData",
      "schema": { ... }
    },
    {
      "action": "click",
      "description": "Click next page",
      "selector": ".next-button",
      "onError": "continue" // If the next button is not found, it might mean the last page is reached
    },
    {
      "action": "evaluate",
      "script": "state.hasNextPage = document.querySelector('.next-button') !== null;"
    }
  ]
}

---

3. Advanced Features

3.1 Loop Wait

Setting loopWait enforces a wait for a specified time (milliseconds) after each iteration. This is very useful for avoiding anti-scraping limits triggered by operating too fast.

• Feature: The wait executes regardless of whether the steps inside the loop succeed or fail (provided it is in onError: continue mode).

{
  "action": "loop",
  "items": "{{state.urls}}",
  "loopWait": 2000, // Wait 2 seconds after processing each URL
  "steps": [ ... ]
}

3.2 Web Page Monitoring

When the monitor property is configured, loop no longer executes in a fixed flow but enters an event-driven mode.

• Trigger Mechanism: The loop suspends until DOM changes occur on the specified URL page.
• Use Case: Real-time monitoring of orders, messages, or stock changes.

For detailed configuration, please refer to the Web Page Monitoring Documentation.

Simple Example:

{
  "action": "loop",
  "monitor": {
    "url": "https://example.com/orders",
    "debounce": 1000
  },
  "while": "state.monitoring !== false", // Optional manual stop condition
  "steps": [
    {
      "action": "print",
      "message": "Page updated, starting processing..."
    }
    // ...processing logic
  ]
}

---

4. FAQ

Q: Can items and while be used together?

A: Yes. If both are specified, the loop stops when iteration of items completes OR when the while condition becomes false (whichever happens first).

Q: How do I break out of a loop early?

A: There is currently no direct break action. You can achieve this by:

1. Using while condition control: Modify a condition variable inside the loop (e.g., state.shouldStop = true).
2. Using the fail action: Be careful, as this may terminate the entire task if not configured properly.

Q: What is the variable scope inside the loop?

A: All state variables are global. loopVar is overwritten and updated with each iteration. If you need to accumulate data inside the loop, use the evaluate action to modify a global array or object.