@dotdo/postgres 0.1.0

package/src/worker/result-handler.ts

@@ -0,0 +1,510 @@
+/**
+ * Optimized Result Set Handler
+ *
+ * Task: postgres-9i9 - Result set handling optimizations
+ *
+ * Provides efficient result set processing with:
+ * - Lazy result iteration for large datasets
+ * - Memory-efficient streaming for large result sets
+ * - Row-level transformation hooks
+ * - Batch result aggregation
+ */
+
+import type { QueryField, QueryResultRow } from './types'
+
+/**
+ * Result set metadata
+ */
+export interface ResultMetadata {
+  /** Total rows returned */
+  rowCount: number
+  /** Column definitions */
+  fields: QueryField[]
+  /** Affected rows for mutations */
+  affectedRows?: number | undefined
+  /** Execution duration in milliseconds */
+  durationMs?: number | undefined
+  /** Whether result was truncated */
+  truncated?: boolean | undefined
+  /** Original row count before truncation */
+  originalRowCount?: number | undefined
+}
+
+/**
+ * Configuration for result handling
+ */
+export interface ResultHandlerConfig {
+  /** Maximum rows to return (default: unlimited) */
+  maxRows?: number
+  /** Enable row transformation (default: false) */
+  enableTransform?: boolean
+  /** Row transformer function */
+  transformer?: RowTransformer
+  /** Enable result caching for repeated queries (default: false) */
+  enableCaching?: boolean
+  /** Cache TTL in milliseconds (default: 60000) */
+  cacheTTL?: number
+  /** Maximum cached results (default: 100) */
+  maxCachedResults?: number
+  /** Enable streaming mode for large results (default: true) */
+  enableStreaming?: boolean
+  /** Streaming chunk size (default: 100) */
+  streamingChunkSize?: number
+}
+
+/**
+ * Row transformer function type
+ */
+export type RowTransformer<T = QueryResultRow, R = T> = (row: T, index: number, fields: QueryField[]) => R
+
+/**
+ * Result iterator for lazy evaluation
+ */
+export interface ResultIterator<T> {
+  /** Get next batch of rows */
+  next(count?: number): T[]
+  /** Check if more rows available */
+  hasMore(): boolean
+  /** Get total row count */
+  count(): number
+  /** Reset iterator to beginning */
+  reset(): void
+  /** Get all remaining rows */
+  toArray(): T[]
+  /** Get metadata */
+  metadata(): ResultMetadata
+}
+
+/**
+ * Streaming result handler for large datasets
+ */
+export interface StreamingResult<T> {
+  /** Process rows in chunks */
+  forEach(callback: (rows: T[], chunkIndex: number) => void | Promise<void>): Promise<void>
+  /** Map rows in chunks */
+  map<R>(mapper: (row: T, index: number) => R): Promise<R[]>
+  /** Reduce rows efficiently */
+  reduce<R>(reducer: (acc: R, row: T, index: number) => R, initial: R): Promise<R>
+  /** Get metadata */
+  metadata(): ResultMetadata
+}
+
+/**
+ * Cached result entry
+ */
+interface CachedResult<T> {
+  rows: T[]
+  metadata: ResultMetadata
+  timestamp: number
+}
+
+/**
+ * Result cache with LRU eviction
+ */
+class ResultCache {
+  private cache = new Map<string, CachedResult<unknown>>()
+  private lruOrder: string[] = []
+  private maxSize: number
+  private ttl: number
+
+  constructor(maxSize: number, ttl: number) {
+    this.maxSize = maxSize
+    this.ttl = ttl
+  }
+
+  get<T>(key: string): CachedResult<T> | null {
+    const entry = this.cache.get(key)
+    if (!entry) return null
+
+    // Check TTL
+    if (Date.now() - entry.timestamp > this.ttl) {
+      this.delete(key)
+      return null
+    }
+
+    // Update LRU order
+    const idx = this.lruOrder.indexOf(key)
+    if (idx > -1) {
+      this.lruOrder.splice(idx, 1)
+      this.lruOrder.push(key)
+    }
+
+    return entry as CachedResult<T>
+  }
+
+  set<T>(key: string, rows: T[], metadata: ResultMetadata): void {
+    // Evict oldest if at capacity
+    while (this.cache.size >= this.maxSize && this.lruOrder.length > 0) {
+      const oldest = this.lruOrder.shift()
+      if (oldest) {
+        this.cache.delete(oldest)
+      }
+    }
+
+    this.cache.set(key, {
+      rows,
+      metadata,
+      timestamp: Date.now(),
+    })
+    this.lruOrder.push(key)
+  }
+
+  delete(key: string): void {
+    const idx = this.lruOrder.indexOf(key)
+    if (idx > -1) {
+      this.lruOrder.splice(idx, 1)
+    }
+    this.cache.delete(key)
+  }
+
+  clear(): void {
+    this.cache.clear()
+    this.lruOrder = []
+  }
+
+  get size(): number {
+    return this.cache.size
+  }
+}
+
+/**
+ * Create a result iterator for lazy evaluation
+ */
+function createResultIterator<T>(rows: T[], metadata: ResultMetadata): ResultIterator<T> {
+  let cursor = 0
+
+  return {
+    next(count: number = 100): T[] {
+      const result = rows.slice(cursor, cursor + count)
+      cursor += result.length
+      return result
+    },
+
+    hasMore(): boolean {
+      return cursor < rows.length
+    },
+
+    count(): number {
+      return rows.length
+    },
+
+    reset(): void {
+      cursor = 0
+    },
+
+    toArray(): T[] {
+      const result = rows.slice(cursor)
+      cursor = rows.length
+      return result
+    },
+
+    metadata(): ResultMetadata {
+      return metadata
+    },
+  }
+}
+
+/**
+ * Create a streaming result handler for memory-efficient processing
+ */
+function createStreamingResult<T>(
+  rows: T[],
+  metadata: ResultMetadata,
+  chunkSize: number
+): StreamingResult<T> {
+  return {
+    async forEach(callback): Promise<void> {
+      let chunkIndex = 0
+      for (let i = 0; i < rows.length; i += chunkSize) {
+        const chunk = rows.slice(i, i + chunkSize)
+        await callback(chunk, chunkIndex++)
+      }
+    },
+
+    async map<R>(mapper: (row: T, index: number) => R): Promise<R[]> {
+      const results: R[] = []
+      results.length = rows.length // Pre-allocate
+
+      for (let i = 0; i < rows.length; i++) {
+        const row = rows[i]
+        if (row !== undefined) {
+          results[i] = mapper(row, i)
+        }
+      }
+
+      return results
+    },
+
+    async reduce<R>(reducer: (acc: R, row: T, index: number) => R, initial: R): Promise<R> {
+      let acc = initial
+      for (let i = 0; i < rows.length; i++) {
+        const row = rows[i]
+        if (row !== undefined) {
+          acc = reducer(acc, row, i)
+        }
+      }
+      return acc
+    },
+
+    metadata(): ResultMetadata {
+      return metadata
+    },
+  }
+}
+
+/**
+ * Optimized Result Handler
+ *
+ * Efficiently processes query results with:
+ * - Optional row transformation
+ * - Result caching
+ * - Lazy iteration
+ * - Streaming for large datasets
+ */
+export class ResultHandler {
+  private config: Required<ResultHandlerConfig>
+  private cache: ResultCache | null
+
+  constructor(config: ResultHandlerConfig = {}) {
+    this.config = {
+      maxRows: config.maxRows ?? Infinity,
+      enableTransform: config.enableTransform ?? false,
+      transformer: config.transformer ?? ((row) => row),
+      enableCaching: config.enableCaching ?? false,
+      cacheTTL: config.cacheTTL ?? 60000,
+      maxCachedResults: config.maxCachedResults ?? 100,
+      enableStreaming: config.enableStreaming ?? true,
+      streamingChunkSize: config.streamingChunkSize ?? 100,
+    }
+
+    this.cache = this.config.enableCaching
+      ? new ResultCache(this.config.maxCachedResults, this.config.cacheTTL)
+      : null
+  }
+
+  /**
+   * Process raw query results into optimized format
+   */
+  process<T extends QueryResultRow>(
+    rawResult: {
+      rows: T[]
+      fields: { name: string; dataTypeID: number }[]
+      affectedRows?: number
+    },
+    options?: {
+      sql?: string
+      durationMs?: number
+    }
+  ): { rows: T[]; metadata: ResultMetadata } {
+    let rows = rawResult.rows
+    const fields = rawResult.fields as QueryField[]
+    let truncated = false
+    const originalRowCount = rows.length
+
+    // Apply row limit if configured
+    if (this.config.maxRows < Infinity && rows.length > this.config.maxRows) {
+      rows = rows.slice(0, this.config.maxRows)
+      truncated = true
+    }
+
+    // Apply transformation if enabled
+    if (this.config.enableTransform && this.config.transformer) {
+      rows = rows.map((row, idx) =>
+        this.config.transformer!(row, idx, fields)
+      ) as T[]
+    }
+
+    const metadata: ResultMetadata = {
+      rowCount: rows.length,
+      fields,
+      affectedRows: rawResult.affectedRows,
+      durationMs: options?.durationMs,
+      truncated,
+      originalRowCount: truncated ? originalRowCount : undefined,
+    }
+
+    // Cache if enabled
+    if (this.cache && options?.sql) {
+      this.cache.set(options.sql, rows, metadata)
+    }
+
+    return { rows, metadata }
+  }
+
+  /**
+   * Get cached result if available
+   */
+  getCached<T extends QueryResultRow>(sql: string): { rows: T[]; metadata: ResultMetadata } | null {
+    if (!this.cache) return null
+    const cached = this.cache.get<T>(sql)
+    return cached ? { rows: cached.rows, metadata: cached.metadata } : null
+  }
+
+  /**
+   * Create a lazy iterator for result set
+   */
+  createIterator<T extends QueryResultRow>(
+    rows: T[],
+    metadata: ResultMetadata
+  ): ResultIterator<T> {
+    return createResultIterator(rows, metadata)
+  }
+
+  /**
+   * Create a streaming handler for large result sets
+   */
+  createStream<T extends QueryResultRow>(
+    rows: T[],
+    metadata: ResultMetadata
+  ): StreamingResult<T> {
+    return createStreamingResult(rows, metadata, this.config.streamingChunkSize)
+  }
+
+  /**
+   * Process and aggregate multiple results
+   */
+  aggregateResults<T extends QueryResultRow>(
+    results: Array<{ rows: T[]; metadata: ResultMetadata }>
+  ): { rows: T[]; metadata: ResultMetadata } {
+    const allRows: T[] = []
+    const allFields: QueryField[] = results[0]?.metadata.fields ?? []
+    let totalAffectedRows = 0
+    let totalDuration = 0
+
+    for (const result of results) {
+      allRows.push(...result.rows)
+      if (result.metadata.affectedRows !== undefined) {
+        totalAffectedRows += result.metadata.affectedRows
+      }
+      if (result.metadata.durationMs !== undefined) {
+        totalDuration += result.metadata.durationMs
+      }
+    }
+
+    // Apply row limit to aggregated result
+    let rows = allRows
+    let truncated = false
+    const originalRowCount = allRows.length
+
+    if (this.config.maxRows < Infinity && rows.length > this.config.maxRows) {
+      rows = rows.slice(0, this.config.maxRows)
+      truncated = true
+    }
+
+    return {
+      rows,
+      metadata: {
+        rowCount: rows.length,
+        fields: allFields,
+        affectedRows: totalAffectedRows > 0 ? totalAffectedRows : undefined,
+        durationMs: totalDuration > 0 ? totalDuration : undefined,
+        truncated,
+        originalRowCount: truncated ? originalRowCount : undefined,
+      },
+    }
+  }
+
+  /**
+   * Clear the result cache
+   */
+  clearCache(): void {
+    this.cache?.clear()
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getCacheStats(): { size: number; enabled: boolean } {
+    return {
+      size: this.cache?.size ?? 0,
+      enabled: this.config.enableCaching,
+    }
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<ResultHandlerConfig>): void {
+    Object.assign(this.config, config)
+
+    // Recreate cache if settings changed
+    if (config.enableCaching !== undefined || config.maxCachedResults !== undefined || config.cacheTTL !== undefined) {
+      if (this.config.enableCaching) {
+        this.cache = new ResultCache(this.config.maxCachedResults, this.config.cacheTTL)
+      } else {
+        this.cache = null
+      }
+    }
+  }
+}
+
+/**
+ * Create a configured result handler
+ */
+export function createResultHandler(config?: ResultHandlerConfig): ResultHandler {
+  return new ResultHandler(config)
+}
+
+/**
+ * Utility: Create a row transformer that extracts specific columns
+ */
+export function createColumnExtractor<T extends QueryResultRow, K extends keyof T>(
+  columns: K[]
+): RowTransformer<T, Pick<T, K>> {
+  return (row: T) => {
+    const result = {} as Pick<T, K>
+    for (const col of columns) {
+      result[col] = row[col]
+    }
+    return result
+  }
+}
+
+/**
+ * Utility: Create a row transformer that renames columns
+ */
+export function createColumnRenamer<T extends QueryResultRow>(
+  mapping: Record<string, string>
+): RowTransformer<T, Record<string, unknown>> {
+  return (row: T) => {
+    const result: Record<string, unknown> = {}
+    for (const [oldName, newName] of Object.entries(mapping)) {
+      result[newName] = row[oldName as keyof T]
+    }
+    // Include unmapped columns
+    for (const key of Object.keys(row)) {
+      if (!(key in mapping)) {
+        result[key] = row[key as keyof T]
+      }
+    }
+    return result
+  }
+}
+
+/**
+ * Utility: Efficiently count rows without full iteration
+ */
+export function countRows<T>(result: { rows: T[] }): number {
+  return result.rows.length
+}
+
+/**
+ * Utility: Check if result is empty
+ */
+export function isEmpty<T>(result: { rows: T[] }): boolean {
+  return result.rows.length === 0
+}
+
+/**
+ * Utility: Get first row or null
+ */
+export function firstRow<T>(result: { rows: T[] }): T | null {
+  return result.rows[0] ?? null
+}
+
+/**
+ * Utility: Get last row or null
+ */
+export function lastRow<T>(result: { rows: T[] }): T | null {
+  return result.rows[result.rows.length - 1] ?? null
+}