@dotdo/postgres 0.1.2 → 0.1.3

package/dist/pglite/workers-pglite.js

@@ -11,6 +11,11 @@
  * - Properly handles fsBundle as ArrayBuffer or Blob
  * - Provides query/exec/transaction interface compatible with PostgresDO
  *
+ * IMPORTANT: This module uses dynamic imports to ensure environment patches
+ * are applied BEFORE pglite.js is evaluated. The Emscripten-generated code
+ * checks `typeof WorkerGlobalScope` at module load time, which must happen
+ * AFTER we've patched the global environment.
+ *
  * @example
  * ```typescript
  * import { createWorkersPGLite } from './workers-pglite'
@@ -27,12 +32,73 @@
  * console.log(result.rows[0].sum) // 2
  * ```
  */
-import { PGlite } from '@dotdo/pglite';
+// Flag to track if patches have been applied
+let patchesApplied = false;
+/**
+ * Apply Cloudflare Workers compatibility patches for Emscripten.
+ *
+ * CRITICAL: This must be called BEFORE importing @dotdo/pglite.
+ * The pglite.js module checks `typeof WorkerGlobalScope` at module load time
+ * to determine if it's running in a web worker. In Cloudflare Workers,
+ * WorkerGlobalScope exists but the environment is not a full web worker,
+ * causing Emscripten to use incompatible code paths.
+ *
+ * This function patches the global environment to make Emscripten think
+ * it's running in a regular web browser environment.
+ */
+function applyWorkersPatches() {
+    if (patchesApplied) {
+        return;
+    }
+    const g = globalThis;
+    // Create a minimal browser-like environment
+    // This helps Emscripten's ENVIRONMENT=web mode work in CF Workers
+    const mockLocation = {
+        href: 'https://localhost/',
+        pathname: '/',
+        protocol: 'https:',
+        host: 'localhost',
+        hostname: 'localhost',
+        port: '',
+        search: '',
+        hash: '',
+        origin: 'https://localhost',
+    };
+    g.window = {
+        sessionStorage: {},
+        localStorage: {},
+        location: mockLocation,
+        encodeURIComponent: encodeURIComponent,
+        decodeURIComponent: decodeURIComponent,
+        encodeURI: encodeURI,
+        decodeURI: decodeURI,
+        atob: atob,
+        btoa: btoa,
+        fetch: fetch,
+        URL: URL,
+        Blob: Blob,
+        crypto: crypto,
+    };
+    g.document = {
+        createElement: () => ({}),
+        currentScript: null,
+        location: mockLocation,
+    };
+    g.location = mockLocation;
+    g.sessionStorage = {};
+    // CRITICAL: Disable WorkerGlobalScope to prevent Emscripten from detecting
+    // this as a worker and trying to use worker-specific APIs that CF Workers
+    // don't fully support
+    g.WorkerGlobalScope = undefined;
+    patchesApplied = true;
+}
 /**
- * Wrapper around PGliteWorkers that provides a compatible interface
+ * Wrapper around PGlite that provides a compatible interface
  * for PostgresDO and handles fsBundle conversion
  */
 export class WorkersPGLite {
+    // Using 'any' here because PGlite type is not available at compile time
+    // due to dynamic import. The actual type is PGlite from @dotdo/pglite.
     pglite;
     _ready = false;
     constructor(pglite) {
@@ -41,9 +107,19 @@ export class WorkersPGLite {
     }
     /**
      * Create a new WorkersPGLite instance
+     *
+     * IMPORTANT: This method uses dynamic import to load @dotdo/pglite
+     * AFTER applying environment patches. This is necessary because
+     * pglite.js evaluates environment detection code at module load time.
      */
     static async create(options) {
-        // Convert fsBundle to ArrayBuffer if needed
+        // Step 1: Apply Cloudflare Workers compatibility patches FIRST
+        // This MUST happen before importing @dotdo/pglite
+        applyWorkersPatches();
+        // Step 2: Now dynamically import @dotdo/pglite
+        // The patches are already applied, so Emscripten will see the correct environment
+        const { PGlite } = await import('@dotdo/pglite');
+        // Step 3: Convert fsBundle to ArrayBuffer if needed
         let fsBundleBuffer;
         if (options.fsBundle instanceof ArrayBuffer) {
             fsBundleBuffer = options.fsBundle;
@@ -73,7 +149,7 @@ export class WorkersPGLite {
             // Fallback for any other type - attempt to use as-is
             fsBundleBuffer = options.fsBundle;
         }
-        // Create PGliteWorkers instance
+        // Step 4: Create PGlite instance
         // fsBundle expects Blob | File, so wrap the ArrayBuffer in a Blob
         const pgliteOptions = {
             wasmModule: options.wasmModule,
@@ -81,7 +157,36 @@ export class WorkersPGLite {
             database: options.database ?? 'postgres',
             debug: options.debug ?? 0,
         };
-        const pglite = await PGlite.create(pgliteOptions);
+        console.log('[WorkersPGLite] Starting PGlite initialization...');
+        console.log('[WorkersPGLite] wasmModule type:', typeof options.wasmModule);
+        console.log('[WorkersPGLite] fsBundle size:', fsBundleBuffer.byteLength);
+        console.log('[WorkersPGLite] Patches applied before import:', patchesApplied);
+        // Environment debug info
+        const g = globalThis;
+        console.log('[WorkersPGLite] ENV CHECK - window:', typeof g.window);
+        console.log('[WorkersPGLite] ENV CHECK - WorkerGlobalScope:', typeof g.WorkerGlobalScope);
+        console.log('[WorkersPGLite] ENV CHECK - document:', typeof g.document);
+        console.log('[WorkersPGLite] ENV CHECK - location:', typeof g.location);
+        console.log('[WorkersPGLite] ENV CHECK - process:', typeof g.process);
+        let pglite;
+        try {
+            console.log('[WorkersPGLite] Calling PGlite.create()...');
+            pglite = await PGlite.create(pgliteOptions);
+            console.log('[WorkersPGLite] PGlite created successfully');
+        }
+        catch (error) {
+            console.error('[WorkersPGLite] PGlite.create failed:', error);
+            // Try to get more information about the error
+            if (error instanceof Error) {
+                console.error('[WorkersPGLite] Error name:', error.name);
+                console.error('[WorkersPGLite] Error message:', error.message);
+                console.error('[WorkersPGLite] Error stack:', error.stack);
+            }
+            throw error;
+        }
+        // Note: We intentionally do NOT restore the original globals after initialization
+        // because pglite.js caches the environment detection results and may still need
+        // the mocked globals for subsequent operations.
         return new WorkersPGLite(pglite);
     }
     /**

package/dist/pglite/workers-pglite.js.map

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

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

@@ -0,0 +1,243 @@
+/**
+ * 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 type { PostgresConfig } from './types';
+import { PluginManager } from './plugin-manager';
+import type { PGliteLike } from './do-pglite-manager';
+/**
+ * Check if the hoisted PGLite instance exists.
+ */
+export declare function hasBgHoistedPglite(): boolean;
+/**
+ * Check if WASM loading is in progress.
+ */
+export declare function isBgWasmLoading(): boolean;
+/**
+ * Get diagnostics about the background hoisted WASM state.
+ */
+export declare function getBgHoistedPgliteDiagnostics(): {
+    hasInstance: boolean;
+    isLoading: boolean;
+    moduleInstanceId: string;
+    wasmLoadStartedAt: number | null;
+    wasmLoadedAt: number | null;
+    loadDurationMs: number | null;
+    timeSinceLoadMs: number | null;
+};
+/**
+ * Reset the hoisted PGLite instance.
+ * WARNING: This should only be used in tests.
+ * @internal
+ */
+export declare function resetBgHoistedPglite(): void;
+export type BGWASMLoadingState = 'not_started' | 'loading' | 'loaded' | 'error';
+export interface BackgroundPGLiteManagerConfig {
+    /** 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.
+     * @default false
+     */
+    disableHoisting?: boolean;
+    /**
+     * waitUntil function from Durable Object context.
+     * Used to keep the DO alive while WASM loads in background.
+     *
+     * @example
+     * ```typescript
+     * new BackgroundPGLiteManager({
+     *   waitUntil: (p) => ctx.waitUntil(p)
+     * })
+     * ```
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * 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 declare class BackgroundPGLiteManager {
+    private pglite;
+    private initialized;
+    private loadingState;
+    private loadError;
+    private config;
+    private pluginManager;
+    private usingHoistedInstance;
+    private loadPromise;
+    /** Timing metrics for diagnostics */
+    private metrics;
+    constructor(config?: BackgroundPGLiteManagerConfig);
+    /**
+     * 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.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if WASM is fully loaded and ready for queries.
+     */
+    isWASMLoaded(): boolean;
+    /**
+     * Check if WASM is currently loading.
+     */
+    isLoading(): boolean;
+    /**
+     * Get the current loading state.
+     */
+    getLoadingState(): BGWASMLoadingState;
+    /**
+     * Get the PGLite instance, waiting for loading to complete if needed.
+     * This is called internally by query methods.
+     */
+    private getPglite;
+    /**
+     * 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.
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+        fields: {
+            name: string;
+            dataTypeID: number;
+        }[];
+        affectedRows?: number;
+    }>;
+    /**
+     * Execute a SQL statement without returning rows.
+     */
+    exec(sql: string): Promise<void>;
+    /**
+     * Check if the manager is initialized (not the same as WASM loaded).
+     */
+    isInitialized(): boolean;
+    /**
+     * Get the PGLite instance if loaded, null otherwise.
+     * Does NOT wait for loading - use for checking readiness.
+     */
+    getInstanceOrNull(): PGliteLike | null;
+    /**
+     * Get the PGLite instance (throws if not loaded).
+     * Use query() instead to automatically wait for loading.
+     */
+    getInstance(): PGliteLike;
+    /**
+     * Wait for WASM to be loaded.
+     * Call this if you want to ensure WASM is ready before proceeding.
+     */
+    ensureWASMLoaded(): Promise<void>;
+    /**
+     * Check if PGLite is responsive.
+     */
+    checkLiveness(): Promise<boolean>;
+    /**
+     * Get timing metrics for diagnostics.
+     */
+    getMetrics(): {
+        initializeCalledAt: number | null;
+        wasmLoadStartAt: number | null;
+        wasmLoadEndAt: number | null;
+        wasmLoadDurationMs: number | null;
+        firstQueryAt: number | null;
+        timeFromInitToFirstQueryMs: number | null;
+        isUsingHoistedInstance: boolean;
+    };
+    /**
+     * Get comprehensive diagnostics.
+     */
+    getDiagnostics(): {
+        manager: {
+            initialized: boolean;
+            loadingState: BGWASMLoadingState;
+            hasInstance: boolean;
+            usingHoistedInstance: boolean;
+            error: string | null;
+        };
+        module: ReturnType<typeof getBgHoistedPgliteDiagnostics>;
+        metrics: ReturnType<BackgroundPGLiteManager['getMetrics']>;
+    };
+    /**
+     * Close the manager.
+     * Note: Does NOT close hoisted instances (they're reused across DO reinstantiations).
+     */
+    close(timeoutMs?: number): Promise<void>;
+    /**
+     * Reset the manager state.
+     */
+    reset(): void;
+    /**
+     * Get the plugin manager.
+     */
+    getPluginManager(): PluginManager;
+}
+/**
+ * Factory function to create a BackgroundPGLiteManager.
+ */
+export declare function createBackgroundPGLiteManager(config?: BackgroundPGLiteManagerConfig): BackgroundPGLiteManager;
+//# sourceMappingURL=background-pglite-manager.d.ts.map

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

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