@dotdo/postgres 0.1.0

package/src/worker/plugin-manager.ts

@@ -0,0 +1,485 @@
+/**
+ * Plugin Manager for PostgresDO
+ *
+ * Handles plugin/extension lifecycle management including loading,
+ * enabling, disabling, and creating extensions.
+ * Extracted from PostgresDO to reduce class size and separate concerns.
+ *
+ * @module worker/plugin-manager
+ */
+
+import {
+  type PluginName,
+  type PluginConfig,
+  type PluginValue,
+  PLUGIN_REGISTRY,
+  isPluginEnabled,
+  generatePluginCreateSQL,
+  getAutoCreatePlugins,
+} from '../extensions/plugins'
+
+import {
+  PluginLoader,
+  type PluginLoadBatchResult,
+  type PluginLoaderOptions,
+} from '../extensions/loader'
+
+import type { PluginStatus, PluginToggleResponse } from './types'
+
+/**
+ * Interface for a query executor (minimal interface for plugin operations)
+ */
+export interface PluginQueryExecutor {
+  query<T = unknown>(sql: string, params?: unknown[]): Promise<{ rows: T[] }>
+}
+
+/**
+ * Plugin manager configuration
+ */
+export interface PluginManagerConfig {
+  /** Initial plugin configuration */
+  plugins?: PluginConfig
+  /** Debug mode for verbose logging */
+  debug?: boolean
+  /** Plugin loader options */
+  loaderOptions?: PluginLoaderOptions
+}
+
+/**
+ * PluginManager handles plugin lifecycle for PostgresDO.
+ *
+ * Features:
+ * - Plugin loading via PluginLoader
+ * - Extension enable/disable
+ * - CREATE/DROP EXTENSION management
+ * - Plugin status queries
+ *
+ * @example
+ * ```typescript
+ * const pluginManager = new PluginManager({
+ *   plugins: { vector: { enabled: true, autoCreate: true } },
+ *   debug: true,
+ * })
+ *
+ * // Load extensions for PGlite
+ * const extensions = await pluginManager.loadEnabledExtensions()
+ *
+ * // Later, with initialized PGlite
+ * await pluginManager.runAutoCreate(pglite)
+ * ```
+ */
+export class PluginManager {
+  private plugins: PluginConfig
+  private debug: boolean
+  private loaderOptions: PluginLoaderOptions
+  private loader: PluginLoader | null = null
+  private lastLoadResult: PluginLoadBatchResult | null = null
+
+  constructor(config: PluginManagerConfig = {}) {
+    this.plugins = config.plugins || {}
+    this.debug = config.debug || false
+    this.loaderOptions = config.loaderOptions || {}
+  }
+
+  /**
+   * Get the current plugin configuration
+   */
+  getConfig(): PluginConfig {
+    return { ...this.plugins }
+  }
+
+  /**
+   * Update the plugin configuration
+   */
+  setConfig(plugins: PluginConfig): void {
+    this.plugins = { ...plugins }
+  }
+
+  /**
+   * Get or create the plugin loader (singleton per manager)
+   */
+  private getLoader(): PluginLoader {
+    if (!this.loader) {
+      this.loader = new PluginLoader({
+        debug: this.debug,
+        ...this.loaderOptions,
+      })
+    }
+    return this.loader
+  }
+
+  /**
+   * Get the last plugin load result
+   */
+  getLastLoadResult(): PluginLoadBatchResult | null {
+    return this.lastLoadResult
+  }
+
+  /**
+   * Load enabled plugin extensions for PGlite initialization
+   *
+   * @returns Record of loaded extensions keyed by name
+   */
+  async loadEnabledExtensions(): Promise<Record<string, unknown>> {
+    if (!this.plugins || Object.keys(this.plugins).length === 0) {
+      return {}
+    }
+
+    const loader = this.getLoader()
+
+    try {
+      const result = await loader.loadPlugins(this.plugins)
+      this.lastLoadResult = result
+
+      // Log failed plugins
+      if (result.failed.length > 0) {
+        for (const failure of result.failed) {
+          console.warn(`[PluginManager] Failed to load plugin "${failure.name}": ${failure.error}`)
+        }
+      }
+
+      // Log successful loads in debug mode
+      if (this.debug) {
+        const loadedNames = Object.keys(result.loaded)
+        if (loadedNames.length > 0) {
+          console.log(`[PluginManager] Loaded plugins: ${loadedNames.join(', ')}`)
+        }
+        console.log(`[PluginManager] Plugin loading completed in ${result.totalLoadTimeMs.toFixed(2)}ms`)
+      }
+
+      return result.loaded
+    } catch (error) {
+      // Log error but don't throw - allow DO to continue without extensions
+      console.error('[PluginManager] Error loading plugins:', error)
+      return {}
+    }
+  }
+
+  /**
+   * Run auto-create SQL for plugins that have autoCreate enabled
+   *
+   * @param executor Query executor to run CREATE EXTENSION statements
+   */
+  async runAutoCreate(executor: PluginQueryExecutor): Promise<void> {
+    if (!this.plugins || Object.keys(this.plugins).length === 0) {
+      return
+    }
+
+    const autoCreateSQL = generatePluginCreateSQL(this.plugins)
+    if (!autoCreateSQL) {
+      return
+    }
+
+    try {
+      // Run each CREATE EXTENSION statement
+      const statements = autoCreateSQL.split('\n').filter((s) => s.trim())
+      for (const sql of statements) {
+        await executor.query(sql)
+      }
+      if (this.debug) {
+        console.log('[PluginManager] Auto-created extensions:', getAutoCreatePlugins(this.plugins))
+      }
+    } catch (error) {
+      console.error('[PluginManager] Failed to auto-create extensions:', error)
+      // Don't throw - let the DO continue without the extensions
+    }
+  }
+
+  /**
+   * List all available plugins with their status
+   *
+   * @param executor Query executor to check installed extensions
+   */
+  async listPlugins(executor: PluginQueryExecutor): Promise<PluginStatus[]> {
+    const pluginStatuses: PluginStatus[] = []
+
+    // Get currently installed extensions from the database
+    const installedExtensions = new Set<string>()
+    try {
+      const result = await executor.query<{ extname: string }>(`SELECT extname FROM pg_extension`)
+      for (const row of result.rows) {
+        installedExtensions.add(row.extname)
+      }
+    } catch {
+      // pg_extension may not be accessible, continue without installed info
+    }
+
+    // Build status for each plugin in the registry
+    for (const [name, metadata] of Object.entries(PLUGIN_REGISTRY)) {
+      const pluginName = name as PluginName
+      const isEnabled = isPluginEnabled(this.plugins, pluginName)
+      const isCreated = installedExtensions.has(metadata.extensionName)
+
+      // Build status without undefined values for exactOptionalPropertyTypes
+      const status: PluginStatus = {
+        name: metadata.name,
+        displayName: metadata.displayName,
+        description: metadata.description,
+        category: metadata.category,
+        available: metadata.available,
+        enabled: isEnabled,
+        created: isCreated,
+        extensionName: metadata.extensionName,
+      }
+      if (metadata.dependencies !== undefined && metadata.dependencies.length > 0) {
+        status.dependencies = metadata.dependencies
+      }
+      pluginStatuses.push(status)
+    }
+
+    return pluginStatuses
+  }
+
+  /**
+   * Get the status of a specific plugin
+   *
+   * @param name Plugin name to get status for
+   * @param executor Query executor to check if extension is installed
+   */
+  async getPluginStatus(name: PluginName, executor: PluginQueryExecutor): Promise<PluginStatus | null> {
+    const metadata = PLUGIN_REGISTRY[name]
+    if (!metadata) {
+      return null
+    }
+
+    // Check if extension is installed in database
+    let isCreated = false
+    try {
+      const result = await executor.query<{ extname: string }>(
+        `SELECT extname FROM pg_extension WHERE extname = $1`,
+        [metadata.extensionName]
+      )
+      isCreated = result.rows.length > 0
+    } catch {
+      // Continue without installed info
+    }
+
+    const isEnabled = isPluginEnabled(this.plugins, name)
+
+    // Build status without undefined values for exactOptionalPropertyTypes
+    const status: PluginStatus = {
+      name: metadata.name,
+      displayName: metadata.displayName,
+      description: metadata.description,
+      category: metadata.category,
+      available: metadata.available,
+      enabled: isEnabled,
+      created: isCreated,
+      extensionName: metadata.extensionName,
+    }
+    if (metadata.dependencies !== undefined && metadata.dependencies.length > 0) {
+      status.dependencies = metadata.dependencies
+    }
+    return status
+  }
+
+  /**
+   * Enable a plugin
+   *
+   * @param name Plugin name to enable
+   * @param executor Query executor for CREATE EXTENSION
+   * @param autoCreate Whether to run CREATE EXTENSION immediately
+   */
+  async enablePlugin(
+    name: PluginName,
+    executor: PluginQueryExecutor | null,
+    autoCreate: boolean = false
+  ): Promise<PluginToggleResponse> {
+    const metadata = PLUGIN_REGISTRY[name]
+    if (!metadata) {
+      return {
+        success: false,
+        name,
+        enabled: false,
+        error: `Unknown plugin: ${name}`,
+        timestamp: new Date().toISOString(),
+      }
+    }
+
+    if (!metadata.available) {
+      return {
+        success: false,
+        name,
+        enabled: false,
+        error: `Plugin "${name}" is not available in PGLite WASM`,
+        timestamp: new Date().toISOString(),
+      }
+    }
+
+    // Update runtime configuration
+    ;(this.plugins as Record<string, PluginValue>)[name] = { enabled: true, autoCreate }
+
+    let created = false
+
+    // Run CREATE EXTENSION if autoCreate is true and executor is provided
+    if (autoCreate && executor) {
+      try {
+        await executor.query(`CREATE EXTENSION IF NOT EXISTS "${metadata.extensionName}"`)
+        created = true
+      } catch (error) {
+        return {
+          success: false,
+          name,
+          enabled: true,
+          error: `Failed to create extension: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          timestamp: new Date().toISOString(),
+        }
+      }
+    }
+
+    return {
+      success: true,
+      name,
+      enabled: true,
+      created,
+      timestamp: new Date().toISOString(),
+    }
+  }
+
+  /**
+   * Disable a plugin
+   *
+   * Note: This does NOT drop the extension from the database
+   *
+   * @param name Plugin name to disable
+   */
+  disablePlugin(name: PluginName): PluginToggleResponse {
+    const metadata = PLUGIN_REGISTRY[name]
+    if (!metadata) {
+      return {
+        success: false,
+        name,
+        enabled: false,
+        error: `Unknown plugin: ${name}`,
+        timestamp: new Date().toISOString(),
+      }
+    }
+
+    // Update runtime configuration
+    ;(this.plugins as Record<string, PluginValue>)[name] = false
+
+    return {
+      success: true,
+      name,
+      enabled: false,
+      timestamp: new Date().toISOString(),
+    }
+  }
+
+  /**
+   * Create an extension in the database
+   *
+   * @param name Plugin name to create extension for
+   * @param executor Query executor to run CREATE EXTENSION
+   */
+  async createExtension(name: PluginName, executor: PluginQueryExecutor): Promise<PluginToggleResponse> {
+    const metadata = PLUGIN_REGISTRY[name]
+    if (!metadata) {
+      return {
+        success: false,
+        name,
+        enabled: false,
+        error: `Unknown plugin: ${name}`,
+        timestamp: new Date().toISOString(),
+      }
+    }
+
+    if (!metadata.available) {
+      return {
+        success: false,
+        name,
+        enabled: false,
+        error: `Plugin "${name}" is not available in PGLite WASM`,
+        timestamp: new Date().toISOString(),
+      }
+    }
+
+    try {
+      await executor.query(`CREATE EXTENSION IF NOT EXISTS "${metadata.extensionName}"`)
+      return {
+        success: true,
+        name,
+        enabled: isPluginEnabled(this.plugins, name),
+        created: true,
+        timestamp: new Date().toISOString(),
+      }
+    } catch (error) {
+      return {
+        success: false,
+        name,
+        enabled: isPluginEnabled(this.plugins, name),
+        error: `Failed to create extension: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        timestamp: new Date().toISOString(),
+      }
+    }
+  }
+
+  /**
+   * Drop an extension from the database
+   *
+   * @param name Plugin name to drop extension for
+   * @param executor Query executor to run DROP EXTENSION
+   * @param cascade Whether to drop dependent objects
+   */
+  async dropExtension(
+    name: PluginName,
+    executor: PluginQueryExecutor,
+    cascade: boolean = false
+  ): Promise<PluginToggleResponse> {
+    const metadata = PLUGIN_REGISTRY[name]
+    if (!metadata) {
+      return {
+        success: false,
+        name,
+        enabled: false,
+        error: `Unknown plugin: ${name}`,
+        timestamp: new Date().toISOString(),
+      }
+    }
+
+    try {
+      const dropSQL = cascade
+        ? `DROP EXTENSION IF EXISTS "${metadata.extensionName}" CASCADE`
+        : `DROP EXTENSION IF EXISTS "${metadata.extensionName}"`
+      await executor.query(dropSQL)
+      return {
+        success: true,
+        name,
+        enabled: isPluginEnabled(this.plugins, name),
+        created: false,
+        timestamp: new Date().toISOString(),
+      }
+    } catch (error) {
+      return {
+        success: false,
+        name,
+        enabled: isPluginEnabled(this.plugins, name),
+        error: `Failed to drop extension: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        timestamp: new Date().toISOString(),
+      }
+    }
+  }
+
+  /**
+   * Check if a specific plugin is enabled
+   */
+  isEnabled(name: PluginName): boolean {
+    return isPluginEnabled(this.plugins, name)
+  }
+
+  /**
+   * Clear the plugin loader cache
+   */
+  clearCache(): void {
+    if (this.loader) {
+      this.loader.clearCache()
+    }
+  }
+}
+
+/**
+ * Create a plugin manager instance
+ */
+export function createPluginManager(config?: PluginManagerConfig): PluginManager {
+  return new PluginManager(config)
+}

package/src/worker/postgres.do-rpc.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Type declarations for postgres.do/rpc module
+ * This module is provided by @dotdo/postgres.do package
+ *
+ * IMPORTANT: These types must match the actual implementation in rpc.ts
+ *
+ * Uses Record<string, unknown> per project convention for pure dictionary types.
+ * @see CLAUDE.md "Record vs Index Signature Usage"
+ */
+declare module 'postgres.do/rpc' {
+  export type RpcRow = Record<string, unknown>
+
+  export interface RpcField {
+    name: string
+    dataTypeID: number
+  }
+
+  export interface RpcQueryResult<T extends RpcRow = RpcRow> {
+    rows: T[]
+    fields: RpcField[]
+    affectedRows?: number
+    rowCount: number
+    durationMs: number
+  }
+
+  // Alias for shared result type
+  export type SharedRpcQueryResult<T extends RpcRow = RpcRow> = RpcQueryResult<T>
+
+  export interface RpcBatchQuery {
+    sql: string
+    params?: unknown[]
+  }
+
+  export interface RpcBatchResult {
+    results: RpcQueryResult[]
+    durationMs: number
+  }
+
+  export interface RpcTransactionOptions {
+    isolationLevel?: 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE'
+    readOnly?: boolean
+  }
+
+  export type RpcTransactionState = 'active' | 'committed' | 'rolled_back'
+
+  /**
+   * PostgresRpcApi interface - main RPC interface
+   * Methods marked with ? are optional in implementations
+   */
+  export interface IPostgresRpcApi {
+    query<T extends RpcRow = RpcRow>(sql: string, params?: unknown[]): Promise<RpcQueryResult<T>>
+    queryOne?<T extends RpcRow = RpcRow>(sql: string, params?: unknown[]): Promise<T | null>
+    queryScalar?<T = unknown>(sql: string, params?: unknown[]): Promise<T | null>
+    execute?(sql: string, params?: unknown[]): Promise<{ rowCount: number; durationMs: number }>
+    batch?(queries: RpcBatchQuery[]): Promise<RpcBatchResult>
+    batchTransaction?(queries: RpcBatchQuery[], options?: RpcTransactionOptions): Promise<RpcBatchResult>
+    transaction?(options?: RpcTransactionOptions): Promise<ITransactionRpcApi>
+    listTables?(): Promise<string[]>
+    describeTable?(tableName: string): Promise<Array<{ column_name: string; data_type: string; is_nullable: boolean; column_default: string | null }>>
+    getDatabase?(): string
+    ping?(): Promise<{ ok: true; durationMs: number }>
+    version?(): Promise<string>
+  }
+
+  /**
+   * TransactionRpcApi interface - transaction-scoped operations
+   * Matches the actual TransactionRpcApi class implementation
+   */
+  export interface ITransactionRpcApi {
+    query<T extends RpcRow = RpcRow>(sql: string, params?: unknown[]): Promise<RpcQueryResult<T>>
+    commit(): Promise<{ success: true; durationMs: number }>
+    rollback(): Promise<{ success: true; durationMs: number }>
+    getState(): RpcTransactionState
+    getQueryCount?(): number
+  }
+}