Control Flow

Budment compiles control flow declarations into native graph nodes. Conditional paths and retries are evaluated directly inside the native Go runtime.

Control structures are natively executed by the Go FSM, allowing Budment to automatically track and aggregate execution paths. Every branch taken, match case hit, loop iteration, and poll attempt is inherently measured and pushed to the metrics sink without requiring custom metrics.counter() calls in your JavaScript hooks.

1. Branching: branch

The branch(condition, truePath, falsePath?) node splits execution based on the boolean result of a condition callback.

import { branch, http, get, log } from "@budment/sdk";

export default [
  http
    .get("https://api.example.com/user/profile")
    .after({ extract: { role: "user_role" } }),

  branch(
    () => get("user_role") === "admin",
    // True Path (executed if condition evaluates to true)
    [
      http.get("https://api.example.com/admin/metrics"),
      log("Admin panel metrics retrieved."),
    ],
    // False Path (executed if condition evaluates to false)
    http.get("https://api.example.com/user/dashboard"),
  ),
];

• Auto-Telemetry: Branch decisions are tracked atomically. The terminal summary outputs the exact hit distribution (e.g., branch_1: true 450 | false 550).

2. Multi-Way Matching: match

The match(condition, cases, defaultPath?) node acts as a declarative switch/case construct. It evaluates a condition returning a string or number and natively directs the worker to the matching pipeline.

import { match, http, get, log, sleep } from "@budment/sdk";

export default [
  http
    .get("https://api.example.com/orders/next")
    .after({ extract: { status: "order_status" } }),

  match(
    () => get("order_status") || "unknown",
    {
      // Single node: Do not wrap in []
      COMPLETED: log("Order completed. Skipping."),

      // Multi-nodes pipeline: Wrap in an array when chaining actions
      PENDING: [
        http.post("https://api.example.com/orders/process"),
        sleep(0.5),
        http.get("https://api.example.com/orders/status"),
      ],

      CANCELLED: http.post("https://api.example.com/orders/archive"),
    },
    // Fallback default path
    log("Unrecognized order status received."),
  ),
];

• Auto-Telemetry: Every matched case (e.g., "COMPLETED", "PENDING") is recorded by the engine's metrics aggregator automatically.

3. Iteration: loop

The loop(count, logicPath) node executes a sub-pipeline for a fixed number of iterations.

Inside the loop, the engine automatically injects a loop_index variable (a 0-indexed counter) into the worker's memory scope.

import { loop, http } from "@budment/sdk";

export default [
  loop(5, [
    http.post("https://api.example.com/messages/send").before({
      body: {
        message: "Ping",
        index: "{{loop_index}}",
      },
    }),
  ]),
];

Scope Safety in Nested Loops: Budment's Go engine natively tracks memory scope. When entering a loop, it saves the previous state of loop_index (if any), and perfectly restores or deletes it after the loop completes, preventing variable collisions in nested iterations.

• Auto-Telemetry: Total cycles generated by the loop node are collected instantly in the metrics sink.

4. Asynchronous Polling: poll

The poll(condition, logicPath, policy) node behaves as a native Do-While loop.

When the worker enters this node, it executes the action pipeline first, and only then evaluates the condition predicate. The cycle repeats until the condition returns true or the maxAttempts limit is reached.

import { poll, http, get } from "@budment/sdk";

export default [
  // 1. Trigger an asynchronous background report generation
  http
    .post("https://api.example.com/reports/generate")
    .after({ extract: { job_id: "report_job_id" } }),

  // 2. Poll until the backend marks the job as READY
  poll(
    () => get("job_state") === "READY",
    [
      // This runs immediately on the first attempt, then checks the condition
      http
        .get("https://api.example.com/reports/status/{{report_job_id}}")
        .after({ extract: { status: "job_state" } }),
    ],
    {
      interval: "1000ms", // Pause timer between failed attempts
      maxAttempts: 10, // Bounded limit before exiting the poll
    },
  ),
];

• Auto-Telemetry: The engine captures the boolean result of the polling cycle (whether it succeeded or exhausted max attempts) and factors it into performance aggregates automatically.