@dotdo/postgres 0.1.2 → 0.1.3

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

@@ -0,0 +1,528 @@
+/**
+ * Background PGLite Manager for PostgresDO
+ *
+ * This module implements a "eager-but-non-blocking" loading pattern:
+ * - WASM loading starts immediately on initialize() but doesn't block
+ * - Non-query endpoints respond instantly while WASM loads in background
+ * - Queries wait for WASM if not ready, but loading already started
+ * - Uses ctx.waitUntil() to keep DO alive during background loading
+ *
+ * ## Why This is Better Than Pure Lazy Loading
+ *
+ * Pure lazy loading just kicks the can down the road:
+ * - First query still pays full ~1200ms WASM load time
+ *
+ * Background loading gives us the best of both worlds:
+ * - Non-query endpoints respond instantly
+ * - WASM starts loading immediately
+ * - First query only waits for remaining load time (often near-zero)
+ * - If query arrives before WASM ready, it waits but loading is already in progress
+ *
+ * ## Usage with Durable Objects
+ *
+ * ```typescript
+ * export class MyDO extends DurableObject {
+ *   private manager: BackgroundPGLiteManager
+ *
+ *   constructor(ctx: DurableObjectState, env: Env) {
+ *     super(ctx, env)
+ *     this.manager = new BackgroundPGLiteManager({
+ *       database: 'mydb',
+ *       waitUntil: (p) => ctx.waitUntil(p), // Keep DO alive during load
+ *     })
+ *   }
+ *
+ *   async init() {
+ *     // Starts WASM loading in background, returns immediately
+ *     await this.manager.initialize()
+ *   }
+ *
+ *   // Health check - responds instantly, triggers background load if needed
+ *   async ping() {
+ *     return { ok: true, wasmLoading: this.manager.isLoading() }
+ *   }
+ *
+ *   // Query - waits for WASM if not ready
+ *   async query(sql: string) {
+ *     return this.manager.query(sql)
+ *   }
+ * }
+ * ```
+ *
+ * @module worker/background-pglite-manager
+ */
+import { PluginManager } from './plugin-manager';
+// Import WASM module and data bundle for Workers
+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 WASM State (for hoisting across DO reinstantiation)
+// =============================================================================
+/**
+ * Hoisted PGLite instance - survives DO class reinstantiation within same isolate.
+ */
+let bgHoistedPglite = null;
+/**
+ * Promise for in-progress PGLite initialization.
+ * Shared across all manager instances for deduplication.
+ */
+let bgHoistedPglitePromise = null;
+/**
+ * Timestamp when WASM loading started
+ */
+let wasmLoadStartedAt = null;
+/**
+ * Timestamp when WASM was loaded
+ */
+let wasmLoadedAt = null;
+/**
+ * Unique identifier for this module instance
+ */
+const BG_MODULE_INSTANCE_ID = Math.random().toString(36).slice(2, 10);
+/**
+ * Check if the hoisted PGLite instance exists.
+ */
+export function hasBgHoistedPglite() {
+    return bgHoistedPglite !== null;
+}
+/**
+ * Check if WASM loading is in progress.
+ */
+export function isBgWasmLoading() {
+    return bgHoistedPglitePromise !== null && bgHoistedPglite === null;
+}
+/**
+ * Get diagnostics about the background hoisted WASM state.
+ */
+export function getBgHoistedPgliteDiagnostics() {
+    const now = Date.now();
+    return {
+        hasInstance: bgHoistedPglite !== null,
+        isLoading: bgHoistedPglitePromise !== null && bgHoistedPglite === null,
+        moduleInstanceId: BG_MODULE_INSTANCE_ID,
+        wasmLoadStartedAt,
+        wasmLoadedAt,
+        loadDurationMs: wasmLoadStartedAt && wasmLoadedAt ? wasmLoadedAt - wasmLoadStartedAt : null,
+        timeSinceLoadMs: wasmLoadedAt !== null ? now - wasmLoadedAt : null,
+    };
+}
+/**
+ * Reset the hoisted PGLite instance.
+ * WARNING: This should only be used in tests.
+ * @internal
+ */
+export function resetBgHoistedPglite() {
+    bgHoistedPglite = null;
+    bgHoistedPglitePromise = null;
+    wasmLoadStartedAt = null;
+    wasmLoadedAt = null;
+}
+/**
+ * Start WASM loading and return the promise.
+ * This is called by initialize() but not awaited.
+ */
+function startWasmLoading(options) {
+    // Fast path: already initialized
+    if (bgHoistedPglite) {
+        return Promise.resolve(bgHoistedPglite);
+    }
+    // Deduplication: return existing promise if loading in progress
+    if (bgHoistedPglitePromise) {
+        return bgHoistedPglitePromise;
+    }
+    wasmLoadStartedAt = Date.now();
+    console.log(`[BackgroundPGLiteManager] Starting WASM load in background - instance: ${BG_MODULE_INSTANCE_ID}`);
+    // Start initialization
+    bgHoistedPglitePromise = createWorkersPGLite({
+        wasmModule: pgliteWasm,
+        fsBundle: pgliteData,
+        database: options.database ?? 'postgres',
+        debug: options.debug ?? 0,
+    }).then((pglite) => {
+        bgHoistedPglite = pglite;
+        wasmLoadedAt = Date.now();
+        const loadDuration = wasmLoadedAt - (wasmLoadStartedAt ?? wasmLoadedAt);
+        console.log(`[BackgroundPGLiteManager] WASM LOADED - took ${loadDuration}ms, instance: ${BG_MODULE_INSTANCE_ID}`);
+        return pglite;
+    }).catch((error) => {
+        console.error(`[BackgroundPGLiteManager] WASM load failed:`, error);
+        // Clear the promise so we can retry
+        bgHoistedPglitePromise = null;
+        throw error;
+    });
+    return bgHoistedPglitePromise;
+}
+/**
+ * Get the hoisted instance, waiting for loading if in progress.
+ */
+async function getOrAwaitHoistedPglite(options) {
+    // Fast path: already loaded
+    if (bgHoistedPglite) {
+        return bgHoistedPglite;
+    }
+    // Loading in progress - wait for it
+    if (bgHoistedPglitePromise) {
+        return bgHoistedPglitePromise;
+    }
+    // Not started yet - start now (shouldn't happen if initialize() was called)
+    return startWasmLoading(options);
+}
+// =============================================================================
+// BackgroundPGLiteManager Class
+// =============================================================================
+/**
+ * BackgroundPGLiteManager starts WASM loading immediately but doesn't block.
+ *
+ * This gives the best of both worlds:
+ * - Non-query endpoints respond instantly
+ * - WASM starts loading on first init
+ * - Queries wait only for remaining load time (often zero if loaded)
+ * - Uses ctx.waitUntil() to keep DO alive during background loading
+ */
+export class BackgroundPGLiteManager {
+    pglite = null;
+    initialized = false;
+    loadingState = 'not_started';
+    loadError = null;
+    config;
+    pluginManager;
+    usingHoistedInstance = false;
+    loadPromise = null;
+    /** Timing metrics for diagnostics */
+    metrics = {
+        initializeCalledAt: null,
+        wasmLoadStartAt: null,
+        wasmLoadEndAt: null,
+        firstQueryAt: null,
+        firstQueryWaitedMs: null,
+    };
+    constructor(config = {}) {
+        this.config = {
+            database: config.database ?? 'postgres',
+            debug: config.debug ?? false,
+            ...config,
+        };
+        const pluginManagerConfig = {};
+        if (config.plugins !== undefined) {
+            pluginManagerConfig.plugins = config.plugins;
+        }
+        if (config.debug !== undefined) {
+            pluginManagerConfig.debug = config.debug;
+        }
+        this.pluginManager = new PluginManager(pluginManagerConfig);
+    }
+    /**
+     * Initialize the manager.
+     *
+     * This starts WASM loading in the background but returns immediately.
+     * Non-query operations can proceed while WASM loads.
+     *
+     * If waitUntil is provided, it's used to keep the DO alive during loading.
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        this.metrics.initializeCalledAt = Date.now();
+        this.initialized = true;
+        // If custom factory provided, use it (for testing)
+        if (this.config.createPGLite) {
+            this.loadingState = 'loading';
+            this.loadPromise = this.config.createPGLite();
+            this.loadPromise.then((pg) => {
+                this.pglite = pg;
+                this.loadingState = 'loaded';
+                this.metrics.wasmLoadEndAt = Date.now();
+            }).catch((err) => {
+                this.loadingState = 'error';
+                this.loadError = err;
+            });
+            if (this.config.waitUntil) {
+                this.config.waitUntil(this.loadPromise.catch(() => { }));
+            }
+            console.log(`[BackgroundPGLiteManager] Initialized (custom factory, loading in background)`);
+            return;
+        }
+        // If hoisting is disabled, start loading but don't hoist
+        if (this.config.disableHoisting) {
+            this.loadingState = 'loading';
+            this.metrics.wasmLoadStartAt = Date.now();
+            this.loadPromise = createWorkersPGLite({
+                wasmModule: pgliteWasm,
+                fsBundle: pgliteData,
+                database: this.config.database ?? 'postgres',
+                debug: this.config.debug ? 1 : 0,
+            });
+            this.loadPromise.then((pg) => {
+                this.pglite = pg;
+                this.loadingState = 'loaded';
+                this.metrics.wasmLoadEndAt = Date.now();
+                console.log(`[BackgroundPGLiteManager] WASM LOADED (non-hoisted) - took ${this.metrics.wasmLoadEndAt - (this.metrics.wasmLoadStartAt ?? 0)}ms`);
+            }).catch((err) => {
+                this.loadingState = 'error';
+                this.loadError = err;
+                console.error(`[BackgroundPGLiteManager] WASM load failed:`, err);
+            });
+            if (this.config.waitUntil) {
+                this.config.waitUntil(this.loadPromise.catch(() => { }));
+            }
+            console.log(`[BackgroundPGLiteManager] Initialized (hoisting disabled, loading in background)`);
+            return;
+        }
+        // Use hoisted instance
+        this.usingHoistedInstance = true;
+        // Check if already loaded
+        if (bgHoistedPglite) {
+            this.pglite = bgHoistedPglite;
+            this.loadingState = 'loaded';
+            console.log(`[BackgroundPGLiteManager] Initialized (WASM already loaded, reusing hoisted instance)`);
+            return;
+        }
+        // Start loading in background
+        this.loadingState = 'loading';
+        this.metrics.wasmLoadStartAt = Date.now();
+        const loadPromise = startWasmLoading({
+            database: this.config.database,
+            debug: this.config.debug ? 1 : 0,
+        });
+        // Track when loading completes for this manager
+        loadPromise.then((pg) => {
+            this.pglite = pg;
+            this.loadingState = 'loaded';
+            this.metrics.wasmLoadEndAt = Date.now();
+        }).catch((err) => {
+            this.loadingState = 'error';
+            this.loadError = err;
+        });
+        // Use waitUntil to keep DO alive during loading
+        if (this.config.waitUntil) {
+            this.config.waitUntil(loadPromise.catch(() => { }));
+        }
+        console.log(`[BackgroundPGLiteManager] Initialized (starting WASM load in background)`);
+    }
+    /**
+     * Check if WASM is fully loaded and ready for queries.
+     */
+    isWASMLoaded() {
+        return this.loadingState === 'loaded' && this.pglite !== null;
+    }
+    /**
+     * Check if WASM is currently loading.
+     */
+    isLoading() {
+        return this.loadingState === 'loading';
+    }
+    /**
+     * Get the current loading state.
+     */
+    getLoadingState() {
+        return this.loadingState;
+    }
+    /**
+     * Get the PGLite instance, waiting for loading to complete if needed.
+     * This is called internally by query methods.
+     */
+    async getPglite() {
+        // Already loaded
+        if (this.pglite) {
+            return this.pglite;
+        }
+        // Using hoisted instance
+        if (this.usingHoistedInstance && !this.config.createPGLite) {
+            const waitStart = performance.now();
+            const pg = await getOrAwaitHoistedPglite({
+                database: this.config.database,
+                debug: this.config.debug ? 1 : 0,
+            });
+            this.pglite = pg;
+            this.loadingState = 'loaded';
+            const waitMs = performance.now() - waitStart;
+            if (waitMs > 1) {
+                console.log(`[BackgroundPGLiteManager] Query waited ${waitMs.toFixed(2)}ms for WASM to finish loading`);
+            }
+            return pg;
+        }
+        // Using custom factory or non-hoisted
+        if (this.loadPromise) {
+            const waitStart = performance.now();
+            const pg = await this.loadPromise;
+            const waitMs = performance.now() - waitStart;
+            if (waitMs > 1) {
+                console.log(`[BackgroundPGLiteManager] Query waited ${waitMs.toFixed(2)}ms for WASM to finish loading`);
+            }
+            return pg;
+        }
+        throw new Error('PGLite not initialized - call initialize() first');
+    }
+    /**
+     * Execute a query.
+     *
+     * If WASM is not loaded yet, this will wait for loading to complete.
+     * If WASM is already loaded, this returns immediately after query execution.
+     */
+    async query(sql, params) {
+        if (!this.initialized) {
+            throw new Error('Manager not initialized - call initialize() first');
+        }
+        if (this.loadingState === 'error') {
+            throw this.loadError ?? new Error('WASM loading failed');
+        }
+        // Track first query timing
+        if (this.metrics.firstQueryAt === null) {
+            this.metrics.firstQueryAt = Date.now();
+        }
+        const pg = await this.getPglite();
+        return pg.query(sql, params);
+    }
+    /**
+     * Execute a SQL statement without returning rows.
+     */
+    async exec(sql) {
+        const pg = await this.getPglite();
+        if (pg.exec) {
+            await pg.exec(sql);
+        }
+        else {
+            await pg.query(sql);
+        }
+    }
+    /**
+     * Check if the manager is initialized (not the same as WASM loaded).
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get the PGLite instance if loaded, null otherwise.
+     * Does NOT wait for loading - use for checking readiness.
+     */
+    getInstanceOrNull() {
+        return this.pglite;
+    }
+    /**
+     * Get the PGLite instance (throws if not loaded).
+     * Use query() instead to automatically wait for loading.
+     */
+    getInstance() {
+        if (!this.pglite) {
+            throw new Error('PGLite not loaded yet');
+        }
+        return this.pglite;
+    }
+    /**
+     * Wait for WASM to be loaded.
+     * Call this if you want to ensure WASM is ready before proceeding.
+     */
+    async ensureWASMLoaded() {
+        await this.getPglite();
+    }
+    /**
+     * Check if PGLite is responsive.
+     */
+    async checkLiveness() {
+        if (!this.isWASMLoaded()) {
+            return false;
+        }
+        try {
+            const result = await this.pglite.query('SELECT 1 as alive');
+            return result.rows.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get timing metrics for diagnostics.
+     */
+    getMetrics() {
+        const loadDuration = this.metrics.wasmLoadStartAt && this.metrics.wasmLoadEndAt
+            ? this.metrics.wasmLoadEndAt - this.metrics.wasmLoadStartAt
+            : null;
+        const initToFirstQuery = this.metrics.initializeCalledAt && this.metrics.firstQueryAt
+            ? this.metrics.firstQueryAt - this.metrics.initializeCalledAt
+            : null;
+        return {
+            ...this.metrics,
+            wasmLoadDurationMs: loadDuration,
+            timeFromInitToFirstQueryMs: initToFirstQuery,
+            isUsingHoistedInstance: this.usingHoistedInstance,
+        };
+    }
+    /**
+     * Get comprehensive diagnostics.
+     */
+    getDiagnostics() {
+        return {
+            manager: {
+                initialized: this.initialized,
+                loadingState: this.loadingState,
+                hasInstance: this.pglite !== null,
+                usingHoistedInstance: this.usingHoistedInstance,
+                error: this.loadError?.message ?? null,
+            },
+            module: getBgHoistedPgliteDiagnostics(),
+            metrics: this.getMetrics(),
+        };
+    }
+    /**
+     * Close the manager.
+     * Note: Does NOT close hoisted instances (they're reused across DO reinstantiations).
+     */
+    async close(timeoutMs = 5000) {
+        // Don't close hoisted instances
+        if (this.usingHoistedInstance) {
+            console.log(`[BackgroundPGLiteManager] Skipping close of hoisted WASM instance (will be reused)`);
+            this.pglite = null;
+            this.initialized = false;
+            return;
+        }
+        // Close non-hoisted instance
+        if (this.pglite?.close) {
+            try {
+                await Promise.race([
+                    this.pglite.close(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('Close timeout')), timeoutMs)),
+                ]);
+            }
+            catch (error) {
+                console.error('[BackgroundPGLiteManager] Error closing PGLite:', error);
+            }
+        }
+        this.pglite = null;
+        this.initialized = false;
+        this.loadingState = 'not_started';
+    }
+    /**
+     * Reset the manager state.
+     */
+    reset() {
+        this.pglite = null;
+        this.initialized = false;
+        this.loadingState = 'not_started';
+        this.loadError = null;
+        this.loadPromise = null;
+        this.usingHoistedInstance = false;
+        this.metrics = {
+            initializeCalledAt: null,
+            wasmLoadStartAt: null,
+            wasmLoadEndAt: null,
+            firstQueryAt: null,
+            firstQueryWaitedMs: null,
+        };
+    }
+    /**
+     * Get the plugin manager.
+     */
+    getPluginManager() {
+        return this.pluginManager;
+    }
+}
+/**
+ * Factory function to create a BackgroundPGLiteManager.
+ */
+export function createBackgroundPGLiteManager(config = {}) {
+    return new BackgroundPGLiteManager(config);
+}
+//# sourceMappingURL=background-pglite-manager.js.map

package/dist/worker/background-pglite-manager.js.map

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

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

@@ -4,10 +4,45 @@
  * Handles PGLite instance creation, initialization, and lifecycle.
  * Extracted from PostgresDO to reduce class size and separate concerns.
  *
+ * ## WASM Hoisting Pattern
+ *
+ * This module implements WASM hoisting to reduce "warm start" time from ~1200ms to ~30ms.
+ *
+ * The problem: In Cloudflare Workers, when a DO class is recreated (but the isolate stays alive),
+ * the PGLite WASM needs to be reloaded. WASM initialization takes ~1200ms.
+ *
+ * The solution: Cache the PGLite instance at module level. The module loads once per isolate,
+ * so the PGLite instance survives DO class reinstantiation. This means:
+ * - Cold start: ~1200ms (full WASM initialization)
+ * - Warm start (isolate alive, DO recreated): ~30ms (reuse cached WASM)
+ *
  * @module worker/do-pglite-manager
  */
 import type { PostgresConfig } from './types';
 import { PluginManager, type PluginQueryExecutor } from './plugin-manager';
+/**
+ * Check if the hoisted PGLite instance exists.
+ * Useful for diagnostics and testing.
+ */
+export declare function hasHoistedPglite(): boolean;
+/**
+ * Get diagnostics about the hoisted WASM state.
+ * Useful for debugging warm start performance.
+ */
+export declare function getHoistedPgliteDiagnostics(): {
+    hasInstance: boolean;
+    hasPendingPromise: boolean;
+    moduleInstanceId: string;
+    moduleLoadTime: number;
+    moduleAgeMs: number;
+};
+/**
+ * Reset the hoisted PGLite instance.
+ * WARNING: This should only be used in tests. In production, the hoisted
+ * instance should persist for the lifetime of the isolate.
+ * @internal
+ */
+export declare function resetHoistedPglite(): void;
 /**
  * PGlite-like interface
  * This interface is implemented by WorkersPGLite for Cloudflare Workers compatibility
@@ -39,6 +74,14 @@ export interface PGLiteManagerConfig {
     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
+     * and survives DO class reinstantiation for optimal warm start performance.
+     * Set to true to create a new WASM instance for each PGLiteManager.
+     * @default false
+     */
+    disableHoisting?: boolean;
 }
 /**
  * PGLiteManager handles PGLite instance lifecycle.
@@ -72,6 +115,8 @@ export declare class PGLiteManager {
     private initialized;
     private config;
     private pluginManager;
+    /** Track whether this manager is using the hoisted instance */
+    private usingHoistedInstance;
     constructor(config?: PGLiteManagerConfig);
     /**
      * Check if PGLite is initialized
@@ -104,6 +149,10 @@ export declare class PGLiteManager {
     /**
      * Create the PGLite instance
      * Can be overridden for testing
+     *
+     * By default, uses the module-level hoisted PGLite instance for optimal
+     * warm start performance. The hoisted instance survives DO class
+     * reinstantiation within the same isolate.
      */
     protected createPGLiteInstance(): Promise<PGliteLike>;
     /**
@@ -122,6 +171,15 @@ export declare class PGLiteManager {
     /**
      * Close PGLite instance
      *
+     * Note: When using the hoisted WASM instance (default), this method does NOT
+     * close the underlying PGLite instance, as it's shared across DO instances.
+     * It only clears the local reference. The hoisted instance persists for the
+     * lifetime of the isolate for optimal warm start performance.
+     *
+     * To actually close the hoisted instance, use resetHoistedPglite() followed
+     * by close() on the next manager that initializes. This should only be done
+     * in tests or when the isolate is shutting down.
+     *
      * @param timeoutMs - Maximum time to wait for close (default: 5000ms)
      */
     close(timeoutMs?: number): Promise<void>;
@@ -129,6 +187,25 @@ export declare class PGLiteManager {
      * Reset manager state (for testing or hibernation recovery)
      */
     reset(): void;
+    /**
+     * Check if this manager is using the hoisted WASM instance
+     */
+    isUsingHoistedInstance(): boolean;
+    /**
+     * Get diagnostics about WASM hoisting and initialization state.
+     * Useful for debugging warm start performance.
+     */
+    getDiagnostics(): {
+        initialized: boolean;
+        usingHoistedInstance: boolean;
+        hoisted: {
+            hasInstance: boolean;
+            hasPendingPromise: boolean;
+            moduleInstanceId: string;
+            moduleLoadTime: number;
+            moduleAgeMs: number;
+        };
+    };
 }
 /**
  * Create a PGLite manager instance

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

@@ -1 +1 @@
-{"version":3,"file":"do-pglite-manager.d.ts","sourceRoot":"","sources":["../../src/worker/do-pglite-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAA4B,MAAM,kBAAkB,CAAA;AAUpG;;;GAGG;AACH,MAAM,WAAW,UAAW,SAAQ,mBAAmB;IACrD,KAAK,CAAC,CAAC,GAAG,OAAO,EACf,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC;QACT,IAAI,EAAE,CAAC,EAAE,CAAA;QACT,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;QAC9C,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAC,CAAA;IACF,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACpC,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,kFAAkF;IAClF,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wBAAwB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,2BAA2B;IAC3B,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAA;IACnC,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAA;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,aAAa,CAAe;gBAExB,MAAM,GAAE,mBAAwB;IAwB5C;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,WAAW,IAAI,UAAU;IAOzB;;OAEG;IACH,iBAAiB,IAAI,UAAU,GAAG,IAAI;IAItC;;OAEG;IACH,gBAAgB,IAAI,aAAa;IAIjC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,GAAG,IAAI;IAKpD;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAIzD;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAKxC;;;OAGG;cACa,oBAAoB,IAAI,OAAO,CAAC,UAAU,CAAC;IAoC3D;;OAEG;cACa,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAQpD;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBjC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAavC;;;;OAIG;IACG,KAAK,CAAC,SAAS,GAAE,MAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBpD;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAE/E"}
+{"version":3,"file":"do-pglite-manager.d.ts","sourceRoot":"","sources":["../../src/worker/do-pglite-manager.ts"],"names":[],"mappings":"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"}