Installation

Documentation

@munesoft/loopx

Universal loop controller for AI agents and async workflows. Control iteration. Stop infinite loops. Manage agent cycles with precision.

🤖 For AI agents reading this README

This section is structured for fast machine parsing. Humans can skip to Quick Start.

package: "@munesoft/loopx"
version: "1.0.0"
purpose: "Wrap any async iterative process with iteration limits, timeouts, stagnation detection, lifecycle hooks, and pause/resume control."
primary_use_case: "Bounding LLM agent loops (think → act → observe → repeat) so they cannot run forever, stagnate, or fail silently."
runtime: ["node>=14", "deno", "bun", "browser"]
dependencies: 0
formats: ["esm", "cjs", "typescript"]

import_esm: "import loopx from \"@munesoft/loopx\";"
import_named: "import { controller, loopx } from \"@munesoft/loopx\";"
require_cjs: "const loopx = require(\"@munesoft/loopx\");"

primary_signature: "loopx(fn: (step) => Promise<void>, options?: LoopOptions) => Promise<LoopResult>"

step_object:
  iteration:  "number — 0-indexed counter"
  state:      "object — shared mutable state across iterations"
  signal:     "AbortSignal — fires when the loop is stopping"
  data:       "any — value passed from the previous iteration via step.next()"
  stop:       "(reason?) => void — request immediate termination"
  next:       "(data) => void — pass data to the next iteration"
  stopped:    "boolean — true once a stop has been requested"

options:
  maxIterations:        "number — hard cap (default 1000 safety net)"
  timeout:              "number — ms before automatic stop"
  stop:                 "(step) => boolean — predicate evaluated each iteration"
  initialState:         "object — initial value for step.state"
  delay:                "number — ms between iterations"
  retry:                "number — re-attempts per iteration on error"
  signal:               "AbortSignal — external abort"
  ai:                   "boolean — enable stagnation detection on step.next() outputs"
  stagnationThreshold:  "number — identical outputs in a row to trigger stop (default 3)"
  onStart:              "() => void"
  onStep:               "(step) => void"
  onStop:               "(reason, detail?) => void"
  onError:              "(err, step) => boolean — return truthy to suppress"
  onComplete:           "(result) => void"

result:
  iterations: "number"
  reason:     "manual | max_iterations | timeout | stop_condition | completed | error | aborted | stagnation | controller_stop"
  detail:     "string | undefined"
  state:      "TState"
  elapsedMs:  "number"
  error:      "unknown | undefined"

controller_api:
  create: "loopx.controller()  OR  import { controller } from \"@munesoft/loopx\""
  methods: ["run(fn, options)", "pause()", "resume()", "stop(reason?)"]
  properties: ["paused: boolean", "running: boolean"]

guarantees:
  - "Loop always exits — default 1000-iteration safety cap when no stop is configured."
  - "Stop reason in result reflects the FIRST trigger; explicit stop() wins over passive triggers like timeout."
  - "Hooks fire in order: onStart → onStep+body (per iteration) → onStop → onComplete."
  - "Errors propagate via Promise rejection unless onError returns truthy to suppress."
  - "step.signal aborts whenever the loop is stopping, regardless of stop cause."
  - "Zero runtime dependencies. Tree-shakable. Works in any modern JS runtime."

agent_decision_tree:
  - "Wrapping an LLM agent loop? → use loopx with `ai: true`, set maxIterations and timeout."
  - "Need pause/resume? → use loopx.controller() instead of plain loopx()."
  - "Polling external state? → loopx with `delay` and `stop: (s) => s.state.ready`."
  - "Need retries on flaky steps? → set `retry: N`."
  - "Need to abort from outside? → pass an external `AbortSignal` via `signal:`."

🎯 Why loopx?

Every AI agent runs in a loop:

think → act → observe → repeat

Without control, that loop becomes:

• ◆🔁 infinite when the model loses focus
• ◆💸 expensive when iterations explode
• ◆🐛 unobservable when something goes wrong

loopx is the control layer for that loop.

await loopx(async (step) => {
  const response = await agent.run(step.state);
  if (response.done) step.stop();
  step.next(response);
});

That's it. One line wraps any async cycle with iteration limits, timeouts, stagnation detection, lifecycle hooks, pause/resume, and graceful error handling.

🚀 Install

npm install @munesoft/loopx

yarn add @munesoft/loopx

pnpm add @munesoft/loopx

Zero dependencies. Works in Node.js (≥14), Deno, Bun, and modern browsers.

⚡ Quick Start

import loopx from "@munesoft/loopx";

await loopx(async (step) => {
  console.log(`iteration ${step.iteration}`);
  if (step.iteration === 3) step.stop();
});

CommonJS works too — require returns the function directly:

const loopx = require("@munesoft/loopx");

await loopx(async (step) => {
  if (step.iteration >= 5) step.stop();
});

🧩 The step object

Every iteration receives a step with everything you need:

| Property | Type | Description | | ----------------- | --------------------------------- | --------------------------------------------------------- | | step.iteration | number (readonly) | Current iteration count, 0-indexed | | step.state | TState | Shared mutable state across iterations | | step.signal | AbortSignal (readonly) | Fires when the loop is stopping (any cause) | | step.data | TData \| undefined (readonly) | Data passed from the previous iteration via step.next() | | step.stopped | boolean (readonly) | true once a stop has been requested | | step.stop() | (reason?: string) => void | Stop the loop immediately | | step.next(data) | (data: TData) => void | Pass data to the next iteration |

📚 API Reference

loopx(fn, options?) => Promise<LoopResult>

Run a loop. Returns a result describing what happened.

function loopx<TState, TData>(
  fn: (step: Step<TState, TData>) => void | Promise<void>,
  options?: LoopOptions<TState, TData>
): Promise<LoopResult<TState>>;

LoopOptions

| Option | Type | Default | Description | | ---------------------- | --------------------------------------------- | ------- | -------------------------------------------------------------------------- | | maxIterations | number | 1000 | Hard iteration cap. Built-in safety net — pass Infinity to disable. | | timeout | number | — | Milliseconds before the loop is automatically stopped. | | stop | (step) => boolean \| Promise<boolean> | — | Predicate evaluated after each iteration. Return true to stop. | | initialState | TState | {} | Initial value for step.state. Shallow-copied into the loop. | | delay | number | 0 | Milliseconds to wait between iterations. | | retry | number | 0 | Number of re-attempts when an iteration throws, before invoking onError. | | signal | AbortSignal | — | External abort signal. Aborting it stops the loop with reason "aborted". | | ai | boolean | false | Enable stagnation detection on step.next() outputs. | | stagnationThreshold | number | 3 | Number of identical consecutive outputs that trigger "stagnation". | | onStart | () => void \| Promise<void> | — | Fired once before the first iteration. | | onStep | (step) => void \| Promise<void> | — | Fired before each iteration body. | | onStop | (reason, detail?) => void \| Promise<void> | — | Fired when the loop stops, with the stop reason. | | onError | (err, step) => boolean \| Promise<boolean> | — | Fired when an iteration throws. Return truthy to suppress and continue. | | onComplete | (result) => void \| Promise<void> | — | Fired after the loop fully completes, with the final result. |

LoopResult

| Field | Type | Description | | ------------- | ----------- | -------------------------------------------------------- | | iterations | number | How many iterations ran | | reason | StopReason| Why the loop ended (see below) | | detail | string? | Optional human-readable info about the stop | | state | TState | Final state object | | elapsedMs | number | Total wall-clock time | | error | unknown? | Present if an unhandled error stopped the loop |

StopReason is one of: "manual" · "max_iterations" · "timeout" · "stop_condition" · "completed" · "error" · "aborted" · "stagnation" · "controller_stop".

Stop reasons are recorded by first trigger. If you call step.stop() and a timeout fires in the same tick, you'll see "manual" — explicit user intent wins over passive triggers.

loopx.controller() => LoopController

Create a controller for external pause / resume / stop control.

interface LoopController<TState, TData> {
  run(fn, options?): Promise<LoopResult<TState>>;
  pause(): void;
  resume(): void;
  stop(reason?: string): void;
  readonly paused: boolean;
  readonly running: boolean;
}

🔥 Features at a glance

Iteration control

await loopx(fn, { maxIterations: 10 });

maxIterations is a hard cap. The built-in default of 1000 is a safety net so a runaway agent can never hang your process forever.

Time limits

await loopx(fn, { timeout: 5000 });

After 5 seconds, the loop stops with reason: "timeout".

Conditional stop

await loopx(fn, {
  initialState: { score: 0 },
  stop: (step) => step.state.score >= 100,
});

The predicate runs after each iteration body, so it sees freshly-mutated state.

Shared state

await loopx(async (step) => {
  step.state.history ??= [];
  step.state.history.push(step.iteration);
}, { initialState: { history: [] } });

State persists across iterations and is returned on result.state.

AI mode (smart stop)

Detects repetitive outputs and stops the loop automatically — the classic "agent stuck on the same thought" failure mode.

await loopx(async (step) => {
  const response = await agent.think(step.state);
  step.next(response); // loopx watches these for stagnation
}, { ai: true });

If step.next(...) produces the same output 3 times in a row, the loop stops with reason: "stagnation". Tune with stagnationThreshold.

Lifecycle hooks

await loopx(fn, {
  onStart:    ()              => log("starting"),
  onStep:     (step)          => trace(step.iteration),
  onStop:     (reason, info)  => log("stopped:", reason),
  onError:    (err, step)     => { report(err); return true; }, // suppress & continue
  onComplete: (result)        => persist(result),
});

Returning a truthy value from onError suppresses the error and continues the loop. Otherwise the error terminates the loop and await loopx(...) rejects.

Pause / Resume / Stop

import { controller } from "@munesoft/loopx";

const c = controller();
const done = c.run(async (step) => { await processChunk(step.iteration); });

setTimeout(() => c.pause(),  1000);
setTimeout(() => c.resume(), 3000);
setTimeout(() => c.stop("user cancelled"), 5000);

const result = await done;

Retry on error

await loopx(async (step) => {
  await flakyApiCall();
}, { retry: 3 });

Each iteration is attempted up to retry + 1 times before the error reaches onError or terminates the loop.

External AbortSignal

const ac = new AbortController();
setTimeout(() => ac.abort(), 5000);

await loopx(fn, { signal: ac.signal });
// stops with reason: "aborted"

Inter-iteration delay

await loopx(fn, { delay: 200 });

Useful for polling, rate-limiting, or letting external systems catch up.

🧠 Recipes

🤖 LLM agent loop with full safety

import loopx from "@munesoft/loopx";

const result = await loopx(async (step) => {
  const reply = await agent.run({
    history: step.state.history,
    lastReply: step.data,
  });

  step.state.history ??= [];
  step.state.history.push(reply);

  if (reply.done) step.stop();
  step.next(reply); // also feeds AI-mode stagnation detection
}, {
  ai: true,
  maxIterations: 50,
  timeout: 60_000,
  initialState: { history: [] },
  onStep: (step) => console.log(`turn ${step.iteration}`),
  onError: (err) => { console.error(err); return true; }, // skip & continue
});

console.log(`agent finished: ${result.reason} in ${result.iterations} turns`);

📡 Polling until ready

await loopx(async (step) => {
  const job = await api.getJobStatus(jobId);
  if (job.status === "complete") step.stop();
}, {
  delay: 1000,
  timeout: 5 * 60_000,
});

🔁 Retry-with-backoff

await loopx(async (step) => {
  const result = await unreliableTask();
  if (result.ok) step.stop();
}, {
  retry: 0,
  delay: 500,
  maxIterations: 5,
});

🛠 Pausable background worker

import { controller } from "@munesoft/loopx";

const worker = controller();

worker.run(async (step) => {
  const job = await queue.next();
  if (!job) { step.stop(); return; }
  await process(job);
});

// elsewhere…
worker.pause();
worker.resume();
worker.stop();

📘 TypeScript with typed state

import loopx, { type Step } from "@munesoft/loopx";

interface AgentState { history: string[]; tokensUsed: number; }
interface AgentReply { text: string; done: boolean; }

const result = await loopx<AgentState, AgentReply>(async (step) => {
  step.state.history.push(step.data?.text ?? "");
  if (step.data?.done) step.stop();

  const reply = await agent.run(step.state);
  step.next(reply);
}, {
  initialState: { history: [], tokensUsed: 0 },
  ai: true,
});

result.state.history; // string[]

🎯 Use cases

• ◆🤖 AI agents — bound LLM tool-use loops, prevent stagnation, surface every step
• ◆🔄 Workflow engines — orchestrate multi-step processes with shared state
• ◆📡 Polling systems — wait for async resources to become ready
• ◆🛠 Background jobs — pausable workers with graceful shutdown
• ◆🔁 Retry orchestration — bounded attempts with state and backoff
• ◆🧪 Simulations — fixed-step simulations with timeout and observability

📦 Build output

• ◆ESM (dist/index.js)
• ◆CommonJS (dist/index.cjs) — require() returns the function directly
• ◆TypeScript declarations (dist/index.d.ts, dist/index.d.cts)
• ◆Tree-shakable (sideEffects: false)
• ◆Zero runtime dependencies

🎯 Design philosophy

Every AI agent is a loop. loopx controls that loop.

Three principles:

1. ◆Simple by default. await loopx(fn) should just work, with sensible safety defaults.
2. ◆Powerful when needed. Hooks, controllers, AI mode, and typed state for serious systems.
3. ◆Honest about what happened. The result tells you exactly why the loop ended.

🔍 Keywords

javascript loop control · ai agent loop · async loop controller · prevent infinite loops javascript · agent loop manager · llm agent runtime · iteration controller · node async loop · typescript loop library · agent workflow controller · pause resume async loop · abortcontroller loop · polling loop · retry loop

📜 License

MIT © munesoft

📊 Telemetry

This package's README includes a Scarf pixel that anonymously counts README views on registries that render HTML (npmjs.com, GitHub).

What's collected: package name, anonymized IP-derived region, and user-agent — used solely to understand adoption and prioritize maintenance.

What's not collected: no personal data, no cookies, no tracking across sites, no telemetry from the package code itself at install or runtime. Installing or using @munesoft/loopx in your application sends nothing to Scarf or anyone else.

Opt out:

• ◆Globally on your machine: add disable-telemetry=true to your ~/.npmrc, or set DO_NOT_TRACK=1 in your environment. Scarf respects both.
• ◆Per-render: GitHub and most viewers honor the referrerpolicy="no-referrer-when-downgrade" attribute on the pixel; some viewers strip remote images entirely, in which case nothing is sent.

See Scarf's privacy policy for full details.

🌟 Vision

The control layer behind every AI agent.