@dotdo/postgres 0.1.0

package/src/storage/r2-overflow.ts

@@ -0,0 +1,920 @@
+/**
+ * R2OverflowManager - Spill large query results to R2 storage
+ *
+ * This module manages automatic spillover of large query results to R2 storage
+ * when they exceed memory limits in Cloudflare Workers (128MB limit).
+ *
+ * ## Features
+ *
+ * - Automatic detection of large result sets
+ * - Spillover to R2 storage when threshold exceeded
+ * - Transparent retrieval of spilled results
+ * - Memory pressure handling with adaptive thresholds
+ * - TTL-based cleanup of overflow data
+ * - LRU caching for frequently accessed overflow data
+ * - Adaptive chunking strategy based on data size
+ * - Parallel chunk operations for improved performance
+ *
+ * ## Performance Characteristics
+ *
+ * ### Chunking Strategy
+ *
+ * The manager uses an adaptive chunking strategy that balances network efficiency,
+ * memory pressure, and parallelism benefits:
+ *
+ * | Data Size      | Chunk Size | Chunks | Strategy                     |
+ * |----------------|------------|--------|------------------------------|
+ * | < 4MB          | 1MB        | 1-4    | Minimize overhead            |
+ * | 4MB - 60MB     | ~data/6    | ~6     | Optimize parallel throughput |
+ * | > 60MB         | 10MB       | N/10MB | Maximize chunk efficiency    |
+ *
+ * ### Parallel Operations
+ *
+ * - Upload/download operations run in parallel batches of 4 concurrent requests
+ * - This provides 3-4x improvement over sequential operations for multi-chunk data
+ * - Memory-conscious: limits concurrent operations to prevent OOM
+ *
+ * ### LRU Cache
+ *
+ * - Default max size: 50MB
+ * - Single items larger than 25% of max cache are not cached
+ * - Automatic eviction of least-recently-used entries
+ * - Cache hits bypass R2 entirely for zero-latency retrieval
+ *
+ * ### Memory Overhead
+ *
+ * - ~2KB per active overflow entry tracking
+ * - Cache entries use actual data size + ~100 bytes metadata
+ * - Chunk metadata stored in R2 customMetadata (not counted against cache)
+ *
+ * ## Usage Example
+ *
+ * ```typescript
+ * const manager = createR2OverflowManager({
+ *   r2Layer,
+ *   spillThresholdBytes: 10 * 1024 * 1024, // 10MB
+ *   memoryPressureThreshold: 0.8,
+ *   maxInMemoryResultBytes: 50 * 1024 * 1024,
+ *   overflowTtlMs: 3600000, // 1 hour
+ *   overflowPrefix: 'overflow/',
+ *   autoCleanup: true,
+ * })
+ *
+ * // Spill large data
+ * if (manager.shouldSpill(largeResult)) {
+ *   const result = await manager.spill(largeResult)
+ *   // Store result.overflowKey for later retrieval
+ * }
+ *
+ * // Prefetch for faster access (optional)
+ * await manager.prefetch(overflowKey)
+ *
+ * // Retrieve data (uses cache if available)
+ * const data = await manager.retrieveByKey(overflowKey)
+ *
+ * // Monitor cache performance
+ * const cacheStats = manager.getCacheStats()
+ * console.log(`Cache hit ratio: ${cacheStats.entries} entries, ${cacheStats.sizeBytes} bytes`)
+ * ```
+ *
+ * ## Best Practices
+ *
+ * 1. **Set appropriate thresholds**: Match spillThresholdBytes to your workload
+ * 2. **Use prefetch**: When you know data will be needed, prefetch it early
+ * 3. **Monitor cache stats**: Adjust cache size based on hit rates
+ * 4. **Handle memory pressure**: Register callbacks for proactive management
+ * 5. **Cleanup expired data**: Enable autoCleanup or call cleanupExpired periodically
+ *
+ * @module storage/r2-overflow
+ */
+
+import type { R2StorageLayer } from './r2-layer'
+
+/**
+ * Configuration for R2 overflow behavior
+ */
+export interface R2OverflowConfig {
+  /** R2 storage layer for overflow data */
+  r2Layer: R2StorageLayer
+  /** Size threshold in bytes before spilling to R2 (default: 10MB) */
+  spillThresholdBytes: number
+  /** Memory pressure threshold (0-1) to trigger aggressive spilling */
+  memoryPressureThreshold: number
+  /** Maximum result size to keep in memory (bytes) */
+  maxInMemoryResultBytes: number
+  /** TTL for overflow data in R2 (ms) */
+  overflowTtlMs: number
+  /** Prefix for overflow keys in R2 */
+  overflowPrefix: string
+  /** Enable automatic cleanup of expired overflow data */
+  autoCleanup: boolean
+}
+
+/**
+ * Result of an overflow operation
+ */
+export interface OverflowResult {
+  /** Whether the result was spilled to R2 */
+  spilled: boolean
+  /** R2 key if spilled */
+  overflowKey?: string
+  /** Original size in bytes */
+  originalSize: number
+  /** Timestamp when spilled */
+  spilledAt?: number
+  /** Number of chunks if split */
+  chunks?: number
+}
+
+/**
+ * Handle for retrieving spilled results
+ */
+export interface SpilledResultHandle {
+  /** R2 key for the spilled data */
+  key: string
+  /** Total size in bytes */
+  size: number
+  /** Number of chunks */
+  chunks: number
+  /** When the data was spilled */
+  spilledAt: number
+  /** When the data expires */
+  expiresAt: number
+  /** Metadata about the original query */
+  metadata: Record<string, string>
+}
+
+/**
+ * Memory pressure signal
+ */
+export interface MemoryPressureSignal {
+  /** Current memory usage ratio (0-1) */
+  usageRatio: number
+  /** Available memory in bytes */
+  availableBytes: number
+  /** Whether immediate action is required */
+  critical: boolean
+  /** Source of the signal */
+  source: 'runtime' | 'manual' | 'periodic'
+}
+
+/**
+ * Statistics for overflow operations
+ */
+export interface OverflowStats {
+  /** Number of results spilled to R2 */
+  spillCount: number
+  /** Total bytes spilled */
+  bytesSpilled: number
+  /** Number of retrievals from R2 */
+  retrievalCount: number
+  /** Total bytes retrieved */
+  bytesRetrieved: number
+  /** Number of cleanup operations */
+  cleanupCount: number
+  /** Bytes cleaned up */
+  bytesCleanedUp: number
+  /** Number of memory pressure events handled */
+  memoryPressureEvents: number
+  /** Current overflow entries in R2 */
+  activeOverflows: number
+}
+
+/**
+ * Chunking Constants
+ *
+ * Adaptive chunking strategy balances:
+ * - Network efficiency (larger chunks = fewer requests)
+ * - Memory pressure (smaller chunks = lower peak memory)
+ * - Parallelism benefits (more chunks = better parallel throughput)
+ */
+/** Minimum chunk size (1MB) - for smaller datasets or high memory pressure */
+const MIN_CHUNK_SIZE = 1 * 1024 * 1024
+/** Maximum chunk size (10MB) - optimal for large sequential transfers */
+const MAX_CHUNK_SIZE = 10 * 1024 * 1024
+/** Target number of chunks for parallel operations (4-8 is optimal for most networks) */
+const TARGET_CHUNK_COUNT = 6
+/** Maximum concurrent chunk operations */
+const MAX_PARALLEL_OPERATIONS = 4
+
+/**
+ * LRU Cache entry for overflow data
+ */
+interface CacheEntry {
+  data: Uint8Array
+  key: string
+  size: number
+  accessedAt: number
+  createdAt: number
+}
+
+/**
+ * LRU Cache for frequently accessed overflow data
+ */
+class OverflowLRUCache {
+  private cache: Map<string, CacheEntry>
+  private maxSizeBytes: number
+  private currentSizeBytes: number
+
+  constructor(maxSizeBytes: number = 50 * 1024 * 1024) {
+    this.cache = new Map()
+    this.maxSizeBytes = maxSizeBytes
+    this.currentSizeBytes = 0
+  }
+
+  get(key: string): Uint8Array | null {
+    const entry = this.cache.get(key)
+    if (!entry) return null
+
+    // Update access time and move to end (most recently used)
+    entry.accessedAt = Date.now()
+    this.cache.delete(key)
+    this.cache.set(key, entry)
+
+    return entry.data
+  }
+
+  set(key: string, data: Uint8Array): void {
+    const size = data.length
+
+    // Don't cache items larger than 25% of max cache size
+    if (size > this.maxSizeBytes * 0.25) return
+
+    // Remove existing entry if present
+    if (this.cache.has(key)) {
+      const existing = this.cache.get(key)!
+      this.currentSizeBytes -= existing.size
+      this.cache.delete(key)
+    }
+
+    // Evict LRU entries until we have space
+    while (this.currentSizeBytes + size > this.maxSizeBytes && this.cache.size > 0) {
+      const oldestKey = this.cache.keys().next().value
+      if (oldestKey) {
+        const entry = this.cache.get(oldestKey)!
+        this.currentSizeBytes -= entry.size
+        this.cache.delete(oldestKey)
+      }
+    }
+
+    // Add new entry
+    const entry: CacheEntry = {
+      data,
+      key,
+      size,
+      accessedAt: Date.now(),
+      createdAt: Date.now(),
+    }
+    this.cache.set(key, entry)
+    this.currentSizeBytes += size
+  }
+
+  delete(key: string): boolean {
+    const entry = this.cache.get(key)
+    if (!entry) return false
+
+    this.currentSizeBytes -= entry.size
+    this.cache.delete(key)
+    return true
+  }
+
+  clear(): void {
+    this.cache.clear()
+    this.currentSizeBytes = 0
+  }
+
+  getStats(): { entries: number; sizeBytes: number; maxSizeBytes: number } {
+    return {
+      entries: this.cache.size,
+      sizeBytes: this.currentSizeBytes,
+      maxSizeBytes: this.maxSizeBytes,
+    }
+  }
+
+  setMaxSize(maxSizeBytes: number): void {
+    this.maxSizeBytes = maxSizeBytes
+    // Evict if over new limit
+    while (this.currentSizeBytes > this.maxSizeBytes && this.cache.size > 0) {
+      const oldestKey = this.cache.keys().next().value
+      if (oldestKey) {
+        const entry = this.cache.get(oldestKey)!
+        this.currentSizeBytes -= entry.size
+        this.cache.delete(oldestKey)
+      }
+    }
+  }
+}
+
+/**
+ * Calculate optimal chunk size based on total data size
+ *
+ * Strategy:
+ * - Small data (< 10MB): Use minimum chunk size for quick transfer
+ * - Medium data (10MB - 100MB): Target 4-8 chunks for parallel benefit
+ * - Large data (> 100MB): Use maximum chunk size to reduce overhead
+ */
+function calculateOptimalChunkSize(totalSize: number): number {
+  if (totalSize < MIN_CHUNK_SIZE * 4) {
+    // Small data: use minimum chunks
+    return MIN_CHUNK_SIZE
+  }
+
+  if (totalSize > MAX_CHUNK_SIZE * TARGET_CHUNK_COUNT) {
+    // Very large data: use maximum chunk size
+    return MAX_CHUNK_SIZE
+  }
+
+  // Medium data: target optimal chunk count
+  const idealChunkSize = Math.ceil(totalSize / TARGET_CHUNK_COUNT)
+  return Math.max(MIN_CHUNK_SIZE, Math.min(MAX_CHUNK_SIZE, idealChunkSize))
+}
+
+/**
+ * R2OverflowManager handles automatic spillover of large query results to R2.
+ *
+ * When query results exceed the configured threshold, they are automatically
+ * stored in R2 and a handle is returned that can be used to retrieve them later.
+ *
+ * @example
+ * ```typescript
+ * const manager = createR2OverflowManager({
+ *   r2Layer,
+ *   spillThresholdBytes: 10 * 1024 * 1024, // 10MB
+ *   memoryPressureThreshold: 0.8,
+ *   maxInMemoryResultBytes: 50 * 1024 * 1024,
+ *   overflowTtlMs: 3600000, // 1 hour
+ *   overflowPrefix: 'overflow/',
+ *   autoCleanup: true,
+ * })
+ *
+ * // Check if data should spill
+ * if (manager.shouldSpill(largeResult)) {
+ *   const result = await manager.spill(largeResult)
+ *   // Store result.overflowKey for later retrieval
+ * }
+ *
+ * // Later, retrieve the data
+ * const data = await manager.retrieveByKey(overflowKey)
+ * ```
+ */
+export class R2OverflowManager {
+  private config: R2OverflowConfig
+  private originalSpillThreshold: number
+  private stats: OverflowStats
+  private activeOverflows: Map<string, SpilledResultHandle>
+  private overflowCallbacks: Array<(result: OverflowResult) => void>
+  private memoryPressureCallbacks: Array<(signal: MemoryPressureSignal) => void>
+  private keyCounter: number
+  private cache: OverflowLRUCache
+
+  constructor(config: R2OverflowConfig) {
+    this.config = { ...config }
+    this.originalSpillThreshold = config.spillThresholdBytes
+    this.stats = {
+      spillCount: 0,
+      bytesSpilled: 0,
+      retrievalCount: 0,
+      bytesRetrieved: 0,
+      cleanupCount: 0,
+      bytesCleanedUp: 0,
+      memoryPressureEvents: 0,
+      activeOverflows: 0,
+    }
+    this.activeOverflows = new Map()
+    this.overflowCallbacks = []
+    this.memoryPressureCallbacks = []
+    this.keyCounter = 0
+    // Initialize LRU cache with 50MB default max size
+    this.cache = new OverflowLRUCache(50 * 1024 * 1024)
+  }
+
+  /**
+   * Check if data should be spilled to R2 based on size threshold
+   */
+  shouldSpill(data: Uint8Array): boolean {
+    return data.length > this.config.spillThresholdBytes
+  }
+
+  /**
+   * Spill data to R2 and return handle
+   *
+   * Data under the threshold will not be spilled.
+   * Very large data will be split into chunks with adaptive sizing.
+   * Chunks are uploaded in parallel for improved performance.
+   */
+  async spill(data: Uint8Array, metadata?: Record<string, string>): Promise<OverflowResult> {
+    const originalSize = data.length
+
+    // Don't spill empty or small data
+    if (originalSize === 0 || originalSize <= this.config.spillThresholdBytes) {
+      return {
+        spilled: false,
+        originalSize,
+      }
+    }
+
+    const spilledAt = Date.now()
+    const overflowKey = this.generateKey()
+    const expiresAt = spilledAt + this.config.overflowTtlMs
+
+    // Calculate adaptive chunk size based on data size
+    const chunkSize = calculateOptimalChunkSize(originalSize)
+    const numChunks = Math.ceil(originalSize / chunkSize)
+
+    const fullMetadata = {
+      ...metadata,
+      originalSize: originalSize.toString(),
+      spilledAt: spilledAt.toString(),
+      expiresAt: expiresAt.toString(),
+      chunks: numChunks.toString(),
+      chunkSize: chunkSize.toString(),
+    }
+
+    if (numChunks === 1) {
+      // Single chunk - write directly
+      await this.config.r2Layer.put(overflowKey, data, {
+        customMetadata: fullMetadata,
+      })
+    } else {
+      // Multiple chunks - upload in parallel batches
+      const uploadChunk = async (chunkIndex: number) => {
+        const start = chunkIndex * chunkSize
+        const end = Math.min(start + chunkSize, originalSize)
+        const chunkData = data.slice(start, end)
+        const chunkKey = `${overflowKey}:chunk:${chunkIndex}`
+
+        await this.config.r2Layer.put(chunkKey, chunkData, {
+          customMetadata: {
+            ...fullMetadata,
+            chunkIndex: chunkIndex.toString(),
+            chunkStart: start.toString(),
+            chunkEnd: end.toString(),
+          },
+        })
+      }
+
+      // Upload chunks in parallel batches
+      for (let batchStart = 0; batchStart < numChunks; batchStart += MAX_PARALLEL_OPERATIONS) {
+        const batchEnd = Math.min(batchStart + MAX_PARALLEL_OPERATIONS, numChunks)
+        const batchPromises: Promise<void>[] = []
+
+        for (let i = batchStart; i < batchEnd; i++) {
+          batchPromises.push(uploadChunk(i))
+        }
+
+        await Promise.all(batchPromises)
+      }
+    }
+
+    // Track the overflow
+    const handle: SpilledResultHandle = {
+      key: overflowKey,
+      size: originalSize,
+      chunks: numChunks,
+      spilledAt,
+      expiresAt,
+      metadata: metadata || {},
+    }
+    this.activeOverflows.set(overflowKey, handle)
+
+    // Update stats
+    this.stats.spillCount++
+    this.stats.bytesSpilled += originalSize
+    this.stats.activeOverflows = this.activeOverflows.size
+
+    const result: OverflowResult = {
+      spilled: true,
+      overflowKey,
+      originalSize,
+      spilledAt,
+      chunks: numChunks,
+    }
+
+    // Notify callbacks
+    for (const callback of this.overflowCallbacks) {
+      callback(result)
+    }
+
+    return result
+  }
+
+  /**
+   * Retrieve spilled data by handle
+   *
+   * Uses LRU cache for frequently accessed data.
+   * Downloads chunks in parallel for improved performance.
+   */
+  async retrieve(handle: SpilledResultHandle): Promise<Uint8Array> {
+    // Check cache first
+    const cached = this.cache.get(handle.key)
+    if (cached) {
+      this.stats.retrievalCount++
+      this.stats.bytesRetrieved += cached.length
+      return cached
+    }
+
+    let result: Uint8Array
+
+    if (handle.chunks === 1) {
+      // Single chunk - read directly
+      const data = await this.config.r2Layer.get(handle.key)
+      if (!data) {
+        throw new Error(`Overflow data not found: ${handle.key}`)
+      }
+      result = data
+    } else {
+      // Multiple chunks - download in parallel batches
+      const chunkResults: Array<{ index: number; data: Uint8Array }> = []
+
+      const downloadChunk = async (chunkIndex: number) => {
+        const chunkKey = `${handle.key}:chunk:${chunkIndex}`
+        const chunkData = await this.config.r2Layer.get(chunkKey)
+        if (!chunkData) {
+          throw new Error(`Chunk not found: ${chunkKey}`)
+        }
+        return { index: chunkIndex, data: chunkData }
+      }
+
+      // Download chunks in parallel batches
+      for (let batchStart = 0; batchStart < handle.chunks; batchStart += MAX_PARALLEL_OPERATIONS) {
+        const batchEnd = Math.min(batchStart + MAX_PARALLEL_OPERATIONS, handle.chunks)
+        const batchPromises: Promise<{ index: number; data: Uint8Array }>[] = []
+
+        for (let i = batchStart; i < batchEnd; i++) {
+          batchPromises.push(downloadChunk(i))
+        }
+
+        const batchResults = await Promise.all(batchPromises)
+        chunkResults.push(...batchResults)
+      }
+
+      // Sort by index and combine
+      chunkResults.sort((a, b) => a.index - b.index)
+      const totalSize = chunkResults.reduce((sum, c) => sum + c.data.length, 0)
+
+      result = new Uint8Array(totalSize)
+      let offset = 0
+      for (const chunk of chunkResults) {
+        result.set(chunk.data, offset)
+        offset += chunk.data.length
+      }
+    }
+
+    // Update stats
+    this.stats.retrievalCount++
+    this.stats.bytesRetrieved += result.length
+
+    // Cache for future access
+    this.cache.set(handle.key, result)
+
+    return result
+  }
+
+  /**
+   * Retrieve spilled data by key directly
+   *
+   * Uses LRU cache for frequently accessed data.
+   * Falls back to R2 retrieval if not cached or tracked.
+   */
+  async retrieveByKey(key: string): Promise<Uint8Array | null> {
+    // Check cache first (even for untracked keys)
+    const cached = this.cache.get(key)
+    if (cached) {
+      this.stats.retrievalCount++
+      this.stats.bytesRetrieved += cached.length
+      return cached
+    }
+
+    // Try to get the handle from our tracking
+    const handle = this.activeOverflows.get(key)
+
+    if (handle) {
+      return this.retrieve(handle)
+    }
+
+    // Direct retrieval for untracked keys
+    const data = await this.config.r2Layer.get(key)
+    if (data) {
+      this.stats.retrievalCount++
+      this.stats.bytesRetrieved += data.length
+      // Cache for future access
+      this.cache.set(key, data)
+    }
+    return data
+  }
+
+  /**
+   * Clean up a specific overflow entry by key
+   *
+   * Removes data from R2 and invalidates cache entry.
+   */
+  async cleanup(key: string): Promise<boolean> {
+    // Always remove from cache regardless of tracking status
+    this.cache.delete(key)
+
+    const handle = this.activeOverflows.get(key)
+
+    if (!handle) {
+      // Check if key exists in R2
+      const exists = await this.config.r2Layer.has(key)
+      if (!exists) {
+        return false
+      }
+      // Delete even if not tracked
+      await this.config.r2Layer.delete(key)
+      return true
+    }
+
+    const size = handle.size
+
+    if (handle.chunks === 1) {
+      // Single chunk
+      await this.config.r2Layer.delete(key)
+    } else {
+      // Multiple chunks - delete all
+      const chunkKeys = Array.from({ length: handle.chunks }, (_, i) => `${key}:chunk:${i}`)
+      await this.config.r2Layer.deleteMany(chunkKeys)
+    }
+
+    // Remove from tracking
+    this.activeOverflows.delete(key)
+
+    // Update stats
+    this.stats.cleanupCount++
+    this.stats.bytesCleanedUp += size
+    this.stats.activeOverflows = this.activeOverflows.size
+
+    return true
+  }
+
+  /**
+   * Clean up all expired overflow entries
+   */
+  async cleanupExpired(): Promise<number> {
+    const now = Date.now()
+    const expiredKeys: string[] = []
+
+    // Check tracked overflows
+    for (const [key, handle] of this.activeOverflows) {
+      if (handle.expiresAt <= now) {
+        expiredKeys.push(key)
+      }
+    }
+
+    // Also check R2 for any untracked expired entries
+    const allKeys = await this.config.r2Layer.listAll()
+    for (const key of allKeys) {
+      if (!this.activeOverflows.has(key)) {
+        const head = await this.config.r2Layer.head(key)
+        if (head?.customMetadata?.expiresAt) {
+          const expiresAt = parseInt(head.customMetadata.expiresAt, 10)
+          if (expiresAt <= now && !expiredKeys.includes(key)) {
+            expiredKeys.push(key)
+          }
+        }
+      }
+    }
+
+    if (expiredKeys.length === 0) {
+      return 0
+    }
+
+    // Delete all expired entries
+    await this.config.r2Layer.deleteMany(expiredKeys)
+
+    // Remove from tracking
+    for (const key of expiredKeys) {
+      const handle = this.activeOverflows.get(key)
+      if (handle) {
+        this.stats.bytesCleanedUp += handle.size
+        this.activeOverflows.delete(key)
+      }
+      // Also remove from cache
+      this.cache.delete(key)
+    }
+
+    this.stats.cleanupCount += expiredKeys.length
+    this.stats.activeOverflows = this.activeOverflows.size
+
+    return expiredKeys.length
+  }
+
+  /**
+   * Handle memory pressure signal
+   *
+   * When memory pressure is high, the manager will:
+   * 1. Lower the spill threshold to encourage more spillover
+   * 2. Trigger cleanup of expired entries (if critical)
+   */
+  async handleMemoryPressure(signal: MemoryPressureSignal): Promise<void> {
+    this.stats.memoryPressureEvents++
+
+    // Notify callbacks
+    for (const callback of this.memoryPressureCallbacks) {
+      callback(signal)
+    }
+
+    // Adjust threshold based on pressure
+    if (signal.usageRatio >= this.config.memoryPressureThreshold) {
+      // Calculate reduced threshold based on pressure severity
+      const pressureFactor = 1 - ((signal.usageRatio - this.config.memoryPressureThreshold) / (1 - this.config.memoryPressureThreshold))
+      const reducedThreshold = Math.max(
+        1024, // Minimum 1KB
+        Math.floor(this.originalSpillThreshold * pressureFactor * 0.5)
+      )
+      this.config.spillThresholdBytes = reducedThreshold
+    } else if (signal.usageRatio < this.config.memoryPressureThreshold) {
+      // Gradually restore threshold when pressure subsides
+      const restorationFactor = 1 - (signal.usageRatio / this.config.memoryPressureThreshold)
+      const restoredThreshold = Math.min(
+        this.originalSpillThreshold,
+        this.config.spillThresholdBytes + Math.floor((this.originalSpillThreshold - this.config.spillThresholdBytes) * restorationFactor)
+      )
+      this.config.spillThresholdBytes = restoredThreshold
+    }
+
+    // Trigger cleanup on critical pressure
+    if (signal.critical && this.config.autoCleanup) {
+      await this.cleanupExpired()
+    }
+  }
+
+  /**
+   * Get all active overflow handles
+   */
+  getActiveOverflows(): SpilledResultHandle[] {
+    return Array.from(this.activeOverflows.values())
+  }
+
+  /**
+   * Get statistics
+   */
+  getStats(): OverflowStats {
+    return { ...this.stats }
+  }
+
+  /**
+   * Reset statistics
+   */
+  resetStats(): void {
+    this.stats = {
+      spillCount: 0,
+      bytesSpilled: 0,
+      retrievalCount: 0,
+      bytesRetrieved: 0,
+      cleanupCount: 0,
+      bytesCleanedUp: 0,
+      memoryPressureEvents: 0,
+      activeOverflows: this.activeOverflows.size,
+    }
+  }
+
+  /**
+   * Configure the manager
+   */
+  configure(config: Partial<R2OverflowConfig>): void {
+    if (config.spillThresholdBytes !== undefined) {
+      this.config.spillThresholdBytes = config.spillThresholdBytes
+      this.originalSpillThreshold = config.spillThresholdBytes
+    }
+    if (config.memoryPressureThreshold !== undefined) {
+      this.config.memoryPressureThreshold = config.memoryPressureThreshold
+    }
+    if (config.maxInMemoryResultBytes !== undefined) {
+      this.config.maxInMemoryResultBytes = config.maxInMemoryResultBytes
+    }
+    if (config.overflowTtlMs !== undefined) {
+      this.config.overflowTtlMs = config.overflowTtlMs
+    }
+    if (config.overflowPrefix !== undefined) {
+      this.config.overflowPrefix = config.overflowPrefix
+    }
+    if (config.autoCleanup !== undefined) {
+      this.config.autoCleanup = config.autoCleanup
+    }
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): R2OverflowConfig {
+    return { ...this.config }
+  }
+
+  /**
+   * Register callback for overflow events
+   */
+  onOverflow(callback: (result: OverflowResult) => void): void {
+    this.overflowCallbacks.push(callback)
+  }
+
+  /**
+   * Register callback for memory pressure events
+   */
+  onMemoryPressure(callback: (signal: MemoryPressureSignal) => void): void {
+    this.memoryPressureCallbacks.push(callback)
+  }
+
+  /**
+   * Generate a unique key for overflow data
+   */
+  private generateKey(): string {
+    const timestamp = Date.now()
+    const random = Math.random().toString(36).substring(2, 10)
+    const counter = this.keyCounter++
+    return `${this.config.overflowPrefix}${timestamp}-${random}-${counter}`
+  }
+
+  // ============================================
+  // Cache Management API
+  // ============================================
+
+  /**
+   * Get cache statistics
+   *
+   * Returns information about the LRU cache state including
+   * number of entries, current size, and maximum size.
+   */
+  getCacheStats(): { entries: number; sizeBytes: number; maxSizeBytes: number } {
+    return this.cache.getStats()
+  }
+
+  /**
+   * Set maximum cache size
+   *
+   * Adjusts the maximum cache size. If the current cache exceeds
+   * the new limit, entries will be evicted (LRU order).
+   *
+   * @param maxSizeBytes - Maximum cache size in bytes
+   */
+  setCacheMaxSize(maxSizeBytes: number): void {
+    this.cache.setMaxSize(maxSizeBytes)
+  }
+
+  /**
+   * Clear the entire cache
+   *
+   * Removes all cached entries. Does not affect R2 storage.
+   */
+  clearCache(): void {
+    this.cache.clear()
+  }
+
+  /**
+   * Prefetch data into cache
+   *
+   * Proactively loads data from R2 into the cache for faster
+   * subsequent access. Useful when you know data will be needed soon.
+   *
+   * @param key - The overflow key to prefetch
+   * @returns true if prefetch succeeded, false if data not found
+   */
+  async prefetch(key: string): Promise<boolean> {
+    // Already cached?
+    if (this.cache.get(key)) {
+      return true
+    }
+
+    const handle = this.activeOverflows.get(key)
+    if (handle) {
+      try {
+        await this.retrieve(handle)
+        return true
+      } catch {
+        return false
+      }
+    }
+
+    // Try direct retrieval
+    const data = await this.config.r2Layer.get(key)
+    if (data) {
+      this.cache.set(key, data)
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Invalidate a specific cache entry
+   *
+   * Removes an entry from the cache without affecting R2 storage.
+   * Useful when you know the data has changed externally.
+   *
+   * @param key - The overflow key to invalidate
+   * @returns true if entry was in cache and removed
+   */
+  invalidateCache(key: string): boolean {
+    return this.cache.delete(key)
+  }
+}
+
+/**
+ * Create a new R2OverflowManager instance
+ *
+ * @param config - Configuration for the overflow manager
+ * @returns A configured R2OverflowManager instance
+ */
+export function createR2OverflowManager(config: R2OverflowConfig): R2OverflowManager {
+  return new R2OverflowManager(config)
+}