queen-mq 0.1.0

package/src/client/utils/loadBalancer.js

@@ -0,0 +1,152 @@
+/**
+ * Load balancer utility for distributing requests across multiple servers
+ */
+
+export const LoadBalancingStrategy = {
+  ROUND_ROBIN: 'ROUND_ROBIN',
+  SESSION: 'SESSION'
+};
+
+/**
+ * Create a load balancer for distributing requests across multiple base URLs
+ */
+export const createLoadBalancer = (urls, strategy = LoadBalancingStrategy.ROUND_ROBIN) => {
+  if (!Array.isArray(urls) || urls.length === 0) {
+    throw new Error('URLs must be a non-empty array');
+  }
+  
+  // Normalize URLs (remove trailing slashes)
+  const normalizedUrls = urls.map(url => url.replace(/\/$/, ''));
+  
+  // Round robin state
+  let currentIndex = 0;
+  
+  // Session affinity state - map of session ID to URL index
+  const sessionMap = new Map();
+  
+  // Generate a session ID for the current client instance
+  const sessionId = generateSessionId();
+  
+  /**
+   * Get the next URL based on the configured strategy
+   */
+  const getNextUrl = (options = {}) => {
+    const { sessionKey = sessionId } = options;
+    
+    switch (strategy) {
+      case LoadBalancingStrategy.ROUND_ROBIN:
+        // Round robin: cycle through URLs
+        const url = normalizedUrls[currentIndex];
+        currentIndex = (currentIndex + 1) % normalizedUrls.length;
+        return url;
+        
+      case LoadBalancingStrategy.SESSION:
+        // Session affinity: stick to the same server per session
+        if (!sessionMap.has(sessionKey)) {
+          // Assign a server to this session (using round robin for initial assignment)
+          const assignedIndex = currentIndex;
+          sessionMap.set(sessionKey, assignedIndex);
+          currentIndex = (currentIndex + 1) % normalizedUrls.length;
+        }
+        return normalizedUrls[sessionMap.get(sessionKey)];
+        
+      default:
+        throw new Error(`Unknown load balancing strategy: ${strategy}`);
+    }
+  };
+  
+  /**
+   * Get all configured URLs
+   */
+  const getAllUrls = () => [...normalizedUrls];
+  
+  /**
+   * Get current strategy
+   */
+  const getStrategy = () => strategy;
+  
+  /**
+   * Reset the load balancer state
+   */
+  const reset = () => {
+    currentIndex = 0;
+    sessionMap.clear();
+  };
+  
+  /**
+   * Get statistics about URL usage (for debugging)
+   */
+  const getStats = () => {
+    return {
+      strategy,
+      urls: normalizedUrls,
+      currentIndex,
+      sessionCount: sessionMap.size,
+      sessions: Array.from(sessionMap.entries()).map(([key, index]) => ({
+        sessionKey: key,
+        url: normalizedUrls[index]
+      }))
+    };
+  };
+  
+  return {
+    getNextUrl,
+    getAllUrls,
+    getStrategy,
+    reset,
+    getStats
+  };
+};
+
+/**
+ * Generate a unique session ID
+ */
+const generateSessionId = () => {
+  return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+};
+
+/**
+ * Create a failover wrapper that tries different servers on failure
+ */
+export const createFailoverWrapper = (loadBalancer, maxRetries = 3) => {
+  const attemptedUrls = new Set();
+  
+  const executeWithFailover = async (requestFn, options = {}) => {
+    const urls = loadBalancer.getAllUrls();
+    let lastError = null;
+    
+    // Try each URL up to maxRetries times total
+    for (let attempt = 0; attempt < Math.min(maxRetries, urls.length); attempt++) {
+      const url = loadBalancer.getNextUrl(options);
+      
+      // Skip if we've already tried this URL in this request
+      if (attemptedUrls.has(url)) {
+        continue;
+      }
+      
+      attemptedUrls.add(url);
+      
+      try {
+        const result = await requestFn(url);
+        attemptedUrls.clear(); // Clear for next request
+        return result;
+      } catch (error) {
+        lastError = error;
+        console.warn(`Request failed for ${url}, attempting next server...`, error.message);
+        
+        // If it's a client error (4xx), don't retry on other servers
+        if (error.status && error.status >= 400 && error.status < 500) {
+          attemptedUrls.clear();
+          throw error;
+        }
+      }
+    }
+    
+    attemptedUrls.clear();
+    throw lastError || new Error('All servers failed');
+  };
+  
+  return {
+    executeWithFailover
+  };
+};

package/src/client/utils/retry.js

@@ -0,0 +1,35 @@
+import config from '../../config.js';
+
+export const withRetry = async (fn, attempts = config.CLIENT.DEFAULT_RETRY_ATTEMPTS, delay = config.CLIENT.DEFAULT_RETRY_DELAY, backoff = config.CLIENT.DEFAULT_RETRY_BACKOFF) => {
+  let lastError;
+  
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      
+      // Don't retry on client errors (4xx)
+      if (error.status && error.status >= 400 && error.status < 500) {
+        throw error;
+      }
+      
+      if (i < attempts - 1) {
+        const waitTime = delay * Math.pow(backoff, i);
+        await new Promise(resolve => setTimeout(resolve, waitTime));
+      }
+    }
+  }
+  
+  throw lastError;
+};
+
+export const createRetryableFunction = (fn, options = {}) => {
+  const {
+    attempts = config.CLIENT.DEFAULT_RETRY_ATTEMPTS,
+    delay = config.CLIENT.DEFAULT_RETRY_DELAY,
+    backoff = config.CLIENT.DEFAULT_RETRY_BACKOFF
+  } = options;
+  
+  return (...args) => withRetry(() => fn(...args), attempts, delay, backoff);
+};

package/src/config.js

@@ -0,0 +1,215 @@
+/**
+ * Centralized Configuration for Queen Message Queue System
+ * 
+ * All configuration values can be overridden using environment variables.
+ * This file provides default values and documentation for all settings.
+ */
+import os from 'os';
+
+// Server Configuration
+export const SERVER = {
+  PORT: parseInt(process.env.PORT) || 6632,
+  HOST: process.env.HOST || '0.0.0.0',
+  WORKER_ID: process.env.WORKER_ID || `worker-${os.hostname()}-${process.pid}`,
+  APPLICATION_NAME: process.env.APP_NAME || 'queen-mq'
+};
+
+// Database Configuration
+export const DATABASE = {
+  // Connection settings
+  USER: process.env.PG_USER || 'postgres',
+  HOST: process.env.PG_HOST || 'localhost',
+  DATABASE: process.env.PG_DB || 'postgres',
+  PASSWORD: process.env.PG_PASSWORD || 'postgres',
+  PORT: parseInt(process.env.PG_PORT) || 5432,
+  
+  // Pool configuration
+  POOL_SIZE: parseInt(process.env.DB_POOL_SIZE) || 20,
+  IDLE_TIMEOUT: parseInt(process.env.DB_IDLE_TIMEOUT) || 30000, // 30 seconds
+  CONNECTION_TIMEOUT: parseInt(process.env.DB_CONNECTION_TIMEOUT) || 2000, // 2 seconds
+  STATEMENT_TIMEOUT: parseInt(process.env.DB_STATEMENT_TIMEOUT) || 30000, // 30 seconds
+  QUERY_TIMEOUT: parseInt(process.env.DB_QUERY_TIMEOUT) || 30000, // 30 seconds
+  
+  // Pool manager settings
+  MAX_RETRIES: parseInt(process.env.DB_MAX_RETRIES) || 3
+};
+
+// Queue Processing Configuration
+export const QUEUE = {
+  // Pop operation defaults
+  DEFAULT_TIMEOUT: parseInt(process.env.DEFAULT_TIMEOUT) || 30000, // 30 seconds
+  MAX_TIMEOUT: parseInt(process.env.MAX_TIMEOUT) || 60000, // 60 seconds
+  DEFAULT_BATCH_SIZE: parseInt(process.env.DEFAULT_BATCH_SIZE) || 1,
+  BATCH_INSERT_SIZE: parseInt(process.env.BATCH_INSERT_SIZE) || 1000,
+  
+  // Long polling
+  POLL_INTERVAL: parseInt(process.env.QUEUE_POLL_INTERVAL) || 100, // 100ms
+  POLL_INTERVAL_FILTERED: parseInt(process.env.QUEUE_POLL_INTERVAL_FILTERED) || 1000, // 1 second
+  
+  // Queue defaults
+  DEFAULT_LEASE_TIME: parseInt(process.env.DEFAULT_LEASE_TIME) || 300, // 5 minutes
+  DEFAULT_RETRY_LIMIT: parseInt(process.env.DEFAULT_RETRY_LIMIT) || 3,
+  DEFAULT_RETRY_DELAY: parseInt(process.env.DEFAULT_RETRY_DELAY) || 1000, // 1 second
+  DEFAULT_MAX_SIZE: parseInt(process.env.DEFAULT_MAX_SIZE) || 10000,
+  DEFAULT_TTL: parseInt(process.env.DEFAULT_TTL) || 3600, // 1 hour
+  DEFAULT_PRIORITY: parseInt(process.env.DEFAULT_PRIORITY) || 0,
+  DEFAULT_DELAYED_PROCESSING: parseInt(process.env.DEFAULT_DELAYED_PROCESSING) || 0,
+  DEFAULT_WINDOW_BUFFER: parseInt(process.env.DEFAULT_WINDOW_BUFFER) || 0,
+  
+  // Dead Letter Queue
+  DEFAULT_DLQ_ENABLED: process.env.DEFAULT_DLQ_ENABLED === 'true' || false,
+  DEFAULT_DLQ_AFTER_MAX_RETRIES: process.env.DEFAULT_DLQ_AFTER_MAX_RETRIES === 'true' || false,
+  
+  // Retention defaults
+  DEFAULT_RETENTION_SECONDS: parseInt(process.env.DEFAULT_RETENTION_SECONDS) || 0,
+  DEFAULT_COMPLETED_RETENTION_SECONDS: parseInt(process.env.DEFAULT_COMPLETED_RETENTION_SECONDS) || 0,
+  DEFAULT_RETENTION_ENABLED: process.env.DEFAULT_RETENTION_ENABLED === 'true' || false,
+  
+  // Eviction
+  DEFAULT_MAX_WAIT_TIME_SECONDS: parseInt(process.env.DEFAULT_MAX_WAIT_TIME_SECONDS) || 0
+};
+
+// System Events Configuration
+export const SYSTEM_EVENTS = {
+  // Enable/disable system event propagation
+  ENABLED: process.env.QUEEN_SYSTEM_EVENTS_ENABLED === 'true' || true,
+  
+  // Batching window for event publishing (milliseconds)
+  BATCH_MS: parseInt(process.env.QUEEN_SYSTEM_EVENTS_BATCH_MS) || 10,
+  
+  // Timeout for startup synchronization (milliseconds)
+  SYNC_TIMEOUT: parseInt(process.env.QUEEN_SYSTEM_EVENTS_SYNC_TIMEOUT) || 30000
+};
+
+// Background Jobs Configuration
+export const JOBS = {
+  // Lease reclamation
+  LEASE_RECLAIM_INTERVAL: parseInt(process.env.LEASE_RECLAIM_INTERVAL) || 5000, // 5 seconds
+  
+  // Retention service
+  RETENTION_INTERVAL: parseInt(process.env.RETENTION_INTERVAL) || 300000, // 5 minutes
+  RETENTION_BATCH_SIZE: parseInt(process.env.RETENTION_BATCH_SIZE) || 1000,
+  PARTITION_CLEANUP_DAYS: parseInt(process.env.PARTITION_CLEANUP_DAYS) || 7,
+  
+  // Eviction service
+  EVICTION_INTERVAL: parseInt(process.env.EVICTION_INTERVAL) || 60000, // 1 minute
+  EVICTION_BATCH_SIZE: parseInt(process.env.EVICTION_BATCH_SIZE) || 1000,
+  
+  // WebSocket updates
+  QUEUE_DEPTH_UPDATE_INTERVAL: parseInt(process.env.QUEUE_DEPTH_UPDATE_INTERVAL) || 5000, // 5 seconds
+  SYSTEM_STATS_UPDATE_INTERVAL: parseInt(process.env.SYSTEM_STATS_UPDATE_INTERVAL) || 10000 // 10 seconds
+};
+
+// WebSocket Configuration
+export const WEBSOCKET = {
+  COMPRESSION: parseInt(process.env.WS_COMPRESSION) || 0,
+  MAX_PAYLOAD_LENGTH: parseInt(process.env.WS_MAX_PAYLOAD_LENGTH) || 16384, // 16KB
+  IDLE_TIMEOUT: parseInt(process.env.WS_IDLE_TIMEOUT) || 60, // 60 seconds
+  MAX_CONNECTIONS: parseInt(process.env.WS_MAX_CONNECTIONS) || 1000,
+  HEARTBEAT_INTERVAL: parseInt(process.env.WS_HEARTBEAT_INTERVAL) || 30000 // 30 seconds
+};
+
+// Encryption Configuration
+export const ENCRYPTION = {
+  KEY_ENV_VAR: 'QUEEN_ENCRYPTION_KEY',
+  ALGORITHM: 'aes-256-gcm',
+  KEY_LENGTH: 32, // bytes
+  IV_LENGTH: 16 // bytes
+};
+
+// Client SDK Configuration
+export const CLIENT = {
+  DEFAULT_BASE_URL: process.env.QUEEN_BASE_URL || 'http://localhost:6632',
+  DEFAULT_RETRY_ATTEMPTS: parseInt(process.env.CLIENT_RETRY_ATTEMPTS) || 3,
+  DEFAULT_RETRY_DELAY: parseInt(process.env.CLIENT_RETRY_DELAY) || 1000, // 1 second
+  DEFAULT_RETRY_BACKOFF: parseFloat(process.env.CLIENT_RETRY_BACKOFF) || 2,
+  CONNECTION_POOL_SIZE: parseInt(process.env.CLIENT_POOL_SIZE) || 10,
+  REQUEST_TIMEOUT: parseInt(process.env.CLIENT_REQUEST_TIMEOUT) || 30000 // 30 seconds
+};
+
+// API Configuration
+export const API = {
+  MAX_BODY_SIZE: parseInt(process.env.MAX_BODY_SIZE) || 10 * 1024 * 1024, // 10MB max body size
+  // Pagination
+  DEFAULT_LIMIT: parseInt(process.env.API_DEFAULT_LIMIT) || 100,
+  MAX_LIMIT: parseInt(process.env.API_MAX_LIMIT) || 1000,
+  DEFAULT_OFFSET: parseInt(process.env.API_DEFAULT_OFFSET) || 0,
+  
+  // CORS
+  CORS_MAX_AGE: parseInt(process.env.CORS_MAX_AGE) || 86400, // 24 hours
+  CORS_ALLOWED_ORIGINS: process.env.CORS_ALLOWED_ORIGINS || '*',
+  CORS_ALLOWED_METHODS: process.env.CORS_ALLOWED_METHODS || 'GET, POST, PUT, DELETE, OPTIONS',
+  CORS_ALLOWED_HEADERS: process.env.CORS_ALLOWED_HEADERS || 'Content-Type, Authorization'
+};
+
+// Analytics Configuration
+export const ANALYTICS = {
+  // Processing time calculations
+  RECENT_COMPLETION_HOURS: parseInt(process.env.ANALYTICS_RECENT_HOURS) || 24,
+  MIN_COMPLETED_FOR_STATS: parseInt(process.env.ANALYTICS_MIN_COMPLETED) || 5,
+  
+  // Time windows
+  RECENT_MESSAGE_WINDOW: parseInt(process.env.RECENT_MESSAGE_WINDOW) || 60, // 1 minute in seconds
+  RELATED_MESSAGE_WINDOW: parseInt(process.env.RELATED_MESSAGE_WINDOW) || 3600, // 1 hour in seconds
+  MAX_RELATED_MESSAGES: parseInt(process.env.MAX_RELATED_MESSAGES) || 10
+};
+
+// Performance Monitoring
+export const MONITORING = {
+  ENABLE_REQUEST_COUNTING: process.env.ENABLE_REQUEST_COUNTING !== 'false',
+  ENABLE_MESSAGE_COUNTING: process.env.ENABLE_MESSAGE_COUNTING !== 'false',
+  METRICS_ENDPOINT_ENABLED: process.env.METRICS_ENDPOINT_ENABLED !== 'false',
+  HEALTH_CHECK_ENABLED: process.env.HEALTH_CHECK_ENABLED !== 'false'
+};
+
+// Logging Configuration
+export const LOGGING = {
+  ENABLE_LOGGING: process.env.ENABLE_LOGGING !== 'false',
+  LOG_LEVEL: process.env.LOG_LEVEL || 'info',
+  LOG_FORMAT: process.env.LOG_FORMAT || 'json',
+  LOG_TIMESTAMP: process.env.LOG_TIMESTAMP !== 'false'
+};
+
+// HTTP Response Status Codes
+export const HTTP_STATUS = {
+  OK: 200,
+  CREATED: 201,
+  NO_CONTENT: 204,
+  BAD_REQUEST: 400,
+  NOT_FOUND: 404,
+  INTERNAL_SERVER_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503
+};
+
+// Export a function to get the complete configuration
+export const getConfig = () => ({
+  server: SERVER,
+  database: DATABASE,
+  queue: QUEUE,
+  jobs: JOBS,
+  websocket: WEBSOCKET,
+  encryption: ENCRYPTION,
+  client: CLIENT,
+  api: API,
+  analytics: ANALYTICS,
+  monitoring: MONITORING,
+  logging: LOGGING,
+  httpStatus: HTTP_STATUS
+});
+
+// Export default configuration object
+export default {
+  SERVER,
+  DATABASE,
+  QUEUE,
+  SYSTEM_EVENTS,
+  JOBS,
+  WEBSOCKET,
+  ENCRYPTION,
+  CLIENT,
+  API,
+  ANALYTICS,
+  MONITORING,
+  LOGGING,
+  HTTP_STATUS
+};

package/src/database/connection.js

@@ -0,0 +1,103 @@
+import pg from 'pg';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const { Pool } = pg;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Create connection pool
+export const createPool = () => {
+  return new Pool({
+    user: process.env.PG_USER || 'postgres',
+    host: process.env.PG_HOST || 'localhost',
+    database: process.env.PG_DB || 'postgres',
+    password: process.env.PG_PASSWORD || 'postgres',
+    port: process.env.PG_PORT || 5432,
+    max: process.env.DB_POOL_SIZE || 20,
+    idleTimeoutMillis: 30000,
+    connectionTimeoutMillis: 2000,
+  });
+};
+
+// Initialize database schema
+export const initDatabase = async (pool) => {
+  try {
+    // Check if the queen schema already exists
+    const schemaCheck = await pool.query(`
+      SELECT schema_name 
+      FROM information_schema.schemata 
+      WHERE schema_name = 'queen'
+    `);
+    
+    if (schemaCheck.rows.length > 0) {
+      console.log('Database schema already exists, skipping initialization');
+      return;
+    }
+    
+    // Schema doesn't exist, create it
+    const schemaPath = path.join(__dirname, 'schema-v2.sql');
+    const schema = fs.readFileSync(schemaPath, 'utf8');
+    
+    await pool.query(schema);
+    console.log('Database schema V2 initialized');
+  } catch (error) {
+    console.error('Failed to initialize database schema:', error);
+    throw error;
+  }
+};
+
+// Valid transaction isolation levels
+const VALID_ISOLATION_LEVELS = [
+  'READ COMMITTED',
+  'REPEATABLE READ', 
+  'SERIALIZABLE'
+];
+
+// Helper for transactions with retry logic
+export const withTransaction = async (pool, callback, isolationLevel = 'READ COMMITTED') => {
+  // Validate isolation level
+  if (isolationLevel && !VALID_ISOLATION_LEVELS.includes(isolationLevel)) {
+    throw new Error(`Invalid isolation level: ${isolationLevel}`);
+  }
+  
+  const maxAttempts = 3;
+  let attempt = 1;
+  
+  while (attempt <= maxAttempts) {
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      
+      if (isolationLevel) {
+        await client.query(`SET TRANSACTION ISOLATION LEVEL ${isolationLevel}`);
+      }
+      
+      // Set timeouts to prevent long blocks
+      await client.query('SET LOCAL statement_timeout = 30000'); // 30 seconds
+      await client.query('SET LOCAL lock_timeout = 5000'); // 5 seconds
+      
+      const result = await callback(client);
+      await client.query('COMMIT');
+      return result;
+    } catch (error) {
+      await client.query('ROLLBACK');
+      
+      // Check for serialization failure or deadlock
+      if ((error.code === '40001' || error.code === '40P01') && attempt < maxAttempts) {
+        // Exponential backoff: 100ms, 200ms, 400ms
+        const delay = Math.min(100 * Math.pow(2, attempt - 1), 1000);
+        await new Promise(resolve => setTimeout(resolve, delay));
+        attempt++;
+        console.log(`Transaction retry attempt ${attempt}/${maxAttempts} after ${error.code}`);
+        continue;
+      }
+      
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  
+  throw new Error('Max transaction retry attempts exceeded');
+};

package/src/database/poolManager.js

@@ -0,0 +1,192 @@
+/**
+ * Connection Pool Manager for High Concurrency
+ * 
+ * This module provides optimized connection pooling for high-throughput scenarios
+ */
+
+import pg from 'pg';
+import appConfig from '../config.js';
+
+const { Pool } = pg;
+
+export class PoolManager {
+  constructor(config) {
+    this.config = {
+      user: appConfig.DATABASE.USER,
+      host: appConfig.DATABASE.HOST,
+      database: appConfig.DATABASE.DATABASE,
+      password: appConfig.DATABASE.PASSWORD,
+      port: appConfig.DATABASE.PORT,
+      max: appConfig.DATABASE.POOL_SIZE,
+      idleTimeoutMillis: appConfig.DATABASE.IDLE_TIMEOUT,
+      connectionTimeoutMillis: appConfig.DATABASE.CONNECTION_TIMEOUT,
+      ...config
+    };
+    
+    this.pool = new Pool(this.config);
+    this.waitingQueue = [];
+    this.activeConnections = 0;
+    this.maxRetries = appConfig.DATABASE.MAX_RETRIES;
+    
+    // Monitor pool events
+    this.pool.on('connect', () => {
+      this.activeConnections++;
+    });
+    
+    this.pool.on('remove', () => {
+      this.activeConnections--;
+    });
+    
+    this.pool.on('error', (err) => {
+      console.error('Unexpected pool error:', err);
+    });
+  }
+  
+  /**
+   * Execute a query with automatic retry and connection management
+   */
+  async query(text, params, retries = this.maxRetries) {
+    for (let attempt = 0; attempt < retries; attempt++) {
+      try {
+        return await this.pool.query(text, params);
+      } catch (error) {
+        if (error.message.includes('timeout exceeded when trying to connect')) {
+          // Connection timeout - retry with exponential backoff
+          if (attempt < retries - 1) {
+            const delay = Math.min(100 * Math.pow(2, attempt), 1000);
+            await new Promise(resolve => setTimeout(resolve, delay));
+            continue;
+          }
+        }
+        throw error;
+      }
+    }
+  }
+  
+  /**
+   * Get a client with retry logic
+   */
+  async getClient(retries = this.maxRetries) {
+    for (let attempt = 0; attempt < retries; attempt++) {
+      try {
+        const client = await this.pool.connect();
+        
+        // Wrap release to ensure proper cleanup
+        const originalRelease = client.release.bind(client);
+        client.release = (err) => {
+          originalRelease(err);
+          this.processWaitingQueue();
+        };
+        
+        return client;
+      } catch (error) {
+        if (error.message.includes('timeout exceeded when trying to connect')) {
+          if (attempt < retries - 1) {
+            const delay = Math.min(100 * Math.pow(2, attempt), 1000);
+            await new Promise(resolve => setTimeout(resolve, delay));
+            continue;
+          }
+        }
+        throw error;
+      }
+    }
+  }
+  
+  /**
+   * Execute a function with a client, ensuring proper cleanup
+   */
+  async withClient(fn) {
+    const client = await this.getClient();
+    try {
+      return await fn(client);
+    } finally {
+      client.release();
+    }
+  }
+  
+  /**
+   * Execute multiple queries in parallel with connection management
+   */
+  async parallelQueries(queries) {
+    const promises = queries.map(({ text, params }) => 
+      this.query(text, params)
+    );
+    return Promise.all(promises);
+  }
+  
+  /**
+   * Batch execute with optimal connection usage
+   */
+  async batchExecute(items, batchSize, executeFn) {
+    const results = [];
+    const batches = [];
+    
+    // Split items into batches
+    for (let i = 0; i < items.length; i += batchSize) {
+      batches.push(items.slice(i, i + batchSize));
+    }
+    
+    // Process batches with controlled concurrency
+    const concurrency = Math.min(Math.floor(this.config.max / 2), 10);
+    
+    for (let i = 0; i < batches.length; i += concurrency) {
+      const batchPromises = batches
+        .slice(i, i + concurrency)
+        .map(batch => this.withClient(client => executeFn(client, batch)));
+      
+      const batchResults = await Promise.all(batchPromises);
+      results.push(...batchResults.flat());
+    }
+    
+    return results;
+  }
+  
+  /**
+   * Process any waiting queue operations
+   */
+  processWaitingQueue() {
+    if (this.waitingQueue.length > 0 && this.pool.idleCount > 0) {
+      const { resolve } = this.waitingQueue.shift();
+      this.getClient().then(resolve).catch(() => {
+        // Re-queue if failed
+        this.waitingQueue.push({ resolve });
+      });
+    }
+  }
+  
+  /**
+   * Get pool statistics
+   */
+  getStats() {
+    return {
+      total: this.pool.totalCount,
+      idle: this.pool.idleCount,
+      waiting: this.pool.waitingCount,
+      active: this.activeConnections,
+      queueLength: this.waitingQueue.length,
+      config: {
+        max: this.config.max,
+        connectionTimeout: this.config.connectionTimeoutMillis
+      }
+    };
+  }
+  
+  /**
+   * Gracefully close the pool
+   */
+  async close() {
+    await this.pool.end();
+  }
+}
+
+// Create a singleton instance
+let poolManager;
+
+export const getPoolManager = (config) => {
+  if (!poolManager) {
+    poolManager = new PoolManager(config);
+  }
+  return poolManager;
+};
+
+export default PoolManager;