@dotdo/postgres 0.1.1 → 0.1.3

package/dist/worker/lazy-pglite-manager.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Lazy PGLite Manager for PostgresDO
+ *
+ * SPIKE: Lazy WASM Loading Experiment
+ *
+ * This module implements a lazy loading variant of PGLiteManager that defers
+ * WASM loading until the first query is executed, rather than loading on
+ * DO instantiation.
+ *
+ * ## Hypothesis
+ *
+ * Loading WASM only on first query (not on DO instantiation) may improve:
+ * 1. Cold start perception (faster initial response for non-query endpoints)
+ * 2. Memory usage (don't load if no queries made)
+ *
+ * ## Trade-offs
+ *
+ * - Eager loading: ~1200ms cold start, all subsequent requests fast
+ * - Lazy loading: ~0ms until first query, first query pays ~1200ms, subsequent fast
+ *
+ * For workloads where:
+ * - Many requests hit non-query endpoints (health checks, metadata) -> lazy wins
+ * - All requests are queries -> eager wins (same total latency, better predictability)
+ * - Mixed workload -> depends on query ratio
+ *
+ * ## Implementation
+ *
+ * The manager provides:
+ * - `isWASMLoaded()` - Check if WASM is loaded without triggering load
+ * - `ensureWASMLoaded()` - Explicitly trigger WASM loading
+ * - `query()` - Execute query (lazy loads WASM if needed)
+ * - Promise deduplication for concurrent first queries
+ *
+ * @module worker/lazy-pglite-manager
+ */
+import type { PostgresConfig } from './types';
+import { PluginManager } from './plugin-manager';
+import type { PGliteLike } from './do-pglite-manager';
+/**
+ * Check if the lazy hoisted PGLite instance exists.
+ */
+export declare function hasLazyHoistedPglite(): boolean;
+/**
+ * Get diagnostics about the lazy hoisted WASM state.
+ */
+export declare function getLazyHoistedPgliteDiagnostics(): {
+    hasInstance: boolean;
+    hasPendingPromise: boolean;
+    moduleInstanceId: string;
+    wasmLoadedAt: number | null;
+    timeSinceLoad: number | null;
+};
+/**
+ * Reset the lazy hoisted PGLite instance.
+ * WARNING: This should only be used in tests.
+ * @internal
+ */
+export declare function resetLazyHoistedPglite(): void;
+/**
+ * WASM loading state for diagnostics
+ */
+export type WASMLoadingState = 'not_loaded' | 'loading' | 'loaded' | 'error';
+/**
+ * Configuration for Lazy PGLite manager
+ */
+export interface LazyPGLiteManagerConfig {
+    /** Database name */
+    database?: string;
+    /** Enable debug mode */
+    debug?: boolean;
+    /** Plugin configuration */
+    plugins?: PostgresConfig['plugins'];
+    /** Custom PGLite factory for testing */
+    createPGLite?: () => Promise<PGliteLike>;
+    /**
+     * Disable WASM hoisting optimization.
+     * When false (default), the PGLite WASM instance is cached at module level.
+     * @default false
+     */
+    disableHoisting?: boolean;
+}
+/**
+ * LazyPGLiteManager defers WASM loading until the first query.
+ *
+ * Unlike the eager PGLiteManager, this manager does NOT load WASM during
+ * initialize(). WASM is only loaded when query() or ensureWASMLoaded() is called.
+ *
+ * Benefits:
+ * - Non-query endpoints (health, metadata, stats) respond immediately
+ * - Memory is not consumed until queries are actually executed
+ * - Better cold start perception for mixed workloads
+ *
+ * Trade-offs:
+ * - First query incurs the full WASM loading time (~1200ms)
+ * - Less predictable query latency (first vs subsequent)
+ *
+ * @example
+ * ```typescript
+ * const manager = new LazyPGLiteManager({ database: 'mydb' })
+ *
+ * // Initialize (fast - no WASM loading)
+ * await manager.initialize()
+ *
+ * // Check if WASM is loaded (without triggering load)
+ * console.log(manager.isWASMLoaded()) // false
+ *
+ * // First query triggers WASM load (~1200ms)
+ * const result1 = await manager.query('SELECT 1')
+ *
+ * // Now WASM is loaded
+ * console.log(manager.isWASMLoaded()) // true
+ *
+ * // Subsequent queries are fast (~ms)
+ * const result2 = await manager.query('SELECT 2')
+ * ```
+ */
+export declare class LazyPGLiteManager {
+    private pglite;
+    private initialized;
+    private loadingState;
+    private loadError;
+    private config;
+    private pluginManager;
+    /** Track whether this manager is using the hoisted instance */
+    private usingHoistedInstance;
+    /** Timing metrics for diagnostics */
+    private metrics;
+    constructor(config?: LazyPGLiteManagerConfig);
+    /**
+     * Check if the manager is initialized.
+     * Note: This returns true after initialize() is called, even if WASM is not loaded.
+     */
+    isInitialized(): boolean;
+    /**
+     * Check if WASM is loaded (without triggering load).
+     * This is the key difference from eager loading.
+     */
+    isWASMLoaded(): boolean;
+    /**
+     * Get the current WASM loading state.
+     */
+    getLoadingState(): WASMLoadingState;
+    /**
+     * Get any error that occurred during WASM loading.
+     */
+    getLoadError(): Error | null;
+    /**
+     * Get the PGLite instance (throws if not loaded).
+     * For lazy loading, prefer using query() which handles loading automatically.
+     */
+    getInstance(): PGliteLike;
+    /**
+     * Get the PGLite instance or null if not loaded.
+     */
+    getInstanceOrNull(): PGliteLike | null;
+    /**
+     * Get the plugin manager.
+     */
+    getPluginManager(): PluginManager;
+    /**
+     * Get timing metrics for diagnostics.
+     */
+    getMetrics(): {
+        initializeCalledAt: number | null;
+        firstQueryAt: number | null;
+        wasmLoadStartAt: number | null;
+        wasmLoadEndAt: number | null;
+        wasmLoadDurationMs: number | null;
+        timeToFirstQuery: number | null;
+    };
+    /**
+     * Initialize the manager (does NOT load WASM).
+     *
+     * This is intentionally fast - WASM loading is deferred to first query.
+     * Safe to call multiple times.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Explicitly ensure WASM is loaded.
+     *
+     * Use this if you want to pre-warm WASM loading before the first query,
+     * but still want the option to skip loading entirely for non-query requests.
+     */
+    ensureWASMLoaded(): Promise<void>;
+    /**
+     * Internal method to load WASM.
+     */
+    private loadWASM;
+    /**
+     * Execute a query (lazy loads WASM if needed).
+     *
+     * This is the primary method for interacting with the database.
+     * On first call, it will trigger WASM loading.
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+        fields: {
+            name: string;
+            dataTypeID: number;
+        }[];
+        affectedRows?: number;
+    }>;
+    /**
+     * Check if PGLite is responsive by running a simple query.
+     * This will trigger WASM loading if not already loaded.
+     */
+    checkLiveness(): Promise<boolean>;
+    /**
+     * Close PGLite instance.
+     */
+    close(timeoutMs?: number): Promise<void>;
+    /**
+     * Reset manager state (for testing or hibernation recovery).
+     */
+    reset(): void;
+    /**
+     * Check if this manager is using the hoisted WASM instance.
+     */
+    isUsingHoistedInstance(): boolean;
+    /**
+     * Get comprehensive diagnostics about lazy loading state.
+     */
+    getDiagnostics(): {
+        initialized: boolean;
+        wasmLoaded: boolean;
+        loadingState: WASMLoadingState;
+        usingHoistedInstance: boolean;
+        metrics: ReturnType<LazyPGLiteManager['getMetrics']>;
+        hoisted: {
+            hasInstance: boolean;
+            hasPendingPromise: boolean;
+            moduleInstanceId: string;
+            wasmLoadedAt: number | null;
+            timeSinceLoad: number | null;
+        };
+    };
+}
+/**
+ * Factory function to create a LazyPGLiteManager.
+ */
+export declare function createLazyPGLiteManager(config?: LazyPGLiteManagerConfig): LazyPGLiteManager;
+//# sourceMappingURL=lazy-pglite-manager.d.ts.map

package/dist/worker/lazy-pglite-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-pglite-manager.d.ts","sourceRoot":"","sources":["../../src/worker/lazy-pglite-manager.ts"],"names":[],"mappings":"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"}

package/dist/worker/lazy-pglite-manager.js

@@ -0,0 +1,463 @@
+/**
+ * Lazy PGLite Manager for PostgresDO
+ *
+ * SPIKE: Lazy WASM Loading Experiment
+ *
+ * This module implements a lazy loading variant of PGLiteManager that defers
+ * WASM loading until the first query is executed, rather than loading on
+ * DO instantiation.
+ *
+ * ## Hypothesis
+ *
+ * Loading WASM only on first query (not on DO instantiation) may improve:
+ * 1. Cold start perception (faster initial response for non-query endpoints)
+ * 2. Memory usage (don't load if no queries made)
+ *
+ * ## Trade-offs
+ *
+ * - Eager loading: ~1200ms cold start, all subsequent requests fast
+ * - Lazy loading: ~0ms until first query, first query pays ~1200ms, subsequent fast
+ *
+ * For workloads where:
+ * - Many requests hit non-query endpoints (health checks, metadata) -> lazy wins
+ * - All requests are queries -> eager wins (same total latency, better predictability)
+ * - Mixed workload -> depends on query ratio
+ *
+ * ## Implementation
+ *
+ * The manager provides:
+ * - `isWASMLoaded()` - Check if WASM is loaded without triggering load
+ * - `ensureWASMLoaded()` - Explicitly trigger WASM loading
+ * - `query()` - Execute query (lazy loads WASM if needed)
+ * - Promise deduplication for concurrent first queries
+ *
+ * @module worker/lazy-pglite-manager
+ */
+import { PluginManager } from './plugin-manager';
+// Import WASM module and data bundle for Workers
+// These are bundled at build time as CompiledWasm and Data modules
+import pgliteWasm from '../pglite-assets/pglite.wasm';
+import pgliteData from '../pglite-assets/pglite.data';
+// Import Workers-compatible PGLite wrapper
+import { createWorkersPGLite } from '../pglite/workers-pglite';
+// =============================================================================
+// Module-Level Lazy WASM State (for hoisting across DO reinstantiation)
+// =============================================================================
+/**
+ * Hoisted PGLite instance - survives DO class reinstantiation within same isolate.
+ * Same as eager loading, but only populated on first query.
+ */
+let lazyHoistedPglite = null;
+/**
+ * Promise for in-progress PGLite initialization.
+ * Prevents duplicate WASM loading when multiple queries execute concurrently.
+ */
+let lazyHoistedPglitePromise = null;
+/**
+ * Timestamp when WASM was first loaded (for diagnostics)
+ */
+let wasmLoadedAt = null;
+/**
+ * Unique identifier for this module instance (for debugging/diagnostics).
+ */
+const LAZY_MODULE_INSTANCE_ID = Math.random().toString(36).slice(2, 10);
+/**
+ * Check if the lazy hoisted PGLite instance exists.
+ */
+export function hasLazyHoistedPglite() {
+    return lazyHoistedPglite !== null;
+}
+/**
+ * Get diagnostics about the lazy hoisted WASM state.
+ */
+export function getLazyHoistedPgliteDiagnostics() {
+    const now = Date.now();
+    return {
+        hasInstance: lazyHoistedPglite !== null,
+        hasPendingPromise: lazyHoistedPglitePromise !== null,
+        moduleInstanceId: LAZY_MODULE_INSTANCE_ID,
+        wasmLoadedAt,
+        timeSinceLoad: wasmLoadedAt !== null ? now - wasmLoadedAt : null,
+    };
+}
+/**
+ * Reset the lazy hoisted PGLite instance.
+ * WARNING: This should only be used in tests.
+ * @internal
+ */
+export function resetLazyHoistedPglite() {
+    lazyHoistedPglite = null;
+    lazyHoistedPglitePromise = null;
+    wasmLoadedAt = null;
+}
+/**
+ * Lazily get or create the hoisted PGLite instance.
+ *
+ * This function is called ONLY when a query is executed, not during
+ * manager initialization.
+ */
+async function lazyGetOrCreateHoistedPglite(options) {
+    // Fast path: already initialized
+    if (lazyHoistedPglite) {
+        return lazyHoistedPglite;
+    }
+    // Deduplication: return existing promise if initialization in progress
+    if (lazyHoistedPglitePromise) {
+        return lazyHoistedPglitePromise;
+    }
+    const loadStartTime = performance.now();
+    // Start initialization
+    lazyHoistedPglitePromise = createWorkersPGLite({
+        wasmModule: pgliteWasm,
+        fsBundle: pgliteData,
+        database: options.database ?? 'postgres',
+        debug: options.debug ?? 0,
+    });
+    try {
+        lazyHoistedPglite = await lazyHoistedPglitePromise;
+        wasmLoadedAt = Date.now();
+        const loadDuration = performance.now() - loadStartTime;
+        console.log(`[LazyPGLiteManager] WASM LOADED (lazy, on first query) - took ${loadDuration.toFixed(2)}ms, instance: ${LAZY_MODULE_INSTANCE_ID}`);
+        return lazyHoistedPglite;
+    }
+    finally {
+        // Clear the promise after resolution (success or failure)
+        lazyHoistedPglitePromise = null;
+    }
+}
+// =============================================================================
+// LazyPGLiteManager Class
+// =============================================================================
+/**
+ * LazyPGLiteManager defers WASM loading until the first query.
+ *
+ * Unlike the eager PGLiteManager, this manager does NOT load WASM during
+ * initialize(). WASM is only loaded when query() or ensureWASMLoaded() is called.
+ *
+ * Benefits:
+ * - Non-query endpoints (health, metadata, stats) respond immediately
+ * - Memory is not consumed until queries are actually executed
+ * - Better cold start perception for mixed workloads
+ *
+ * Trade-offs:
+ * - First query incurs the full WASM loading time (~1200ms)
+ * - Less predictable query latency (first vs subsequent)
+ *
+ * @example
+ * ```typescript
+ * const manager = new LazyPGLiteManager({ database: 'mydb' })
+ *
+ * // Initialize (fast - no WASM loading)
+ * await manager.initialize()
+ *
+ * // Check if WASM is loaded (without triggering load)
+ * console.log(manager.isWASMLoaded()) // false
+ *
+ * // First query triggers WASM load (~1200ms)
+ * const result1 = await manager.query('SELECT 1')
+ *
+ * // Now WASM is loaded
+ * console.log(manager.isWASMLoaded()) // true
+ *
+ * // Subsequent queries are fast (~ms)
+ * const result2 = await manager.query('SELECT 2')
+ * ```
+ */
+export class LazyPGLiteManager {
+    pglite = null;
+    initialized = false;
+    loadingState = 'not_loaded';
+    loadError = null;
+    config;
+    pluginManager;
+    /** Track whether this manager is using the hoisted instance */
+    usingHoistedInstance = false;
+    /** Timing metrics for diagnostics */
+    metrics = {
+        initializeCalledAt: null,
+        firstQueryAt: null,
+        wasmLoadStartAt: null,
+        wasmLoadEndAt: null,
+    };
+    constructor(config = {}) {
+        this.config = {
+            database: config.database ?? 'postgres',
+            debug: config.debug ?? false,
+        };
+        if (config.plugins !== undefined) {
+            this.config.plugins = config.plugins;
+        }
+        if (config.createPGLite !== undefined) {
+            this.config.createPGLite = config.createPGLite;
+        }
+        if (config.disableHoisting !== undefined) {
+            this.config.disableHoisting = config.disableHoisting;
+        }
+        // Build plugin manager config
+        const pluginManagerConfig = {};
+        if (config.plugins !== undefined) {
+            pluginManagerConfig.plugins = config.plugins;
+        }
+        if (config.debug !== undefined) {
+            pluginManagerConfig.debug = config.debug;
+        }
+        this.pluginManager = new PluginManager(pluginManagerConfig);
+    }
+    /**
+     * Check if the manager is initialized.
+     * Note: This returns true after initialize() is called, even if WASM is not loaded.
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Check if WASM is loaded (without triggering load).
+     * This is the key difference from eager loading.
+     */
+    isWASMLoaded() {
+        return this.pglite !== null;
+    }
+    /**
+     * Get the current WASM loading state.
+     */
+    getLoadingState() {
+        return this.loadingState;
+    }
+    /**
+     * Get any error that occurred during WASM loading.
+     */
+    getLoadError() {
+        return this.loadError;
+    }
+    /**
+     * Get the PGLite instance (throws if not loaded).
+     * For lazy loading, prefer using query() which handles loading automatically.
+     */
+    getInstance() {
+        if (!this.pglite) {
+            throw new Error('PGLite WASM not loaded. Call ensureWASMLoaded() or query() first.');
+        }
+        return this.pglite;
+    }
+    /**
+     * Get the PGLite instance or null if not loaded.
+     */
+    getInstanceOrNull() {
+        return this.pglite;
+    }
+    /**
+     * Get the plugin manager.
+     */
+    getPluginManager() {
+        return this.pluginManager;
+    }
+    /**
+     * Get timing metrics for diagnostics.
+     */
+    getMetrics() {
+        const wasmLoadDurationMs = this.metrics.wasmLoadStartAt !== null && this.metrics.wasmLoadEndAt !== null
+            ? this.metrics.wasmLoadEndAt - this.metrics.wasmLoadStartAt
+            : null;
+        const timeToFirstQuery = this.metrics.initializeCalledAt !== null && this.metrics.firstQueryAt !== null
+            ? this.metrics.firstQueryAt - this.metrics.initializeCalledAt
+            : null;
+        return {
+            ...this.metrics,
+            wasmLoadDurationMs,
+            timeToFirstQuery,
+        };
+    }
+    /**
+     * Initialize the manager (does NOT load WASM).
+     *
+     * This is intentionally fast - WASM loading is deferred to first query.
+     * Safe to call multiple times.
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        this.metrics.initializeCalledAt = performance.now();
+        this.initialized = true;
+        console.log(`[LazyPGLiteManager] Initialized (WASM not loaded yet)`);
+    }
+    /**
+     * Explicitly ensure WASM is loaded.
+     *
+     * Use this if you want to pre-warm WASM loading before the first query,
+     * but still want the option to skip loading entirely for non-query requests.
+     */
+    async ensureWASMLoaded() {
+        if (this.pglite) {
+            return;
+        }
+        await this.loadWASM();
+    }
+    /**
+     * Internal method to load WASM.
+     */
+    async loadWASM() {
+        if (this.pglite) {
+            return this.pglite;
+        }
+        if (this.loadingState === 'loading') {
+            // Wait for existing load to complete
+            if (lazyHoistedPglitePromise) {
+                const result = await lazyHoistedPglitePromise;
+                this.pglite = result;
+                this.loadingState = 'loaded';
+                return result;
+            }
+        }
+        this.loadingState = 'loading';
+        this.metrics.wasmLoadStartAt = performance.now();
+        try {
+            // Use custom factory if provided (for testing)
+            if (this.config.createPGLite) {
+                this.usingHoistedInstance = false;
+                this.pglite = await this.config.createPGLite();
+            }
+            else if (this.config.disableHoisting) {
+                // Create new instance without hoisting
+                this.usingHoistedInstance = false;
+                console.log(`[LazyPGLiteManager] WASM hoisting disabled - creating new instance`);
+                this.pglite = await createWorkersPGLite({
+                    wasmModule: pgliteWasm,
+                    fsBundle: pgliteData,
+                    database: this.config.database ?? 'postgres',
+                    debug: this.config.debug ? 1 : 0,
+                });
+            }
+            else {
+                // Use the lazy hoisted instance
+                const wasmWasAlreadyLoaded = lazyHoistedPglite !== null;
+                this.pglite = await lazyGetOrCreateHoistedPglite({
+                    database: this.config.database,
+                    debug: this.config.debug ? 1 : 0,
+                });
+                this.usingHoistedInstance = true;
+                if (wasmWasAlreadyLoaded) {
+                    const diagnostics = getLazyHoistedPgliteDiagnostics();
+                    console.log(`[LazyPGLiteManager] WASM REUSED (lazy hoisted) - loaded ${diagnostics.timeSinceLoad}ms ago, instance: ${diagnostics.moduleInstanceId}`);
+                }
+            }
+            this.metrics.wasmLoadEndAt = performance.now();
+            this.loadingState = 'loaded';
+            // Wait for ready if needed
+            if (this.pglite.waitReady) {
+                await this.pglite.waitReady;
+            }
+            // Run auto-create for plugins
+            await this.pluginManager.runAutoCreate(this.pglite);
+            return this.pglite;
+        }
+        catch (error) {
+            this.loadingState = 'error';
+            this.loadError = error instanceof Error ? error : new Error(String(error));
+            throw error;
+        }
+    }
+    /**
+     * Execute a query (lazy loads WASM if needed).
+     *
+     * This is the primary method for interacting with the database.
+     * On first call, it will trigger WASM loading.
+     */
+    async query(sql, params) {
+        // Track first query time
+        if (this.metrics.firstQueryAt === null) {
+            this.metrics.firstQueryAt = performance.now();
+        }
+        // Lazy load WASM if not loaded
+        const pglite = await this.loadWASM();
+        // Execute query
+        return pglite.query(sql, params);
+    }
+    /**
+     * Check if PGLite is responsive by running a simple query.
+     * This will trigger WASM loading if not already loaded.
+     */
+    async checkLiveness() {
+        try {
+            const result = await this.query('SELECT 1 as alive');
+            return result.rows.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Close PGLite instance.
+     */
+    async close(timeoutMs = 5000) {
+        // If using hoisted instance, don't close it
+        if (this.usingHoistedInstance) {
+            console.log(`[LazyPGLiteManager] Skipping close of hoisted WASM instance (will be reused)`);
+            this.pglite = null;
+            this.initialized = false;
+            this.usingHoistedInstance = false;
+            this.loadingState = 'not_loaded';
+            return;
+        }
+        if (!this.pglite?.close) {
+            this.pglite = null;
+            this.initialized = false;
+            this.loadingState = 'not_loaded';
+            return;
+        }
+        try {
+            await Promise.race([
+                this.pglite.close(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('PGlite close timeout')), timeoutMs)),
+            ]);
+        }
+        catch (error) {
+            console.error('Error closing PGlite:', error);
+        }
+        this.pglite = null;
+        this.initialized = false;
+        this.loadingState = 'not_loaded';
+    }
+    /**
+     * Reset manager state (for testing or hibernation recovery).
+     */
+    reset() {
+        this.pglite = null;
+        this.initialized = false;
+        this.usingHoistedInstance = false;
+        this.loadingState = 'not_loaded';
+        this.loadError = null;
+        this.metrics = {
+            initializeCalledAt: null,
+            firstQueryAt: null,
+            wasmLoadStartAt: null,
+            wasmLoadEndAt: null,
+        };
+    }
+    /**
+     * Check if this manager is using the hoisted WASM instance.
+     */
+    isUsingHoistedInstance() {
+        return this.usingHoistedInstance;
+    }
+    /**
+     * Get comprehensive diagnostics about lazy loading state.
+     */
+    getDiagnostics() {
+        return {
+            initialized: this.initialized,
+            wasmLoaded: this.pglite !== null,
+            loadingState: this.loadingState,
+            usingHoistedInstance: this.usingHoistedInstance,
+            metrics: this.getMetrics(),
+            hoisted: getLazyHoistedPgliteDiagnostics(),
+        };
+    }
+}
+/**
+ * Factory function to create a LazyPGLiteManager.
+ */
+export function createLazyPGLiteManager(config) {
+    return new LazyPGLiteManager(config);
+}
+//# sourceMappingURL=lazy-pglite-manager.js.map