@dotdo/postgres 0.1.0

package/dist/routing/index.js

@@ -0,0 +1,59 @@
+/**
+ * Query Routing Module
+ *
+ * Provides intelligent query routing based on CPU time estimation:
+ * - <50ms CPU time -> Worker (cheaper due to CPU time billing)
+ * - >50ms CPU time -> Durable Object (cheaper due to wall time billing)
+ *
+ * Features:
+ * - QueryComplexityEstimator: Static analysis of query complexity
+ * - RuntimeRouter: Routes queries to optimal runtime
+ * - AdaptiveRouter: Learns from execution history
+ * - CostMetrics: Tracks and analyzes routing costs
+ * - WebSocketPool: Connection pool with hibernation support
+ * - CircuitBreaker: Resilience pattern for DO failover with exponential backoff
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   QueryComplexityEstimator,
+ *   RuntimeRouter,
+ *   AdaptiveRouter,
+ *   CostMetrics,
+ *   WebSocketPool,
+ *   CircuitBreaker,
+ * } from '@dotdo/postgres/routing'
+ *
+ * // Create estimator
+ * const estimator = new QueryComplexityEstimator({
+ *   cpuTimeThresholdMs: 50,
+ *   tableSizeHints: { users: 10000 },
+ * })
+ *
+ * // Estimate query complexity
+ * const estimate = estimator.estimate('SELECT * FROM users WHERE id = $1')
+ * console.log(estimate.recommendation) // 'worker' or 'durable-object'
+ *
+ * // Use runtime router
+ * const router = new RuntimeRouter({
+ *   cpuTimeThresholdMs: 50,
+ *   executors: { worker: workerExecutor, 'durable-object': doExecutor },
+ * })
+ * const result = await router.execute('SELECT * FROM users')
+ * ```
+ */
+// Query Complexity Estimator
+export { QueryComplexityEstimator, } from './query-complexity-estimator';
+// Runtime Router
+export { RuntimeRouter, } from './runtime-router';
+// Adaptive Router
+export { AdaptiveRouter, } from './adaptive-router';
+// Cost Metrics
+export { CostMetricsCollector, } from './cost-metrics';
+// WebSocket Pool
+export { WebSocketPool, PooledConnection, } from './websocket-pool';
+// Request Coalescing
+export { RequestCoalescer, createCoalescedExecutor, fnv1aHash, createFnvHashFn, } from './request-coalescing';
+// Circuit Breaker
+export { CircuitBreaker, CircuitOpenError, DOCircuitBreakerWrapper, DefaultMetricsCollector, } from './circuit-breaker';
+//# sourceMappingURL=index.js.map

package/dist/routing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,6BAA6B;AAC7B,OAAO,EACL,wBAAwB,GACzB,MAAM,8BAA8B,CAAA;AAUrC,iBAAiB;AACjB,OAAO,EACL,aAAa,GACd,MAAM,kBAAkB,CAAA;AAczB,kBAAkB;AAClB,OAAO,EACL,cAAc,GACf,MAAM,mBAAmB,CAAA;AAe1B,eAAe;AACf,OAAO,EACL,oBAAoB,GACrB,MAAM,gBAAgB,CAAA;AAgBvB,iBAAiB;AACjB,OAAO,EACL,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAA;AASzB,qBAAqB;AACrB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,SAAS,EACT,eAAe,GAChB,MAAM,sBAAsB,CAAA;AAS7B,kBAAkB;AAClB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,mBAAmB,CAAA"}

package/dist/routing/query-complexity-estimator.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Query Complexity Estimator
+ *
+ * Task: postgres-d6g.1
+ *
+ * Estimates SQL query CPU time to determine optimal routing:
+ * - <50ms CPU time -> Worker (cheaper due to CPU time billing)
+ * - >50ms CPU time -> Durable Object (cheaper due to wall time billing)
+ *
+ * The estimator analyzes query structure without actually executing it,
+ * looking for complexity indicators like JOINs, aggregations, subqueries, etc.
+ */
+export type RuntimeRecommendation = 'worker' | 'durable-object';
+export type ConfidenceLevel = 'high' | 'medium' | 'low';
+export interface QueryComplexityFactors {
+    joinCount: number;
+    subqueryCount: number;
+    unionCount: number;
+    cteCount: number;
+    windowFunctionCount: number;
+    hasAggregation: boolean;
+    hasGroupBy: boolean;
+    hasHaving: boolean;
+    hasOrderBy: boolean;
+    hasDistinct: boolean;
+    hasLimit: boolean;
+    limitValue: number | null;
+    estimatedRowsScanned: number;
+    tablesReferenced: string[];
+    hasFullTableScan: boolean;
+    isTransaction: boolean;
+    queryType: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'TRANSACTION' | 'OTHER';
+}
+export interface ComplexityEstimate {
+    estimatedMs: number;
+    recommendation: RuntimeRecommendation;
+    confidence: ConfidenceLevel;
+    factors: QueryComplexityFactors;
+    threshold: number;
+}
+export interface EstimatorOptions {
+    /** CPU time threshold in ms (default: 50) */
+    cpuTimeThresholdMs?: number;
+    /** Hints about table sizes (table name -> estimated row count) */
+    tableSizeHints?: Record<string, number>;
+    /** Known indexed columns (table name -> column names) */
+    indexedColumns?: Record<string, string[]>;
+}
+export declare class QueryComplexityEstimator {
+    private options;
+    constructor(options?: EstimatorOptions);
+    /**
+     * Estimate the complexity of a SQL query
+     */
+    estimate(sql: string): ComplexityEstimate;
+    /**
+     * Estimate multiple queries efficiently
+     */
+    estimateBatch(queries: string[]): ComplexityEstimate[];
+    private removeComments;
+    private analyzeQuery;
+    private determineQueryType;
+    private countMatches;
+    private extractTables;
+    private isSqlKeyword;
+    private analyzeTableAccess;
+    private checkIndexUsage;
+    private calculateEstimatedMs;
+    private determineConfidence;
+    private createEstimate;
+    private createEmptyFactors;
+}
+//# sourceMappingURL=query-complexity-estimator.d.ts.map

package/dist/routing/query-complexity-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-complexity-estimator.d.ts","sourceRoot":"","sources":["../../src/routing/query-complexity-estimator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,gBAAgB,CAAA;AAC/D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEvD,MAAM,WAAW,sBAAsB;IAErC,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,mBAAmB,EAAE,MAAM,CAAA;IAG3B,cAAc,EAAE,OAAO,CAAA;IACvB,UAAU,EAAE,OAAO,CAAA;IACnB,SAAS,EAAE,OAAO,CAAA;IAClB,UAAU,EAAE,OAAO,CAAA;IACnB,WAAW,EAAE,OAAO,CAAA;IAGpB,QAAQ,EAAE,OAAO,CAAA;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAGzB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,gBAAgB,EAAE,OAAO,CAAA;IAGzB,aAAa,EAAE,OAAO,CAAA;IAGtB,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,OAAO,CAAA;CAC/E;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,qBAAqB,CAAA;IACrC,UAAU,EAAE,eAAe,CAAA;IAC3B,OAAO,EAAE,sBAAsB,CAAA;IAC/B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE3B,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEvC,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;CAC1C;AAoDD,qBAAa,wBAAwB;IACnC,OAAO,CAAC,OAAO,CAA4B;gBAE/B,OAAO,GAAE,gBAAqB;IAQ1C;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB;IAqBzC;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,kBAAkB,EAAE;IAItD,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,YAAY;IA2DpB,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,kBAAkB;IA6B1B,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,oBAAoB;IAiD5B,OAAO,CAAC,mBAAmB;IAsC3B,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,kBAAkB;CAqB3B"}

package/dist/routing/query-complexity-estimator.js

@@ -0,0 +1,327 @@
+/**
+ * Query Complexity Estimator
+ *
+ * Task: postgres-d6g.1
+ *
+ * Estimates SQL query CPU time to determine optimal routing:
+ * - <50ms CPU time -> Worker (cheaper due to CPU time billing)
+ * - >50ms CPU time -> Durable Object (cheaper due to wall time billing)
+ *
+ * The estimator analyzes query structure without actually executing it,
+ * looking for complexity indicators like JOINs, aggregations, subqueries, etc.
+ */
+// Default weights for complexity factors (in estimated milliseconds)
+const COMPLEXITY_WEIGHTS = {
+    baseQuery: 1, // Base cost for any query
+    perJoin: 15, // Each JOIN adds complexity
+    perSubquery: 20, // Subqueries are expensive
+    perUnion: 10, // UNION operations
+    perCte: 15, // CTEs (WITH clause)
+    perWindowFunction: 25, // Window functions are expensive
+    aggregation: 10, // Aggregation functions
+    groupBy: 8, // GROUP BY clause
+    having: 5, // HAVING clause
+    orderBy: 8, // ORDER BY clause
+    distinct: 10, // DISTINCT keyword
+    noLimit: 15, // No LIMIT on SELECT (full result)
+    fullTableScan: 20, // Full table scan indicator
+    largeTableMultiplier: 0.00001, // Per-row estimate for large tables
+    transaction: 5, // Transaction overhead
+};
+// Patterns for SQL analysis
+const SQL_PATTERNS = {
+    join: /\bJOIN\b/gi,
+    leftJoin: /\bLEFT\s+(?:OUTER\s+)?JOIN\b/gi,
+    rightJoin: /\bRIGHT\s+(?:OUTER\s+)?JOIN\b/gi,
+    innerJoin: /\bINNER\s+JOIN\b/gi,
+    crossJoin: /\bCROSS\s+JOIN\b/gi,
+    fullJoin: /\bFULL\s+(?:OUTER\s+)?JOIN\b/gi,
+    subquery: /\(\s*SELECT\b/gi,
+    union: /\bUNION(?:\s+ALL)?\b/gi,
+    cte: /(?:^|\bWITH\b|,)\s*\w+\s+AS\s*\(/gi, // Matches CTE definitions in WITH clause
+    windowFunction: /\b(ROW_NUMBER|RANK|DENSE_RANK|NTILE|LAG|LEAD|FIRST_VALUE|LAST_VALUE|NTH_VALUE)\s*\(/gi,
+    aggregation: /\b(COUNT|SUM|AVG|MIN|MAX|ARRAY_AGG|STRING_AGG|JSON_AGG)\s*\(/gi,
+    groupBy: /\bGROUP\s+BY\b/gi,
+    having: /\bHAVING\b/gi,
+    orderBy: /\bORDER\s+BY\b/gi,
+    distinct: /\bDISTINCT\b/gi,
+    limit: /\bLIMIT\s+(\d+)/gi,
+    from: /\bFROM\s+(\w+)/gi,
+    tableName: /(?:FROM|JOIN|INTO|UPDATE)\s+(\w+)/gi,
+    select: /^\s*SELECT\b/i,
+    insert: /^\s*INSERT\b/i,
+    update: /^\s*UPDATE\b/i,
+    delete: /^\s*DELETE\b/i,
+    begin: /^\s*BEGIN\b/i,
+    commit: /^\s*COMMIT\b/i,
+    rollback: /^\s*ROLLBACK\b/i,
+    comment: /--.*$|\/\*[\s\S]*?\*\//gm,
+    whereIndex: /WHERE\s+(\w+)\s*=/gi,
+};
+export class QueryComplexityEstimator {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            cpuTimeThresholdMs: options.cpuTimeThresholdMs ?? 50,
+            tableSizeHints: options.tableSizeHints ?? {},
+            indexedColumns: options.indexedColumns ?? {},
+        };
+    }
+    /**
+     * Estimate the complexity of a SQL query
+     */
+    estimate(sql) {
+        // Handle empty query
+        if (!sql || sql.trim() === '') {
+            return this.createEstimate(0, this.createEmptyFactors(), 'high');
+        }
+        // Remove comments for analysis
+        const cleanSql = this.removeComments(sql);
+        // Extract complexity factors
+        const factors = this.analyzeQuery(cleanSql);
+        // Calculate estimated milliseconds
+        const estimatedMs = this.calculateEstimatedMs(factors);
+        // Determine confidence based on query complexity
+        const confidence = this.determineConfidence(factors, cleanSql);
+        return this.createEstimate(estimatedMs, factors, confidence);
+    }
+    /**
+     * Estimate multiple queries efficiently
+     */
+    estimateBatch(queries) {
+        return queries.map(sql => this.estimate(sql));
+    }
+    removeComments(sql) {
+        return sql.replace(SQL_PATTERNS.comment, ' ');
+    }
+    analyzeQuery(sql) {
+        const upperSql = sql.toUpperCase();
+        // Determine query type
+        const queryType = this.determineQueryType(sql);
+        // Count structural elements
+        const joinCount = this.countMatches(sql, SQL_PATTERNS.join);
+        const subqueryCount = this.countMatches(sql, SQL_PATTERNS.subquery);
+        const unionCount = this.countMatches(sql, SQL_PATTERNS.union);
+        const cteCount = this.countMatches(sql, SQL_PATTERNS.cte);
+        const windowFunctionCount = this.countMatches(sql, SQL_PATTERNS.windowFunction);
+        // Boolean checks
+        const hasAggregation = SQL_PATTERNS.aggregation.test(sql);
+        const hasGroupBy = SQL_PATTERNS.groupBy.test(upperSql);
+        const hasHaving = SQL_PATTERNS.having.test(upperSql);
+        const hasOrderBy = SQL_PATTERNS.orderBy.test(upperSql);
+        const hasDistinct = SQL_PATTERNS.distinct.test(upperSql);
+        // LIMIT analysis
+        const limitMatch = sql.match(/\bLIMIT\s+(\d+)/i);
+        const hasLimit = !!limitMatch;
+        const limitValue = limitMatch?.[1] ? parseInt(limitMatch[1], 10) : null;
+        // Table analysis
+        const tablesReferenced = this.extractTables(sql);
+        const { estimatedRowsScanned, hasFullTableScan } = this.analyzeTableAccess(sql, tablesReferenced);
+        // Transaction check
+        const isTransaction = SQL_PATTERNS.begin.test(sql) ||
+            SQL_PATTERNS.commit.test(sql) ||
+            SQL_PATTERNS.rollback.test(sql);
+        return {
+            joinCount,
+            subqueryCount,
+            unionCount,
+            cteCount,
+            windowFunctionCount,
+            hasAggregation,
+            hasGroupBy,
+            hasHaving,
+            hasOrderBy,
+            hasDistinct,
+            hasLimit,
+            limitValue,
+            estimatedRowsScanned,
+            tablesReferenced,
+            hasFullTableScan,
+            isTransaction,
+            queryType,
+        };
+    }
+    determineQueryType(sql) {
+        const trimmed = sql.trim();
+        if (SQL_PATTERNS.select.test(trimmed))
+            return 'SELECT';
+        if (SQL_PATTERNS.insert.test(trimmed))
+            return 'INSERT';
+        if (SQL_PATTERNS.update.test(trimmed))
+            return 'UPDATE';
+        if (SQL_PATTERNS.delete.test(trimmed))
+            return 'DELETE';
+        if (SQL_PATTERNS.begin.test(trimmed) ||
+            SQL_PATTERNS.commit.test(trimmed) ||
+            SQL_PATTERNS.rollback.test(trimmed)) {
+            return 'TRANSACTION';
+        }
+        return 'OTHER';
+    }
+    countMatches(sql, pattern) {
+        // Reset lastIndex for global patterns
+        pattern.lastIndex = 0;
+        const matches = sql.match(pattern);
+        return matches ? matches.length : 0;
+    }
+    extractTables(sql) {
+        const tables = new Set();
+        const pattern = /(?:FROM|JOIN|INTO|UPDATE)\s+(\w+)/gi;
+        let match;
+        while ((match = pattern.exec(sql)) !== null) {
+            const tableName = match[1];
+            if (!tableName)
+                continue;
+            // Filter out SQL keywords that might be mistaken for tables
+            if (!this.isSqlKeyword(tableName.toLowerCase())) {
+                tables.add(tableName.toLowerCase());
+            }
+        }
+        return Array.from(tables);
+    }
+    isSqlKeyword(word) {
+        const keywords = new Set([
+            'select', 'from', 'where', 'and', 'or', 'not', 'in',
+            'exists', 'between', 'like', 'is', 'null', 'true', 'false',
+            'as', 'on', 'using', 'natural', 'cross', 'inner', 'outer',
+            'left', 'right', 'full', 'lateral',
+        ]);
+        return keywords.has(word.toLowerCase());
+    }
+    analyzeTableAccess(sql, tables) {
+        let estimatedRowsScanned = 0;
+        let hasFullTableScan = false;
+        for (const table of tables) {
+            const tableSize = this.options.tableSizeHints[table] ?? 1000; // Default 1K rows
+            // Check if query uses indexed columns for this table
+            const indexedCols = this.options.indexedColumns[table] ?? [];
+            const usesIndex = this.checkIndexUsage(sql, table, indexedCols);
+            if (usesIndex) {
+                // Indexed access: estimate small fraction of rows
+                estimatedRowsScanned += Math.min(tableSize * 0.01, 100);
+            }
+            else {
+                // Potential full scan
+                estimatedRowsScanned += tableSize;
+                if (tableSize > 10000) {
+                    hasFullTableScan = true;
+                }
+            }
+        }
+        return { estimatedRowsScanned, hasFullTableScan };
+    }
+    checkIndexUsage(sql, _table, indexedColumns) {
+        if (indexedColumns.length === 0)
+            return false;
+        // Simple heuristic: check if WHERE clause uses indexed columns
+        const wherePattern = new RegExp(`\\bWHERE\\b[^;]*\\b(${indexedColumns.join('|')})\\s*=`, 'i');
+        return wherePattern.test(sql);
+    }
+    calculateEstimatedMs(factors) {
+        let estimate = COMPLEXITY_WEIGHTS.baseQuery;
+        // Structural complexity
+        estimate += factors.joinCount * COMPLEXITY_WEIGHTS.perJoin;
+        estimate += factors.subqueryCount * COMPLEXITY_WEIGHTS.perSubquery;
+        estimate += factors.unionCount * COMPLEXITY_WEIGHTS.perUnion;
+        estimate += factors.cteCount * COMPLEXITY_WEIGHTS.perCte;
+        estimate += factors.windowFunctionCount * COMPLEXITY_WEIGHTS.perWindowFunction;
+        // Aggregation complexity
+        if (factors.hasAggregation)
+            estimate += COMPLEXITY_WEIGHTS.aggregation;
+        if (factors.hasGroupBy)
+            estimate += COMPLEXITY_WEIGHTS.groupBy;
+        if (factors.hasHaving)
+            estimate += COMPLEXITY_WEIGHTS.having;
+        if (factors.hasOrderBy)
+            estimate += COMPLEXITY_WEIGHTS.orderBy;
+        if (factors.hasDistinct)
+            estimate += COMPLEXITY_WEIGHTS.distinct;
+        // LIMIT can reduce cost
+        if (factors.queryType === 'SELECT' && !factors.hasLimit) {
+            estimate += COMPLEXITY_WEIGHTS.noLimit;
+        }
+        else if (factors.hasLimit && factors.limitValue !== null) {
+            // Small LIMIT reduces estimate
+            if (factors.limitValue <= 10) {
+                estimate *= 0.5;
+            }
+            else if (factors.limitValue <= 100) {
+                estimate *= 0.75;
+            }
+        }
+        // Table size impact
+        if (factors.hasFullTableScan) {
+            estimate += COMPLEXITY_WEIGHTS.fullTableScan;
+        }
+        estimate +=
+            factors.estimatedRowsScanned * COMPLEXITY_WEIGHTS.largeTableMultiplier;
+        // Transaction overhead
+        if (factors.isTransaction) {
+            estimate += COMPLEXITY_WEIGHTS.transaction;
+        }
+        // Transactions should route to DO for persistence
+        if (factors.isTransaction) {
+            estimate = Math.max(estimate, this.options.cpuTimeThresholdMs);
+        }
+        return Math.round(estimate * 100) / 100;
+    }
+    determineConfidence(factors, sql) {
+        // Malformed queries have low confidence (check this FIRST)
+        if (factors.queryType === 'OTHER' && sql.trim().length > 0) {
+            return 'low';
+        }
+        // Simple queries have high confidence
+        if (factors.joinCount === 0 &&
+            factors.subqueryCount === 0 &&
+            factors.unionCount === 0 &&
+            factors.cteCount === 0 &&
+            factors.windowFunctionCount === 0 &&
+            !factors.hasAggregation) {
+            return 'high';
+        }
+        // Complex queries with subqueries are harder to estimate
+        if (factors.subqueryCount > 1 || factors.cteCount > 1) {
+            return 'low';
+        }
+        // Moderate complexity
+        if (factors.subqueryCount > 0 ||
+            factors.joinCount > 2 ||
+            factors.windowFunctionCount > 0) {
+            return 'medium';
+        }
+        return 'high';
+    }
+    createEstimate(estimatedMs, factors, confidence) {
+        const threshold = this.options.cpuTimeThresholdMs;
+        const recommendation = estimatedMs >= threshold ? 'durable-object' : 'worker';
+        return {
+            estimatedMs,
+            recommendation,
+            confidence,
+            factors,
+            threshold,
+        };
+    }
+    createEmptyFactors() {
+        return {
+            joinCount: 0,
+            subqueryCount: 0,
+            unionCount: 0,
+            cteCount: 0,
+            windowFunctionCount: 0,
+            hasAggregation: false,
+            hasGroupBy: false,
+            hasHaving: false,
+            hasOrderBy: false,
+            hasDistinct: false,
+            hasLimit: false,
+            limitValue: null,
+            estimatedRowsScanned: 0,
+            tablesReferenced: [],
+            hasFullTableScan: false,
+            isTransaction: false,
+            queryType: 'OTHER',
+        };
+    }
+}
+//# sourceMappingURL=query-complexity-estimator.js.map

package/dist/routing/query-complexity-estimator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-complexity-estimator.js","sourceRoot":"","sources":["../../src/routing/query-complexity-estimator.ts"],"names":[],"mappings":"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"}

package/dist/routing/request-coalescing.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Request Coalescing
+ *
+ * Task: postgres-4ei - Implement request coalescing for duplicate queries
+ *
+ * When multiple identical queries arrive simultaneously, execute once
+ * and share the result with all waiters.
+ *
+ * Benefits:
+ * - Reduces duplicate work
+ * - Improves latency for thundering herd scenarios
+ * - Reduces DO load
+ */
+import type { QueryResult } from './runtime-router';
+/**
+ * Configuration for request coalescing
+ */
+export interface CoalescingConfig {
+    /** Enable coalescing (default: true) */
+    enabled?: boolean;
+    /** TTL for coalescing window in milliseconds (default: 100ms) */
+    coalescingWindowMs?: number;
+    /** Maximum number of in-flight queries to track (default: 10000) */
+    maxInFlightQueries?: number;
+    /** Include params in cache key (default: true) */
+    includeParams?: boolean;
+    /** Custom hash function for cache keys */
+    hashFn?: (sql: string, params?: unknown[]) => string;
+}
+/**
+ * Result of a coalesced request
+ */
+export interface CoalescedResult<T = QueryResult> {
+    /** The query result */
+    result: T;
+    /** Whether this was a coalesced result (true) or fresh execution (false) */
+    coalesced: boolean;
+    /** Number of requests that were coalesced together */
+    coalescedCount: number;
+    /** Time the original request started */
+    startTime: number;
+    /** Total duration including any wait time */
+    durationMs: number;
+}
+/**
+ * Metrics for coalescing performance
+ */
+export interface CoalescingMetrics {
+    /** Total requests processed */
+    totalRequests: number;
+    /** Requests that were coalesced (waited for existing result) */
+    coalescedRequests: number;
+    /** Requests that executed fresh */
+    freshExecutions: number;
+    /** Coalescing hit rate (0-1) */
+    hitRate: number;
+    /** Current in-flight queries */
+    inFlightQueries: number;
+    /** Peak in-flight queries */
+    peakInFlightQueries: number;
+    /** Total bytes saved estimate (based on result size reuse) */
+    estimatedBytesSaved: number;
+}
+/**
+ * Query executor function type
+ */
+export type QueryExecutorFn<T = QueryResult> = (sql: string, params?: unknown[]) => Promise<T>;
+/**
+ * Request Coalescing Layer
+ *
+ * Deduplicates identical concurrent queries by executing once and
+ * sharing the result with all waiters.
+ *
+ * @example
+ * ```typescript
+ * const coalescer = new RequestCoalescer({
+ *   coalescingWindowMs: 100,
+ * })
+ *
+ * // All 100 concurrent identical queries will share one execution
+ * const results = await Promise.all(
+ *   Array(100).fill(null).map(() =>
+ *     coalescer.execute(
+ *       'SELECT * FROM users WHERE id = $1',
+ *       [1],
+ *       (sql, params) => db.query(sql, params)
+ *     )
+ *   )
+ * )
+ * ```
+ */
+export declare class RequestCoalescer<T = QueryResult> {
+    private config;
+    private inFlightQueries;
+    private metrics;
+    constructor(config?: CoalescingConfig);
+    /**
+     * Execute a query with coalescing
+     *
+     * If an identical query is already in-flight, wait for its result.
+     * Otherwise, execute the query and share the result with any
+     * concurrent identical requests.
+     */
+    execute(sql: string, params: unknown[] | undefined, executor: QueryExecutorFn<T>): Promise<CoalescedResult<T>>;
+    /**
+     * Check if a query is currently in-flight
+     */
+    isInFlight(sql: string, params?: unknown[]): boolean;
+    /**
+     * Get the number of waiters for an in-flight query
+     */
+    getWaiterCount(sql: string, params?: unknown[]): number;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): CoalescingMetrics;
+    /**
+     * Reset metrics
+     */
+    resetMetrics(): void;
+    /**
+     * Clear all in-flight queries
+     */
+    clear(): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Required<CoalescingConfig>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<CoalescingConfig>): void;
+    /**
+     * Default hash function using simple string concatenation
+     */
+    private defaultHashFn;
+    /**
+     * Schedule cleanup of cache entry after coalescing window
+     */
+    private scheduleCleanup;
+    /**
+     * Estimate the size of a result for metrics
+     */
+    private estimateResultSize;
+    /**
+     * Create empty metrics object
+     */
+    private createEmptyMetrics;
+}
+/**
+ * Create a coalesced query executor
+ *
+ * Wraps an existing executor with coalescing behavior.
+ *
+ * @example
+ * ```typescript
+ * const coalescedExecutor = createCoalescedExecutor(
+ *   (sql, params) => db.query(sql, params),
+ *   { coalescingWindowMs: 100 }
+ * )
+ *
+ * // Use like a normal executor, coalescing happens automatically
+ * const result = await coalescedExecutor('SELECT * FROM users WHERE id = $1', [1])
+ * ```
+ */
+export declare function createCoalescedExecutor<T = QueryResult>(executor: QueryExecutorFn<T>, config?: CoalescingConfig): {
+    execute: (sql: string, params?: unknown[]) => Promise<CoalescedResult<T>>;
+    coalescer: RequestCoalescer<T>;
+};
+/**
+ * Hash function using FNV-1a algorithm for better distribution
+ */
+export declare function fnv1aHash(str: string): string;
+/**
+ * Create a hash function that uses FNV-1a
+ */
+export declare function createFnvHashFn(includeParams?: boolean): (sql: string, params?: unknown[]) => string;
+//# sourceMappingURL=request-coalescing.d.ts.map

package/dist/routing/request-coalescing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-coalescing.d.ts","sourceRoot":"","sources":["../../src/routing/request-coalescing.ts"],"names":[],"mappings":"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"}