@dotdo/postgres 0.1.0

package/src/pglite/warm-loader.test.ts

@@ -0,0 +1,1701 @@
+/**
+ * Tests for Warm WASM Loader Pattern
+ *
+ * Tests cover:
+ * - Singleton pattern within isolate
+ * - Cold start initialization
+ * - Warm start (cached instance) retrieval
+ * - Statistics tracking
+ * - Reset functionality
+ * - Concurrent access handling
+ * - Error handling and recovery
+ * - Resource cleanup
+ *
+ * @module pglite/warm-loader.test
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  createWarmPGliteLoader,
+  type WarmPGliteLoader,
+  type WarmLoaderConfig,
+  type WarmLoaderStats,
+} from './warm-loader'
+import type { PGlite } from '@dotdo/pglite'
+import {
+  delay,
+  createMockWasmModule,
+  createMockFsBundle,
+  createMockPGlite as createBaseMockPGlite,
+  CI_MULTIPLIER,
+} from '../__tests__/test-utils'
+
+// ============================================================================
+// Mock Factories (using shared utilities + local extensions)
+// ============================================================================
+
+/**
+ * Create a mock PGlite instance with full interface for warm-loader tests
+ */
+function createMockPGlite(): PGlite {
+  const baseMock = createBaseMockPGlite()
+  return {
+    ...baseMock,
+    query: vi.fn().mockResolvedValue({ rows: [], fields: [] }),
+    exec: vi.fn().mockResolvedValue([]),
+  } as unknown as PGlite
+}
+
+function createMockConfig(overrides?: Partial<WarmLoaderConfig>): WarmLoaderConfig {
+  return {
+    wasmModule: createMockWasmModule(),
+    fsBundle: createMockFsBundle(),
+    ...overrides,
+  }
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe('WarmPGliteLoader', () => {
+  let loader: WarmPGliteLoader
+
+  beforeEach(() => {
+    loader = createWarmPGliteLoader()
+  })
+
+  afterEach(async () => {
+    // Clean up loader instance after each test
+    if (loader.isWarm()) {
+      await loader.reset()
+    }
+  })
+
+  // ==========================================================================
+  // Singleton Pattern Tests
+  // ==========================================================================
+
+  describe('singleton pattern', () => {
+    it('should return same instance across multiple calls', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      const pglite1 = await loader.get(config)
+      const pglite2 = await loader.get(config)
+
+      expect(pglite1).toBe(pglite2) // reference equality
+      await loader.close()
+    })
+
+    it('should only initialize PGlite once per isolate', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      await loader.get(config)
+      await loader.get(config)
+
+      expect(factory).toHaveBeenCalledTimes(1)
+      await loader.close()
+    })
+
+    it('should handle concurrent initialization requests', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockImplementation(async () => {
+        await delay(50) // Simulate slow initialization
+        return mockPGlite
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      const [pglite1, pglite2, pglite3] = await Promise.all([
+        loader.get(config),
+        loader.get(config),
+        loader.get(config),
+      ])
+
+      expect(pglite1).toBe(pglite2)
+      expect(pglite2).toBe(pglite3)
+      expect(factory).toHaveBeenCalledTimes(1)
+      await loader.close()
+    })
+
+    it('should ignore config on warm start (use original config)', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      const configA = createMockConfig({ dataDir: 'idb://configA' })
+      const configB = createMockConfig({ dataDir: 'idb://configB' })
+
+      await loader.get(configA)
+      await loader.get(configB)
+
+      // Factory should be called only once with configA
+      expect(factory).toHaveBeenCalledTimes(1)
+      expect(factory).toHaveBeenCalledWith(configA)
+      await loader.close()
+    })
+
+    it('should maintain singleton across different config objects', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      // Two structurally identical but different config objects
+      const config1 = createMockConfig()
+      const config2 = createMockConfig()
+
+      const pglite1 = await loader.get(config1)
+      const pglite2 = await loader.get(config2)
+
+      expect(pglite1).toBe(pglite2)
+      expect(factory).toHaveBeenCalledTimes(1)
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Cold Start Tests
+  // ==========================================================================
+
+  describe('cold start', () => {
+    it('should load WASM module on first request', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const wasmModule = createMockWasmModule()
+      const config = createMockConfig({ wasmModule })
+
+      expect(loader.isWarm()).toBe(false)
+
+      await loader.get(config)
+
+      expect(loader.isWarm()).toBe(true)
+      expect(factory).toHaveBeenCalledWith(expect.objectContaining({ wasmModule }))
+      await loader.close()
+    })
+
+    it('should load filesystem bundle', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const fsBundle = createMockFsBundle(2048)
+      const config = createMockConfig({ fsBundle })
+
+      await loader.get(config)
+
+      expect(factory).toHaveBeenCalledWith(expect.objectContaining({ fsBundle }))
+      await loader.close()
+    })
+
+    it('should initialize PGlite with provided config', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig({
+        dataDir: 'idb://custom',
+        readOnly: true,
+        pgliteOptions: { debug: 1 },
+      })
+
+      await loader.get(config)
+
+      expect(factory).toHaveBeenCalledWith(
+        expect.objectContaining({
+          dataDir: 'idb://custom',
+          readOnly: true,
+          pgliteOptions: { debug: 1 },
+        })
+      )
+      await loader.close()
+    })
+
+    it('should report cold start in stats', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      const stats = loader.getStats()
+
+      expect(stats.coldStarts).toBe(1)
+      expect(stats.warmStarts).toBe(0)
+      await loader.close()
+    })
+
+    it('should handle ArrayBuffer fsBundle', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const fsBundle = new ArrayBuffer(1024)
+      const config = createMockConfig({ fsBundle })
+
+      const pglite = await loader.get(config)
+
+      expect(pglite).toBe(mockPGlite)
+      await loader.close()
+    })
+
+    it('should handle Blob fsBundle', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const fsBundle = new Blob([new ArrayBuffer(1024)])
+      const config: WarmLoaderConfig = {
+        wasmModule: createMockWasmModule(),
+        fsBundle,
+      }
+
+      const pglite = await loader.get(config)
+
+      expect(pglite).toBe(mockPGlite)
+      await loader.close()
+    })
+
+    it('should initialize with extensions when provided', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const extensions = { vector: {}, pgcrypto: {} }
+      const config = createMockConfig({ extensions })
+
+      await loader.get(config)
+
+      expect(factory).toHaveBeenCalledWith(expect.objectContaining({ extensions }))
+      await loader.close()
+    })
+
+    it('should use default options when not specified', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig() // minimal config
+
+      await loader.get(config)
+
+      // Factory should be called with the minimal config (defaults handled inside factory)
+      expect(factory).toHaveBeenCalledTimes(1)
+      const calledConfig = factory.mock.calls[0][0]
+      expect(calledConfig.wasmModule).toBeDefined()
+      expect(calledConfig.fsBundle).toBeDefined()
+      await loader.close()
+    })
+
+    it('should timeout if initialization takes too long', async () => {
+      const factory = vi.fn().mockImplementation(async () => {
+        await delay(500) // Slow initialization
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig({ initTimeoutMs: 50 }) // Short timeout
+
+      await expect(loader.get(config)).rejects.toThrow(/timed out/)
+
+      // Loader should be in clean state (can retry)
+      expect(loader.isWarm()).toBe(false)
+      await loader.close()
+    })
+
+    it('should track initialization duration accurately', async () => {
+      const initDelay = 50
+      const factory = vi.fn().mockImplementation(async () => {
+        await delay(initDelay)
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      const stats = loader.getStats()
+
+      // Should be close to initDelay (with some tolerance)
+      expect(stats.lastInitDurationMs).toBeGreaterThanOrEqual(initDelay - 10)
+      expect(stats.lastInitDurationMs).toBeLessThan(initDelay + 100)
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Warm Start Tests
+  // ==========================================================================
+
+  describe('warm start', () => {
+    it('should return cached instance immediately', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      const pglite1 = await loader.get(config)
+      const pglite2 = await loader.get(config)
+
+      expect(pglite2).toBe(pglite1)
+      expect(factory).toHaveBeenCalledTimes(1)
+      await loader.close()
+    })
+
+    it('should complete in <1ms for warm starts', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Cold start first
+      await loader.get(config)
+
+      // Warm start timing
+      const start = performance.now()
+      await loader.get(config)
+      const duration = performance.now() - start
+
+      expect(duration).toBeLessThan(1 * CI_MULTIPLIER)
+      await loader.close()
+    })
+
+    it('should report warm start in stats', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config) // cold start
+      await loader.get(config) // warm start 1
+      await loader.get(config) // warm start 2
+
+      const stats = loader.getStats()
+      expect(stats.coldStarts).toBe(1)
+      expect(stats.warmStarts).toBe(2)
+      await loader.close()
+    })
+
+    it('should not re-initialize on warm start', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      await loader.get(config)
+      await loader.get(config)
+      await loader.get(config)
+
+      expect(factory).toHaveBeenCalledTimes(1)
+      await loader.close()
+    })
+
+    it('should work correctly after many warm starts', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Cold start
+      const first = await loader.get(config)
+
+      // 999 warm starts
+      for (let i = 0; i < 999; i++) {
+        const instance = await loader.get(config)
+        expect(instance).toBe(first)
+      }
+
+      const stats = loader.getStats()
+      expect(stats.warmStarts).toBe(999)
+      expect(factory).toHaveBeenCalledTimes(1)
+      await loader.close()
+    })
+
+    it('should handle warm start during concurrent requests', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Cold start first
+      const first = await loader.get(config)
+
+      // Many concurrent warm starts
+      const instances = await Promise.all(
+        Array.from({ length: 100 }, () => loader.get(config))
+      )
+
+      instances.forEach((instance) => {
+        expect(instance).toBe(first)
+      })
+      expect(factory).toHaveBeenCalledTimes(1)
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Stats Tests
+  // ==========================================================================
+
+  describe('stats', () => {
+    it('should track cold start count', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      expect(loader.getStats().coldStarts).toBe(1)
+
+      await loader.reset()
+      await loader.get(config)
+      expect(loader.getStats().coldStarts).toBe(2)
+
+      await loader.reset()
+      await loader.get(config)
+      expect(loader.getStats().coldStarts).toBe(3)
+
+      await loader.close()
+    })
+
+    it('should track warm start count', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config) // cold start
+      expect(loader.getStats().warmStarts).toBe(0)
+
+      await loader.get(config) // warm start 1
+      expect(loader.getStats().warmStarts).toBe(1)
+
+      await loader.get(config) // warm start 2
+      expect(loader.getStats().warmStarts).toBe(2)
+
+      await loader.get(config) // warm start 3
+      expect(loader.getStats().warmStarts).toBe(3)
+
+      await loader.close()
+    })
+
+    it('should track last init duration', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      const stats = loader.getStats()
+
+      expect(stats.lastInitDurationMs).toBeGreaterThan(0)
+      expect(stats.lastInitDurationMs).toBeLessThan(1000) // Reasonable upper bound
+      await loader.close()
+    })
+
+    it('should track isolate age', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      const statsInitial = loader.getStats()
+      await delay(50)
+      const statsAfter = loader.getStats()
+
+      expect(statsAfter.isolateAgeMs).toBeGreaterThanOrEqual(statsInitial.isolateAgeMs + 40)
+      await loader.close()
+    })
+
+    it('should track isolate start time', async () => {
+      const now = Date.now()
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      const stats = loader.getStats()
+
+      // Should be close to now (within 100ms)
+      expect(stats.isolateStartedAt).toBeGreaterThanOrEqual(now - 100)
+      expect(stats.isolateStartedAt).toBeLessThanOrEqual(now + 100)
+      await loader.close()
+    })
+
+    it('should track last cold start time', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      const firstColdStartAt = loader.getStats().lastColdStartAt
+
+      await delay(50)
+      await loader.reset()
+      await loader.get(config)
+      const secondColdStartAt = loader.getStats().lastColdStartAt
+
+      expect(secondColdStartAt).toBeGreaterThan(firstColdStartAt)
+      await loader.close()
+    })
+
+    it('should calculate estimated time saved', async () => {
+      const initDelay = 20
+      const factory = vi.fn().mockImplementation(async () => {
+        await delay(initDelay)
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config) // cold start
+      await loader.get(config) // warm start 1
+      await loader.get(config) // warm start 2
+      await loader.get(config) // warm start 3
+
+      const stats = loader.getStats()
+      expect(stats.estimatedTimeSavedMs).toBe(stats.warmStarts * stats.lastInitDurationMs)
+      await loader.close()
+    })
+
+    it('should report isWarm correctly in stats', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      expect(loader.getStats().isWarm).toBe(false)
+
+      await loader.get(config)
+      expect(loader.getStats().isWarm).toBe(true)
+
+      await loader.reset()
+      expect(loader.getStats().isWarm).toBe(false)
+
+      await loader.close()
+    })
+
+    it('should return snapshot not live reference', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+
+      const stats1 = loader.getStats()
+      const originalColdStarts = stats1.coldStarts
+
+      // Modify the returned object
+      stats1.coldStarts = 999
+
+      // Get stats again - should have original value
+      const stats2 = loader.getStats()
+      expect(stats2.coldStarts).toBe(originalColdStarts)
+
+      await loader.close()
+    })
+
+    it('should maintain stats across reset', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config) // cold start 1
+      await loader.get(config) // warm start 1
+      await loader.get(config) // warm start 2
+
+      await loader.reset()
+
+      await loader.get(config) // cold start 2
+      await loader.get(config) // warm start 3
+
+      const stats = loader.getStats()
+      expect(stats.coldStarts).toBe(2)
+      expect(stats.warmStarts).toBe(3)
+
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Reset Tests
+  // ==========================================================================
+
+  describe('reset', () => {
+    it('should allow forced re-initialization', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      expect(loader.isWarm()).toBe(true)
+
+      await loader.reset()
+      expect(loader.isWarm()).toBe(false)
+
+      await loader.get(config) // Should trigger another cold start
+      expect(factory).toHaveBeenCalledTimes(2)
+
+      await loader.close()
+    })
+
+    it('should close existing instance before reset', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      await loader.reset()
+
+      expect(mockPGlite.close).toHaveBeenCalled()
+      await loader.close()
+    })
+
+    it('should handle reset when not initialized', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      // Reset without any get() call
+      await expect(loader.reset()).resolves.toBeUndefined()
+      expect(loader.isWarm()).toBe(false)
+      await loader.close()
+    })
+
+    it('should handle concurrent reset calls', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+
+      // Multiple concurrent resets
+      await Promise.all([loader.reset(), loader.reset(), loader.reset()])
+
+      expect(loader.isWarm()).toBe(false)
+      await loader.close()
+    })
+
+    it('should allow new initialization after reset', async () => {
+      const mockPGlite1 = createMockPGlite()
+      const mockPGlite2 = createMockPGlite()
+      let callCount = 0
+      const factory = vi.fn().mockImplementation(async () => {
+        callCount++
+        return callCount === 1 ? mockPGlite1 : mockPGlite2
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      const configA = createMockConfig({ dataDir: 'idb://configA' })
+      const configB = createMockConfig({ dataDir: 'idb://configB' })
+
+      const instance1 = await loader.get(configA)
+      expect(instance1).toBe(mockPGlite1)
+
+      await loader.reset()
+
+      const instance2 = await loader.get(configB)
+      expect(instance2).toBe(mockPGlite2)
+      expect(factory).toHaveBeenLastCalledWith(expect.objectContaining({ dataDir: 'idb://configB' }))
+
+      await loader.close()
+    })
+
+    it('should update stats after reset', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      const firstColdStartAt = loader.getStats().lastColdStartAt
+
+      await delay(20)
+      await loader.reset()
+      await loader.get(config)
+
+      const stats = loader.getStats()
+      expect(stats.coldStarts).toBe(2)
+      expect(stats.lastColdStartAt).toBeGreaterThan(firstColdStartAt)
+
+      await loader.close()
+    })
+
+    it('should handle reset during initialization', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockImplementation(async () => {
+        await delay(100)
+        return mockPGlite
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Start initialization
+      const getPromise = loader.get(config)
+
+      // Reset during initialization (should wait for init to complete)
+      await delay(10)
+      await loader.reset()
+
+      // The original get should have completed
+      await expect(getPromise).resolves.toBe(mockPGlite)
+
+      // Loader should be in clean state after reset
+      expect(loader.isWarm()).toBe(false)
+
+      await loader.close()
+    })
+
+    it('should handle reset with pending get() calls', async () => {
+      const mockPGlite1 = createMockPGlite()
+      const mockPGlite2 = createMockPGlite()
+      let callCount = 0
+      const factory = vi.fn().mockImplementation(async () => {
+        callCount++
+        await delay(50)
+        return callCount === 1 ? mockPGlite1 : mockPGlite2
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // First get starts initialization
+      const get1Promise = loader.get(config)
+
+      // Reset is called
+      await delay(10)
+      const resetPromise = loader.reset()
+
+      // First get should complete with first instance
+      const result1 = await get1Promise
+      expect(result1).toBe(mockPGlite1)
+
+      // Wait for reset to complete
+      await resetPromise
+
+      // Subsequent get should trigger new initialization
+      const result2 = await loader.get(config)
+      expect(result2).toBe(mockPGlite2)
+
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Error Handling Tests
+  // ==========================================================================
+
+  describe('error handling', () => {
+    it('should handle initialization failure', async () => {
+      const factory = vi.fn().mockRejectedValue(new Error('Init failed'))
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await expect(loader.get(config)).rejects.toThrow('Init failed')
+      expect(loader.isWarm()).toBe(false)
+      await loader.close()
+    })
+
+    it('should allow retry after initialization failure', async () => {
+      const mockPGlite = createMockPGlite()
+      let callCount = 0
+      const factory = vi.fn().mockImplementation(async () => {
+        callCount++
+        if (callCount === 1) {
+          throw new Error('First attempt failed')
+        }
+        return mockPGlite
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // First attempt fails
+      await expect(loader.get(config)).rejects.toThrow('First attempt failed')
+
+      // Second attempt succeeds
+      const result = await loader.get(config)
+      expect(result).toBe(mockPGlite)
+      expect(loader.isWarm()).toBe(true)
+
+      await loader.close()
+    })
+
+    it('should handle invalid WASM module', async () => {
+      const factory = vi.fn().mockImplementation(async (config: WarmLoaderConfig) => {
+        if (!config.wasmModule || Object.keys(config.wasmModule).length === 0) {
+          throw new Error('Invalid WASM module')
+        }
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig({ wasmModule: {} as WebAssembly.Module })
+
+      await expect(loader.get(config)).rejects.toThrow('Invalid WASM module')
+      await loader.close()
+    })
+
+    it('should handle invalid fsBundle', async () => {
+      const factory = vi.fn().mockImplementation(async (config: WarmLoaderConfig) => {
+        if (!config.fsBundle || (config.fsBundle as ArrayBuffer).byteLength === 0) {
+          throw new Error('Invalid fsBundle')
+        }
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig({ fsBundle: new ArrayBuffer(0) })
+
+      await expect(loader.get(config)).rejects.toThrow('Invalid fsBundle')
+      await loader.close()
+    })
+
+    it('should handle close() failure gracefully', async () => {
+      const mockPGlite = createMockPGlite()
+      ;(mockPGlite.close as ReturnType<typeof vi.fn>).mockRejectedValue(
+        new Error('Close failed')
+      )
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+
+      // Reset should complete even if close fails
+      await expect(loader.reset()).resolves.toBeUndefined()
+      expect(loader.isWarm()).toBe(false)
+
+      await loader.close()
+    })
+
+    it('should handle concurrent get() when one fails', async () => {
+      const factory = vi.fn().mockImplementation(async () => {
+        await delay(50)
+        throw new Error('Init failed for all')
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Multiple concurrent get() calls
+      const results = await Promise.allSettled([
+        loader.get(config),
+        loader.get(config),
+        loader.get(config),
+      ])
+
+      // All should fail with the same error
+      results.forEach((result) => {
+        expect(result.status).toBe('rejected')
+        if (result.status === 'rejected') {
+          expect(result.reason.message).toBe('Init failed for all')
+        }
+      })
+
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Close Tests
+  // ==========================================================================
+
+  describe('close', () => {
+    it('should close PGlite instance', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      await loader.close()
+
+      expect(mockPGlite.close).toHaveBeenCalled()
+    })
+
+    it('should prevent further get() calls after close', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      await loader.close()
+
+      await expect(loader.get(config)).rejects.toThrow('Loader is closed')
+    })
+
+    it('should handle close when not initialized', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      // Close without any get() call
+      await expect(loader.close()).resolves.toBeUndefined()
+    })
+
+    it('should handle multiple close() calls', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await loader.get(config)
+      await loader.close()
+      await loader.close()
+      await loader.close()
+
+      // Should not throw, idempotent
+      expect(mockPGlite.close).toHaveBeenCalledTimes(1)
+    })
+
+    it('should reject pending get() calls on close', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockImplementation(async () => {
+        await delay(100)
+        return mockPGlite
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Start slow initialization
+      const getPromise = loader.get(config)
+
+      // Close during initialization
+      await delay(10)
+      await loader.close()
+
+      // The get should have completed before close finished waiting
+      // (close waits for pending initialization)
+      const result = await getPromise
+      expect(result).toBe(mockPGlite)
+
+      // But further calls should fail
+      await expect(loader.get(config)).rejects.toThrow('Loader is closed')
+    })
+  })
+
+  // ==========================================================================
+  // Concurrency Tests
+  // ==========================================================================
+
+  describe('concurrency', () => {
+    it('should serialize initialization requests', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockImplementation(async () => {
+        await delay(50)
+        return mockPGlite
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Many concurrent get() calls
+      const promises = Array.from({ length: 10 }, () => loader.get(config))
+      const results = await Promise.all(promises)
+
+      // All should get the same instance
+      results.forEach((result) => expect(result).toBe(mockPGlite))
+
+      // Factory should only be called once
+      expect(factory).toHaveBeenCalledTimes(1)
+
+      await loader.close()
+    })
+
+    it('should not deadlock under high concurrency', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockImplementation(async () => {
+        await delay(5)
+        return mockPGlite
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Many concurrent operations
+      const operations: Promise<unknown>[] = []
+      for (let i = 0; i < 20; i++) {
+        operations.push(loader.get(config))
+        if (i % 5 === 0) {
+          operations.push(loader.reset())
+        }
+      }
+
+      // All should complete without hanging (timeout would fail the test)
+      await Promise.all(operations)
+
+      await loader.close()
+    })
+
+    it('should handle interleaved get/reset calls', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Rapid get/reset pattern
+      await loader.get(config)
+      await loader.reset()
+      await loader.get(config)
+      await loader.reset()
+      await loader.get(config)
+      await loader.reset()
+      await loader.get(config)
+
+      // Should complete without errors
+      expect(factory).toHaveBeenCalledTimes(4)
+      expect(loader.isWarm()).toBe(true)
+
+      await loader.close()
+    })
+
+    it('should handle get() during reset()', async () => {
+      const mockPGlite1 = createMockPGlite()
+      const mockPGlite2 = createMockPGlite()
+      let callCount = 0
+      const factory = vi.fn().mockImplementation(async () => {
+        callCount++
+        await delay(30)
+        return callCount === 1 ? mockPGlite1 : mockPGlite2
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Get first instance
+      await loader.get(config)
+
+      // Start reset (which will wait for any pending init)
+      const resetPromise = loader.reset()
+
+      // Immediately try to get (should wait for reset then trigger new init)
+      await resetPromise
+
+      // Now get should trigger new initialization
+      const result = await loader.get(config)
+      expect(result).toBe(mockPGlite2)
+
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Memory Pressure Handling Tests
+  // ==========================================================================
+
+  describe('memory pressure handling', () => {
+    it('should handle simulated memory pressure during WASM loading', async () => {
+      const mockPGlite = createMockPGlite()
+      let attemptCount = 0
+      const factory = vi.fn().mockImplementation(async () => {
+        attemptCount++
+        if (attemptCount === 1) {
+          // Simulate memory pressure on first attempt
+          const memoryError = new Error('WebAssembly.Memory(): could not allocate memory')
+          memoryError.name = 'RangeError'
+          throw memoryError
+        }
+        return mockPGlite
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // First attempt fails with memory error
+      await expect(loader.get(config)).rejects.toThrow('could not allocate memory')
+
+      // Retry after memory pressure subsides should succeed
+      const result = await loader.get(config)
+      expect(result).toBe(mockPGlite)
+      expect(attemptCount).toBe(2)
+      await loader.close()
+    })
+
+    it('should track memory-related failures in stats', async () => {
+      const factory = vi.fn().mockImplementation(async () => {
+        const memoryError = new Error('Out of memory')
+        throw memoryError
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      await expect(loader.get(config)).rejects.toThrow('Out of memory')
+
+      const stats = loader.getStats()
+      expect(stats.coldStarts).toBe(0) // Failed initialization doesn't count as cold start
+      expect(loader.isWarm()).toBe(false)
+      await loader.close()
+    })
+
+    it('should handle large WASM modules gracefully', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      // Simulate a large WASM module (realistic size for PGlite)
+      const largeWasmModule = createMockWasmModule()
+      const largeFsBundle = createMockFsBundle(50 * 1024 * 1024) // 50MB
+      const config = createMockConfig({ wasmModule: largeWasmModule, fsBundle: largeFsBundle })
+
+      const result = await loader.get(config)
+      expect(result).toBe(mockPGlite)
+      expect(loader.isWarm()).toBe(true)
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Multiple WASM Module Versions Tests
+  // ==========================================================================
+
+  describe('multiple WASM module versions in same isolate', () => {
+    it('should use original WASM module version after warm start', async () => {
+      const mockPGlite1 = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite1)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      const wasmModuleV1 = createMockWasmModule()
+      const wasmModuleV2 = createMockWasmModule()
+
+      // Initialize with v1
+      const configV1 = createMockConfig({ wasmModule: wasmModuleV1 })
+      await loader.get(configV1)
+
+      // Try to get with v2 - should still use v1's cached instance
+      const configV2 = createMockConfig({ wasmModule: wasmModuleV2 })
+      await loader.get(configV2)
+
+      // Factory should only be called once with v1
+      expect(factory).toHaveBeenCalledTimes(1)
+      expect(factory).toHaveBeenCalledWith(expect.objectContaining({ wasmModule: wasmModuleV1 }))
+      await loader.close()
+    })
+
+    it('should allow different WASM version after reset', async () => {
+      const mockPGlite1 = createMockPGlite()
+      const mockPGlite2 = createMockPGlite()
+      let callCount = 0
+      const factory = vi.fn().mockImplementation(async () => {
+        callCount++
+        return callCount === 1 ? mockPGlite1 : mockPGlite2
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      const wasmModuleV1 = createMockWasmModule()
+      const wasmModuleV2 = createMockWasmModule()
+
+      // Initialize with v1
+      const configV1 = createMockConfig({ wasmModule: wasmModuleV1 })
+      const instance1 = await loader.get(configV1)
+      expect(instance1).toBe(mockPGlite1)
+
+      // Reset and initialize with v2
+      await loader.reset()
+      const configV2 = createMockConfig({ wasmModule: wasmModuleV2 })
+      const instance2 = await loader.get(configV2)
+
+      expect(instance2).toBe(mockPGlite2)
+      expect(factory).toHaveBeenCalledTimes(2)
+      expect(factory).toHaveBeenLastCalledWith(expect.objectContaining({ wasmModule: wasmModuleV2 }))
+      await loader.close()
+    })
+
+    it('should isolate different loader instances with different WASM versions', async () => {
+      const mockPGlite1 = createMockPGlite()
+      const mockPGlite2 = createMockPGlite()
+      const factory1 = vi.fn().mockResolvedValue(mockPGlite1)
+      const factory2 = vi.fn().mockResolvedValue(mockPGlite2)
+
+      const loader1 = createWarmPGliteLoader({ pgliteFactory: factory1 })
+      const loader2 = createWarmPGliteLoader({ pgliteFactory: factory2 })
+
+      const wasmModuleV1 = createMockWasmModule()
+      const wasmModuleV2 = createMockWasmModule()
+
+      const configV1 = createMockConfig({ wasmModule: wasmModuleV1 })
+      const configV2 = createMockConfig({ wasmModule: wasmModuleV2 })
+
+      const instance1 = await loader1.get(configV1)
+      const instance2 = await loader2.get(configV2)
+
+      expect(instance1).toBe(mockPGlite1)
+      expect(instance2).toBe(mockPGlite2)
+      expect(factory1).toHaveBeenCalledWith(expect.objectContaining({ wasmModule: wasmModuleV1 }))
+      expect(factory2).toHaveBeenCalledWith(expect.objectContaining({ wasmModule: wasmModuleV2 }))
+
+      await loader1.close()
+      await loader2.close()
+    })
+  })
+
+  // ==========================================================================
+  // Extension Loading Failures Tests
+  // ==========================================================================
+
+  describe('extension loading failures', () => {
+    it('should handle extension loading failure gracefully', async () => {
+      const factory = vi.fn().mockImplementation(async (config: WarmLoaderConfig) => {
+        if (config.extensions && Object.keys(config.extensions).length > 0) {
+          throw new Error('Failed to load extension: vector')
+        }
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig({ extensions: { vector: {} } })
+
+      await expect(loader.get(config)).rejects.toThrow('Failed to load extension: vector')
+      expect(loader.isWarm()).toBe(false)
+      await loader.close()
+    })
+
+    it('should allow retry after extension loading failure', async () => {
+      const mockPGlite = createMockPGlite()
+      let callCount = 0
+      const factory = vi.fn().mockImplementation(async (config: WarmLoaderConfig) => {
+        callCount++
+        if (callCount === 1 && config.extensions?.vector) {
+          throw new Error('Extension vector not available')
+        }
+        return mockPGlite
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      // First attempt with extension fails
+      const configWithExt = createMockConfig({ extensions: { vector: {} } })
+      await expect(loader.get(configWithExt)).rejects.toThrow('Extension vector not available')
+
+      // Second attempt without extension succeeds
+      const configWithoutExt = createMockConfig()
+      const result = await loader.get(configWithoutExt)
+      expect(result).toBe(mockPGlite)
+      await loader.close()
+    })
+
+    it('should handle partial extension loading (some succeed, some fail)', async () => {
+      const factory = vi.fn().mockImplementation(async (config: WarmLoaderConfig) => {
+        if (config.extensions?.badExtension) {
+          throw new Error('Extension badExtension failed to load')
+        }
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      // Config with problematic extension
+      const config = createMockConfig({
+        extensions: { pgcrypto: {}, badExtension: {} },
+      })
+
+      await expect(loader.get(config)).rejects.toThrow('Extension badExtension failed to load')
+      expect(loader.isWarm()).toBe(false)
+      await loader.close()
+    })
+
+    it('should handle extension initialization timeout', async () => {
+      const factory = vi.fn().mockImplementation(async (config: WarmLoaderConfig) => {
+        if (config.extensions?.slowExtension) {
+          await delay(500) // Simulate slow extension loading
+        }
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig({
+        extensions: { slowExtension: {} },
+        initTimeoutMs: 50, // Short timeout
+      })
+
+      await expect(loader.get(config)).rejects.toThrow(/timed out/)
+      expect(loader.isWarm()).toBe(false)
+      await loader.close()
+    })
+
+    it('should handle extension with invalid WASM module', async () => {
+      const factory = vi.fn().mockImplementation(async (config: WarmLoaderConfig) => {
+        if (config.extensions?.corruptExtension) {
+          const error = new Error('WebAssembly.instantiate(): invalid module')
+          error.name = 'CompileError'
+          throw error
+        }
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig({
+        extensions: { corruptExtension: {} },
+      })
+
+      await expect(loader.get(config)).rejects.toThrow('invalid module')
+      expect(loader.isWarm()).toBe(false)
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Graceful Degradation Tests
+  // ==========================================================================
+
+  describe('graceful degradation when FS bundle is missing', () => {
+    it('should handle undefined fsBundle in config', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config: WarmLoaderConfig = {
+        wasmModule: createMockWasmModule(),
+        fsBundle: undefined,
+      }
+
+      const result = await loader.get(config)
+      expect(result).toBe(mockPGlite)
+      expect(factory).toHaveBeenCalledWith(expect.objectContaining({ fsBundle: undefined }))
+      await loader.close()
+    })
+
+    it('should handle null fsBundle gracefully', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config: WarmLoaderConfig = {
+        wasmModule: createMockWasmModule(),
+        fsBundle: null as unknown as ArrayBuffer,
+      }
+
+      // Factory should be called with the null value - how it handles it is up to the implementation
+      const result = await loader.get(config)
+      expect(result).toBe(mockPGlite)
+      await loader.close()
+    })
+
+    it('should fail gracefully when fsBundle fetch fails', async () => {
+      const factory = vi.fn().mockImplementation(async (config: WarmLoaderConfig) => {
+        if (!config.fsBundle || (config.fsBundle as ArrayBuffer).byteLength === 0) {
+          throw new Error('FS bundle required but not provided or empty')
+        }
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig({ fsBundle: new ArrayBuffer(0) })
+
+      await expect(loader.get(config)).rejects.toThrow('FS bundle required but not provided or empty')
+      expect(loader.isWarm()).toBe(false)
+      await loader.close()
+    })
+
+    it('should handle corrupted fsBundle data', async () => {
+      const factory = vi.fn().mockImplementation(async (config: WarmLoaderConfig) => {
+        // Simulate validation of fsBundle content
+        if (config.fsBundle instanceof ArrayBuffer) {
+          const view = new Uint8Array(config.fsBundle)
+          // Check for a magic header (simplified validation)
+          if (view.length > 0 && view[0] === 0xFF) {
+            throw new Error('Corrupted FS bundle: invalid header')
+          }
+        }
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+      // Create an ArrayBuffer with invalid header
+      const corruptedBundle = new ArrayBuffer(1024)
+      const view = new Uint8Array(corruptedBundle)
+      view[0] = 0xFF // Invalid header marker
+      const config = createMockConfig({ fsBundle: corruptedBundle })
+
+      await expect(loader.get(config)).rejects.toThrow('Corrupted FS bundle: invalid header')
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Graceful Degradation with Minimal Config Tests
+  // ==========================================================================
+
+  describe('graceful degradation when config is minimal', () => {
+    it('should initialize with only required wasmModule and fsBundle', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const minimalConfig: WarmLoaderConfig = {
+        wasmModule: createMockWasmModule(),
+        fsBundle: createMockFsBundle(),
+      }
+
+      const result = await loader.get(minimalConfig)
+      expect(result).toBe(mockPGlite)
+      expect(loader.isWarm()).toBe(true)
+      await loader.close()
+    })
+
+    it('should use sensible defaults when optional fields are omitted', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const minimalConfig: WarmLoaderConfig = {
+        wasmModule: createMockWasmModule(),
+        fsBundle: createMockFsBundle(),
+      }
+
+      await loader.get(minimalConfig)
+
+      // Factory should be called with the minimal config (defaults applied internally)
+      const calledConfig = factory.mock.calls[0][0]
+      expect(calledConfig.wasmModule).toBeDefined()
+      expect(calledConfig.fsBundle).toBeDefined()
+      // Optional fields should be undefined (not set to invalid values)
+      expect(calledConfig.dataDir).toBeUndefined()
+      expect(calledConfig.readOnly).toBeUndefined()
+      expect(calledConfig.extensions).toBeUndefined()
+      await loader.close()
+    })
+
+    it('should work without pgliteOptions', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config: WarmLoaderConfig = {
+        wasmModule: createMockWasmModule(),
+        fsBundle: createMockFsBundle(),
+        // pgliteOptions intentionally omitted
+      }
+
+      const result = await loader.get(config)
+      expect(result).toBe(mockPGlite)
+
+      const calledConfig = factory.mock.calls[0][0]
+      expect(calledConfig.pgliteOptions).toBeUndefined()
+      await loader.close()
+    })
+  })
+
+  // ==========================================================================
+  // Integration Scenarios
+  // ==========================================================================
+
+  describe('integration scenarios', () => {
+    it('should work with typical Worker request pattern', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // Simulate multiple Worker requests
+      await loader.get(config) // Request 1 - cold start
+      await loader.get(config) // Request 2 - warm start
+      await loader.get(config) // Request 3 - warm start
+      await loader.get(config) // Request 4 - warm start
+      await loader.get(config) // Request 5 - warm start
+
+      const stats = loader.getStats()
+      expect(stats.coldStarts).toBe(1)
+      expect(stats.warmStarts).toBe(4)
+      expect(factory).toHaveBeenCalledTimes(1)
+
+      await loader.close()
+    })
+
+    it('should handle isolate recycling pattern', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      // First isolate lifetime
+      await loader.get(config)
+      await loader.get(config)
+
+      // Simulate isolate recycle
+      await loader.reset()
+
+      // Second isolate lifetime
+      await loader.get(config)
+      await loader.get(config)
+
+      const stats = loader.getStats()
+      expect(stats.coldStarts).toBe(2)
+      expect(stats.warmStarts).toBe(2)
+
+      await loader.close()
+    })
+
+    it('should provide accurate metrics for observability', async () => {
+      const initDelay = 25
+      const factory = vi.fn().mockImplementation(async () => {
+        await delay(initDelay)
+        return createMockPGlite()
+      })
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig()
+
+      const startTime = Date.now()
+
+      // Cold start
+      await loader.get(config)
+      const statsAfterCold = loader.getStats()
+
+      expect(statsAfterCold.coldStarts).toBe(1)
+      expect(statsAfterCold.warmStarts).toBe(0)
+      expect(statsAfterCold.lastInitDurationMs).toBeGreaterThanOrEqual(initDelay - 10)
+      expect(statsAfterCold.isWarm).toBe(true)
+      expect(statsAfterCold.isolateStartedAt).toBeLessThanOrEqual(startTime + 100)
+      expect(statsAfterCold.lastColdStartAt).toBeGreaterThanOrEqual(startTime)
+
+      // Warm starts
+      await loader.get(config)
+      await loader.get(config)
+
+      const statsAfterWarm = loader.getStats()
+      expect(statsAfterWarm.warmStarts).toBe(2)
+      expect(statsAfterWarm.estimatedTimeSavedMs).toBe(
+        statsAfterWarm.warmStarts * statsAfterWarm.lastInitDurationMs
+      )
+      expect(statsAfterWarm.isolateAgeMs).toBeGreaterThan(0)
+
+      await loader.close()
+    })
+
+    it('should work with read-only configuration', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig({ readOnly: true })
+
+      await loader.get(config)
+
+      expect(factory).toHaveBeenCalledWith(expect.objectContaining({ readOnly: true }))
+
+      await loader.close()
+    })
+
+    it('should work with custom dataDir', async () => {
+      const mockPGlite = createMockPGlite()
+      const factory = vi.fn().mockResolvedValue(mockPGlite)
+      const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+      const config = createMockConfig({ dataDir: 'idb://custom-database' })
+
+      await loader.get(config)
+
+      expect(factory).toHaveBeenCalledWith(
+        expect.objectContaining({ dataDir: 'idb://custom-database' })
+      )
+
+      await loader.close()
+    })
+  })
+})
+
+// ============================================================================
+// isWarm Tests (standalone function tests)
+// ============================================================================
+
+describe('isWarm', () => {
+  it('should return false on fresh loader', () => {
+    const mockPGlite = createMockPGlite()
+    const factory = vi.fn().mockResolvedValue(mockPGlite)
+    const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+
+    expect(loader.isWarm()).toBe(false)
+  })
+
+  it('should return true after successful get()', async () => {
+    const mockPGlite = createMockPGlite()
+    const factory = vi.fn().mockResolvedValue(mockPGlite)
+    const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+    const config = createMockConfig()
+
+    await loader.get(config)
+
+    expect(loader.isWarm()).toBe(true)
+    await loader.close()
+  })
+
+  it('should return false after reset()', async () => {
+    const mockPGlite = createMockPGlite()
+    const factory = vi.fn().mockResolvedValue(mockPGlite)
+    const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+    const config = createMockConfig()
+
+    await loader.get(config)
+    await loader.reset()
+
+    expect(loader.isWarm()).toBe(false)
+    await loader.close()
+  })
+
+  it('should return false after close()', async () => {
+    const mockPGlite = createMockPGlite()
+    const factory = vi.fn().mockResolvedValue(mockPGlite)
+    const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+    const config = createMockConfig()
+
+    await loader.get(config)
+    await loader.close()
+
+    expect(loader.isWarm()).toBe(false)
+  })
+
+  it('should return false during initialization', async () => {
+    const mockPGlite = createMockPGlite()
+    const factory = vi.fn().mockImplementation(async () => {
+      await delay(100)
+      return mockPGlite
+    })
+    const loader = createWarmPGliteLoader({ pgliteFactory: factory })
+    const config = createMockConfig()
+
+    // Start initialization but don't await
+    const getPromise = loader.get(config)
+
+    // Check isWarm during initialization
+    expect(loader.isWarm()).toBe(false)
+
+    // Wait for initialization to complete
+    await getPromise
+
+    // Now should be warm
+    expect(loader.isWarm()).toBe(true)
+
+    await loader.close()
+  })
+})
+
+// ============================================================================
+// Factory Function Tests
+// ============================================================================
+
+describe('createWarmPGliteLoader', () => {
+  it('should create independent loader instances', async () => {
+    const mockPGlite = createMockPGlite()
+    const factory = vi.fn().mockResolvedValue(mockPGlite)
+
+    const loader1 = createWarmPGliteLoader({ pgliteFactory: factory })
+    const loader2 = createWarmPGliteLoader({ pgliteFactory: factory })
+    const config = createMockConfig()
+
+    await loader1.get(config)
+
+    expect(loader1.isWarm()).toBe(true)
+    expect(loader2.isWarm()).toBe(false)
+
+    await loader1.close()
+    await loader2.close()
+  })
+
+  it('should return object with all interface methods', () => {
+    const loader = createWarmPGliteLoader()
+
+    expect(typeof loader.get).toBe('function')
+    expect(typeof loader.isWarm).toBe('function')
+    expect(typeof loader.getStats).toBe('function')
+    expect(typeof loader.reset).toBe('function')
+    expect(typeof loader.close).toBe('function')
+  })
+
+  it('should create loader with clean initial stats', () => {
+    const loader = createWarmPGliteLoader()
+
+    const stats = loader.getStats()
+
+    expect(stats.coldStarts).toBe(0)
+    expect(stats.warmStarts).toBe(0)
+    expect(stats.lastInitDurationMs).toBe(0)
+    expect(stats.lastColdStartAt).toBe(0)
+    expect(stats.isWarm).toBe(false)
+    expect(stats.estimatedTimeSavedMs).toBe(0)
+    expect(stats.isolateStartedAt).toBeGreaterThan(0)
+    expect(stats.isolateAgeMs).toBeGreaterThanOrEqual(0)
+  })
+})