@dotdo/postgres 0.1.0

package/src/pglite/warm-loader.ts

@@ -0,0 +1,528 @@
+/**
+ * Warm WASM Loader Pattern
+ *
+ * Provides a singleton pattern for PGLite instances within a Cloudflare Worker isolate.
+ * The goal is to minimize cold start latency by:
+ *
+ * 1. Caching the initialized PGLite instance at the module level
+ * 2. Tracking cold vs warm starts for observability
+ * 3. Providing reset capability for testing and error recovery
+ *
+ * Cloudflare Worker Isolate Lifecycle:
+ * - Workers run in V8 isolates that persist across multiple requests
+ * - Global/module-level state survives between requests in the same isolate
+ * - Isolates are eventually recycled (cold start) or reused (warm start)
+ *
+ * Usage Pattern:
+ * ```typescript
+ * import wasmModule from './pglite.wasm'
+ *
+ * const loader = createWarmPGliteLoader()
+ *
+ * export default {
+ *   async fetch(request, env) {
+ *     const pglite = await loader.get({
+ *       wasmModule,
+ *       fsBundle: env.FS_BUNDLE,
+ *     })
+ *
+ *     const result = await pglite.query('SELECT 1')
+ *     return new Response(JSON.stringify(result))
+ *   }
+ * }
+ * ```
+ *
+ * @module pglite/warm-loader
+ */
+
+import type { PGlite, PGliteOptions, Extensions } from '@dotdo/pglite'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Configuration for warm loader initialization
+ */
+export interface WarmLoaderConfig {
+  /**
+   * Pre-compiled WebAssembly module for PGLite
+   * Should be statically imported: `import wasmModule from './pglite.wasm'`
+   */
+  wasmModule: WebAssembly.Module
+
+  /**
+   * Filesystem bundle containing PGLite's PostgreSQL data directory
+   * Can be an ArrayBuffer from R2/Cache or a Blob
+   */
+  fsBundle: ArrayBuffer | Blob
+
+  /**
+   * Whether to initialize PGLite in read-only mode
+   * Read-only instances can share the same WASM memory more efficiently
+   * @default false
+   */
+  readOnly?: boolean
+
+  /**
+   * Database name/path for PGLite
+   * @default 'idb://pglite'
+   */
+  dataDir?: string
+
+  /**
+   * Additional PGLite options to pass during initialization
+   */
+  pgliteOptions?: Partial<PGliteOptions>
+
+  /**
+   * Extensions to load during initialization
+   * Extensions are loaded once during cold start
+   */
+  extensions?: Extensions
+
+  /**
+   * Timeout for initialization in milliseconds
+   * @default 30000 (30 seconds)
+   */
+  initTimeoutMs?: number
+}
+
+/**
+ * Statistics about warm loader usage
+ */
+export interface WarmLoaderStats {
+  /**
+   * Number of cold starts (full initialization)
+   * Incremented each time PGLite is initialized from scratch
+   */
+  coldStarts: number
+
+  /**
+   * Number of warm starts (cached instance returned)
+   * Incremented each time a cached instance is returned
+   */
+  warmStarts: number
+
+  /**
+   * Duration of the last initialization in milliseconds
+   * Only updated on cold starts
+   */
+  lastInitDurationMs: number
+
+  /**
+   * Time since the isolate started in milliseconds
+   * Useful for understanding isolate recycling patterns
+   */
+  isolateAgeMs: number
+
+  /**
+   * Timestamp when the isolate started (first cold start)
+   */
+  isolateStartedAt: number
+
+  /**
+   * Timestamp of the last cold start
+   * May differ from isolateStartedAt if reset() was called
+   */
+  lastColdStartAt: number
+
+  /**
+   * Total time saved by warm starts in milliseconds
+   * Calculated as: warmStarts * lastInitDurationMs
+   */
+  estimatedTimeSavedMs: number
+
+  /**
+   * Whether the loader currently has a cached instance
+   */
+  isWarm: boolean
+}
+
+/**
+ * Warm PGLite Loader interface
+ *
+ * Implements the singleton pattern for PGLite instances within an isolate.
+ * Thread-safe handling of concurrent initialization requests is guaranteed.
+ */
+export interface WarmPGliteLoader {
+  /**
+   * Get or initialize a PGLite instance
+   *
+   * On cold start: Initializes a new PGLite instance with the provided config
+   * On warm start: Returns the cached instance immediately
+   *
+   * Thread-safe: Concurrent calls during initialization will wait for the
+   * same initialization promise to resolve.
+   *
+   * @param config - Configuration for initialization (used only on cold start)
+   * @returns Promise resolving to the PGLite instance
+   * @throws Error if initialization fails or times out
+   *
+   * @example
+   * ```typescript
+   * const pglite = await loader.get({
+   *   wasmModule: wasmModule,
+   *   fsBundle: env.FS_BUNDLE,
+   *   dataDir: 'idb://mydb',
+   *   readOnly: false,
+   *   initTimeoutMs: 30000,
+   * })
+   *
+   * // Execute queries
+   * const result = await pglite.query('SELECT NOW()')
+   * console.log(result.rows[0])
+   * ```
+   */
+  get(config: WarmLoaderConfig): Promise<PGlite>
+
+  /**
+   * Check if the loader has a cached instance ready
+   *
+   * @returns true if a warm instance is available, false if next get() will cold start
+   */
+  isWarm(): boolean
+
+  /**
+   * Get current statistics about loader usage
+   *
+   * @returns Current stats snapshot
+   *
+   * @example
+   * ```typescript
+   * const stats = loader.getStats()
+   * console.log(`Cold starts: ${stats.coldStarts}`)
+   * console.log(`Warm starts: ${stats.warmStarts}`)
+   * console.log(`Time saved: ${stats.estimatedTimeSavedMs}ms`)
+   * console.log(`Isolate age: ${stats.isolateAgeMs}ms`)
+   * ```
+   */
+  getStats(): WarmLoaderStats
+
+  /**
+   * Reset the loader, closing any existing instance
+   *
+   * Use cases:
+   * - Error recovery (instance in bad state)
+   * - Testing (verify cold start behavior)
+   * - Configuration change (need different options)
+   *
+   * @returns Promise that resolves when reset is complete
+   */
+  reset(): Promise<void>
+
+  /**
+   * Close the loader and release resources
+   *
+   * Should be called when the worker is shutting down.
+   * After close(), the loader cannot be used again.
+   *
+   * @returns Promise that resolves when close is complete
+   */
+  close(): Promise<void>
+}
+
+// ============================================================================
+// Factory
+// ============================================================================
+
+/**
+ * Default PGLite factory function
+ * Can be overridden in tests via dependency injection
+ */
+export type PGliteFactory = (config: WarmLoaderConfig) => Promise<PGlite>
+
+/**
+ * Options for creating a warm loader (for testing/dependency injection)
+ */
+export interface WarmLoaderOptions {
+  /**
+   * Custom PGLite factory function for dependency injection
+   * Useful for testing without actual WASM loading
+   */
+  pgliteFactory?: PGliteFactory
+}
+
+/**
+ * Default factory that creates real PGLite instances
+ *
+ * Supports Cloudflare Workers by accepting pre-compiled wasmModule and fsBundle
+ * to bypass dynamic WASM loading which is blocked in Workers environments.
+ */
+async function defaultPGliteFactory(config: WarmLoaderConfig): Promise<PGlite> {
+  // Dynamic import to avoid issues when PGlite is not available
+  const { PGlite } = await import('@dotdo/pglite')
+
+  const options: PGliteOptions = {
+    ...config.pgliteOptions,
+    dataDir: config.dataDir ?? 'idb://pglite',
+  }
+
+  // Pass wasmModule for Cloudflare Workers compatibility
+  // This allows using statically imported WASM modules:
+  //   import wasmModule from './pglite.wasm'
+  if (config.wasmModule) {
+    options.wasmModule = config.wasmModule
+  }
+
+  // Pass fsBundle for Cloudflare Workers compatibility
+  // This provides the PostgreSQL filesystem bundle without URL resolution:
+  //   fsBundle: new Blob([fsBundleData])
+  if (config.fsBundle) {
+    // PGLite expects Blob | File, convert ArrayBuffer if needed
+    options.fsBundle =
+      config.fsBundle instanceof Blob ? config.fsBundle : new Blob([config.fsBundle])
+  }
+
+  // Only add extensions if provided and non-empty
+  if (config.extensions && Object.keys(config.extensions).length > 0) {
+    options.extensions = config.extensions
+  }
+
+  const pglite = new PGlite(options)
+  await pglite.waitReady
+  return pglite
+}
+
+/**
+ * Create a new WarmPGliteLoader instance
+ *
+ * Typically called once at module level to create the singleton loader.
+ *
+ * @param options - Optional configuration for dependency injection
+ * @returns A new WarmPGliteLoader instance
+ *
+ * @example
+ * ```typescript
+ * import wasmModule from './pglite.wasm'
+ *
+ * // Create loader at module level (singleton pattern)
+ * const loader = createWarmPGliteLoader()
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     // Get or initialize PGLite instance
+ *     const pglite = await loader.get({
+ *       wasmModule,
+ *       fsBundle: env.FS_BUNDLE,
+ *       dataDir: 'idb://mydb',
+ *     })
+ *
+ *     const result = await pglite.query('SELECT * FROM users')
+ *     return Response.json(result.rows)
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom factory for testing
+ * const mockPGlite = { query: vi.fn(), close: vi.fn() } as unknown as PGlite
+ * const loader = createWarmPGliteLoader({
+ *   pgliteFactory: async () => mockPGlite,
+ * })
+ * ```
+ */
+export function createWarmPGliteLoader(options: WarmLoaderOptions = {}): WarmPGliteLoader {
+  const factory = options.pgliteFactory ?? defaultPGliteFactory
+
+  // Instance state
+  let instance: PGlite | null = null
+  let initPromise: Promise<PGlite> | null = null
+  let closed = false
+
+  // Statistics state
+  let coldStarts = 0
+  let warmStarts = 0
+  let lastInitDurationMs = 0
+  let lastColdStartAt = 0
+  const isolateStartedAt = Date.now()
+
+  /**
+   * Internal initialization function
+   */
+  async function doInitialize(config: WarmLoaderConfig): Promise<PGlite> {
+    const startTime = performance.now()
+
+    // Set up timeout if specified
+    const timeoutMs = config.initTimeoutMs ?? 30000
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(`PGLite initialization timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+    })
+
+    try {
+      const pglite = await Promise.race([factory(config), timeoutPromise])
+      clearTimeout(timeoutId)
+
+      const endTime = performance.now()
+      lastInitDurationMs = endTime - startTime
+      lastColdStartAt = Date.now()
+      coldStarts++
+
+      return pglite
+    } catch (error) {
+      clearTimeout(timeoutId)
+      // Clear the init promise so retry is possible
+      initPromise = null
+      throw error
+    }
+  }
+
+  return {
+    async get(config: WarmLoaderConfig): Promise<PGlite> {
+      // Check if closed
+      if (closed) {
+        throw new Error('Loader is closed')
+      }
+
+      // Warm start: return cached instance
+      if (instance) {
+        warmStarts++
+        return instance
+      }
+
+      // Cold start or concurrent initialization
+      if (!initPromise) {
+        // Start new initialization
+        initPromise = doInitialize(config).then((pglite) => {
+          instance = pglite
+          return pglite
+        })
+      }
+
+      // Wait for initialization (handles both new and concurrent cases)
+      return initPromise
+    },
+
+    isWarm(): boolean {
+      return instance !== null && !closed
+    },
+
+    getStats(): WarmLoaderStats {
+      const now = Date.now()
+      return {
+        coldStarts,
+        warmStarts,
+        lastInitDurationMs,
+        isolateAgeMs: now - isolateStartedAt,
+        isolateStartedAt,
+        lastColdStartAt,
+        estimatedTimeSavedMs: warmStarts * lastInitDurationMs,
+        isWarm: instance !== null && !closed,
+      }
+    },
+
+    async reset(): Promise<void> {
+      // Wait for any pending initialization to complete first
+      if (initPromise) {
+        try {
+          await initPromise
+        } catch {
+          // Ignore errors from pending initialization
+        }
+      }
+
+      // Close existing instance if present
+      if (instance) {
+        try {
+          await instance.close()
+        } catch {
+          // Ignore close errors during reset
+        }
+      }
+
+      // Reset state
+      instance = null
+      initPromise = null
+    },
+
+    async close(): Promise<void> {
+      // Mark as closed first to prevent new get() calls
+      closed = true
+
+      // Wait for any pending initialization
+      if (initPromise) {
+        try {
+          await initPromise
+        } catch {
+          // Ignore errors from pending initialization
+        }
+      }
+
+      // Close the instance
+      if (instance) {
+        try {
+          await instance.close()
+        } catch {
+          // Ignore close errors
+        }
+        instance = null
+      }
+
+      initPromise = null
+    },
+  }
+}
+
+// ============================================================================
+// Module-level Singleton (convenience export)
+// ============================================================================
+
+/**
+ * Lazily initialized default loader instance
+ */
+let _defaultLoader: WarmPGliteLoader | null = null
+
+/**
+ * Get the default module-level loader instance
+ *
+ * Uses lazy initialization to avoid issues with module load order.
+ * The loader is created on first access.
+ *
+ * For simple use cases, you can import and use this directly:
+ * ```typescript
+ * import { getDefaultLoader } from './warm-loader'
+ *
+ * const pglite = await getDefaultLoader().get(config)
+ * ```
+ */
+export function getDefaultLoader(): WarmPGliteLoader {
+  if (!_defaultLoader) {
+    _defaultLoader = createWarmPGliteLoader()
+  }
+  return _defaultLoader
+}
+
+/**
+ * Default module-level loader instance
+ *
+ * For simple use cases, you can import and use this directly:
+ * ```typescript
+ * import { defaultLoader } from './warm-loader'
+ *
+ * const pglite = await defaultLoader.get(config)
+ * ```
+ *
+ * Note: This is a proxy that lazily creates the loader on first use.
+ */
+export const defaultLoader: WarmPGliteLoader = {
+  get(config: WarmLoaderConfig): Promise<PGlite> {
+    return getDefaultLoader().get(config)
+  },
+  isWarm(): boolean {
+    return _defaultLoader?.isWarm() ?? false
+  },
+  getStats(): WarmLoaderStats {
+    return getDefaultLoader().getStats()
+  },
+  reset(): Promise<void> {
+    return _defaultLoader?.reset() ?? Promise.resolve()
+  },
+  close(): Promise<void> {
+    return _defaultLoader?.close() ?? Promise.resolve()
+  },
+}