@dotdo/postgres 0.1.2 → 0.1.3

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdo/postgres",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "PostgreSQL server for Cloudflare Workers/DOs with PGLite WASM and tiered storage",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./do": {
+      "types": "./dist/do/index.d.ts",
+      "import": "./dist/do/index.js"
+    },
     "./pglite": {
       "types": "./dist/pglite/index.d.ts",
       "import": "./dist/pglite/index.js"
@@ -41,6 +45,14 @@
     "./migration-tooling": {
       "types": "./dist/migration-tooling/index.d.ts",
       "import": "./dist/migration-tooling/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
     }
   },
   "files": [
@@ -65,11 +77,12 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@dotdo/pglite": "^0.1.1",
+    "@dotdo/pglite": "^0.1.4",
     "@dotdo/postgres-shared": "^0.1.2",
     "capnweb": "^0.4.0",
     "hono": "^4.0.0",
-    "postgres.do": "^0.1.2"
+    "postgres.do": "^0.1.2",
+    "rpc.do": "^0.2.1"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.8.0",

package/src/client/index.ts

@@ -0,0 +1,61 @@
+/**
+ * PostgresDO WebSocket Client
+ *
+ * A typed WebSocket client for PostgresDO with rpc.do integration.
+ * Provides automatic reconnection, heartbeat, and first-message authentication.
+ *
+ * @module client
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createPostgresClient } from '@dotdo/postgres/client'
+ *
+ * const client = createPostgresClient({
+ *   url: 'wss://postgres.example.com/ws',
+ *   auth: 'your-api-key',
+ * })
+ *
+ * // Execute queries
+ * const users = await client.query('SELECT * FROM users')
+ * const user = await client.queryOne('SELECT * FROM users WHERE id = $1', [1])
+ * const count = await client.queryScalar<number>('SELECT COUNT(*) FROM users')
+ *
+ * // Transactions
+ * const tx = await client.transaction()
+ * await tx.execute('INSERT INTO users (name) VALUES ($1)', ['Alice'])
+ * await tx.commit()
+ *
+ * // Clean up
+ * await client.close()
+ * ```
+ *
+ * @example With oauth.do authentication
+ * ```typescript
+ * import { createPostgresClient } from '@dotdo/postgres/client'
+ * import { oauthProvider } from 'rpc.do/auth'
+ *
+ * const client = createPostgresClient({
+ *   url: 'wss://postgres.example.com/ws',
+ *   auth: oauthProvider(),
+ *   onConnect: () => console.log('Connected!'),
+ *   onReconnecting: (attempt) => console.log(`Reconnecting (${attempt})...`),
+ * })
+ * ```
+ */
+
+// Main client export
+export { PostgresClient, createPostgresClient } from './postgres-client'
+
+// Type exports
+export type {
+  PostgresClientConfig,
+  PostgresDORpcApi,
+  RpcQueryResult,
+  RpcBatchQuery,
+  RpcBatchResult,
+  RpcTransactionOptions,
+  TransactionApi,
+  ColumnInfo,
+  DatabaseStats,
+  ConnectionState,
+} from './types'