@dotdo/postgres 0.1.0

package/src/extensions/plugins.ts

@@ -0,0 +1,718 @@
+/**
+ * Plugin Configuration System for PostgresDO
+ *
+ * Provides a simple flag-based system for enabling PostgreSQL extensions
+ * on Durable Object instances. Extensions are pre-bundled with PGLite WASM
+ * and can be enabled per-instance.
+ *
+ * @example
+ * ```typescript
+ * // Simple boolean flags
+ * const config: PluginConfig = {
+ *   vector: true,
+ *   pgsearch: true,
+ * }
+ *
+ * // With configuration options
+ * const config: PluginConfig = {
+ *   vector: {
+ *     enabled: true,
+ *     autoCreate: true,  // Run CREATE EXTENSION on init
+ *   },
+ *   postgis: false,
+ * }
+ *
+ * // Using presets
+ * const config = PLUGIN_PRESETS.AI_SEARCH
+ * ```
+ *
+ * @module extensions/plugins
+ */
+
+// ============================================================================
+// Core Plugin Types
+// ============================================================================
+
+/**
+ * Supported PGLite plugins/extensions
+ *
+ * These are extensions that are pre-bundled with PGLite WASM
+ * and can be enabled on PostgresDO instances.
+ */
+export type PluginName =
+  | 'vector'      // pgvector - Vector similarity search
+  | 'pgsearch'    // Full-text search enhancements
+  | 'postgis'     // Geographic objects support (lightweight)
+  | 'cube'        // Multi-dimensional cube data type (for earthdistance)
+  | 'earthdistance' // Earth distance calculations using great circle math
+  | 'pg_lake'     // Data lake integration
+  | 'pgmq'        // Message queue (PostgreSQL extension)
+  | 'pgmq_lite'   // Message queue (pure SQL, PGLite compatible)
+  | 'pg_trgm'     // Trigram text similarity
+  | 'hstore'      // Key-value pairs
+  | 'citext'      // Case-insensitive text
+  | 'uuid_ossp'   // UUID generation
+  | 'pgcrypto'    // Cryptographic functions
+  | 'btree_gin'   // GIN operator classes
+  | 'btree_gist'  // GiST operator classes
+  | 'fuzzystrmatch' // Fuzzy string matching
+  | 'intarray'    // Integer array functions
+  | 'ltree'       // Hierarchical tree data
+  | 'tablefunc'   // Table manipulation
+  | 'unaccent'    // Accent removal
+
+/**
+ * Configuration options for a single plugin
+ */
+export interface PluginOptions {
+  /**
+   * Whether the plugin is enabled
+   */
+  enabled: boolean
+
+  /**
+   * Automatically run CREATE EXTENSION on initialization
+   * @default false
+   */
+  autoCreate?: boolean
+
+  /**
+   * Plugin-specific configuration options
+   * Different plugins may support different options
+   */
+  config?: Record<string, unknown>
+}
+
+/**
+ * Plugin configuration value - boolean or options object
+ *
+ * @example
+ * ```typescript
+ * // Simple enable
+ * const value: PluginValue = true
+ *
+ * // With options
+ * const value: PluginValue = {
+ *   enabled: true,
+ *   autoCreate: true,
+ * }
+ * ```
+ */
+export type PluginValue = boolean | PluginOptions
+
+/**
+ * Plugin configuration for PostgresDO
+ *
+ * Maps plugin names to their configuration (enabled/disabled or options)
+ *
+ * @example
+ * ```typescript
+ * const plugins: PluginConfig = {
+ *   vector: true,
+ *   pgsearch: { enabled: true, autoCreate: true },
+ *   postgis: false,
+ * }
+ * ```
+ */
+export type PluginConfig = Partial<Record<PluginName, PluginValue>>
+
+// ============================================================================
+// Plugin Metadata
+// ============================================================================
+
+/**
+ * Metadata about a plugin/extension
+ */
+export interface PluginMetadata {
+  /** Internal name (matches PluginName) */
+  name: PluginName
+  /** Display name for UI/logs */
+  displayName: string
+  /** Description of functionality */
+  description: string
+  /** PostgreSQL extension name for CREATE EXTENSION */
+  extensionName: string
+  /** Whether this plugin is available in PGLite WASM */
+  available: boolean
+  /** Dependencies on other plugins */
+  dependencies?: PluginName[]
+  /** Category for organization */
+  category: PluginCategory
+}
+
+/**
+ * Plugin categories for organization
+ */
+export type PluginCategory =
+  | 'search'      // Search-related (vector, pgsearch, pg_trgm)
+  | 'geo'         // Geographic (postgis)
+  | 'data'        // Data types and storage (hstore, ltree, intarray)
+  | 'utility'     // Utilities (uuid_ossp, pgcrypto)
+  | 'messaging'   // Messaging (pgmq)
+  | 'integration' // External integration (pg_lake)
+
+/**
+ * Registry of all supported plugins with metadata
+ */
+export const PLUGIN_REGISTRY: Record<PluginName, PluginMetadata> = {
+  // Search plugins
+  vector: {
+    name: 'vector',
+    displayName: 'pgvector',
+    description: 'Vector similarity search for embeddings and AI applications',
+    extensionName: 'vector',
+    available: true,
+    category: 'search',
+  },
+  pgsearch: {
+    name: 'pgsearch',
+    displayName: 'ParadeDB Search',
+    description: 'Enhanced full-text search with BM25 ranking',
+    extensionName: 'pg_search',
+    available: false, // Not yet available in PGLite WASM
+    category: 'search',
+  },
+  pg_trgm: {
+    name: 'pg_trgm',
+    displayName: 'pg_trgm',
+    description: 'Trigram-based text similarity and fuzzy matching',
+    extensionName: 'pg_trgm',
+    available: true,
+    category: 'search',
+  },
+  fuzzystrmatch: {
+    name: 'fuzzystrmatch',
+    displayName: 'fuzzystrmatch',
+    description: 'Soundex, Levenshtein, and other fuzzy string matching',
+    extensionName: 'fuzzystrmatch',
+    available: true,
+    category: 'search',
+  },
+
+  // Geographic plugins
+  postgis: {
+    name: 'postgis',
+    displayName: 'PostGIS',
+    description: 'Geographic object support for spatial queries',
+    extensionName: 'postgis',
+    available: false, // Not yet available in PGLite WASM
+    category: 'geo',
+  },
+  cube: {
+    name: 'cube',
+    displayName: 'cube',
+    description: 'Multi-dimensional cube data type for n-dimensional indexing',
+    extensionName: 'cube',
+    available: true,
+    category: 'geo',
+  },
+  earthdistance: {
+    name: 'earthdistance',
+    displayName: 'earthdistance',
+    description: 'Calculate great circle distances on Earth using latitude/longitude',
+    extensionName: 'earthdistance',
+    available: true,
+    dependencies: ['cube'], // earthdistance depends on cube extension
+    category: 'geo',
+  },
+
+  // Data plugins
+  hstore: {
+    name: 'hstore',
+    displayName: 'hstore',
+    description: 'Key-value pairs data type',
+    extensionName: 'hstore',
+    available: true,
+    category: 'data',
+  },
+  citext: {
+    name: 'citext',
+    displayName: 'citext',
+    description: 'Case-insensitive character string type',
+    extensionName: 'citext',
+    available: true,
+    category: 'data',
+  },
+  ltree: {
+    name: 'ltree',
+    displayName: 'ltree',
+    description: 'Hierarchical tree-like data type for labels',
+    extensionName: 'ltree',
+    available: true,
+    category: 'data',
+  },
+  intarray: {
+    name: 'intarray',
+    displayName: 'intarray',
+    description: 'Functions and operators for integer arrays',
+    extensionName: 'intarray',
+    available: true,
+    category: 'data',
+  },
+
+  // Utility plugins
+  uuid_ossp: {
+    name: 'uuid_ossp',
+    displayName: 'uuid-ossp',
+    description: 'UUID generation functions',
+    extensionName: 'uuid-ossp',
+    available: true,
+    category: 'utility',
+  },
+  pgcrypto: {
+    name: 'pgcrypto',
+    displayName: 'pgcrypto',
+    description: 'Cryptographic functions for encryption and hashing',
+    extensionName: 'pgcrypto',
+    available: true,
+    category: 'utility',
+  },
+  btree_gin: {
+    name: 'btree_gin',
+    displayName: 'btree_gin',
+    description: 'GIN operator classes for btree-indexable types',
+    extensionName: 'btree_gin',
+    available: true,
+    category: 'utility',
+  },
+  btree_gist: {
+    name: 'btree_gist',
+    displayName: 'btree_gist',
+    description: 'GiST operator classes for btree-indexable types',
+    extensionName: 'btree_gist',
+    available: true,
+    category: 'utility',
+  },
+  tablefunc: {
+    name: 'tablefunc',
+    displayName: 'tablefunc',
+    description: 'Functions for table manipulation (crosstab, etc.)',
+    extensionName: 'tablefunc',
+    available: true,
+    category: 'utility',
+  },
+  unaccent: {
+    name: 'unaccent',
+    displayName: 'unaccent',
+    description: 'Text search dictionary for removing accents',
+    extensionName: 'unaccent',
+    available: true,
+    category: 'utility',
+  },
+
+  // Messaging plugins
+  pgmq: {
+    name: 'pgmq',
+    displayName: 'PGMQ',
+    description: 'PostgreSQL message queue for async processing',
+    extensionName: 'pgmq',
+    available: false, // Not yet available in PGLite WASM
+    category: 'messaging',
+  },
+  pgmq_lite: {
+    name: 'pgmq_lite',
+    displayName: 'PGMQ-Lite',
+    description: 'Lightweight message queue using pure SQL (PGLite compatible)',
+    extensionName: 'pgmq_lite', // Uses schema-based setup, not CREATE EXTENSION
+    available: true, // Works with any PostgreSQL/PGLite
+    category: 'messaging',
+  },
+
+  // Integration plugins
+  pg_lake: {
+    name: 'pg_lake',
+    displayName: 'pg_lake',
+    description: 'Data lake integration for external data sources',
+    extensionName: 'pg_lake',
+    available: false, // Not yet available in PGLite WASM
+    category: 'integration',
+  },
+}
+
+// ============================================================================
+// Plugin Presets
+// ============================================================================
+
+/**
+ * Pre-configured plugin configurations for common use cases
+ */
+export const PLUGIN_PRESETS = {
+  /**
+   * No plugins enabled
+   */
+  MINIMAL: {} as PluginConfig,
+
+  /**
+   * Vector similarity search for AI applications
+   */
+  AI_SEARCH: {
+    vector: { enabled: true, autoCreate: true },
+  } as PluginConfig,
+
+  /**
+   * Full-text search configuration
+   */
+  TEXT_SEARCH: {
+    pg_trgm: { enabled: true, autoCreate: true },
+    fuzzystrmatch: { enabled: true, autoCreate: true },
+    unaccent: { enabled: true, autoCreate: true },
+  } as PluginConfig,
+
+  /**
+   * Common utilities for general applications
+   */
+  COMMON: {
+    uuid_ossp: { enabled: true, autoCreate: true },
+    pgcrypto: { enabled: true, autoCreate: true },
+    citext: { enabled: true, autoCreate: true },
+  } as PluginConfig,
+
+  /**
+   * Data-focused extensions
+   */
+  DATA: {
+    hstore: { enabled: true, autoCreate: true },
+    ltree: { enabled: true, autoCreate: true },
+    intarray: { enabled: true, autoCreate: true },
+  } as PluginConfig,
+
+  /**
+   * Geospatial extensions (PostGIS alternative for PGLite)
+   *
+   * Uses earthdistance + cube extensions for location-based queries.
+   * Also works well with PostgreSQL's native geo types (point, box, polygon).
+   */
+  GEOSPATIAL: {
+    cube: { enabled: true, autoCreate: true },
+    earthdistance: { enabled: true, autoCreate: true },
+  } as PluginConfig,
+
+  /**
+   * Message queue for async processing
+   *
+   * Uses PGMQ-Lite, a pure SQL message queue that works with PGLite.
+   * Supports visibility timeout, dead letter queues, and transactional outbox pattern.
+   */
+  MESSAGING: {
+    pgmq_lite: { enabled: true, autoCreate: true },
+  } as PluginConfig,
+
+  /**
+   * All available plugins enabled
+   */
+  FULL: {
+    vector: { enabled: true, autoCreate: true },
+    pg_trgm: { enabled: true, autoCreate: true },
+    cube: { enabled: true, autoCreate: true },
+    earthdistance: { enabled: true, autoCreate: true },
+    pgmq_lite: { enabled: true, autoCreate: true },
+    hstore: { enabled: true, autoCreate: true },
+    citext: { enabled: true, autoCreate: true },
+    uuid_ossp: { enabled: true, autoCreate: true },
+    pgcrypto: { enabled: true, autoCreate: true },
+    btree_gin: { enabled: true, autoCreate: true },
+    btree_gist: { enabled: true, autoCreate: true },
+    fuzzystrmatch: { enabled: true, autoCreate: true },
+    intarray: { enabled: true, autoCreate: true },
+    ltree: { enabled: true, autoCreate: true },
+    tablefunc: { enabled: true, autoCreate: true },
+    unaccent: { enabled: true, autoCreate: true },
+  } as PluginConfig,
+} as const
+
+// ============================================================================
+// Plugin Configuration Utilities
+// ============================================================================
+
+/**
+ * Check if a plugin is enabled in the configuration
+ */
+export function isPluginEnabled(config: PluginConfig, name: PluginName): boolean {
+  const value = config[name]
+  if (value === undefined || value === false) return false
+  if (value === true) return true
+  return value.enabled
+}
+
+/**
+ * Check if a plugin should auto-create its extension
+ * A plugin must be both enabled AND have autoCreate set to true
+ */
+export function shouldPluginAutoCreate(config: PluginConfig, name: PluginName): boolean {
+  const value = config[name]
+  if (value === undefined || value === false || value === true) return false
+  // Must be enabled AND have autoCreate
+  return value.enabled && (value.autoCreate ?? false)
+}
+
+/**
+ * Get all enabled plugin names from configuration
+ */
+export function getEnabledPlugins(config: PluginConfig): PluginName[] {
+  return (Object.keys(config) as PluginName[]).filter(name => isPluginEnabled(config, name))
+}
+
+/**
+ * Get all plugins that should auto-create extensions
+ */
+export function getAutoCreatePlugins(config: PluginConfig): PluginName[] {
+  return (Object.keys(config) as PluginName[]).filter(name => shouldPluginAutoCreate(config, name))
+}
+
+/**
+ * Merge two plugin configurations (second takes precedence)
+ */
+export function mergePluginConfigs(
+  base: PluginConfig | undefined,
+  override: PluginConfig | undefined
+): PluginConfig {
+  if (!base && !override) return {}
+  if (!base) return { ...override }
+  if (!override) return { ...base }
+
+  const merged: PluginConfig = { ...base }
+
+  for (const [name, value] of Object.entries(override) as [PluginName, PluginValue][]) {
+    const baseValue = base[name]
+
+    // If both are objects, merge them
+    if (
+      typeof baseValue === 'object' &&
+      baseValue !== null &&
+      typeof value === 'object' &&
+      value !== null
+    ) {
+      merged[name] = { ...baseValue, ...value }
+    } else {
+      merged[name] = value
+    }
+  }
+
+  return merged
+}
+
+// ============================================================================
+// Plugin Validation
+// ============================================================================
+
+/**
+ * Result of plugin configuration validation
+ */
+export interface PluginValidationResult {
+  /** Whether the configuration is valid */
+  valid: boolean
+  /** Validation errors (configuration is invalid) */
+  errors: string[]
+  /** Validation warnings (configuration may have issues) */
+  warnings: string[]
+  /** List of unavailable plugins that were requested */
+  unavailablePlugins: PluginName[]
+}
+
+/**
+ * Validate a plugin configuration
+ *
+ * @param config Plugin configuration to validate
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validatePluginConfig({ vector: true, postgis: true })
+ * if (!result.valid) {
+ *   console.error('Invalid config:', result.errors)
+ * }
+ * if (result.unavailablePlugins.length > 0) {
+ *   console.warn('Unavailable plugins:', result.unavailablePlugins)
+ * }
+ * ```
+ */
+export function validatePluginConfig(config: PluginConfig): PluginValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+  const unavailablePlugins: PluginName[] = []
+
+  for (const [name, value] of Object.entries(config) as [PluginName, PluginValue][]) {
+    // Check if plugin exists in registry
+    const metadata = PLUGIN_REGISTRY[name]
+    if (!metadata) {
+      errors.push(`Unknown plugin "${name}". Available plugins: ${Object.keys(PLUGIN_REGISTRY).join(', ')}`)
+      continue
+    }
+
+    // Check if plugin is available
+    if (isPluginEnabled(config, name) && !metadata.available) {
+      unavailablePlugins.push(name)
+      warnings.push(
+        `Plugin "${name}" (${metadata.displayName}) is not yet available in PGLite WASM. ` +
+        `It will be ignored until support is added.`
+      )
+    }
+
+    // Validate options format
+    if (typeof value === 'object' && value !== null) {
+      if (typeof value.enabled !== 'boolean') {
+        errors.push(`Plugin "${name}": "enabled" must be a boolean`)
+      }
+      if (value.autoCreate !== undefined && typeof value.autoCreate !== 'boolean') {
+        errors.push(`Plugin "${name}": "autoCreate" must be a boolean`)
+      }
+    }
+
+    // Check dependencies
+    if (isPluginEnabled(config, name) && metadata.dependencies) {
+      for (const dep of metadata.dependencies) {
+        if (!isPluginEnabled(config, dep)) {
+          warnings.push(
+            `Plugin "${name}" depends on "${dep}" which is not enabled. ` +
+            `Consider enabling "${dep}" for full functionality.`
+          )
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    unavailablePlugins,
+  }
+}
+
+// ============================================================================
+// Plugin SQL Generation
+// ============================================================================
+
+/**
+ * Generate CREATE EXTENSION SQL for enabled plugins with autoCreate
+ *
+ * @param config Plugin configuration
+ * @returns SQL string with CREATE EXTENSION statements
+ *
+ * @example
+ * ```typescript
+ * const sql = generatePluginCreateSQL({
+ *   vector: { enabled: true, autoCreate: true },
+ *   hstore: true, // enabled but not autoCreate
+ * })
+ * // Returns: "CREATE EXTENSION IF NOT EXISTS vector;"
+ * ```
+ */
+export function generatePluginCreateSQL(config: PluginConfig): string {
+  const autoCreatePlugins = getAutoCreatePlugins(config)
+
+  if (autoCreatePlugins.length === 0) {
+    return ''
+  }
+
+  const statements = autoCreatePlugins
+    .filter(name => {
+      const metadata = PLUGIN_REGISTRY[name]
+      return metadata && metadata.available
+    })
+    .map(name => {
+      const metadata = PLUGIN_REGISTRY[name]
+      return `CREATE EXTENSION IF NOT EXISTS "${metadata.extensionName}";`
+    })
+
+  return statements.join('\n')
+}
+
+/**
+ * Get plugin metadata for an enabled plugin
+ */
+export function getPluginMetadata(name: PluginName): PluginMetadata | undefined {
+  return PLUGIN_REGISTRY[name]
+}
+
+/**
+ * Get all available plugins (those that can be used in PGLite WASM)
+ */
+export function getAvailablePlugins(): PluginMetadata[] {
+  return Object.values(PLUGIN_REGISTRY).filter(p => p.available)
+}
+
+/**
+ * Get plugins by category
+ */
+export function getPluginsByCategory(category: PluginCategory): PluginMetadata[] {
+  return Object.values(PLUGIN_REGISTRY).filter(p => p.category === category)
+}
+
+// ============================================================================
+// Environment Variable Parsing
+// ============================================================================
+
+/**
+ * Parse plugin configuration from environment variables
+ *
+ * Supports formats:
+ * - POSTGRES_PLUGINS=vector,pg_trgm,hstore (comma-separated list)
+ * - POSTGRES_PLUGIN_VECTOR=true (individual plugin)
+ * - POSTGRES_PLUGIN_VECTOR_AUTOCREATE=true (plugin option)
+ *
+ * @param env Environment variables object
+ * @returns Parsed plugin configuration
+ *
+ * @example
+ * ```typescript
+ * const config = parsePluginEnv({
+ *   POSTGRES_PLUGINS: 'vector,pg_trgm',
+ *   POSTGRES_PLUGIN_HSTORE: 'true',
+ *   POSTGRES_PLUGIN_HSTORE_AUTOCREATE: 'true',
+ * })
+ * // Returns: { vector: true, pg_trgm: true, hstore: { enabled: true, autoCreate: true } }
+ * ```
+ */
+export function parsePluginEnv(env: Record<string, string | undefined>): PluginConfig {
+  const config: PluginConfig = {}
+
+  // Parse comma-separated list
+  const pluginsList = env.POSTGRES_PLUGINS || env.PLUGINS
+  if (pluginsList) {
+    const plugins = pluginsList.split(',').map(p => p.trim().toLowerCase())
+    for (const plugin of plugins) {
+      if (plugin in PLUGIN_REGISTRY) {
+        config[plugin as PluginName] = true
+      }
+    }
+  }
+
+  // Parse individual plugin environment variables
+  for (const [key, value] of Object.entries(env)) {
+    // Match POSTGRES_PLUGIN_<NAME> or PLUGIN_<NAME>
+    const pluginMatch = key.match(/^(?:POSTGRES_)?PLUGIN_([A-Z_]+)$/i)
+    if (pluginMatch && pluginMatch[1] && value) {
+      const pluginName = pluginMatch[1].toLowerCase() as PluginName
+      if (!(pluginName in PLUGIN_REGISTRY)) continue
+
+      const isAutoCreate = key.endsWith('_AUTOCREATE')
+      const baseName = isAutoCreate
+        ? pluginName.replace(/_autocreate$/i, '') as PluginName
+        : pluginName
+
+      if (!(baseName in PLUGIN_REGISTRY)) continue
+
+      if (isAutoCreate) {
+        // Set autoCreate option
+        const existing = config[baseName]
+        if (typeof existing === 'object') {
+          existing.autoCreate = value.toLowerCase() === 'true'
+        } else if (existing === true) {
+          config[baseName] = { enabled: true, autoCreate: value.toLowerCase() === 'true' }
+        }
+      } else {
+        // Enable the plugin
+        const enabled = value.toLowerCase() === 'true'
+        const existingValue = config[baseName]
+        if (typeof existingValue === 'object') {
+          existingValue.enabled = enabled
+        } else {
+          config[baseName] = enabled
+        }
+      }
+    }
+  }
+
+  return config
+}