Fluent Batcher

When building loop-heavy scripts, background workers, or autonomous AI agents that run multiple reasoning steps, calling log() individually on every step introduces network overhead.

To solve this, Volidator provides the Fluent Batcher client helper. It lets you push logs to an in-memory queue that automatically flushes and posts batches (using logBatch()) based on count or timing.

---

Basic Integration

Get a batcher instance from your initialized VolidatorClient:

import { volidator } from "@/lib/volidator";

// 1. Initialize the batcher
const batcher = volidator.batcher({
  autoFlushCount: 50,      // Automatically flush and ingest when queue reaches 50 logs
  autoFlushInterval: 5000, // Or automatically flush every 5 seconds (Node-only, see warning)
});

// 2. Queue logs in your application loop
for (const step of agentExecutionSteps) {
  batcher.push({
    actor: "writer-agent-v1",
    action: "agent.thought",
    metadata: { step: step.number, text: step.description }
  });
}

// 3. Always manually flush at the end of the script or request path!
await batcher.flush();

---

Batcher Configuration Options

Option	Type	Default	Description
autoFlushCount	number	50	The number of logs to queue before automatically flushing. Max recommended size is 100 per batch.
autoFlushInterval	number	—	The interval in milliseconds to wait before flushing queued logs. Only active if specified.

---

⚠️ Critical Serverless & Edge Warning

In serverless and Edge environments (such as Cloudflare Workers, Next.js Edge, and Vercel Edge Functions), the V8 runtime isolate is frozen or destroyed as soon as the HTTP response is delivered to the client.

• The Problem: The autoFlushInterval option relies on setInterval in the background. In serverless environments, this background timer will be paused, causing queued logs to be lost.
• The Solution: In serverless or edge environments, never rely on autoFlushInterval. You must either:
  1. Manually call await batcher.flush() at the end of your handler’s execution path.
  2. Or pass the flush promise to your runtime’s wait-until lifecycle method to execute in the background:

     // Next.js middleware / Cloudflare Workers
     context.waitUntil(batcher.flush());

---

Error Handling

If log preparation or delivery fails during an automatic flush, the batcher will print errors to console.error. If you want custom failure behaviors, handle them via your client’s constructor onDeliveryFailure callback.