@dotdo/postgres 0.1.0

package/src/worker/rpc.ts

@@ -0,0 +1,524 @@
+/**
+ * PostgresDO capnweb RPC API
+ *
+ * Implements capnweb RPC for PostgresDO to enable:
+ * - Magic map support for N+1 query elimination
+ * - Promise pipelining for efficient RPC
+ * - Direct Worker-to-DO communication without HTTP overhead
+ * - Bidirectional RPC between Workers and Durable Objects
+ *
+ * The capnweb package provides enhanced RPC capabilities on top of
+ * Cloudflare Workers' built-in RPC support. It's aliased through
+ * 'cloudflare:workers' but we import directly from capnweb to
+ * ensure access to all features including magic map.
+ *
+ * IMPORTANT: RPC types are imported from postgres.do to ensure
+ * the same types are used by both client and server. This is the
+ * single source of truth for the RPC contract.
+ *
+ * @see https://github.com/cloudflare/capnweb
+ * @see https://blog.cloudflare.com/capnweb-javascript-rpc-library/
+ * @see packages/postgres.do/src/rpc/shared-types.ts - Shared RPC types
+ */
+
+// Import RpcTarget from capnweb for full magic map and promise pipelining support
+// Note: capnweb's RpcTarget is compatible with cloudflare:workers' RpcTarget
+// but provides additional features for N+1 elimination and batched operations
+import { RpcTarget } from 'capnweb'
+
+// Import shared RPC types from postgres.do - single source of truth for RPC contract
+import type {
+  RpcRow,
+  RpcField,
+  SharedRpcQueryResult,
+  RpcBatchQuery,
+  RpcBatchResult as SharedRpcBatchResult,
+  RpcTransactionOptions,
+  RpcTransactionState,
+  IPostgresRpcApi,
+  ITransactionRpcApi,
+} from 'postgres.do/rpc'
+
+// Re-export shared types for consumers of this module
+export type {
+  RpcRow,
+  RpcField,
+  RpcBatchQuery,
+  RpcTransactionOptions,
+  RpcTransactionState,
+  IPostgresRpcApi,
+  ITransactionRpcApi,
+}
+
+// Local type imports for internal use
+import type { QueryResultRow, QueryField } from './types'
+import { TransactionError } from './errors'
+
+/**
+ * RPC query result - uses shared types from postgres.do
+ *
+ * This type alias ensures compatibility with the client-side types
+ * while allowing use of the server-side QueryResultRow type.
+ */
+export type RpcQueryResult<T extends QueryResultRow = QueryResultRow> = SharedRpcQueryResult<T>
+
+/**
+ * RPC batch result - uses shared types from postgres.do
+ */
+export type RpcBatchResult = SharedRpcBatchResult
+
+/**
+ * PGlite-like interface for RPC API
+ */
+interface PGliteLike {
+  query<T = unknown>(sql: string, params?: unknown[]): Promise<{
+    rows: T[]
+    fields: { name: string; dataTypeID: number }[]
+    affectedRows?: number
+  }>
+}
+
+/**
+ * Transaction RPC API
+ *
+ * Provides transaction-scoped query methods with promise pipelining support.
+ * Returned from PostgresRpcApi.transaction() to enable patterns like:
+ *
+ * ```typescript
+ * const tx = db.transaction()
+ * const user = tx.query('SELECT * FROM users WHERE id = $1', [1])
+ * const orders = tx.query('SELECT * FROM orders WHERE user_id = $1', [user.id])
+ * await tx.commit()
+ * ```
+ *
+ * Implements ITransactionRpcApi from postgres.do/rpc for type-safe RPC.
+ */
+export class TransactionRpcApi extends RpcTarget implements ITransactionRpcApi {
+  private pglite: PGliteLike
+  private committed = false
+  private rolledBack = false
+  private queries: Array<{ sql: string; params?: unknown[] }> = []
+  private startTime: number
+
+  constructor(pglite: PGliteLike) {
+    super()
+    this.pglite = pglite
+    this.startTime = performance.now()
+  }
+
+  /**
+   * Execute a query within this transaction
+   *
+   * Supports promise pipelining - you can chain queries without awaiting:
+   * ```typescript
+   * const user = tx.query('SELECT * FROM users WHERE id = $1', [1])
+   * const prefs = tx.query('SELECT * FROM prefs WHERE user_id = $1', [user.id])
+   * ```
+   */
+  async query<T extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<RpcQueryResult<T>> {
+    if (this.committed || this.rolledBack) {
+      throw new TransactionError('Transaction has already ended', {
+        currentState: this.committed ? 'committed' : 'rolled_back',
+        expectedStates: ['active'],
+      })
+    }
+
+    this.queries.push({ sql, params: params ?? [] })
+
+    const startTime = performance.now()
+    const result = await this.pglite.query<T>(sql, params)
+    const durationMs = performance.now() - startTime
+
+    return {
+      rows: result.rows,
+      fields: result.fields as QueryField[],
+      rowCount: result.affectedRows ?? result.rows.length,
+      durationMs,
+    }
+  }
+
+  /**
+   * Commit the transaction
+   */
+  async commit(): Promise<{ success: true; durationMs: number }> {
+    if (this.committed) {
+      throw new TransactionError('Transaction already committed', {
+        currentState: 'committed',
+        expectedStates: ['active'],
+      })
+    }
+    if (this.rolledBack) {
+      throw new TransactionError('Transaction already rolled back', {
+        currentState: 'rolled_back',
+        expectedStates: ['active'],
+      })
+    }
+
+    await this.pglite.query('COMMIT')
+    this.committed = true
+
+    return {
+      success: true,
+      durationMs: performance.now() - this.startTime,
+    }
+  }
+
+  /**
+   * Rollback the transaction
+   */
+  async rollback(): Promise<{ success: true; durationMs: number }> {
+    if (this.committed) {
+      throw new TransactionError('Transaction already committed', {
+        currentState: 'committed',
+        expectedStates: ['active'],
+      })
+    }
+    if (this.rolledBack) {
+      throw new TransactionError('Transaction already rolled back', {
+        currentState: 'rolled_back',
+        expectedStates: ['active'],
+      })
+    }
+
+    await this.pglite.query('ROLLBACK')
+    this.rolledBack = true
+
+    return {
+      success: true,
+      durationMs: performance.now() - this.startTime,
+    }
+  }
+
+  /**
+   * Get transaction state
+   */
+  getState(): RpcTransactionState {
+    if (this.committed) return 'committed'
+    if (this.rolledBack) return 'rolled_back'
+    return 'active'
+  }
+
+  /**
+   * Get number of queries executed in this transaction
+   */
+  getQueryCount(): number {
+    return this.queries.length
+  }
+}
+
+/**
+ * PostgreSQL RPC API
+ *
+ * Main RPC interface for PostgresDO. Extends RpcTarget to enable
+ * capnweb features:
+ *
+ * ## Magic Map (N+1 Query Elimination)
+ * ```typescript
+ * const results = await db.query('SELECT id FROM users WHERE active = true')
+ *   .map(users => Promise.all(
+ *     users.map(u => db.query('SELECT * FROM orders WHERE user_id = $1', [u.id]))
+ *   ))
+ * ```
+ *
+ * ## Promise Pipelining
+ * ```typescript
+ * const user = db.query('SELECT * FROM users WHERE id = $1', [id])
+ * const orders = db.query('SELECT * FROM orders WHERE user_id = $1', [user.id])
+ * const [userData, orderData] = await Promise.all([user, orders])
+ * ```
+ *
+ * ## Transaction Support
+ * ```typescript
+ * const tx = db.transaction()
+ * await tx.query('INSERT INTO users (name) VALUES ($1)', ['Alice'])
+ * await tx.query('INSERT INTO audit_log (action) VALUES ($1)', ['user_created'])
+ * await tx.commit()
+ * ```
+ *
+ * Implements IPostgresRpcApi from postgres.do/rpc for type-safe RPC.
+ */
+export class PostgresRpcApi extends RpcTarget implements IPostgresRpcApi {
+  private pglite: PGliteLike
+  private database: string
+
+  constructor(pglite: PGliteLike, database: string = 'postgres') {
+    super()
+    this.pglite = pglite
+    this.database = database
+  }
+
+  /**
+   * Execute a SQL query
+   *
+   * Returns an RpcPromise that supports .map() for magic map functionality:
+   * ```typescript
+   * const users = await db.query('SELECT * FROM users')
+   * // OR with magic map
+   * const usersWithOrders = await db.query('SELECT id FROM users')
+   *   .map(users => Promise.all(users.map(u =>
+   *     db.query('SELECT * FROM orders WHERE user_id = $1', [u.id])
+   *   )))
+   * ```
+   */
+  async query<T extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<RpcQueryResult<T>> {
+    const startTime = performance.now()
+    const result = await this.pglite.query<T>(sql, params)
+    const durationMs = performance.now() - startTime
+
+    return {
+      rows: result.rows,
+      fields: result.fields as QueryField[],
+      rowCount: result.affectedRows ?? result.rows.length,
+      durationMs,
+    }
+  }
+
+  /**
+   * Execute a batch of queries
+   *
+   * More efficient than individual queries for bulk operations.
+   * All queries execute sequentially in a single round-trip.
+   *
+   * ```typescript
+   * const results = await db.batch([
+   *   { sql: 'SELECT * FROM users' },
+   *   { sql: 'SELECT * FROM orders' },
+   *   { sql: 'SELECT COUNT(*) FROM products' },
+   * ])
+   * ```
+   */
+  async batch(queries: RpcBatchQuery[]): Promise<RpcBatchResult> {
+    const startTime = performance.now()
+    const results: RpcQueryResult[] = []
+
+    for (const query of queries) {
+      const queryStart = performance.now()
+      const result = await this.pglite.query(query.sql, query.params)
+      const durationMs = performance.now() - queryStart
+
+      results.push({
+        rows: result.rows as QueryResultRow[],
+        fields: result.fields as QueryField[],
+        rowCount: result.affectedRows ?? result.rows.length,
+        durationMs,
+      })
+    }
+
+    return {
+      results,
+      durationMs: performance.now() - startTime,
+    }
+  }
+
+  /**
+   * Execute a batch of queries within a transaction
+   *
+   * All queries are wrapped in BEGIN/COMMIT. If any query fails,
+   * the entire batch is rolled back.
+   *
+   * ```typescript
+   * const results = await db.batchTransaction([
+   *   { sql: 'INSERT INTO users (name) VALUES ($1)', params: ['Alice'] },
+   *   { sql: 'INSERT INTO audit_log (action) VALUES ($1)', params: ['user_created'] },
+   * ])
+   * ```
+   */
+  async batchTransaction(
+    queries: RpcBatchQuery[],
+    _options?: RpcTransactionOptions
+  ): Promise<RpcBatchResult> {
+    const startTime = performance.now()
+    const results: RpcQueryResult[] = []
+
+    await this.pglite.query('BEGIN')
+
+    try {
+      for (const query of queries) {
+        const queryStart = performance.now()
+        const result = await this.pglite.query(query.sql, query.params)
+        const durationMs = performance.now() - queryStart
+
+        results.push({
+          rows: result.rows as QueryResultRow[],
+          fields: result.fields as QueryField[],
+          rowCount: result.affectedRows ?? result.rows.length,
+          durationMs,
+        })
+      }
+
+      await this.pglite.query('COMMIT')
+    } catch (error) {
+      await this.pglite.query('ROLLBACK')
+      throw error
+    }
+
+    return {
+      results,
+      durationMs: performance.now() - startTime,
+    }
+  }
+
+  /**
+   * Start a transaction and return a TransactionRpcApi
+   *
+   * The returned TransactionRpcApi supports promise pipelining:
+   * ```typescript
+   * const tx = await db.transaction()
+   * const user = tx.query('SELECT * FROM users WHERE id = $1', [1])
+   * const orders = tx.query('SELECT * FROM orders WHERE user_id = $1', [user.id])
+   * await tx.commit()
+   * ```
+   */
+  async transaction(options?: RpcTransactionOptions): Promise<TransactionRpcApi> {
+    let beginSql = 'BEGIN'
+
+    if (options?.isolationLevel) {
+      beginSql += ` ISOLATION LEVEL ${options.isolationLevel}`
+    }
+
+    if (options?.readOnly) {
+      beginSql += ' READ ONLY'
+    }
+
+    await this.pglite.query(beginSql)
+
+    return new TransactionRpcApi(this.pglite)
+  }
+
+  /**
+   * Execute a query and return only the first row
+   *
+   * Convenience method for single-row queries:
+   * ```typescript
+   * const user = await db.queryOne('SELECT * FROM users WHERE id = $1', [id])
+   * ```
+   */
+  async queryOne<T extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<T | null> {
+    const result = await this.query<T>(sql, params)
+    return result.rows[0] ?? null
+  }
+
+  /**
+   * Execute a query and return the scalar value (first column of first row)
+   *
+   * Useful for COUNT, SUM, etc.:
+   * ```typescript
+   * const count = await db.queryScalar<number>('SELECT COUNT(*) FROM users')
+   * ```
+   */
+  async queryScalar<T = unknown>(sql: string, params?: unknown[]): Promise<T | null> {
+    const result = await this.query(sql, params)
+    const row = result.rows[0]
+    if (!row) return null
+
+    const firstKey = Object.keys(row)[0]
+    return (firstKey ? row[firstKey] : null) as T
+  }
+
+  /**
+   * Execute a SQL statement that doesn't return rows
+   *
+   * For INSERT, UPDATE, DELETE operations:
+   * ```typescript
+   * const { rowCount } = await db.execute('DELETE FROM users WHERE id = $1', [id])
+   * ```
+   */
+  async execute(
+    sql: string,
+    params?: unknown[]
+  ): Promise<{ rowCount: number; durationMs: number }> {
+    const result = await this.query(sql, params)
+    return {
+      rowCount: result.rowCount,
+      durationMs: result.durationMs,
+    }
+  }
+
+  /**
+   * Get database name
+   */
+  getDatabase(): string {
+    return this.database
+  }
+
+  /**
+   * Health check - verify PGlite is responsive
+   */
+  async ping(): Promise<{ ok: true; durationMs: number }> {
+    const startTime = performance.now()
+    await this.pglite.query('SELECT 1')
+    return {
+      ok: true,
+      durationMs: performance.now() - startTime,
+    }
+  }
+
+  /**
+   * Get database version
+   */
+  async version(): Promise<string> {
+    const result = await this.queryScalar<string>('SELECT version()')
+    return result ?? 'unknown'
+  }
+
+  /**
+   * List all tables in the public schema
+   */
+  async listTables(): Promise<string[]> {
+    const result = await this.query<{ tablename: string }>(
+      `SELECT tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename`
+    )
+    return result.rows.map((r) => r.tablename)
+  }
+
+  /**
+   * Get table schema information
+   */
+  async describeTable(tableName: string): Promise<
+    Array<{
+      column_name: string
+      data_type: string
+      is_nullable: boolean
+      column_default: string | null
+    }>
+  > {
+    const result = await this.query<{
+      column_name: string
+      data_type: string
+      is_nullable: string
+      column_default: string | null
+    }>(
+      `SELECT column_name, data_type, is_nullable, column_default
+       FROM information_schema.columns
+       WHERE table_schema = 'public' AND table_name = $1
+       ORDER BY ordinal_position`,
+      [tableName]
+    )
+
+    return result.rows.map((r) => ({
+      column_name: r.column_name,
+      data_type: r.data_type,
+      is_nullable: r.is_nullable === 'YES',
+      column_default: r.column_default,
+    }))
+  }
+}
+
+/**
+ * Create a PostgresRpcApi instance from a PGlite instance
+ */
+export function createPostgresRpcApi(
+  pglite: PGliteLike,
+  database?: string
+): PostgresRpcApi {
+  return new PostgresRpcApi(pglite, database)
+}