@dotdo/postgres 0.1.1 → 0.1.3

package/README.md

@@ -99,10 +99,22 @@ Done. PostgreSQL at the edge.
 | **Latency** | <10ms (edge) | 50-200ms (regional) |
 | **Idle cost** | $0 (hibernation) | $$$ (always running) |
 | **Cache reads** | FREE | Per-query cost |
-| **Cold starts** | <10ms | 50-200ms |
+| **Warm starts** | **16ms** (WASM hoisting) | 50-200ms |
+| **Cold starts** | ~1200ms (full WASM) | 50-200ms |
 | **Per-user DBs** | Built-in | Complex infra |
 | **WebSocket** | 95% cheaper | Full connection cost |
 
+### Performance
+
+| Scenario | Latency | Notes |
+|----------|---------|-------|
+| **Warm query** | 13-16ms | WASM hoisted, consistent |
+| **Warm start** (DO reinstantiated) | **16ms** | 75x faster with WASM hoisting |
+| **Cold start** | ~1200ms | Full WASM initialization |
+| **Non-query endpoints** | **Instant** | Respond while WASM loads |
+
+The key insight: **Isolates stay warm much longer than DO class instances**. WASM hoisting at the module level means most requests hit a warm isolate where WASM is already loaded, reducing latency from ~1200ms to ~16ms.
+
 ## API Reference
 
 ### Worker Module
@@ -130,6 +142,19 @@ export const AuthenticatedPostgresDO = createAuthenticatedPostgresDO({
   oauthDoBinding: 'OAUTH_DO',
   requiredScopes: ['read', 'write'],
 })
+
+// WASM hoisting utilities for diagnostics
+import {
+  hasBgHoistedPglite,      // Check if WASM is loaded
+  isBgWasmLoading,          // Check if WASM is loading
+  getBgHoistedPgliteDiagnostics,  // Get detailed diagnostics
+} from '@dotdo/postgres/worker'
+
+// Check WASM state
+console.log('WASM loaded:', hasBgHoistedPglite())
+console.log('WASM loading:', isBgWasmLoading())
+console.log('Diagnostics:', getBgHoistedPgliteDiagnostics())
+// { hasInstance: true, isLoading: false, loadDurationMs: 1156, ... }
 ```
 
 #### createRoutes
@@ -155,6 +180,53 @@ app.route('/api/sql', createRoutes(postgresDO))
 // GET  /schema        - Get schema version info
 ```
 
+#### BackgroundPGLiteManager
+
+Eager-but-non-blocking WASM loading for optimal performance.
+
+```typescript
+import { BackgroundPGLiteManager, createBackgroundPGLiteManager } from '@dotdo/postgres/worker'
+
+// In your Durable Object
+export class PostgresDO extends DurableObject {
+  private manager: BackgroundPGLiteManager
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env)
+    this.manager = createBackgroundPGLiteManager({
+      database: 'mydb',
+      waitUntil: (p) => ctx.waitUntil(p), // Keep DO alive during WASM load
+    })
+  }
+
+  async init() {
+    // Starts WASM loading in background, returns IMMEDIATELY
+    await this.manager.initialize()
+  }
+
+  // Health check - responds INSTANTLY (doesn't wait for WASM)
+  ping() {
+    return {
+      ok: true,
+      wasmLoaded: this.manager.isWASMLoaded(),
+      wasmLoading: this.manager.isLoading(),
+    }
+  }
+
+  // Query - waits for WASM if not ready (loading already started)
+  async query(sql: string) {
+    return this.manager.query(sql)
+  }
+}
+```
+
+**Why eager-but-non-blocking?**
+- Pure lazy loading "kicks the can down the road" - first query still pays full ~1200ms
+- Background loading gives 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)
+
 #### WebSocket Handler
 
 Real-time query execution and CDC subscriptions via WebSocket.

package/dist/client/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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})...`),
+ * })
+ * ```
+ */
+export { PostgresClient, createPostgresClient } from './postgres-client';
+export type { PostgresClientConfig, PostgresDORpcApi, RpcQueryResult, RpcBatchQuery, RpcBatchResult, RpcTransactionOptions, TransactionApi, ColumnInfo, DatabaseStats, ConnectionState, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAGxE,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,UAAU,EACV,aAAa,EACb,eAAe,GAChB,MAAM,SAAS,CAAA"}

package/dist/client/index.js

@@ -0,0 +1,47 @@
+/**
+ * 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';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,qBAAqB;AACrB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/client/postgres-client.d.ts

@@ -0,0 +1,273 @@
+/**
+ * PostgresClient - WebSocket client for PostgresDO with rpc.do integration
+ *
+ * Provides typed access to PostgresDO's RPC methods over WebSocket with:
+ * - Automatic reconnection with exponential backoff
+ * - Heartbeat ping/pong for connection health
+ * - First-message authentication
+ * - Full TypeScript support
+ *
+ * @module client/postgres-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')
+ * console.log(users.rows)
+ *
+ * // Single row
+ * const user = await client.queryOne('SELECT * FROM users WHERE id = $1', [1])
+ *
+ * // Scalar value
+ * const count = await client.queryScalar<number>('SELECT COUNT(*) FROM users')
+ *
+ * // Clean up
+ * await client.close()
+ * ```
+ *
+ * @example With rpc.do transport
+ * ```typescript
+ * import { createPostgresClient } from '@dotdo/postgres/client'
+ * import { capnweb } from 'rpc.do/transports'
+ *
+ * // Using capnweb transport with reconnection
+ * const client = createPostgresClient({
+ *   url: 'wss://postgres.example.com/ws',
+ *   auth: () => localStorage.getItem('token'),
+ *   autoReconnect: true,
+ *   onConnect: () => console.log('Connected!'),
+ *   onReconnecting: (attempt) => console.log(`Reconnecting... (${attempt})`),
+ * })
+ * ```
+ */
+import type { PostgresClientConfig, RpcQueryResult, RpcBatchQuery, RpcBatchResult, RpcTransactionOptions, TransactionApi, ColumnInfo, DatabaseStats, ConnectionState } from './types';
+import type { QueryResultRow } from '../worker/types';
+/**
+ * PostgresClient - typed WebSocket client for PostgresDO
+ *
+ * Uses rpc.do's capnweb transport for efficient RPC communication
+ * with automatic reconnection and hibernation support.
+ */
+export declare class PostgresClient {
+    private config;
+    private rpcClient;
+    private transport;
+    private connectionPromise;
+    private state;
+    constructor(config: PostgresClientConfig);
+    /**
+     * Connect to the PostgresDO WebSocket endpoint
+     */
+    private connect;
+    /**
+     * Establish the WebSocket connection using rpc.do
+     */
+    private establishConnection;
+    /**
+     * Ensure we're connected before making RPC calls
+     */
+    private ensureConnected;
+    /**
+     * Execute a SQL query and return full results
+     *
+     * @example
+     * ```typescript
+     * const result = await client.query('SELECT * FROM users WHERE active = $1', [true])
+     * console.log(result.rows)
+     * console.log(`${result.rowCount} rows returned in ${result.durationMs}ms`)
+     * ```
+     */
+    query<T extends QueryResultRow = QueryResultRow>(sql: string, params?: unknown[]): Promise<RpcQueryResult<T>>;
+    /**
+     * Execute a query and return only the first row
+     *
+     * @example
+     * ```typescript
+     * const user = await client.queryOne('SELECT * FROM users WHERE id = $1', [1])
+     * if (user) {
+     *   console.log(user.name)
+     * }
+     * ```
+     */
+    queryOne<T extends QueryResultRow = QueryResultRow>(sql: string, params?: unknown[]): Promise<T | null>;
+    /**
+     * Execute a query and return a scalar value (first column of first row)
+     *
+     * @example
+     * ```typescript
+     * const count = await client.queryScalar<number>('SELECT COUNT(*) FROM users')
+     * console.log(`Total users: ${count}`)
+     * ```
+     */
+    queryScalar<T = unknown>(sql: string, params?: unknown[]): Promise<T | null>;
+    /**
+     * Execute a statement that doesn't return rows
+     *
+     * @example
+     * ```typescript
+     * const { rowCount } = await client.execute('DELETE FROM users WHERE inactive = true')
+     * console.log(`Deleted ${rowCount} inactive users`)
+     * ```
+     */
+    execute(sql: string, params?: unknown[]): Promise<{
+        rowCount: number;
+        durationMs: number;
+    }>;
+    /**
+     * Execute multiple queries in a single round trip
+     *
+     * @example
+     * ```typescript
+     * const result = await client.batch([
+     *   { sql: 'SELECT * FROM users' },
+     *   { sql: 'SELECT * FROM orders' },
+     *   { sql: 'SELECT * FROM products' },
+     * ])
+     * const [users, orders, products] = result.results
+     * ```
+     */
+    batch(queries: RpcBatchQuery[]): Promise<RpcBatchResult>;
+    /**
+     * Execute multiple queries within a transaction
+     *
+     * @example
+     * ```typescript
+     * const result = await client.batchTransaction([
+     *   { sql: 'INSERT INTO users (name) VALUES ($1)', params: ['Alice'] },
+     *   { sql: 'INSERT INTO audit_log (action) VALUES ($1)', params: ['user_created'] },
+     * ])
+     * ```
+     */
+    batchTransaction(queries: RpcBatchQuery[]): Promise<RpcBatchResult>;
+    /**
+     * Start a transaction and return a transaction API
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.transaction()
+     * try {
+     *   await tx.execute('INSERT INTO users (name) VALUES ($1)', ['Alice'])
+     *   await tx.execute('INSERT INTO audit_log (action) VALUES ($1)', ['user_created'])
+     *   await tx.commit()
+     * } catch (error) {
+     *   await tx.rollback()
+     *   throw error
+     * }
+     * ```
+     *
+     * @example With isolation level
+     * ```typescript
+     * const tx = await client.transaction({ isolationLevel: 'SERIALIZABLE' })
+     * // ... perform queries
+     * await tx.commit()
+     * ```
+     */
+    transaction(options?: RpcTransactionOptions): Promise<TransactionApi>;
+    /**
+     * Health check - verify the database is responsive
+     *
+     * @example
+     * ```typescript
+     * const { ok, durationMs } = await client.ping()
+     * console.log(`Database responded in ${durationMs}ms`)
+     * ```
+     */
+    ping(): Promise<{
+        ok: true;
+        durationMs: number;
+    }>;
+    /**
+     * Get the PostgreSQL version
+     *
+     * @example
+     * ```typescript
+     * const version = await client.version()
+     * console.log(`PostgreSQL version: ${version}`)
+     * ```
+     */
+    version(): Promise<string>;
+    /**
+     * List all tables in the public schema
+     *
+     * @example
+     * ```typescript
+     * const tables = await client.listTables()
+     * console.log('Tables:', tables)
+     * ```
+     */
+    listTables(): Promise<string[]>;
+    /**
+     * Get schema information for a table
+     *
+     * @example
+     * ```typescript
+     * const columns = await client.describeTable('users')
+     * for (const col of columns) {
+     *   console.log(`${col.column_name}: ${col.data_type}`)
+     * }
+     * ```
+     */
+    describeTable(tableName: string): Promise<ColumnInfo[]>;
+    /**
+     * Get database statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.getStats()
+     * console.log(`Queries: ${stats.queryCount}, Avg: ${stats.avgDurationMs}ms`)
+     * ```
+     */
+    getStats(): Promise<DatabaseStats>;
+    /**
+     * Get current connection state
+     */
+    getConnectionState(): ConnectionState;
+    /**
+     * Check if currently connected
+     */
+    isConnected(): boolean;
+    /**
+     * Close the connection
+     *
+     * @example
+     * ```typescript
+     * await client.close()
+     * ```
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create a PostgresClient instance
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createPostgresClient } from '@dotdo/postgres/client'
+ *
+ * const client = createPostgresClient({
+ *   url: 'wss://postgres.example.com/ws',
+ *   auth: 'your-api-key',
+ * })
+ *
+ * const users = await client.query('SELECT * FROM users')
+ * ```
+ *
+ * @example With reconnection callbacks
+ * ```typescript
+ * const client = createPostgresClient({
+ *   url: 'wss://postgres.example.com/ws',
+ *   auth: () => getAuthToken(),
+ *   onConnect: () => console.log('Connected!'),
+ *   onDisconnect: (reason) => console.log('Disconnected:', reason),
+ *   onReconnecting: (attempt) => console.log(`Reconnecting (${attempt})...`),
+ * })
+ * ```
+ */
+export declare function createPostgresClient(config: PostgresClientConfig): PostgresClient;
+//# sourceMappingURL=postgres-client.d.ts.map

package/dist/client/postgres-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-client.d.ts","sourceRoot":"","sources":["../../src/client/postgres-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EACV,oBAAoB,EAEpB,cAAc,EACd,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,UAAU,EACV,aAAa,EACb,eAAe,EAChB,MAAM,SAAS,CAAA;AAChB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,KAAK,CAAkC;gBAEnC,MAAM,EAAE,oBAAoB;IAaxC;;OAEG;YACW,OAAO;IAoBrB;;OAEG;YACW,mBAAmB;IA+BjC;;OAEG;YACW,eAAe;IAgB7B;;;;;;;;;OASG;IACG,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACnD,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAK7B;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACtD,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAKpB;;;;;;;;OAQG;IACG,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAKlF;;;;;;;;OAQG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IASjG;;;;;;;;;;;;OAYG;IACG,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAK9D;;;;;;;;;;OAUG;IACG,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IASzE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;IAS3E;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAKvD;;;;;;;;OAQG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAKhC;;;;;;;;OAQG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKrC;;;;;;;;;;OAUG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAK7D;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC;IASxC;;OAEG;IACH,kBAAkB,IAAI,eAAe;IAIrC;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAEjF"}