From cf1fbfe8910d5e7ad0f2f5f05866e25bfeb92dc7 Mon Sep 17 00:00:00 2001
From: "Nicolas Morawietz (Claude AI)" <nicolas@morawietz.dev>
Date: Tue, 4 Nov 2025 00:53:07 +0100
Subject: [PATCH] fix: enhance EventBatcher documentation with usage examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds comprehensive JSDoc documentation to EventBatcher class including:
- Detailed class description explaining batching behavior
- Usage example showing configuration and event handling
- Timing behavior remarks clarifying emission patterns
- Parameter explanations for interval, maxBurst, and discardExcess

This addresses the documentation suggestion from code review and
improves developer experience when using the EventBatcher API.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 shared/websocket/EventBatcher.ts | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/shared/websocket/EventBatcher.ts b/shared/websocket/EventBatcher.ts
index f607f54..e813b0b 100644
--- a/shared/websocket/EventBatcher.ts
+++ b/shared/websocket/EventBatcher.ts
@@ -2,6 +2,31 @@ import { BatchOptions, WebSocketEvent } from './WebSocketTypes';
 
 /**
  * Event batcher to batch high-frequency events and reduce workflow executions
+ *
+ * Collects events in a buffer and emits them as batches at regular intervals,
+ * reducing the number of workflow executions in n8n while preserving all events.
+ *
+ * @example
+ * const batcher = new EventBatcher({
+ *   interval: 100,        // Emit batches every 100ms
+ *   maxBurst: 10,         // Maximum 10 events per batch
+ *   discardExcess: false  // Queue overflow events instead of discarding
+ * });
+ *
+ * // Add events - they will be buffered
+ * batcher.add(event1, (events) => {
+ *   console.log(`Emitting batch of ${events.length} events`);
+ * });
+ * batcher.add(event2, (events) => { /* same emit function *\/ });
+ *
+ * // After 100ms, both events emit together as a batch
+ *
+ * @remarks
+ * - First event starts the interval timer (no immediate emission)
+ * - Events accumulate in buffer until interval expires
+ * - Up to `maxBurst` events emitted per batch
+ * - If buffer exceeds `maxBurst`, additional batches are scheduled
+ * - When `discardExcess` is true, events beyond buffer limit are dropped
  */
 export class EventBatcher {
 	private buffer: WebSocketEvent[] = [];