@dotdo/postgres 0.1.0

package/src/worker/query-stats-manager.ts

@@ -0,0 +1,229 @@
+/**
+ * Query Statistics Manager for PostgresDO
+ *
+ * Tracks query execution statistics including count, duration, and timing.
+ * Extracted from PostgresDO to reduce class size and separate concerns.
+ *
+ * @module worker/query-stats-manager
+ */
+
+/**
+ * Query statistics
+ */
+export interface QueryStats {
+  /** Total number of queries executed */
+  queryCount: number
+  /** Total duration of all queries in milliseconds */
+  totalDurationMs: number
+  /** Average duration per query in milliseconds */
+  avgDurationMs: number
+  /** Timestamp of the last query */
+  lastQueryAt?: Date
+}
+
+/**
+ * Extended query statistics with additional metrics
+ */
+export interface ExtendedQueryStats extends QueryStats {
+  /** Minimum query duration in milliseconds */
+  minDurationMs: number
+  /** Maximum query duration in milliseconds */
+  maxDurationMs: number
+  /** Number of successful queries */
+  successCount: number
+  /** Number of failed queries */
+  errorCount: number
+  /** Queries per second (rolling average) */
+  queriesPerSecond: number
+}
+
+/**
+ * Configuration for the query stats manager
+ */
+export interface QueryStatsConfig {
+  /** Track extended statistics (min, max, error counts) - default: false */
+  trackExtended?: boolean
+  /** Rolling window for queries per second calculation in ms - default: 60000 */
+  qpsWindowMs?: number
+}
+
+/**
+ * QueryStatsManager tracks query execution statistics.
+ *
+ * Features:
+ * - Basic stats: count, total duration, average
+ * - Extended stats: min, max, success/error counts, QPS
+ * - Lightweight tracking with minimal overhead
+ *
+ * @example
+ * ```typescript
+ * const statsManager = new QueryStatsManager()
+ *
+ * // Track a query
+ * const startTime = performance.now()
+ * try {
+ *   await executeQuery()
+ *   const durationMs = performance.now() - startTime
+ *   statsManager.recordQuery(durationMs, true)
+ * } catch (error) {
+ *   const durationMs = performance.now() - startTime
+ *   statsManager.recordQuery(durationMs, false)
+ *   throw error
+ * }
+ *
+ * // Get stats
+ * const stats = statsManager.getStats()
+ * console.log(`Average query time: ${stats.avgDurationMs}ms`)
+ * ```
+ */
+export class QueryStatsManager {
+  private stats: QueryStats = {
+    queryCount: 0,
+    totalDurationMs: 0,
+    avgDurationMs: 0,
+  }
+
+  private extendedStats: {
+    minDurationMs: number
+    maxDurationMs: number
+    successCount: number
+    errorCount: number
+    recentQueries: number[]
+    recentQueriesTimestamp: number
+  } = {
+    minDurationMs: Infinity,
+    maxDurationMs: 0,
+    successCount: 0,
+    errorCount: 0,
+    recentQueries: [],
+    recentQueriesTimestamp: Date.now(),
+  }
+
+  private config: QueryStatsConfig
+  private startTime: number
+
+  constructor(config: QueryStatsConfig = {}) {
+    this.config = {
+      trackExtended: config.trackExtended ?? false,
+      qpsWindowMs: config.qpsWindowMs ?? 60000,
+    }
+    this.startTime = Date.now()
+  }
+
+  /**
+   * Record a query execution
+   *
+   * @param durationMs - Query duration in milliseconds
+   * @param success - Whether the query succeeded (default: true)
+   */
+  recordQuery(durationMs: number, success: boolean = true): void {
+    this.stats.queryCount++
+    this.stats.totalDurationMs += durationMs
+    this.stats.avgDurationMs = this.stats.totalDurationMs / this.stats.queryCount
+    this.stats.lastQueryAt = new Date()
+
+    if (this.config.trackExtended) {
+      if (durationMs < this.extendedStats.minDurationMs) {
+        this.extendedStats.minDurationMs = durationMs
+      }
+      if (durationMs > this.extendedStats.maxDurationMs) {
+        this.extendedStats.maxDurationMs = durationMs
+      }
+
+      if (success) {
+        this.extendedStats.successCount++
+      } else {
+        this.extendedStats.errorCount++
+      }
+
+      // Track recent queries for QPS calculation
+      const now = Date.now()
+      this.extendedStats.recentQueries.push(now)
+
+      // Clean up old entries outside the window
+      const windowStart = now - (this.config.qpsWindowMs ?? 60000)
+      this.extendedStats.recentQueries = this.extendedStats.recentQueries.filter(
+        (t) => t > windowStart
+      )
+    }
+  }
+
+  /**
+   * Get basic query statistics
+   */
+  getStats(): QueryStats {
+    return { ...this.stats }
+  }
+
+  /**
+   * Get extended query statistics (if tracking is enabled)
+   */
+  getExtendedStats(): ExtendedQueryStats {
+    const windowMs = this.config.qpsWindowMs ?? 60000
+    const now = Date.now()
+
+    // Clean up and calculate QPS
+    const windowStart = now - windowMs
+    const recentQueries = this.extendedStats.recentQueries.filter((t) => t > windowStart)
+    const queriesPerSecond =
+      recentQueries.length > 0 ? (recentQueries.length / windowMs) * 1000 : 0
+
+    return {
+      ...this.stats,
+      minDurationMs:
+        this.extendedStats.minDurationMs === Infinity ? 0 : this.extendedStats.minDurationMs,
+      maxDurationMs: this.extendedStats.maxDurationMs,
+      successCount: this.extendedStats.successCount,
+      errorCount: this.extendedStats.errorCount,
+      queriesPerSecond,
+    }
+  }
+
+  /**
+   * Get uptime in milliseconds
+   */
+  getUptime(): number {
+    return Date.now() - this.startTime
+  }
+
+  /**
+   * Reset all statistics
+   */
+  reset(): void {
+    this.stats = {
+      queryCount: 0,
+      totalDurationMs: 0,
+      avgDurationMs: 0,
+    }
+    this.extendedStats = {
+      minDurationMs: Infinity,
+      maxDurationMs: 0,
+      successCount: 0,
+      errorCount: 0,
+      recentQueries: [],
+      recentQueriesTimestamp: Date.now(),
+    }
+    this.startTime = Date.now()
+  }
+
+  /**
+   * Enable or disable extended statistics tracking
+   */
+  setTrackExtended(enabled: boolean): void {
+    this.config.trackExtended = enabled
+  }
+
+  /**
+   * Check if extended statistics tracking is enabled
+   */
+  isTrackingExtended(): boolean {
+    return this.config.trackExtended ?? false
+  }
+}
+
+/**
+ * Create a query stats manager instance
+ */
+export function createQueryStatsManager(config?: QueryStatsConfig): QueryStatsManager {
+  return new QueryStatsManager(config)
+}

package/src/worker/result-handler.test.ts

@@ -0,0 +1,364 @@
+/**
+ * Result Handler Tests
+ *
+ * Task: postgres-9i9 - Result set handling optimizations
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  ResultHandler,
+  createResultHandler,
+  createColumnExtractor,
+  createColumnRenamer,
+  countRows,
+  isEmpty,
+  firstRow,
+  lastRow,
+  type ResultMetadata,
+} from './result-handler'
+
+describe('ResultHandler', () => {
+  let handler: ResultHandler
+
+  beforeEach(() => {
+    handler = createResultHandler({
+      maxRows: 1000,
+      enableTransform: false,
+      enableCaching: true,
+      cacheTTL: 60000,
+      maxCachedResults: 100,
+      streamingChunkSize: 100,
+    })
+  })
+
+  describe('process', () => {
+    it('should process raw query results', () => {
+      const rawResult = {
+        rows: [{ id: 1, name: 'test' }],
+        fields: [
+          { name: 'id', dataTypeID: 23 },
+          { name: 'name', dataTypeID: 25 },
+        ],
+        affectedRows: 1,
+      }
+
+      const { rows, metadata } = handler.process(rawResult, { durationMs: 10 })
+
+      expect(rows).toEqual([{ id: 1, name: 'test' }])
+      expect(metadata.rowCount).toBe(1)
+      expect(metadata.affectedRows).toBe(1)
+      expect(metadata.durationMs).toBe(10)
+      expect(metadata.truncated).toBe(false)
+    })
+
+    it('should truncate results when exceeding maxRows', () => {
+      const handlerWithLimit = createResultHandler({ maxRows: 5 })
+      const rawResult = {
+        rows: Array(10).fill(null).map((_, i) => ({ id: i })),
+        fields: [{ name: 'id', dataTypeID: 23 }],
+      }
+
+      const { rows, metadata } = handlerWithLimit.process(rawResult)
+
+      expect(rows).toHaveLength(5)
+      expect(metadata.rowCount).toBe(5)
+      expect(metadata.truncated).toBe(true)
+      expect(metadata.originalRowCount).toBe(10)
+    })
+
+    it('should apply transformation when enabled', () => {
+      const handlerWithTransform = createResultHandler({
+        enableTransform: true,
+        transformer: (row) => ({
+          ...row,
+          processed: true,
+        }),
+      })
+
+      const rawResult = {
+        rows: [{ id: 1, name: 'test' }],
+        fields: [
+          { name: 'id', dataTypeID: 23 },
+          { name: 'name', dataTypeID: 25 },
+        ],
+      }
+
+      const { rows } = handlerWithTransform.process(rawResult)
+
+      expect(rows[0]).toEqual({ id: 1, name: 'test', processed: true })
+    })
+
+    it('should cache results when enabled', () => {
+      const rawResult = {
+        rows: [{ id: 1 }],
+        fields: [{ name: 'id', dataTypeID: 23 }],
+      }
+
+      handler.process(rawResult, { sql: 'SELECT 1' })
+
+      const cached = handler.getCached('SELECT 1')
+      expect(cached).not.toBeNull()
+      expect(cached?.rows).toEqual([{ id: 1 }])
+    })
+  })
+
+  describe('getCached', () => {
+    it('should return null for non-cached queries', () => {
+      const cached = handler.getCached('SELECT non_existent')
+      expect(cached).toBeNull()
+    })
+
+    it('should return cached result', () => {
+      const rawResult = {
+        rows: [{ id: 1 }],
+        fields: [{ name: 'id', dataTypeID: 23 }],
+      }
+
+      handler.process(rawResult, { sql: 'SELECT 1' })
+      const cached = handler.getCached('SELECT 1')
+
+      expect(cached).not.toBeNull()
+      expect(cached?.rows).toEqual([{ id: 1 }])
+    })
+  })
+
+  describe('createIterator', () => {
+    it('should create a lazy iterator', () => {
+      const rows = Array(100).fill(null).map((_, i) => ({ id: i }))
+      const metadata: ResultMetadata = {
+        rowCount: 100,
+        fields: [{ name: 'id', dataTypeID: 23 }],
+      }
+
+      const iterator = handler.createIterator(rows, metadata)
+
+      expect(iterator.count()).toBe(100)
+      expect(iterator.hasMore()).toBe(true)
+
+      const batch1 = iterator.next(10)
+      expect(batch1).toHaveLength(10)
+      expect(batch1[0]!.id).toBe(0)
+
+      const batch2 = iterator.next(10)
+      expect(batch2[0]!.id).toBe(10)
+
+      expect(iterator.hasMore()).toBe(true)
+    })
+
+    it('should support reset', () => {
+      const rows = [{ id: 1 }, { id: 2 }]
+      const metadata: ResultMetadata = {
+        rowCount: 2,
+        fields: [{ name: 'id', dataTypeID: 23 }],
+      }
+
+      const iterator = handler.createIterator(rows, metadata)
+
+      iterator.next(1)
+      iterator.reset()
+
+      const batch = iterator.next(1)
+      expect(batch[0]!.id).toBe(1)
+    })
+
+    it('should support toArray', () => {
+      const rows = [{ id: 1 }, { id: 2 }, { id: 3 }]
+      const metadata: ResultMetadata = {
+        rowCount: 3,
+        fields: [{ name: 'id', dataTypeID: 23 }],
+      }
+
+      const iterator = handler.createIterator(rows, metadata)
+
+      iterator.next(1) // Skip first row
+      const remaining = iterator.toArray()
+
+      expect(remaining).toHaveLength(2)
+      expect(remaining[0]!.id).toBe(2)
+    })
+  })
+
+  describe('createStream', () => {
+    it('should create a streaming handler', async () => {
+      const rows = Array(250).fill(null).map((_, i) => ({ id: i }))
+      const metadata: ResultMetadata = {
+        rowCount: 250,
+        fields: [{ name: 'id', dataTypeID: 23 }],
+      }
+
+      const stream = handler.createStream(rows, metadata)
+      const chunks: Array<{ id: number }[]> = []
+
+      await stream.forEach((chunk) => {
+        chunks.push(chunk)
+      })
+
+      expect(chunks.length).toBe(3) // 100 + 100 + 50
+      expect(chunks[0]).toHaveLength(100)
+      expect(chunks[2]).toHaveLength(50)
+    })
+
+    it('should support map operation', async () => {
+      const rows = [{ id: 1 }, { id: 2 }, { id: 3 }]
+      const metadata: ResultMetadata = {
+        rowCount: 3,
+        fields: [{ name: 'id', dataTypeID: 23 }],
+      }
+
+      const stream = handler.createStream(rows, metadata)
+      const doubled = await stream.map((row) => row.id * 2)
+
+      expect(doubled).toEqual([2, 4, 6])
+    })
+
+    it('should support reduce operation', async () => {
+      const rows = [{ id: 1 }, { id: 2 }, { id: 3 }]
+      const metadata: ResultMetadata = {
+        rowCount: 3,
+        fields: [{ name: 'id', dataTypeID: 23 }],
+      }
+
+      const stream = handler.createStream(rows, metadata)
+      const sum = await stream.reduce((acc, row) => acc + row.id, 0)
+
+      expect(sum).toBe(6)
+    })
+  })
+
+  describe('aggregateResults', () => {
+    it('should aggregate multiple result sets', () => {
+      const results = [
+        {
+          rows: [{ id: 1 }, { id: 2 }],
+          metadata: {
+            rowCount: 2,
+            fields: [{ name: 'id', dataTypeID: 23 }],
+            affectedRows: 2,
+            durationMs: 10,
+          },
+        },
+        {
+          rows: [{ id: 3 }, { id: 4 }],
+          metadata: {
+            rowCount: 2,
+            fields: [{ name: 'id', dataTypeID: 23 }],
+            affectedRows: 2,
+            durationMs: 15,
+          },
+        },
+      ]
+
+      const { rows, metadata } = handler.aggregateResults(results)
+
+      expect(rows).toHaveLength(4)
+      expect(metadata.rowCount).toBe(4)
+      expect(metadata.affectedRows).toBe(4)
+      expect(metadata.durationMs).toBe(25)
+    })
+
+    it('should truncate aggregated results when exceeding maxRows', () => {
+      const handlerWithLimit = createResultHandler({ maxRows: 3 })
+      const results = [
+        {
+          rows: [{ id: 1 }, { id: 2 }],
+          metadata: {
+            rowCount: 2,
+            fields: [{ name: 'id', dataTypeID: 23 }],
+          },
+        },
+        {
+          rows: [{ id: 3 }, { id: 4 }],
+          metadata: {
+            rowCount: 2,
+            fields: [{ name: 'id', dataTypeID: 23 }],
+          },
+        },
+      ]
+
+      const { rows, metadata } = handlerWithLimit.aggregateResults(results)
+
+      expect(rows).toHaveLength(3)
+      expect(metadata.truncated).toBe(true)
+      expect(metadata.originalRowCount).toBe(4)
+    })
+  })
+
+  describe('clearCache', () => {
+    it('should clear the result cache', () => {
+      const rawResult = {
+        rows: [{ id: 1 }],
+        fields: [{ name: 'id', dataTypeID: 23 }],
+      }
+
+      handler.process(rawResult, { sql: 'SELECT 1' })
+      expect(handler.getCacheStats().size).toBe(1)
+
+      handler.clearCache()
+      expect(handler.getCacheStats().size).toBe(0)
+    })
+  })
+})
+
+describe('Column Utilities', () => {
+  describe('createColumnExtractor', () => {
+    it('should extract specified columns', () => {
+      const extractor = createColumnExtractor<{ id: number; name: string; email: string }, 'id' | 'name'>(['id', 'name'])
+      const row = { id: 1, name: 'test', email: 'test@example.com' }
+
+      const extracted = extractor(row, 0, [])
+
+      expect(extracted).toEqual({ id: 1, name: 'test' })
+      expect(extracted).not.toHaveProperty('email')
+    })
+  })
+
+  describe('createColumnRenamer', () => {
+    it('should rename columns', () => {
+      const renamer = createColumnRenamer({ id: 'userId', name: 'userName' })
+      const row = { id: 1, name: 'test', status: 'active' }
+
+      const renamed = renamer(row, 0, [])
+
+      expect(renamed).toEqual({ userId: 1, userName: 'test', status: 'active' })
+    })
+  })
+})
+
+describe('Result Utilities', () => {
+  describe('countRows', () => {
+    it('should return the row count', () => {
+      const result = { rows: [1, 2, 3] }
+      expect(countRows(result)).toBe(3)
+    })
+  })
+
+  describe('isEmpty', () => {
+    it('should return true for empty results', () => {
+      expect(isEmpty({ rows: [] })).toBe(true)
+    })
+
+    it('should return false for non-empty results', () => {
+      expect(isEmpty({ rows: [1] })).toBe(false)
+    })
+  })
+
+  describe('firstRow', () => {
+    it('should return the first row', () => {
+      expect(firstRow({ rows: [1, 2, 3] })).toBe(1)
+    })
+
+    it('should return null for empty results', () => {
+      expect(firstRow({ rows: [] })).toBeNull()
+    })
+  })
+
+  describe('lastRow', () => {
+    it('should return the last row', () => {
+      expect(lastRow({ rows: [1, 2, 3] })).toBe(3)
+    })
+
+    it('should return null for empty results', () => {
+      expect(lastRow({ rows: [] })).toBeNull()
+    })
+  })
+})