bunsane 0.1.4 → 0.2.0

package/database/IndexingStrategy.ts

@@ -0,0 +1,342 @@
+import db from "./index";
+import { logger } from "../core/Logger";
+
+const validateIdentifier = (str: string, maxLength: number = 64): string => {
+    if (!str || typeof str !== 'string' || str.length === 0 || str.length > maxLength) {
+        throw new Error(`Invalid identifier: ${str}`);
+    }
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(str)) {
+        throw new Error(`Invalid identifier format: ${str}`);
+    }
+    return str;
+};
+
+export type IndexType = 'gin' | 'btree' | 'hash' | 'numeric';
+
+export interface IndexDefinition {
+    tableName: string;
+    field: string;
+    indexType: IndexType;
+    isDateField?: boolean;
+}
+
+/**
+ * Ensures a JSONB path-specific index exists on a table
+ * @param tableName The table name to create index on
+ * @param field The JSONB field path to index
+ * @param indexType The type of index to create
+ * @param isDateField Whether this field should be cast to DATE for BTREE indexing
+ */
+export const ensureJSONBPathIndex = async (
+    tableName: string,
+    field: string,
+    indexType: IndexType = 'gin',
+    isDateField: boolean = false
+): Promise<void> => {
+    tableName = validateIdentifier(tableName);
+    field = validateIdentifier(field);
+
+    const indexName = `idx_${tableName}_${field}_${indexType}${isDateField ? '_date' : ''}`;
+
+    try {
+
+        logger.trace(`Ensuring ${indexType.toUpperCase()} index ${indexName} on ${tableName} for field ${field}${isDateField ? ' (date field - indexed as text)' : ''}`);
+
+        // Check if index already exists
+        const existingIndexes = await db.unsafe(`
+            SELECT indexname
+            FROM pg_indexes
+            WHERE tablename = '${tableName}' AND indexname = '${indexName}'
+        `);
+
+        if (existingIndexes.length > 0) {
+            logger.trace(`Index ${indexName} already exists`);
+            return;
+        }
+
+        // Check if table is partitioned
+        const partitionCheck = await db.unsafe(`
+            SELECT relkind
+            FROM pg_class
+            WHERE relname = '${tableName}' AND relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'public')
+        `);
+
+        const isPartitioned = partitionCheck.length > 0 && partitionCheck[0].relkind === 'p';
+        const useConcurrently = !isPartitioned && !process.env.USE_PGLITE;
+
+        let indexSQL: string;
+
+        switch (indexType) {
+            case 'gin':
+                // GIN indexes always use CONCURRENTLY for non-blocking operation (if not partitioned)
+                indexSQL = `CREATE INDEX${useConcurrently ? ' CONCURRENTLY' : ''} ${indexName} ON ${tableName} USING GIN ((data->'${field}') jsonb_path_ops)`;
+                break;
+
+            case 'btree':
+                if (isDateField) {
+                    // BTREE index on date field - store as text and let PostgreSQL handle conversions at query time
+                    // Note: Direct casting in index expressions requires IMMUTABLE functions
+                    // Storing as text allows the index to work while queries can still cast when filtering
+                    indexSQL = `CREATE INDEX${useConcurrently ? ' CONCURRENTLY' : ''} ${indexName} ON ${tableName} ((data->>'${field}'))`;
+                } else {
+                    // BTREE index on text field
+                    indexSQL = `CREATE INDEX${useConcurrently ? ' CONCURRENTLY' : ''} ${indexName} ON ${tableName} ((data->>'${field}'))`;
+                }
+                break;
+
+            case 'hash':
+                // HASH index (generally not recommended for JSONB fields)
+                indexSQL = `CREATE INDEX${useConcurrently ? ' CONCURRENTLY' : ''} ${indexName} ON ${tableName} USING HASH ((data->>'${field}'))`;
+                break;
+
+            default:
+                throw new Error(`Unsupported index type: ${indexType}`);
+        }
+
+        logger.trace(`Creating index with SQL: ${indexSQL}`);
+        await db.unsafe(indexSQL);
+        logger.info(`Created ${indexType.toUpperCase()} index ${indexName} on ${tableName}${useConcurrently ? ' (concurrently)' : ' (blocking)'}`);
+
+    } catch (error: any) {
+        // Check if the error is about duplicate key or relation already exists (race condition handling)
+        if (error.message && (
+            error.message.includes('duplicate key value violates unique constraint "pg_class_relname_nsp_index"') ||
+            error.message.includes('already exists') ||
+            error.code === '42P07' // PostgreSQL error code for duplicate_table/relation
+        )) {
+            logger.trace(`Index ${indexName} already exists (confirmed by error), skipping creation`);
+            return;
+        }
+        // Handle deadlock by checking if index was created by another process
+        if (error.code === '40P01' || (error.message && error.message.includes('deadlock'))) {
+            logger.warn(`Deadlock detected while creating index ${indexName}, checking if it exists now...`);
+            // Wait a bit and check if index exists now (created by another process)
+            await new Promise(resolve => setTimeout(resolve, 500));
+            const checkAgain = await db.unsafe(`
+                SELECT indexname FROM pg_indexes
+                WHERE tablename = '${tableName}' AND indexname = '${indexName}'
+            `);
+            if (checkAgain.length > 0) {
+                logger.trace(`Index ${indexName} was created by another process during deadlock`);
+                return;
+            }
+            // If still doesn't exist, log but don't throw - index creation is best-effort
+            logger.warn(`Index ${indexName} still doesn't exist after deadlock, skipping`);
+            return;
+        }
+        logger.error(`Failed to create ${indexType} index on ${tableName} for field ${field}: ${error}`);
+        throw error;
+    }
+};
+
+/**
+ * Ensures multiple JSONB path indexes exist on a table
+ * @param tableName The table name to create indexes on
+ * @param indexDefinitions Array of index definitions to create
+ */
+export const ensureMultipleJSONBPathIndexes = async (
+    tableName: string,
+    indexDefinitions: IndexDefinition[]
+): Promise<void> => {
+    for (const def of indexDefinitions) {
+        if (def.indexType === 'numeric') {
+            // Use numeric index for range queries
+            await ensureNumericIndex(def.tableName, def.field);
+        } else {
+            await ensureJSONBPathIndex(
+                def.tableName,
+                def.field,
+                def.indexType,
+                def.isDateField
+            );
+        }
+    }
+};
+
+/**
+ * Analyzes a table to update query planner statistics
+ * @param tableName The table name to analyze
+ */
+export const analyzeTable = async (tableName: string): Promise<void> => {
+    try {
+        tableName = validateIdentifier(tableName);
+        logger.trace(`Running ANALYZE on table ${tableName}`);
+        await db.unsafe(`ANALYZE ${tableName}`);
+        logger.info(`Completed ANALYZE on table ${tableName}`);
+    } catch (error) {
+        logger.error(`Failed to ANALYZE table ${tableName}: ${error}`);
+        throw error;
+    }
+};
+
+/**
+ * Analyzes all component partition tables
+ */
+/**
+ * Creates a functional index on a JSONB numeric field for efficient range queries.
+ * This is critical for queries like `WHERE (data->>'age')::numeric BETWEEN 25 AND 35`
+ *
+ * @param tableName The table name to create index on
+ * @param field The JSONB field path containing numeric values
+ */
+export const ensureNumericIndex = async (
+    tableName: string,
+    field: string
+): Promise<void> => {
+    tableName = validateIdentifier(tableName);
+    field = validateIdentifier(field);
+
+    const indexName = `idx_${tableName}_${field}_numeric`;
+
+    try {
+        logger.trace(`Ensuring numeric index ${indexName} on ${tableName} for field ${field}`);
+
+        // Check if index already exists
+        const existingIndexes = await db.unsafe(`
+            SELECT indexname
+            FROM pg_indexes
+            WHERE tablename = '${tableName}' AND indexname = '${indexName}'
+        `);
+
+        if (existingIndexes.length > 0) {
+            logger.trace(`Index ${indexName} already exists`);
+            return;
+        }
+
+        // Check if table is partitioned
+        const partitionCheck = await db.unsafe(`
+            SELECT relkind
+            FROM pg_class
+            WHERE relname = '${tableName}' AND relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'public')
+        `);
+
+        const isPartitioned = partitionCheck.length > 0 && partitionCheck[0].relkind === 'p';
+        const useConcurrently = !isPartitioned && !process.env.USE_PGLITE;
+
+        // Create a partial index that only includes rows where the field is a valid number
+        // This prevents errors when some rows have non-numeric values
+        const indexSQL = `CREATE INDEX${useConcurrently ? ' CONCURRENTLY' : ''} ${indexName}
+            ON ${tableName} (((data->>'${field}')::numeric))
+            WHERE data->>'${field}' IS NOT NULL
+            AND data->>'${field}' ~ '^-?[0-9]+\\.?[0-9]*$'`;
+
+        logger.trace(`Creating numeric index with SQL: ${indexSQL}`);
+        await db.unsafe(indexSQL);
+        logger.info(`Created numeric index ${indexName} on ${tableName}${useConcurrently ? ' (concurrently)' : ' (blocking)'}`);
+
+    } catch (error: any) {
+        if (error.message && (
+            error.message.includes('already exists') ||
+            error.code === '42P07'
+        )) {
+            logger.trace(`Index ${indexName} already exists (confirmed by error), skipping creation`);
+            return;
+        }
+        if (error.code === '40P01' || (error.message && error.message.includes('deadlock'))) {
+            logger.warn(`Deadlock detected while creating index ${indexName}, skipping`);
+            return;
+        }
+        logger.error(`Failed to create numeric index on ${tableName} for field ${field}: ${error}`);
+        throw error;
+    }
+};
+
+/**
+ * Creates a composite index on multiple JSONB fields for efficient combined filter queries.
+ * Useful for queries like `WHERE status = 'active' AND age >= 21`
+ *
+ * @param tableName The table name to create index on
+ * @param fields Array of field definitions with type information
+ */
+export const ensureCompositeIndex = async (
+    tableName: string,
+    fields: Array<{ name: string; type: 'text' | 'numeric' | 'boolean' }>
+): Promise<void> => {
+    tableName = validateIdentifier(tableName);
+    fields.forEach(f => validateIdentifier(f.name));
+
+    const fieldNames = fields.map(f => f.name).join('_');
+    const indexName = `idx_${tableName}_${fieldNames}_composite`;
+
+    try {
+        logger.trace(`Ensuring composite index ${indexName} on ${tableName}`);
+
+        // Check if index already exists
+        const existingIndexes = await db.unsafe(`
+            SELECT indexname
+            FROM pg_indexes
+            WHERE tablename = '${tableName}' AND indexname = '${indexName}'
+        `);
+
+        if (existingIndexes.length > 0) {
+            logger.trace(`Index ${indexName} already exists`);
+            return;
+        }
+
+        // Check if table is partitioned
+        const partitionCheck = await db.unsafe(`
+            SELECT relkind
+            FROM pg_class
+            WHERE relname = '${tableName}' AND relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'public')
+        `);
+
+        const isPartitioned = partitionCheck.length > 0 && partitionCheck[0].relkind === 'p';
+        const useConcurrently = !isPartitioned && !process.env.USE_PGLITE;
+
+        // Build index expressions for each field
+        const indexExpressions = fields.map(f => {
+            switch (f.type) {
+                case 'numeric':
+                    return `((data->>'${f.name}')::numeric)`;
+                case 'boolean':
+                    return `((data->>'${f.name}')::boolean)`;
+                default:
+                    return `(data->>'${f.name}')`;
+            }
+        }).join(', ');
+
+        const indexSQL = `CREATE INDEX${useConcurrently ? ' CONCURRENTLY' : ''} ${indexName}
+            ON ${tableName} (${indexExpressions})`;
+
+        logger.trace(`Creating composite index with SQL: ${indexSQL}`);
+        await db.unsafe(indexSQL);
+        logger.info(`Created composite index ${indexName} on ${tableName}${useConcurrently ? ' (concurrently)' : ' (blocking)'}`);
+
+    } catch (error: any) {
+        if (error.message && (
+            error.message.includes('already exists') ||
+            error.code === '42P07'
+        )) {
+            logger.trace(`Index ${indexName} already exists (confirmed by error), skipping creation`);
+            return;
+        }
+        if (error.code === '40P01' || (error.message && error.message.includes('deadlock'))) {
+            logger.warn(`Deadlock detected while creating index ${indexName}, skipping`);
+            return;
+        }
+        logger.error(`Failed to create composite index on ${tableName}: ${error}`);
+        throw error;
+    }
+};
+
+export const analyzeAllComponentTables = async (): Promise<void> => {
+    try {
+        logger.trace(`Analyzing all component tables`);
+
+        // Get all component partition tables
+        const tables = await db.unsafe(`
+            SELECT tablename
+            FROM pg_tables
+            WHERE tablename LIKE 'components_%' AND schemaname = 'public'
+        `);
+
+        for (const row of tables) {
+            await analyzeTable(row.tablename);
+        }
+
+        logger.info(`Completed ANALYZE on ${tables.length} component tables`);
+    } catch (error) {
+        logger.error(`Failed to analyze component tables: ${error}`);
+        throw error;
+    }
+};

package/database/PreparedStatementCache.ts

@@ -0,0 +1,226 @@
+import { logger } from "../core/Logger";
+
+export interface CacheEntry {
+    sql: string;
+    preparedStatement: any; // Bun's SQL prepared statement type
+    lastUsed: number;
+    hitCount: number;
+    createdAt: number;
+}
+
+export interface CacheStats {
+    size: number;
+    maxSize: number;
+    hits: number;
+    misses: number;
+    evictions: number;
+    totalPlanningTimeSaved: number;
+    averagePlanningTimeSaved: number;
+}
+
+/**
+ * LRU Cache for prepared statements to eliminate PostgreSQL planning overhead
+ * for repeated query patterns in the Bunsane Query system.
+ */
+export class PreparedStatementCache {
+    private cache: Map<string, CacheEntry> = new Map();
+    private maxSize: number;
+    private stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+        totalPlanningTimeSaved: 0
+    };
+
+    constructor(maxSize: number = 100) {
+        this.maxSize = maxSize;
+        logger.info(`Initialized PreparedStatementCache with max size: ${maxSize}`);
+    }
+
+    /**
+     * Generate a cache key from QueryContext fingerprint
+     */
+    public generateCacheKey(context: {
+        componentIds: Set<string>;
+        componentFilters: Map<string, any[]>;
+        sortOrders: any[];
+        excludedComponentIds: Set<string>;
+        hasCTE: boolean;
+        cteName: string;
+    }): string {
+        // Create a deterministic fingerprint of the query structure
+        const components = Array.from(context.componentIds).sort().join(',');
+        const excludedComponents = Array.from(context.excludedComponentIds).sort().join(',');
+        const filters = Array.from(context.componentFilters.entries())
+            .map(([typeId, filters]) => `${typeId}:${filters.map(f => `${f.field}${f.operator}`).sort().join('|')}`)
+            .sort()
+            .join(';');
+        const sorts = context.sortOrders
+            .map(s => `${s.component}.${s.property}:${s.direction}`)
+            .sort()
+            .join(',');
+
+        const key = `${components}|${excludedComponents}|${filters}|${sorts}|${context.hasCTE}|${context.cteName}`;
+        return key;
+    }
+
+    /**
+     * Get a prepared statement from cache, or create new one
+     */
+    public async getOrCreate(sql: string, key: string, db: any): Promise<{ statement: any; isHit: boolean }> {
+        const now = Date.now();
+        const existing = this.cache.get(key);
+
+        if (existing) {
+            // Cache hit
+            existing.lastUsed = now;
+            existing.hitCount++;
+            this.stats.hits++;
+            // logger.trace(`Cache hit for key: ${key.substring(0, 50)}...`);
+            return { statement: existing.preparedStatement, isHit: true };
+        }
+
+        // Cache miss - create new prepared statement
+        this.stats.misses++;
+        logger.trace(`Cache miss for key: ${key.substring(0, 50)}..., creating prepared statement`);
+
+        // Create prepared statement using Bun's SQL
+        // Note: Bun's SQL may not have explicit prepare(), so we'll use the query as-is
+        // In postgres.js this would be: db.unsafe(sql, params, { prepare: true })
+        // For Bun, we may need to adapt this
+        const preparedStatement = { sql, _isPrepared: true }; // Placeholder
+
+        const entry: CacheEntry = {
+            sql,
+            preparedStatement,
+            lastUsed: now,
+            hitCount: 1,
+            createdAt: now
+        };
+
+        // Evict if at capacity
+        if (this.cache.size >= this.maxSize) {
+            this.evictLRU();
+        }
+
+        this.cache.set(key, entry);
+        return { statement: preparedStatement, isHit: false };
+    }
+
+    /**
+     * Execute a prepared statement with parameters
+     */
+    public async execute(statement: any, params: any[], db: any): Promise<any[]> {
+        // Validate params to catch empty strings that would cause UUID parsing errors
+        for (let i = 0; i < params.length; i++) {
+            const param = params[i];
+            if (param === '' || (typeof param === 'string' && param.trim() === '')) {
+                logger.error(`[PreparedStatementCache] Empty string parameter at position ${i + 1}`);
+                logger.error(`[PreparedStatementCache] SQL: ${statement.sql}`);
+                logger.error(`[PreparedStatementCache] All params: ${JSON.stringify(params)}`);
+                throw new Error(`PreparedStatementCache.execute: Parameter $${i + 1} is an empty string. SQL: ${statement.sql.substring(0, 100)}...`);
+            }
+        }
+        
+        // For Bun's SQL, we still use db.unsafe() but with the prepared statement concept
+        // In a real implementation, this might use a prepared statement pool
+        return await db.unsafe(statement.sql, params);
+    }
+
+    /**
+     * Evict least recently used entry
+     */
+    private evictLRU(): void {
+        let oldestKey: string | null = null;
+        let oldestTime = Date.now();
+
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.lastUsed < oldestTime) {
+                oldestTime = entry.lastUsed;
+                oldestKey = key;
+            }
+        }
+
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            this.stats.evictions++;
+            logger.trace(`Evicted LRU cache entry: ${oldestKey.substring(0, 50)}...`);
+        }
+    }
+
+    /**
+     * Invalidate cache entries when component schemas change
+     */
+    public invalidateByComponent(componentTypeId: string): void {
+        const keysToDelete: string[] = [];
+
+        for (const [key, entry] of this.cache.entries()) {
+            if (key.includes(componentTypeId)) {
+                keysToDelete.push(key);
+            }
+        }
+
+        keysToDelete.forEach(key => {
+            this.cache.delete(key);
+            logger.trace(`Invalidated cache entry due to component change: ${key.substring(0, 50)}...`);
+        });
+
+        logger.info(`Invalidated ${keysToDelete.length} cache entries for component: ${componentTypeId}`);
+    }
+
+    /**
+     * Clear entire cache
+     */
+    public clear(): void {
+        const size = this.cache.size;
+        this.cache.clear();
+        logger.info(`Cleared prepared statement cache (${size} entries)`);
+    }
+
+    /**
+     * Get cache statistics
+     */
+    public getStats(): CacheStats {
+        const totalRequests = this.stats.hits + this.stats.misses;
+        const hitRate = totalRequests > 0 ? this.stats.hits / totalRequests : 0;
+
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            evictions: this.stats.evictions,
+            totalPlanningTimeSaved: this.stats.totalPlanningTimeSaved,
+            averagePlanningTimeSaved: this.stats.totalPlanningTimeSaved / Math.max(this.stats.hits, 1)
+        };
+    }
+
+    /**
+     * Warm up cache with common query patterns
+     */
+    public async warmUp(commonQueries: Array<{ sql: string; key: string }>, db: any): Promise<void> {
+        logger.info(`Warming up prepared statement cache with ${commonQueries.length} queries`);
+
+        for (const query of commonQueries) {
+            try {
+                await this.getOrCreate(query.sql, query.key, db);
+            } catch (error) {
+                logger.warn(`Failed to warm up query: ${error}`);
+            }
+        }
+
+        logger.info(`Cache warm-up complete. Cache size: ${this.cache.size}`);
+    }
+
+    /**
+     * Record planning time saved for metrics
+     */
+    public recordPlanningTimeSaved(timeMs: number): void {
+        this.stats.totalPlanningTimeSaved += timeMs;
+    }
+}
+
+// Global cache instance
+export const preparedStatementCache = new PreparedStatementCache(
+    parseInt(process.env.BUNSANE_QUERY_CACHE_SIZE || '100', 10)
+);

package/database/index.ts

@@ -1,17 +1,38 @@
 import {SQL} from "bun";
-import { logger } from "core/Logger";
+import { logger } from "../core/Logger";
 
 let connectionUrl = `postgres://${process.env.POSTGRES_USER}:${process.env.POSTGRES_PASSWORD}@${process.env.POSTGRES_HOST}:${process.env.POSTGRES_PORT ?? "5432"}/${process.env.POSTGRES_DB}`;
 if(process.env.DB_CONNECTION_URL) {
     connectionUrl = process.env.DB_CONNECTION_URL;
 }
-logger.info(`Database connection URL: ${connectionUrl}`);
+
+// Add statement_timeout only when explicitly configured (opt-in)
+// Note: PgBouncer rejects statement_timeout as a startup parameter — use PostgreSQL config or connect_query instead
+if (process.env.USE_PGLITE !== 'true' && process.env.DB_STATEMENT_TIMEOUT) {
+    try {
+        const urlObj = new URL(connectionUrl);
+        urlObj.searchParams.set('options', `-c statement_timeout=${process.env.DB_STATEMENT_TIMEOUT}`);
+        connectionUrl = urlObj.toString();
+    } catch {
+        // Non-standard URL format, skip statement_timeout
+    }
+}
+
+// Log connection URL with credentials redacted
+const redactedUrl = connectionUrl.replace(/:\/\/([^:]+):([^@]+)@/, '://$1:****@');
+logger.info(`Database connection URL: ${redactedUrl}`);
+
+// OPTIMIZED: Reduced from 20 to 10 to prevent overwhelming PGBouncer
+// With 5 app instances: 5 × 10 = 50 connections (well under PGBouncer's limit)
+const maxConnections = parseInt(process.env.POSTGRES_MAX_CONNECTIONS ?? '10', 10);
+logger.info(`Connection pool size: ${maxConnections} connections`);
+
 const db = new SQL({
     url: connectionUrl,
-    // Connection pool settings - FIXED
-    max: parseInt(process.env.POSTGRES_MAX_CONNECTIONS ?? '20', 10), // Increased max connections
-    idleTimeout: 30000, // Close idle connections after 30s (was 0)
-    maxLifetime: 600000, // Connection lifetime 10 minutes (was 0 = forever)
+    // Connection pool settings - OPTIMIZED for PGBouncer
+    max: maxConnections,
+    idleTimeout: 30000, // Close idle connections after 30s
+    maxLifetime: 600000, // Connection lifetime 10 minutes
     connectionTimeout: 30, // Timeout when establishing new connections
     onclose: (err) => {
         if (err) {
@@ -22,9 +43,13 @@ const db = new SQL({
                 logger.error(err);
             }
         } else {
-            logger.info("Database connection closed.");
+            logger.trace("Database connection closed gracefully.");
         }   
     },
+    onconnect: () => {
+        // Log when new connections are created
+        logger.trace("New database connection established");
+    }
 });
 
 

package/database/sqlHelpers.ts

@@ -1,5 +1,17 @@
 export function inList<T>(values: T[], paramIndex: number): { sql: string, params: any[], newParamIndex: number } {
   if (values.length === 0) return { sql: '()', params: [], newParamIndex: paramIndex };
-  const placeholders = Array.from({length: values.length}, (_, i) => `$${paramIndex + i}`).join(', ');
-  return { sql: `(${placeholders})`, params: values, newParamIndex: paramIndex + values.length };
+  
+  // Filter out empty strings to prevent PostgreSQL UUID parsing errors
+  const filteredValues = values.filter(v => {
+    if (v === '' || (typeof v === 'string' && v.trim() === '')) {
+      console.error(`[sqlHelpers.inList] Empty string value detected in array, filtering out`);
+      return false;
+    }
+    return true;
+  });
+  
+  if (filteredValues.length === 0) return { sql: '()', params: [], newParamIndex: paramIndex };
+  
+  const placeholders = Array.from({length: filteredValues.length}, (_, i) => `$${paramIndex + i}`).join(', ');
+  return { sql: `(${placeholders})`, params: filteredValues, newParamIndex: paramIndex + filteredValues.length };
 }