queen-mq 0.3.1 → 0.4.0

package/client-js/client/client.js

@@ -1,1536 +0,0 @@
-import { createHttpClient, createLoadBalancedHttpClient } from './utils/http.js';
-import { withRetry } from './utils/retry.js';
-import { createLoadBalancer, LoadBalancingStrategy } from './utils/loadBalancer.js';
-import { generateUUID } from '../utils/uuid.js';
-
-/**
- * Minimalist Queen Message Queue Client
- * 
- * Simple, powerful API with just 4 methods:
- * - queue: Configure a queue
- * - push: Send messages
- * - take: Receive messages (async iterator)
- * - ack: Acknowledge messages
- */
-export class Queen {
-  #config;
-  #http;
-  #loadBalancer;
-  #connected = false;
-  #bufferManager;
-  
-  constructor(config = {}) {
-    this.#config = {
-      baseUrls: null,
-      loadBalancingStrategy: LoadBalancingStrategy.ROUND_ROBIN,
-      enableFailover: true,
-      timeout: 30000,
-      retryAttempts: 3,
-      retryDelay: 1000,
-      ...config
-    };
-    this.#bufferManager = new BufferManager(this);
-  }
-  
-  /**
-   * Ensure HTTP client is connected
-   */
-  async #ensureConnected() {
-    if (this.#connected) return;
-    
-    const { baseUrl, baseUrls, loadBalancingStrategy, enableFailover, timeout } = this.#config;
-    
-    if (baseUrls && Array.isArray(baseUrls) && baseUrls.length > 0) {
-      // Multiple servers with load balancing
-      this.#loadBalancer = createLoadBalancer(baseUrls, loadBalancingStrategy);
-      this.#http = createLoadBalancedHttpClient({ 
-        baseUrls, 
-        loadBalancer: this.#loadBalancer, 
-        timeout,
-        enableFailover 
-      });
-    } else {
-      // Single server
-      const singleUrl = baseUrls && baseUrls.length === 1 ? baseUrls[0] : baseUrl;
-      this.#http = createHttpClient({ baseUrl: singleUrl, timeout });
-    }
-    
-    this.#connected = true;
-  }
-  
-  /**
-   * Validate if a string is a valid UUID v4
-   */
-  #isValidUUID(str) {
-    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-    return uuidRegex.test(str);
-  }
-  
-  /**
-   * Parse address string into components
-   * Examples:
-   * - "myqueue" -> { queue: "myqueue" }
-   * - "myqueue/urgent" -> { queue: "myqueue", partition: "urgent" }
-   * - "myqueue@workers" -> { queue: "myqueue", consumerGroup: "workers" }
-   * - "myqueue/urgent@workers" -> { queue: "myqueue", partition: "urgent", consumerGroup: "workers" }
-   * - "namespace:billing" -> { namespace: "billing" }
-   * - "task:process" -> { task: "process" }
-   * - "namespace:billing/task:process" -> { namespace: "billing", task: "process" }
-   */
-  #parseAddress(address) {
-    // Check for namespace/task pattern
-    if (address.includes('namespace:') || address.includes('task:')) {
-      const parts = {};
-      
-      // Extract consumer group if present (after @)
-      let workingAddress = address;
-      const atIndex = address.lastIndexOf('@');
-      if (atIndex > 0) {
-        parts.consumerGroup = address.substring(atIndex + 1);
-        workingAddress = address.substring(0, atIndex);
-      }
-      
-      const segments = workingAddress.split('/');
-      
-      for (const segment of segments) {
-        if (segment.startsWith('namespace:')) {
-          parts.namespace = segment.substring(10);
-        } else if (segment.startsWith('task:')) {
-          parts.task = segment.substring(5);
-        }
-      }
-      
-      return parts;
-    }
-    
-    // Standard queue[/partition][@group] pattern
-    const match = address.match(/^([^/@]+)(?:\/([^@]+))?(?:@(.+))?$/);
-    if (!match) {
-      throw new Error(`Invalid address format: ${address}`);
-    }
-    
-    return {
-      queue: match[1],
-      partition: match[2] || 'Default',
-      consumerGroup: match[3] || null
-    };
-  }
-  
-  /**
-   * Configure a queue with options
-   * @param {string} name - Queue name
-   * @param {Object} options - Queue configuration options
-   * @param {Object} metadata - Optional metadata { namespace, task }
-   */
-  async queue(name, options = {}, metadata = {}) {
-    await this.#ensureConnected();
-    
-    const { namespace, task } = metadata;
-    
-    const result = await withRetry(
-      () => this.#http.post('/api/v1/configure', { 
-        queue: name,
-        namespace: namespace || null,
-        task: task || null,
-        options 
-      }),
-      this.#config.retryAttempts,
-      this.#config.retryDelay
-    );
-    
-    if (result && result.error) {
-      throw new Error(result.error);
-    }
-    
-    return result;
-  }
-  
-  /**
-   * Push messages to a queue
-   * @param {string} address - Queue address (e.g., "myqueue" or "myqueue/partition")
-   * @param {Object|Array} payload - Single message or array of messages
-   * @param {Object} options - Optional message properties { transactionId, traceId, buffer }
-   */
-  async push(address, payload, options = {}) {
-    await this.#ensureConnected();
-    
-    const { queue, partition } = this.#parseAddress(address);
-    
-    // Handle both single and array inputs
-    const items = Array.isArray(payload) ? payload : [payload];
-    
-    // Format items for the API
-    const formattedItems = items.map(item => {
-      // If item is an object with special properties, extract them
-      const isMessageObject = typeof item === 'object' && item !== null &&
-        (item._payload || item._transactionId || item._traceId);
-      
-      if (isMessageObject) {
-        const result = {
-          queue,
-          partition,
-          payload: item._payload || item,
-          transactionId: item._transactionId || item.transactionId || generateUUID()  // Always generate if missing
-        };
-        
-        // Include traceId if provided and valid UUID
-        const traceId = item._traceId || item.traceId;
-        if (traceId && this.#isValidUUID(traceId)) {
-          result.traceId = traceId;
-        }
-        
-        return result;
-      }
-      
-      // Otherwise use the item as payload and apply options
-      const result = {
-        queue,
-        partition,
-        payload: item,
-        transactionId: options.transactionId || 
-                      (item && typeof item === 'object' ? item.transactionId : undefined) ||
-                      generateUUID()  // Always generate if missing
-      };
-      
-      // Include traceId if provided and valid UUID
-      const traceId = options.traceId || (item && typeof item === 'object' ? item.traceId : undefined);
-      if (traceId && this.#isValidUUID(traceId)) {
-        result.traceId = traceId;
-      }
-      
-      return result;
-    });
-    
-    // Check if client-side buffering is enabled
-    if (options.buffer && typeof options.buffer === 'object') {
-      return this.#pushBuffered(address, formattedItems, options.buffer);
-    }
-    
-    // Build request body for immediate push
-    const requestBody = { items: formattedItems };
-    
-    // Add server-side buffering flag if specified
-    if (options.buffer === true || options.qos0 === true) {
-      requestBody.qos0 = true;  // Server still uses 'qos0' internally
-    }
-    
-    // Legacy support: bufferMs/bufferMax are aliases for buffer
-    if (options.bufferMs !== undefined || options.bufferMax !== undefined) {
-      requestBody.qos0 = true;
-    }
-    
-    const result = await withRetry(
-      () => this.#http.post('/api/v1/push', requestBody),
-      this.#config.retryAttempts,
-      this.#config.retryDelay
-    );
-    
-    if (result && result.error) {
-      throw new Error(result.error);
-    }
-    
-    return result;
-  }
-  
-  /**
-   * Push messages using client-side buffering
-   * @private
-   */
-  #pushBuffered(address, formattedItems, bufferOptions) {
-    // Validate buffer options
-    if (!bufferOptions.size || !bufferOptions.time) {
-      throw new Error('Buffer options must include both size and time');
-    }
-    
-    // Add each formatted message to the buffer
-    for (const item of formattedItems) {
-      this.#bufferManager.addMessage(address, item, bufferOptions);
-    }
-    
-    // Return immediately (non-blocking)
-    return { buffered: true, count: formattedItems.length };
-  }
-  
-  /**
-   * Internal method that yields batches of messages (arrays)
-   * @private
-   * @param {string} address - Queue address
-   * @param {Object} options - Options for taking messages
-   * @yields {Array} Arrays of message objects
-   */
-  async *#takeInternal(address, options = {}) {
-    await this.#ensureConnected();
-    
-    const { queue, partition, consumerGroup, namespace, task } = this.#parseAddress(address);
-    const { 
-      limit = null,
-      batch = 1, 
-      wait = false, 
-      timeout = 30000,
-      subscriptionMode = null,
-      subscriptionFrom = null,
-      idleTimeout = null
-    } = options;
-    
-    let totalCount = 0;
-    let consecutiveEmptyResponses = 0;
-    let consecutiveNetworkErrors = 0;
-    const maxConsecutiveEmpty = 3;
-    let lastMessageTime = idleTimeout ? Date.now() : null;
-    
-    while (true) {
-      // Check if we've reached the limit
-      if (limit && totalCount >= limit) break;
-      
-      // Check idle timeout
-      if (idleTimeout && lastMessageTime) {
-        const idleTime = Date.now() - lastMessageTime;
-        if (idleTime >= idleTimeout) {
-          break; // Exit if idle time exceeded
-        }
-      }
-      
-      // Calculate batch size respecting the limit
-      const effectiveBatch = limit ? Math.min(batch, limit - totalCount) : batch;
-      
-      // Build the request path and parameters
-      let path;
-      const params = new URLSearchParams({
-        wait: wait.toString(),
-        timeout: timeout.toString(),
-        batch: effectiveBatch.toString()
-      });
-      
-      // Add consumer group parameters if provided
-      if (consumerGroup) params.append('consumerGroup', consumerGroup);
-      if (subscriptionMode) params.append('subscriptionMode', subscriptionMode);
-      if (subscriptionFrom) params.append('subscriptionFrom', subscriptionFrom);
-      
-      // Add auto-ack option if specified
-      if (options.autoAck) params.append('autoAck', 'true');
-      
-      // Determine the endpoint based on parameters
-      if (queue) {
-        if (partition && partition !== 'Default') {
-          path = `/api/v1/pop/queue/${queue}/partition/${partition}`;
-        } else {
-          path = `/api/v1/pop/queue/${queue}`;
-        }
-      } else if (namespace || task) {
-        // Pop by namespace/task
-        path = '/api/v1/pop';
-        if (namespace) params.append('namespace', namespace);
-        if (task) params.append('task', task);
-      } else {
-        throw new Error('Must specify either queue, namespace, or task');
-      }
-      
-      try {
-        // For long polling, use a slightly longer client timeout
-        const clientTimeout = wait ? timeout + 5000 : timeout;
-        
-        const result = await this.#http.get(`${path}?${params}`, clientTimeout);
-        
-        // Handle empty response
-        if (!result || !result.messages || result.messages.length === 0) {
-          if (wait) {
-            // For long polling, immediately retry
-            continue;
-          } else {
-            // For non-waiting mode, stop after several empty responses
-            consecutiveEmptyResponses++;
-            if (consecutiveEmptyResponses >= maxConsecutiveEmpty) {
-              break;
-            }
-            // Small delay before retry
-            await new Promise(resolve => setTimeout(resolve, 100));
-            continue;
-          }
-        }
-        
-        // Reset counters on successful fetch
-        consecutiveEmptyResponses = 0;
-        consecutiveNetworkErrors = 0;
-        
-        // Update last message time if tracking idle timeout
-        if (idleTimeout) {
-          lastMessageTime = Date.now();
-        }
-        
-        // Filter out null/undefined messages
-        const messages = result.messages.filter(msg => msg != null);
-        
-        if (messages.length > 0) {
-          totalCount += messages.length;
-          yield messages;
-          
-          // If we've hit the limit, stop
-          if (limit && totalCount >= limit) {
-            break;
-          }
-        }
-        
-      } catch (error) {
-        // Check if this is a timeout error (expected for long polling)
-        const isTimeoutError = error.name === 'AbortError' || 
-                              error.message?.includes('abort') ||
-                              error.message?.includes('timeout');
-        
-        if (isTimeoutError && wait) {
-          // For long polling timeout, immediately retry
-          continue;
-        }
-        
-        // Check if this is a network error (connection refused, socket closed, etc.)
-        const isNetworkError = error.message?.includes('fetch failed') ||
-                              error.message?.includes('ECONNREFUSED') ||
-                              error.message?.includes('ECONNRESET') ||
-                              error.message?.includes('closed') ||
-                              error.cause?.code === 'UND_ERR_SOCKET' ||
-                              error.code === 'ECONNREFUSED' ||
-                              error.code === 'ECONNRESET';
-        
-        if (isNetworkError) {
-          // Log the network error
-          console.warn(`Network error while polling queue: ${error.message}`);
-          
-          // Retry with exponential backoff (capped at 30 seconds)
-          const retryDelay = Math.min(this.#config.retryDelay * Math.pow(2, Math.min(consecutiveNetworkErrors, 10)), 30000);
-          console.warn(`Retrying in ${retryDelay}ms... (attempt ${consecutiveNetworkErrors + 1})`);
-          await new Promise(resolve => setTimeout(resolve, retryDelay));
-          
-          consecutiveNetworkErrors++;
-          
-          // Continue retrying indefinitely
-          continue;
-        }
-        
-        // For other errors, throw
-        throw error;
-      }
-    }
-  }
-  
-  /**
-   * Take messages from a queue one at a time (async iterator)
-   * @param {string} address - Queue address (e.g., "myqueue", "myqueue/partition", "myqueue@group")
-   * @param {Object} options - Options for taking messages
-   * @yields {Object} Individual message objects
-   */
-  async *take(address, options = {}) {
-    let count = 0;
-    const { limit = null } = options;
-    
-    for await (const messages of this.#takeInternal(address, options)) {
-      for (const message of messages) {
-        yield message;
-        count++;
-        
-        // Double-check limit (internal method also checks, but this ensures exact limit)
-        if (limit && count >= limit) {
-          return;
-        }
-      }
-    }
-  }
-  
-  /**
-   * Take messages from a queue in batches (async iterator)
-   * @param {string} address - Queue address (e.g., "myqueue", "myqueue/partition", "myqueue@group")
-   * @param {Object} options - Options for taking messages
-   * @yields {Array} Arrays of message objects
-   */
-  async *takeBatch(address, options = {}) {
-    for await (const messages of this.#takeInternal(address, options)) {
-      // Only yield non-empty batches
-      if (messages && messages.length > 0) {
-        yield messages;
-      }
-    }
-  }
-  
-  /**
-   * Take a single batch of messages (convenience method)
-   * @param {string} address - Queue address
-   * @param {Object} options - Options for taking messages
-   * @returns {Promise<Array>} Array of messages
-   */
-  async takeSingleBatch(address, options = {}) {
-    const messages = [];
-    for await (const batch of this.takeBatch(address, options)) {
-      messages.push(...batch);
-      break; // Take only one batch
-    }
-    return messages;
-  }
-  
-  /**
-   * Renew lease for a message or batch of messages
-   * @param {Object|Array|string} messageOrLeaseId - Message object(s) or lease ID(s)
-   * @returns {Promise<Object>} Renewal result
-   */
-  async renewLease(messageOrLeaseId) {
-    await this.#ensureConnected();
-    
-    // Handle different input types
-    let leaseIds = [];
-    
-    if (typeof messageOrLeaseId === 'string') {
-      // Direct lease ID
-      leaseIds = [messageOrLeaseId];
-    } else if (Array.isArray(messageOrLeaseId)) {
-      // Array of messages or lease IDs
-      leaseIds = messageOrLeaseId.map(item => 
-        typeof item === 'string' ? item : item.leaseId
-      ).filter(Boolean);
-    } else if (messageOrLeaseId && typeof messageOrLeaseId === 'object') {
-      // Single message object
-      if (messageOrLeaseId.leaseId) {
-        leaseIds = [messageOrLeaseId.leaseId];
-      }
-    }
-    
-    if (leaseIds.length === 0) {
-      throw new Error('No valid lease IDs found for renewal');
-    }
-    
-    // Renew all leases
-    const results = [];
-    for (const leaseId of leaseIds) {
-      try {
-        const result = await withRetry(
-          () => this.#http.post(`/api/v1/lease/${leaseId}/extend`, {}),
-          this.#config.retryAttempts,
-          this.#config.retryDelay
-        );
-        results.push({ 
-          leaseId, 
-          success: true, 
-          newExpiresAt: result.leaseId ? result.newExpiresAt : result.lease_expires_at 
-        });
-      } catch (error) {
-        results.push({ leaseId, success: false, error: error.message });
-      }
-    }
-    
-    // Return single result for single input, array for array input
-    return Array.isArray(messageOrLeaseId) ? results : results[0];
-  }
-  
-  /**
-   * Acknowledge a message or batch of messages
-   * @param {Object|string|Array} message - Message object, transaction ID, or array of messages
-   * @param {boolean|string} status - true for success, false for failure, or 'retry'
-   * @param {Object} context - Optional context (e.g., { group: 'workers', error: 'reason' })
-   */
-  async ack(message, status = true, context = {}) {
-    await this.#ensureConnected();
-    
-    // Handle batch acknowledgment
-    if (Array.isArray(message)) {
-      if (message.length === 0) {
-        return { processed: 0, results: [] };
-      }
-      
-      // Check if messages have individual status (Option B pattern)
-      const hasIndividualStatus = message.some(msg => 
-        typeof msg === 'object' && msg !== null && ('_status' in msg || '_error' in msg)
-      );
-      
-      let acknowledgments;
-      
-      if (hasIndividualStatus) {
-        // Option B: Each message has its own status
-        acknowledgments = message.map(msg => {
-          // Extract transaction ID, partition ID, and lease ID
-          let transactionId;
-          let partitionId = null;
-          let leaseId = null;
-          
-          if (typeof msg === 'string') {
-            transactionId = msg;
-          } else if (typeof msg === 'object' && msg !== null) {
-            transactionId = msg.transactionId || msg.id;
-            partitionId = msg.partitionId || null;
-            leaseId = msg.leaseId || null;
-            if (!transactionId) {
-              throw new Error('Message object must have transactionId or id property');
-            }
-          } else {
-            throw new Error('Invalid message in batch');
-          }
-          
-          // Get individual status or fall back to parameter
-          let msgStatus = msg._status !== undefined ? msg._status : status;
-          let statusStr;
-          if (typeof msgStatus === 'boolean') {
-            statusStr = msgStatus ? 'completed' : 'failed';
-          } else {
-            statusStr = msgStatus;
-          }
-          
-          const ack = {
-            transactionId,
-            status: statusStr,
-            error: msg._error || context.error || null
-          };
-          
-          // Include partition ID if available
-          if (partitionId) {
-            ack.partitionId = partitionId;
-          }
-          
-          // Include lease ID if available
-          if (leaseId) {
-            ack.leaseId = leaseId;
-          }
-          
-          return ack;
-        });
-      } else {
-        // Option A: Same status for all messages
-        const statusStr = typeof status === 'boolean' 
-          ? (status ? 'completed' : 'failed')
-          : status;
-        
-        acknowledgments = message.map(msg => {
-          // Extract transaction ID, partition ID, and lease ID
-          let transactionId;
-          let partitionId = null;
-          let leaseId = null;
-          
-          if (typeof msg === 'string') {
-            transactionId = msg;
-          } else if (typeof msg === 'object' && msg !== null) {
-            transactionId = msg.transactionId || msg.id;
-            partitionId = msg.partitionId || null;
-            leaseId = msg.leaseId || null;
-            if (!transactionId) {
-              throw new Error('Message object must have transactionId or id property');
-            }
-          } else {
-            throw new Error('Invalid message in batch');
-          }
-          
-          const ack = {
-            transactionId,
-            status: statusStr,
-            error: context.error || null
-          };
-          
-          // Include partition ID if available
-          if (partitionId) {
-            ack.partitionId = partitionId;
-          }
-          
-          // Include lease ID if available
-          if (leaseId) {
-            ack.leaseId = leaseId;
-          }
-          
-          return ack;
-        });
-      }
-      
-      // Call batch ack endpoint
-      const result = await withRetry(
-        () => this.#http.post('/api/v1/ack/batch', { 
-          acknowledgments,
-          consumerGroup: context.group || null
-        }),
-        this.#config.retryAttempts,
-        this.#config.retryDelay
-      );
-      
-      if (result && result.error) {
-        throw new Error(result.error);
-      }
-      
-      return result;
-    }
-    
-    // Handle single message acknowledgment
-    // Extract transaction ID, partition ID, and lease ID
-    let transactionId;
-    let partitionId = null;
-    let leaseId = null;
-    
-    if (typeof message === 'string') {
-      transactionId = message;
-    } else if (typeof message === 'object' && message !== null) {
-      transactionId = message.transactionId || message.id;
-      partitionId = message.partitionId || null;  // Extract partition ID for partition-scoped ACK
-      leaseId = message.leaseId || null;  // Extract lease ID if present
-      if (!transactionId) {
-        throw new Error('Message object must have transactionId or id property');
-      }
-    } else {
-      throw new Error('Message must be a string (transaction ID) or object with transactionId');
-    }
-    
-    // Determine status string
-    let statusStr;
-    if (typeof status === 'boolean') {
-      statusStr = status ? 'completed' : 'failed';
-    } else {
-      statusStr = status; // Allow custom status like 'retry'
-    }
-    
-    // Build request body
-    const body = {
-      transactionId,
-      status: statusStr,
-      error: context.error || null,
-      consumerGroup: context.group || null
-    };
-    
-    // Include partition ID if available for partition-scoped operations
-    if (partitionId) {
-      body.partitionId = partitionId;
-    }
-    
-    // Include lease ID if available for lease validation
-    if (leaseId) {
-      body.leaseId = leaseId;
-    }
-    
-    const result = await withRetry(
-      () => this.#http.post('/api/v1/ack', body),
-      this.#config.retryAttempts,
-      this.#config.retryDelay
-    );
-    
-    if (result && result.error) {
-      throw new Error(result.error);
-    }
-    
-    return result;
-  }
-  
-  /**
-   * Delete a queue (removes queue and all its messages/partitions)
-   * @param {string} name - Queue name to delete
-   * @returns {Promise<Object>} Deletion result
-   */
-  async queueDelete(name) {
-    await this.#ensureConnected();
-    
-    if (typeof name !== 'string' || !name) {
-      throw new Error('Queue name must be a non-empty string');
-    }
-    
-    const result = await withRetry(
-      () => this.#http.delete(`/api/v1/resources/queues/${encodeURIComponent(name)}`),
-      this.#config.retryAttempts,
-      this.#config.retryDelay
-    );
-    
-    if (result && result.error) {
-      throw new Error(result.error);
-    }
-    
-    return result;
-  }
-  
-  /**
-   * Manually flush a specific buffer
-   * @param {string} address - Queue address to flush
-   * @returns {Promise<void>}
-   */
-  async flushBuffer(address) {
-    return this.#bufferManager.flushBuffer(address);
-  }
-  
-  /**
-   * Manually flush all buffers
-   * @returns {Promise<void>}
-   */
-  async flushAllBuffers() {
-    return this.#bufferManager.flushAllBuffers();
-  }
-  
-  /**
-   * Get buffer statistics
-   * @returns {Object} Buffer statistics
-   */
-  getBufferStats() {
-    return this.#bufferManager.getStats();
-  }
-  
-  /**
-   * Close the client connection
-   */
-  async close() {
-    // Flush all buffers before closing
-    try {
-      await this.#bufferManager.flushAllBuffers();
-    } catch (error) {
-      console.warn('Error flushing buffers during close:', error);
-    }
-    
-    // Cleanup buffer manager
-    this.#bufferManager.cleanup();
-    
-    this.#connected = false;
-    this.#http = null;
-    this.#loadBalancer = null;
-  }
-  
-  /**
-   * Create a transaction builder for atomic operations
-   * @returns {TransactionBuilder} Transaction builder instance
-   */
-  transaction() {
-    return new TransactionBuilder(this);
-  }
-  
-  /**
-   * Create a pipeline for message processing workflows
-   * @param {string} queue - Source queue name
-   * @returns {PipelineBuilder} Pipeline builder instance
-   */
-  pipeline(queue) {
-    return new PipelineBuilder(this, queue);
-  }
-  
-  // Internal helper methods for Transaction and Pipeline
-  async _ensureConnected() {
-    return this.#ensureConnected();
-  }
-  
-  get _http() {
-    return this.#http;
-  }
-  
-  get _config() {
-    return this.#config;
-  }
-}
-
-/**
- * Message Buffer for client-side buffering
- */
-class MessageBuffer {
-  constructor(address, options, flushCallback) {
-    this.address = address;
-    this.messages = [];
-    this.options = options;
-    this.flushCallback = flushCallback;
-    this.timer = null;
-    this.firstMessageTime = null;
-    this.flushing = false;
-  }
-  
-  add(formattedMessage) {
-    // Set first message time if this is the first message
-    if (this.messages.length === 0) {
-      this.firstMessageTime = Date.now();
-      this.#startTimer();
-    }
-    
-    this.messages.push(formattedMessage);
-    
-    // Check if we should flush based on size
-    if (this.messages.length >= this.options.size) {
-      this.#triggerFlush();
-    }
-  }
-  
-  #startTimer() {
-    if (this.timer) return; // Timer already running
-    
-    this.timer = setTimeout(() => {
-      this.#triggerFlush();
-    }, this.options.time);
-  }
-  
-  #triggerFlush() {
-    if (this.flushing || this.messages.length === 0) return;
-    
-    // Clear timer
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = null;
-    }
-    
-    // Trigger flush via callback
-    this.flushCallback(this.address);
-  }
-  
-  extractMessages() {
-    const messages = [...this.messages];
-    this.messages = [];
-    this.firstMessageTime = null;
-    this.flushing = false;
-    
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = null;
-    }
-    
-    return messages;
-  }
-  
-  cleanup() {
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = null;
-    }
-    this.messages = [];
-    this.firstMessageTime = null;
-    this.flushing = false;
-  }
-}
-
-/**
- * Buffer Manager for client-side message buffering
- */
-class BufferManager {
-  constructor(client) {
-    this.client = client;
-    this.buffers = new Map(); // address -> MessageBuffer
-    this.flushCount = 0;
-  }
-  
-  addMessage(address, formattedMessage, bufferOptions) {
-    const bufferKey = address;
-    
-    if (!this.buffers.has(bufferKey)) {
-      this.buffers.set(bufferKey, new MessageBuffer(
-        address, 
-        bufferOptions, 
-        (addr) => this.#flushBuffer(addr)
-      ));
-    }
-    
-    const buffer = this.buffers.get(bufferKey);
-    buffer.add(formattedMessage);
-  }
-  
-  async #flushBuffer(address) {
-    const buffer = this.buffers.get(address);
-    if (!buffer || buffer.flushing || buffer.messages.length === 0) {
-      return;
-    }
-    
-    buffer.flushing = true;
-    
-    try {
-      const messages = buffer.extractMessages();
-      
-      if (messages.length === 0) return;
-      
-      // Call the original push logic with the buffered messages
-      const requestBody = { items: messages };
-      
-      await withRetry(
-        () => this.client._http.post('/api/v1/push', requestBody),
-        this.client._config.retryAttempts,
-        this.client._config.retryDelay
-      );
-      
-      this.flushCount++;
-      
-      // Call onFlush callback if provided
-      if (buffer.options.onFlush) {
-        buffer.options.onFlush(address, messages.length);
-      }
-      
-      // Remove empty buffer
-      this.buffers.delete(address);
-      
-    } catch (error) {
-      buffer.flushing = false;
-      
-      // Call onError callback if provided
-      if (buffer.options.onError) {
-        buffer.options.onError(address, error);
-      }
-      
-      throw error;
-    }
-  }
-  
-  async flushBuffer(address) {
-    return this.#flushBuffer(address);
-  }
-  
-  async flushAllBuffers() {
-    const flushPromises = [];
-    for (const address of this.buffers.keys()) {
-      flushPromises.push(this.#flushBuffer(address));
-    }
-    await Promise.all(flushPromises);
-  }
-  
-  getStats() {
-    let totalBufferedMessages = 0;
-    let oldestBufferAge = 0;
-    
-    for (const buffer of this.buffers.values()) {
-      totalBufferedMessages += buffer.messages.length;
-      if (buffer.firstMessageTime) {
-        const age = Date.now() - buffer.firstMessageTime;
-        oldestBufferAge = Math.max(oldestBufferAge, age);
-      }
-    }
-    
-    return {
-      activeBuffers: this.buffers.size,
-      totalBufferedMessages,
-      oldestBufferAge,
-      flushesPerformed: this.flushCount
-    };
-  }
-  
-  cleanup() {
-    for (const buffer of this.buffers.values()) {
-      buffer.cleanup();
-    }
-    this.buffers.clear();
-  }
-}
-
-/**
- * Transaction Builder for atomic operations
- */
-class TransactionBuilder {
-  #client;
-  #operations = [];
-  #requiredLeases = [];
-  
-  constructor(client) {
-    this.#client = client;
-  }
-  
-  /**
-   * Add ACK operation to transaction
-   * @param {Array|Object} messages - Messages to acknowledge
-   * @param {string} status - Status ('completed' or 'failed')
-   * @returns {TransactionBuilder} this for chaining
-   */
-  ack(messages, status = 'completed') {
-    const msgs = Array.isArray(messages) ? messages : [messages];
-    
-    msgs.forEach(msg => {
-      const transactionId = msg.transactionId || msg.id || msg;
-      const leaseId = msg.leaseId || null;
-      
-      this.#operations.push({
-        type: 'ack',
-        transactionId,
-        status
-      });
-      
-      if (leaseId) {
-        this.#requiredLeases.push(leaseId);
-      }
-    });
-    
-    return this;
-  }
-  
-  /**
-   * Add PUSH operation to transaction
-   * @param {string} queue - Target queue
-   * @param {Array|Object} items - Items to push
-   * @returns {TransactionBuilder} this for chaining
-   */
-  push(queue, items) {
-    const itemArray = Array.isArray(items) ? items : [items];
-    
-    this.#operations.push({
-      type: 'push',
-      items: itemArray.map(item => ({
-        queue,
-        payload: item
-      }))
-    });
-    
-    return this;
-  }
-  
-  /**
-   * Add lease extension to transaction
-   * @param {string} leaseId - Lease ID to extend
-   * @returns {TransactionBuilder} this for chaining
-   */
-  extend(leaseId) {
-    this.#operations.push({
-      type: 'extend',
-      leaseId
-    });
-    
-    this.#requiredLeases.push(leaseId);
-    return this;
-  }
-  
-  /**
-   * Execute the transaction
-   * @returns {Promise<Object>} Transaction result
-   */
-  async commit() {
-    await this.#client._ensureConnected();
-    
-    const result = await this.#client._http.post('/api/v1/transaction', {
-      operations: this.#operations,
-      requiredLeases: [...new Set(this.#requiredLeases)] // Unique leases
-    });
-    
-    if (!result.success) {
-      throw new Error(result.error || 'Transaction failed');
-    }
-    
-    return result;
-  }
-}
-
-/**
- * Pipeline Builder for message processing workflows
- */
-class PipelineBuilder {
-  #client;
-  #queue;
-  #options = {};
-  #processor = null;
-  #errorHandler = null;
-  #atomicOps = null;
-  #leaseRenewal = null;
-  #repeatConfig = null;
-  #concurrency = 1;
-  
-  constructor(client, queue) {
-    this.#client = client;
-    this.#queue = queue;
-  }
-  
-  /**
-   * Take messages from the queue
-   * @param {number} count - Number of messages to take
-   * @param {Object} options - Take options
-   * @returns {PipelineBuilder} this for chaining
-   */
-  take(count, options = {}) {
-    this.#options = { ...options, batch: count, limit: count };
-    return this;
-  }
-  
-  /**
-   * Process messages individually (one at a time)
-   * @param {Function} handler - Async function to process a single message
-   * @returns {PipelineBuilder} this for chaining
-   */
-  process(handler) {
-    // Wrap the single-message handler to process messages one by one
-    this.#processor = async (messages) => {
-      const results = [];
-      for (const message of messages) {
-        const result = await handler(message);
-        results.push(result);
-      }
-      return results;
-    };
-    return this;
-  }
-  
-  /**
-   * Process messages as a batch
-   * @param {Function} handler - Async function to process a batch of messages
-   * @returns {PipelineBuilder} this for chaining
-   */
-  processBatch(handler) {
-    this.#processor = handler;
-    return this;
-  }
-  
-  /**
-   * Define atomic operations to execute after processing
-   * @param {Function} txBuilder - Function that receives a TransactionBuilder
-   * @returns {PipelineBuilder} this for chaining
-   */
-  atomically(txBuilder) {
-    this.#atomicOps = txBuilder;
-    return this;
-  }
-  
-  /**
-   * Handle errors
-   * @param {Function} handler - Error handler function
-   * @returns {PipelineBuilder} this for chaining
-   */
-  onError(handler) {
-    this.#errorHandler = handler;
-    return this;
-  }
-  
-  /**
-   * Enable automatic lease renewal
-   * @param {Object} options - Renewal options
-   * @returns {PipelineBuilder} this for chaining
-   */
-  withAutoRenewal(options = {}) {
-    this.#leaseRenewal = {
-      interval: options.interval || 30000, // Renew every 30s by default
-      enabled: true
-    };
-    return this;
-  }
-  
-  /**
-   * Set concurrency level for parallel batch processing
-   * @param {number} level - Number of concurrent batches to process
-   * @returns {PipelineBuilder} this for chaining
-   */
-  withConcurrency(level) {
-    this.#concurrency = Math.max(1, level);
-    return this;
-  }
-  
-  /**
-   * Configure repeated execution
-   * @param {Object} options - Repeat options
-   * @returns {PipelineBuilder} this for chaining
-   */
-  repeat(options = {}) {
-    this.#repeatConfig = {
-      maxIterations: options.maxIterations || Infinity,
-      delay: options.delay || 0,
-      continuous: options.continuous !== undefined ? options.continuous : true,  // Default to continuous mode
-      waitOnEmpty: options.waitOnEmpty || 1000  // Wait time when no messages
-    };
-    return this;
-  }
-  
-  /**
-   * Execute the pipeline (once or repeatedly based on configuration)
-   * @param {Object} options - Execution options
-   * @param {boolean} options.returnGenerator - For repeat mode, return generator instead of running loop
-   * @returns {Promise<Object>} Result or summary of all iterations
-   */
-  async execute(options = {}) {
-    // If repeat is configured
-    if (this.#repeatConfig) {
-      // Option to return generator for advanced users
-      if (options.returnGenerator) {
-        return this.#executeRepeatedly();
-      }
-      
-      // Default: run the loop internally and return summary
-      return this.#executeRepeatedlyWithSummary();
-    }
-    
-    // Otherwise execute once
-    return this.#executeSingle();
-  }
-  
-  /**
-   * Execute the pipeline once (internal)
-   * @private
-   * @returns {Promise<Object>} Pipeline execution result
-   */
-  async #executeSingle() {
-    // Use local variables to avoid race conditions in parallel execution
-    let messages = null;
-    let processedMessages = null;
-    
-    try {
-      // 1. Take messages
-      messages = await this.#client.takeSingleBatch(this.#queue, this.#options);
-      
-      if (!messages || messages.length === 0) {
-        return { processed: 0, messages: [] };
-      }
-      
-      // 2. Set up auto-renewal if enabled
-      let renewalTimer = null;
-      if (this.#leaseRenewal?.enabled) {
-        renewalTimer = this.#setupAutoRenewal(messages);
-      }
-      
-      try {
-        // 3. Process messages
-        if (this.#processor) {
-          processedMessages = await this.#processor(messages);
-        } else {
-          processedMessages = messages;
-        }
-        
-        // 4. Execute atomic operations
-        if (this.#atomicOps) {
-          const tx = new TransactionBuilder(this.#client);
-          
-          // Apply the atomic operations
-          this.#atomicOps(tx, messages, processedMessages);
-          
-          await tx.commit();
-        } else {
-          // Default: just ACK the messages
-          // Extract consumer group from queue address if present (format: queue@group)
-          const atIndex = this.#queue.lastIndexOf('@');
-          const consumerGroup = atIndex > 0 ? this.#queue.substring(atIndex + 1) : null;
-          const context = consumerGroup ? { group: consumerGroup } : {};
-          await this.#client.ack(messages, true, context);
-        }
-        
-        return {
-          processed: messages.length,
-          messages: processedMessages
-        };
-        
-      } finally {
-        // Clean up renewal timer
-        if (renewalTimer) {
-          clearInterval(renewalTimer);
-        }
-      }
-      
-    } catch (error) {
-      if (this.#errorHandler) {
-        await this.#errorHandler(error, messages || []);
-        return { processed: 0, messages: [], error: error.message };
-      } else {
-        throw error;
-      }
-    }
-  }
-  
-  /**
-   * Execute the pipeline repeatedly (internal)
-   * @private
-   * @returns {AsyncGenerator} Async generator of results
-   */
-  async *#executeRepeatedly() {
-    const { maxIterations, delay } = this.#repeatConfig;
-    let iteration = 0;
-    
-    while (iteration < maxIterations) {
-      const result = await this.#executeSingle();
-      yield result;
-      
-      iteration++;
-      
-      if (delay > 0) {
-        await new Promise(resolve => setTimeout(resolve, delay));
-      }
-    }
-  }
-  
-  /**
-   * Execute the pipeline repeatedly and return summary
-   * @private
-   * @returns {Promise<Object>} Summary of all iterations
-   */
-  async #executeRepeatedlyWithSummary() {
-    const { maxIterations, delay, continuous, waitOnEmpty } = this.#repeatConfig;
-    
-    // If concurrency > 1, use parallel workers
-    if (this.#concurrency > 1) {
-      return this.#executeRepeatedlyParallel();
-    }
-    
-    // Sequential processing
-    let iteration = 0;
-    let totalProcessed = 0;
-    const results = [];
-    let consecutiveEmpty = 0;
-    const maxConsecutiveEmpty = continuous ? Infinity : 3; // In continuous mode, never stop on empty
-    
-    while (iteration < maxIterations) {
-      const result = await this.#executeSingle();
-      
-      if (result.processed === 0) {
-        consecutiveEmpty++;
-        
-        // In continuous mode, wait and retry
-        if (continuous || consecutiveEmpty < maxConsecutiveEmpty) {
-          await new Promise(resolve => setTimeout(resolve, waitOnEmpty));
-          continue; // Don't increment iteration for empty results
-        } else {
-          // Not continuous and too many empty results
-          break;
-        }
-      } else {
-        // Reset empty counter on successful batch
-        consecutiveEmpty = 0;
-        results.push(result);
-        totalProcessed += result.processed;
-        iteration++;
-      }
-      
-      if (delay > 0 && iteration < maxIterations) {
-        await new Promise(resolve => setTimeout(resolve, delay));
-      }
-    }
-    
-    return {
-      iterations: iteration,
-      totalProcessed,
-      results,
-      summary: {
-        averagePerBatch: iteration > 0 ? totalProcessed / iteration : 0,
-        completed: iteration >= maxIterations ? 'maxIterations' : 'noMessages',
-        concurrency: this.#concurrency,
-        continuous
-      }
-    };
-  }
-  
-  /**
-   * Execute pipeline with parallel processing
-   * Each worker independently calls take(), allowing them to work on different partitions
-   * @private
-   * @returns {Promise<Object>} Summary of all parallel executions
-   */
-  async #executeRepeatedlyParallel() {
-    const { maxIterations = Infinity, delay, continuous, waitOnEmpty } = this.#repeatConfig || {};
-    const workers = [];
-    const results = [];
-    
-    // Shared state for coordination
-    const sharedState = {
-      shouldStop: false,
-      emptyWorkers: new Set(),
-      lock: Promise.resolve()
-    };
-    
-    // Worker function - each worker independently takes and processes messages
-    const worker = async (workerId) => {
-      let workerIterations = 0;
-      let workerProcessed = 0;
-      let consecutiveEmpty = 0;
-      const maxConsecutiveEmpty = continuous ? Infinity : 10;
-      
-      while (!sharedState.shouldStop && workerIterations < maxIterations) {
-        try {
-          // Each worker independently calls executeSingle (which calls take)
-          const result = await this.#executeSingle();
-          
-          if (result.processed === 0) {
-            consecutiveEmpty++;
-            
-            // Add this worker to empty set
-            sharedState.emptyWorkers.add(workerId);
-            
-            // If all workers are empty, consider stopping
-            if (!continuous && sharedState.emptyWorkers.size === this.#concurrency) {
-              // Double-check with a small delay to avoid race conditions
-              await new Promise(resolve => setTimeout(resolve, 200));
-              
-              // Re-check after delay
-              if (sharedState.emptyWorkers.size === this.#concurrency) {
-                sharedState.shouldStop = true;
-                break;
-              }
-            }
-            
-            // Individual worker timeout
-            if (!continuous && consecutiveEmpty >= maxConsecutiveEmpty) {
-              break;
-            }
-            
-            // Wait before retry
-            await new Promise(resolve => setTimeout(resolve, waitOnEmpty || 1000));
-            continue; // Don't count empty iterations
-          }
-          
-          // Reset empty counter on successful batch
-          consecutiveEmpty = 0;
-          sharedState.emptyWorkers.delete(workerId);
-          
-          // Store result with worker info
-          results.push({ 
-            ...result, 
-            workerId, 
-            timestamp: new Date().toISOString() 
-          });
-          
-          workerProcessed += result.processed;
-          workerIterations++;
-          
-          if (delay > 0) {
-            await new Promise(resolve => setTimeout(resolve, delay));
-          }
-        } catch (error) {
-          console.error(`Worker ${workerId} error:`, error);
-          if (this.#errorHandler) {
-            await this.#errorHandler(error, []);
-          } else {
-            sharedState.shouldStop = true;
-            throw error;
-          }
-        }
-      }
-      
-      return { 
-        workerId, 
-        iterations: workerIterations, 
-        processed: workerProcessed,
-        consecutiveEmpty 
-      };
-    };
-    
-    // Start parallel workers
-    console.log(`🚀 Starting ${this.#concurrency} parallel workers...`);
-    for (let i = 0; i < this.#concurrency; i++) {
-      workers.push(worker(i));
-    }
-    
-    // Wait for all workers
-    const workerResults = await Promise.all(workers);
-    
-    // Aggregate results
-    let totalProcessed = 0;
-    let totalIterations = 0;
-    
-    workerResults.forEach(wr => {
-      totalProcessed += wr.processed;
-      totalIterations += wr.iterations;
-      if (wr.iterations > 0) {
-        console.log(`Worker ${wr.workerId}: Processed ${wr.processed} messages in ${wr.iterations} batches`);
-      }
-    });
-    
-    return {
-      iterations: totalIterations,
-      totalProcessed,
-      results,
-      workers: workerResults,
-      summary: {
-        averagePerBatch: totalIterations > 0 ? totalProcessed / totalIterations : 0,
-        completed: totalIterations >= (maxIterations * this.#concurrency) ? 'maxIterations' : 'noMessages',
-        concurrency: this.#concurrency,
-        workersUtilized: workerResults.filter(w => w.iterations > 0).length,
-        continuous
-      }
-    };
-  }
-  
-  /**
-   * Set up automatic lease renewal
-   * @private
-   */
-  #setupAutoRenewal(messages) {
-    const leaseIds = messages
-      .map(m => m.leaseId)
-      .filter(id => id != null);
-    
-    if (leaseIds.length === 0) return null;
-    
-    return setInterval(async () => {
-      try {
-        // Extend all leases using the client's renewLease method
-        for (const leaseId of leaseIds) {
-          const result = await this.#client.renewLease(leaseId);
-          if (!result.success) {
-            console.error('Lease renewal failed:', result.error);
-          }
-        }
-      } catch (error) {
-        console.error('Failed to renew lease:', error);
-      }
-    }, this.#leaseRenewal.interval);
-  }
-}
-
-// Export the class as default as well for convenience
-export default Queen;