@dotdo/postgres 0.1.0

package/dist/routing/request-coalescing.js

@@ -0,0 +1,325 @@
+/**
+ * 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
+ */
+/**
+ * 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 class RequestCoalescer {
+    config;
+    inFlightQueries = new Map();
+    metrics;
+    constructor(config = {}) {
+        this.config = {
+            enabled: config.enabled ?? true,
+            coalescingWindowMs: config.coalescingWindowMs ?? 100,
+            maxInFlightQueries: config.maxInFlightQueries ?? 10000,
+            includeParams: config.includeParams ?? true,
+            hashFn: config.hashFn ?? this.defaultHashFn.bind(this),
+        };
+        this.metrics = this.createEmptyMetrics();
+    }
+    /**
+     * 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.
+     */
+    async execute(sql, params, executor) {
+        this.metrics.totalRequests++;
+        // If coalescing is disabled, execute directly
+        if (!this.config.enabled) {
+            const startTime = Date.now();
+            const result = await executor(sql, params);
+            return {
+                result,
+                coalesced: false,
+                coalescedCount: 1,
+                startTime,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        const cacheKey = this.config.hashFn(sql, params);
+        // Check for existing in-flight query
+        const existing = this.inFlightQueries.get(cacheKey);
+        if (existing) {
+            this.metrics.coalescedRequests++;
+            existing.waiterCount++;
+            try {
+                const result = await existing.promise;
+                return {
+                    result,
+                    coalesced: true,
+                    coalescedCount: existing.waiterCount,
+                    startTime: existing.startTime,
+                    durationMs: Date.now() - existing.startTime,
+                };
+            }
+            catch (error) {
+                throw error;
+            }
+        }
+        // No existing query, execute fresh
+        this.metrics.freshExecutions++;
+        // Check max in-flight limit
+        if (this.inFlightQueries.size >= this.config.maxInFlightQueries) {
+            // Remove oldest entry to make room
+            const oldestKey = this.inFlightQueries.keys().next().value;
+            if (oldestKey) {
+                this.inFlightQueries.delete(oldestKey);
+            }
+        }
+        const startTime = Date.now();
+        let resolvePromise;
+        let rejectPromise;
+        const promise = new Promise((resolve, reject) => {
+            resolvePromise = resolve;
+            rejectPromise = reject;
+        });
+        // Attach a no-op catch handler to prevent Node.js from treating rejections
+        // from clear() as unhandled. The actual error will still propagate to waiters
+        // because they await the promise directly.
+        void promise.catch(() => { });
+        const inFlight = {
+            promise,
+            waiterCount: 1,
+            startTime,
+            resolve: resolvePromise,
+            reject: rejectPromise,
+            cancelled: false,
+        };
+        this.inFlightQueries.set(cacheKey, inFlight);
+        // Update peak metrics
+        if (this.inFlightQueries.size > this.metrics.peakInFlightQueries) {
+            this.metrics.peakInFlightQueries = this.inFlightQueries.size;
+        }
+        try {
+            // Execute the query
+            const result = await executor(sql, params);
+            // Check if cancelled during execution (e.g., via clear())
+            if (inFlight.cancelled) {
+                // The promise was already rejected by clear(), so just throw
+                throw new Error('Coalescer cleared');
+            }
+            // Resolve all waiters
+            inFlight.resolve(result);
+            // Calculate bytes saved estimate
+            const resultSize = this.estimateResultSize(result);
+            const bytesSaved = resultSize * (inFlight.waiterCount - 1);
+            this.metrics.estimatedBytesSaved += bytesSaved;
+            // Schedule cleanup after coalescing window
+            this.scheduleCleanup(cacheKey);
+            return {
+                result,
+                coalesced: false,
+                coalescedCount: inFlight.waiterCount,
+                startTime,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            // Reject all waiters (if not already rejected by clear())
+            if (!inFlight.cancelled) {
+                inFlight.reject(error instanceof Error ? error : new Error(String(error)));
+            }
+            // Remove from in-flight immediately on error
+            this.inFlightQueries.delete(cacheKey);
+            throw error;
+        }
+    }
+    /**
+     * Check if a query is currently in-flight
+     */
+    isInFlight(sql, params) {
+        const cacheKey = this.config.hashFn(sql, params);
+        return this.inFlightQueries.has(cacheKey);
+    }
+    /**
+     * Get the number of waiters for an in-flight query
+     */
+    getWaiterCount(sql, params) {
+        const cacheKey = this.config.hashFn(sql, params);
+        const existing = this.inFlightQueries.get(cacheKey);
+        return existing?.waiterCount ?? 0;
+    }
+    /**
+     * Get current metrics
+     */
+    getMetrics() {
+        return {
+            ...this.metrics,
+            inFlightQueries: this.inFlightQueries.size,
+            hitRate: this.metrics.totalRequests > 0
+                ? this.metrics.coalescedRequests / this.metrics.totalRequests
+                : 0,
+        };
+    }
+    /**
+     * Reset metrics
+     */
+    resetMetrics() {
+        this.metrics = this.createEmptyMetrics();
+    }
+    /**
+     * Clear all in-flight queries
+     */
+    clear() {
+        // Mark all as cancelled and reject pending promises
+        for (const [, inFlight] of this.inFlightQueries) {
+            inFlight.cancelled = true;
+            inFlight.reject(new Error('Coalescer cleared'));
+        }
+        this.inFlightQueries.clear();
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(config) {
+        if (config.enabled !== undefined) {
+            this.config.enabled = config.enabled;
+        }
+        if (config.coalescingWindowMs !== undefined) {
+            this.config.coalescingWindowMs = config.coalescingWindowMs;
+        }
+        if (config.maxInFlightQueries !== undefined) {
+            this.config.maxInFlightQueries = config.maxInFlightQueries;
+        }
+        if (config.includeParams !== undefined) {
+            this.config.includeParams = config.includeParams;
+        }
+        if (config.hashFn !== undefined) {
+            this.config.hashFn = config.hashFn;
+        }
+    }
+    /**
+     * Default hash function using simple string concatenation
+     */
+    defaultHashFn(sql, params) {
+        // Normalize SQL by trimming whitespace
+        const normalizedSql = sql.trim();
+        if (!this.config.includeParams || !params || params.length === 0) {
+            return normalizedSql;
+        }
+        // Create a stable string representation of params
+        const paramsKey = JSON.stringify(params);
+        return `${normalizedSql}::${paramsKey}`;
+    }
+    /**
+     * Schedule cleanup of cache entry after coalescing window
+     */
+    scheduleCleanup(cacheKey) {
+        setTimeout(() => {
+            this.inFlightQueries.delete(cacheKey);
+        }, this.config.coalescingWindowMs);
+    }
+    /**
+     * Estimate the size of a result for metrics
+     */
+    estimateResultSize(result) {
+        try {
+            return JSON.stringify(result).length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Create empty metrics object
+     */
+    createEmptyMetrics() {
+        return {
+            totalRequests: 0,
+            coalescedRequests: 0,
+            freshExecutions: 0,
+            hitRate: 0,
+            inFlightQueries: 0,
+            peakInFlightQueries: 0,
+            estimatedBytesSaved: 0,
+        };
+    }
+}
+/**
+ * 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 function createCoalescedExecutor(executor, config = {}) {
+    const coalescer = new RequestCoalescer(config);
+    return {
+        execute: (sql, params) => coalescer.execute(sql, params, executor),
+        coalescer,
+    };
+}
+/**
+ * Hash function using FNV-1a algorithm for better distribution
+ */
+export function fnv1aHash(str) {
+    let hash = 2166136261;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = (hash * 16777619) >>> 0;
+    }
+    return hash.toString(36);
+}
+/**
+ * Create a hash function that uses FNV-1a
+ */
+export function createFnvHashFn(includeParams = true) {
+    return (sql, params) => {
+        const normalizedSql = sql.trim();
+        if (!includeParams || !params || params.length === 0) {
+            return fnv1aHash(normalizedSql);
+        }
+        const paramsKey = JSON.stringify(params);
+        return fnv1aHash(`${normalizedSql}::${paramsKey}`);
+    };
+}
+//# sourceMappingURL=request-coalescing.js.map

package/dist/routing/request-coalescing.js.map

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

package/dist/routing/runtime-router.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Runtime Router
+ *
+ * Task: postgres-d6g.7
+ *
+ * Routes queries to optimal runtime based on complexity estimate:
+ * - <50ms CPU time -> Worker (cheaper due to CPU time billing)
+ * - >50ms CPU time -> Durable Object (cheaper due to wall time billing)
+ */
+import { QueryComplexityFactors, ConfidenceLevel, EstimatorOptions } from './query-complexity-estimator';
+export type RuntimeTarget = 'worker' | 'durable-object';
+export type ConnectionType = 'http' | 'websocket';
+export interface QueryResult {
+    rows: unknown[];
+    rowCount: number;
+}
+export interface QueryExecutor {
+    execute(sql: string, params?: unknown[]): Promise<QueryResult>;
+}
+export interface RouterConfig extends EstimatorOptions {
+    /** Executors for each runtime target */
+    executors?: {
+        worker?: QueryExecutor;
+        'durable-object'?: QueryExecutor;
+    };
+    /** Enable caching of routing decisions */
+    enableCache?: boolean;
+    /** Cache TTL in milliseconds */
+    cacheTtlMs?: number;
+    /** Fallback target when estimation fails */
+    fallbackTarget?: RuntimeTarget;
+    /** Prefer WebSocket connections for DO */
+    preferWebSocket?: boolean;
+}
+export interface RoutingOptions {
+    /** Force routing to specific target */
+    forceTarget?: RuntimeTarget;
+    /** Transaction ID for transaction context */
+    transactionId?: string;
+}
+export interface RoutingDecision {
+    target: RuntimeTarget;
+    reason: string;
+    estimatedMs: number;
+    threshold: number;
+    confidence: ConfidenceLevel;
+    factors?: QueryComplexityFactors;
+    forced?: boolean;
+    cached?: boolean;
+    connectionType?: ConnectionType;
+}
+export interface RouterMetrics {
+    totalRoutes: number;
+    workerRoutes: number;
+    doRoutes: number;
+    byQueryType: Record<string, number>;
+}
+export interface BatchOptimization {
+    workerQueries: string[];
+    doQueries: string[];
+    decisions: RoutingDecision[];
+}
+export declare class RuntimeRouter {
+    private estimator;
+    private config;
+    private activeTransactions;
+    private metrics;
+    private cache;
+    constructor(config?: RouterConfig);
+    /**
+     * Route a SQL query to the appropriate runtime
+     */
+    route(sql: string, options?: RoutingOptions): Promise<RoutingDecision>;
+    /**
+     * Execute a query using the appropriate runtime
+     */
+    execute(sql: string, params?: unknown[], options?: RoutingOptions): Promise<QueryResult>;
+    /**
+     * Route multiple queries
+     */
+    routeBatch(queries: string[]): Promise<RoutingDecision[]>;
+    /**
+     * Optimize batch of queries to minimize runtime switches
+     */
+    optimizeBatch(queries: string[]): Promise<BatchOptimization>;
+    /**
+     * Check if a transaction is active
+     */
+    hasActiveTransaction(transactionId: string): boolean;
+    /**
+     * Get routing metrics
+     */
+    getMetrics(): RouterMetrics;
+    /**
+     * Reset routing metrics
+     */
+    resetMetrics(): void;
+    private isTransactionCommand;
+    private createDecision;
+    private createForcedDecision;
+    private createTransactionDecision;
+    private getCachedDecision;
+    private cacheDecision;
+    private updateMetrics;
+    private createEmptyMetrics;
+}
+//# sourceMappingURL=runtime-router.d.ts.map

package/dist/routing/runtime-router.d.ts.map

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

package/dist/routing/runtime-router.js

@@ -0,0 +1,246 @@
+/**
+ * Runtime Router
+ *
+ * Task: postgres-d6g.7
+ *
+ * Routes queries to optimal runtime based on complexity estimate:
+ * - <50ms CPU time -> Worker (cheaper due to CPU time billing)
+ * - >50ms CPU time -> Durable Object (cheaper due to wall time billing)
+ */
+import { QueryComplexityEstimator, } from './query-complexity-estimator';
+export class RuntimeRouter {
+    estimator;
+    config;
+    activeTransactions;
+    metrics;
+    cache;
+    constructor(config = {}) {
+        this.config = {
+            cpuTimeThresholdMs: config.cpuTimeThresholdMs ?? 50,
+            tableSizeHints: config.tableSizeHints ?? {},
+            indexedColumns: config.indexedColumns ?? {},
+            executors: config.executors ?? {},
+            enableCache: config.enableCache ?? false,
+            cacheTtlMs: config.cacheTtlMs ?? 60000,
+            fallbackTarget: config.fallbackTarget ?? 'worker',
+            preferWebSocket: config.preferWebSocket ?? false,
+        };
+        this.estimator = new QueryComplexityEstimator({
+            cpuTimeThresholdMs: this.config.cpuTimeThresholdMs,
+            tableSizeHints: this.config.tableSizeHints,
+            indexedColumns: this.config.indexedColumns,
+        });
+        this.activeTransactions = new Set();
+        this.cache = new Map();
+        this.metrics = this.createEmptyMetrics();
+    }
+    /**
+     * Route a SQL query to the appropriate runtime
+     */
+    async route(sql, options = {}) {
+        // Check cache first
+        if (this.config.enableCache && !options.forceTarget && !options.transactionId) {
+            const cached = this.getCachedDecision(sql);
+            if (cached) {
+                this.updateMetrics(cached);
+                return { ...cached, cached: true };
+            }
+        }
+        // Handle forced routing
+        if (options.forceTarget) {
+            const decision = this.createForcedDecision(sql, options.forceTarget);
+            this.updateMetrics(decision);
+            return decision;
+        }
+        // Handle transaction context
+        if (options.transactionId) {
+            const isTransactionCommand = this.isTransactionCommand(sql);
+            if (isTransactionCommand.isBegin) {
+                this.activeTransactions.add(options.transactionId);
+            }
+            else if (isTransactionCommand.isEnd) {
+                this.activeTransactions.delete(options.transactionId);
+            }
+            if (this.activeTransactions.has(options.transactionId) || isTransactionCommand.isBegin) {
+                const decision = this.createTransactionDecision(sql);
+                this.updateMetrics(decision);
+                return decision;
+            }
+        }
+        // Get complexity estimate
+        const estimate = this.estimator.estimate(sql);
+        // Create routing decision (use fallback target for low confidence parse errors)
+        const decision = this.createDecision(estimate);
+        // Cache if enabled (mark as not cached for fresh decisions)
+        if (this.config.enableCache) {
+            this.cacheDecision(sql, { ...decision, cached: false });
+        }
+        this.updateMetrics(decision);
+        const result = { ...decision };
+        if (this.config.enableCache) {
+            result.cached = false;
+        }
+        return result;
+    }
+    /**
+     * Execute a query using the appropriate runtime
+     */
+    async execute(sql, params, options = {}) {
+        const decision = await this.route(sql, options);
+        const executor = this.config.executors[decision.target];
+        if (!executor) {
+            throw new Error(`No executor configured for ${decision.target}`);
+        }
+        return executor.execute(sql, params);
+    }
+    /**
+     * Route multiple queries
+     */
+    async routeBatch(queries) {
+        return Promise.all(queries.map(sql => this.route(sql)));
+    }
+    /**
+     * Optimize batch of queries to minimize runtime switches
+     */
+    async optimizeBatch(queries) {
+        const decisions = await this.routeBatch(queries);
+        const workerQueries = [];
+        const doQueries = [];
+        decisions.forEach((decision, index) => {
+            const query = queries[index];
+            if (!query)
+                return;
+            if (decision.target === 'worker') {
+                workerQueries.push(query);
+            }
+            else {
+                doQueries.push(query);
+            }
+        });
+        return {
+            workerQueries,
+            doQueries,
+            decisions,
+        };
+    }
+    /**
+     * Check if a transaction is active
+     */
+    hasActiveTransaction(transactionId) {
+        return this.activeTransactions.has(transactionId);
+    }
+    /**
+     * Get routing metrics
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Reset routing metrics
+     */
+    resetMetrics() {
+        this.metrics = this.createEmptyMetrics();
+    }
+    isTransactionCommand(sql) {
+        const trimmed = sql.trim().toUpperCase();
+        return {
+            isBegin: trimmed.startsWith('BEGIN'),
+            isEnd: trimmed.startsWith('COMMIT') || trimmed.startsWith('ROLLBACK'),
+        };
+    }
+    createDecision(estimate) {
+        // Use fallback target for low confidence (e.g., parse errors)
+        let target;
+        if (estimate.confidence === 'low' && estimate.factors.queryType === 'OTHER') {
+            target = this.config.fallbackTarget;
+        }
+        else {
+            target = estimate.recommendation === 'durable-object' ? 'durable-object' : 'worker';
+        }
+        const isComplex = estimate.estimatedMs >= this.config.cpuTimeThresholdMs;
+        const isTransaction = estimate.factors.isTransaction;
+        let reason;
+        if (isTransaction) {
+            reason = 'transaction requires state persistence';
+        }
+        else if (isComplex) {
+            reason = `complex query (estimated ${estimate.estimatedMs}ms CPU time)`;
+        }
+        else {
+            reason = `fast query (estimated ${estimate.estimatedMs}ms CPU time)`;
+        }
+        const connectionType = target === 'durable-object' && this.config.preferWebSocket ? 'websocket' : 'http';
+        return {
+            target,
+            reason,
+            estimatedMs: estimate.estimatedMs,
+            threshold: estimate.threshold,
+            confidence: estimate.confidence,
+            factors: estimate.factors,
+            connectionType,
+        };
+    }
+    createForcedDecision(sql, target) {
+        const estimate = this.estimator.estimate(sql);
+        return {
+            target,
+            reason: 'forced routing',
+            estimatedMs: estimate.estimatedMs,
+            threshold: estimate.threshold,
+            confidence: estimate.confidence,
+            factors: estimate.factors,
+            forced: true,
+            connectionType: target === 'durable-object' && this.config.preferWebSocket ? 'websocket' : 'http',
+        };
+    }
+    createTransactionDecision(sql) {
+        const estimate = this.estimator.estimate(sql);
+        return {
+            target: 'durable-object',
+            reason: 'transaction context requires durable-object',
+            estimatedMs: estimate.estimatedMs,
+            threshold: estimate.threshold,
+            confidence: estimate.confidence,
+            factors: estimate.factors,
+            connectionType: this.config.preferWebSocket ? 'websocket' : 'http',
+        };
+    }
+    getCachedDecision(sql) {
+        const entry = this.cache.get(sql);
+        if (!entry)
+            return null;
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(sql);
+            return null;
+        }
+        return entry.decision;
+    }
+    cacheDecision(sql, decision) {
+        this.cache.set(sql, {
+            decision,
+            expiresAt: Date.now() + this.config.cacheTtlMs,
+        });
+    }
+    updateMetrics(decision) {
+        this.metrics.totalRoutes++;
+        if (decision.target === 'worker') {
+            this.metrics.workerRoutes++;
+        }
+        else {
+            this.metrics.doRoutes++;
+        }
+        if (decision.factors) {
+            const queryType = decision.factors.queryType;
+            this.metrics.byQueryType[queryType] = (this.metrics.byQueryType[queryType] ?? 0) + 1;
+        }
+    }
+    createEmptyMetrics() {
+        return {
+            totalRoutes: 0,
+            workerRoutes: 0,
+            doRoutes: 0,
+            byQueryType: {},
+        };
+    }
+}
+//# sourceMappingURL=runtime-router.js.map