@dotdo/postgres 0.1.0

package/src/extensions/config.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Extension Configuration API Tests
+ * RED phase: Define expected behavior for extension configuration
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  createExtensionConfig,
+  mergeExtensionConfigs,
+  validateExtensionConfig,
+  type PostgresExtensionsConfig,
+} from './config'
+
+describe('createExtensionConfig', () => {
+  it('should create config with no extensions enabled by default', () => {
+    const config = createExtensionConfig()
+    expect(config.extensions).toEqual({})
+  })
+
+  it('should create config with specified extensions enabled', () => {
+    const config = createExtensionConfig({
+      vector: true,
+      hstore: true,
+    })
+    expect(config.extensions).toEqual({
+      vector: true,
+      hstore: true,
+    })
+  })
+
+  it('should support extension options', () => {
+    const config = createExtensionConfig({
+      vector: { enabled: true, autoCreate: true },
+      pg_trgm: { enabled: true, autoCreate: false },
+    })
+    expect(config.extensions?.vector).toEqual({ enabled: true, autoCreate: true })
+    expect(config.extensions?.pg_trgm).toEqual({ enabled: true, autoCreate: false })
+  })
+
+  it('should support mixed boolean and options', () => {
+    const config = createExtensionConfig({
+      vector: true,
+      hstore: { enabled: true, autoCreate: true },
+    })
+    expect(config.extensions?.vector).toBe(true)
+    expect(config.extensions?.hstore).toEqual({ enabled: true, autoCreate: true })
+  })
+})
+
+describe('mergeExtensionConfigs', () => {
+  it('should merge two configs', () => {
+    const base = createExtensionConfig({ vector: true })
+    const override = createExtensionConfig({ hstore: true })
+
+    const merged = mergeExtensionConfigs(base, override)
+
+    expect(merged.extensions?.vector).toBe(true)
+    expect(merged.extensions?.hstore).toBe(true)
+  })
+
+  it('should override same extension', () => {
+    const base = createExtensionConfig({ vector: true })
+    const override = createExtensionConfig({ vector: false })
+
+    const merged = mergeExtensionConfigs(base, override)
+
+    expect(merged.extensions?.vector).toBe(false)
+  })
+
+  it('should merge extension options deeply', () => {
+    const base = createExtensionConfig({
+      vector: { enabled: true, autoCreate: false },
+    })
+    const override = createExtensionConfig({
+      vector: { enabled: true, autoCreate: true },
+    })
+
+    const merged = mergeExtensionConfigs(base, override)
+
+    expect(merged.extensions?.vector).toEqual({ enabled: true, autoCreate: true })
+  })
+
+  it('should handle undefined base', () => {
+    const override = createExtensionConfig({ vector: true })
+    const merged = mergeExtensionConfigs(undefined, override)
+    expect(merged.extensions?.vector).toBe(true)
+  })
+
+  it('should handle undefined override', () => {
+    const base = createExtensionConfig({ vector: true })
+    const merged = mergeExtensionConfigs(base, undefined)
+    expect(merged.extensions?.vector).toBe(true)
+  })
+})
+
+describe('validateExtensionConfig', () => {
+  it('should return valid for correct config', () => {
+    const config = createExtensionConfig({ vector: true })
+    const result = validateExtensionConfig(config)
+    expect(result.valid).toBe(true)
+    expect(result.errors).toHaveLength(0)
+  })
+
+  it('should return errors for invalid extension names', () => {
+    const config = createExtensionConfig({
+      'invalid-name-with-dashes!': true,
+    })
+    const result = validateExtensionConfig(config)
+    expect(result.valid).toBe(false)
+    expect(result.errors.length).toBeGreaterThan(0)
+  })
+
+  it('should return warnings for unknown extensions', () => {
+    const config = createExtensionConfig({
+      unknown_extension: true,
+    })
+    const result = validateExtensionConfig(config)
+    expect(result.warnings.length).toBeGreaterThan(0)
+    expect(result.warnings[0]).toContain('unknown_extension')
+  })
+
+  it('should validate extension options', () => {
+    const config = createExtensionConfig({
+      vector: { enabled: 'not-a-boolean' as any },
+    })
+    const result = validateExtensionConfig(config)
+    expect(result.valid).toBe(false)
+  })
+})
+
+describe('PostgresExtensionsConfig type', () => {
+  it('should have extensions property', () => {
+    const config: PostgresExtensionsConfig = {
+      extensions: {
+        vector: true,
+      },
+    }
+    expect(config.extensions).toBeDefined()
+  })
+
+  it('should support all common extensions', () => {
+    const config: PostgresExtensionsConfig = {
+      extensions: {
+        vector: true,
+        pg_trgm: true,
+        hstore: true,
+        citext: true,
+        uuid_ossp: true,
+        pgcrypto: true,
+        btree_gin: true,
+        btree_gist: true,
+        fuzzystrmatch: true,
+        intarray: true,
+        ltree: true,
+        tablefunc: true,
+        unaccent: true,
+      },
+    }
+    expect(Object.keys(config.extensions!)).toHaveLength(13)
+  })
+})
+
+describe('Extension presets', () => {
+  it('should have a minimal preset', async () => {
+    const { PRESETS } = await import('./config')
+    expect(PRESETS.MINIMAL).toBeDefined()
+    expect(Object.keys(PRESETS.MINIMAL.extensions || {})).toHaveLength(0)
+  })
+
+  it('should have a vector search preset', async () => {
+    const { PRESETS } = await import('./config')
+    expect(PRESETS.VECTOR_SEARCH).toBeDefined()
+    expect(PRESETS.VECTOR_SEARCH.extensions?.vector).toBeTruthy()
+  })
+
+  it('should have a full-text search preset', async () => {
+    const { PRESETS } = await import('./config')
+    expect(PRESETS.FULL_TEXT_SEARCH).toBeDefined()
+    expect(PRESETS.FULL_TEXT_SEARCH.extensions?.pg_trgm).toBeTruthy()
+  })
+
+  it('should have a common preset with popular extensions', async () => {
+    const { PRESETS } = await import('./config')
+    expect(PRESETS.COMMON).toBeDefined()
+    expect(PRESETS.COMMON.extensions?.uuid_ossp).toBeTruthy()
+    expect(PRESETS.COMMON.extensions?.pgcrypto).toBeTruthy()
+  })
+})

package/src/extensions/config.ts

@@ -0,0 +1,278 @@
+/**
+ * Extension Configuration API
+ *
+ * Provides configuration utilities for enabling and managing PostgreSQL extensions
+ * with support for presets, validation, and merging.
+ */
+
+/**
+ * Options for configuring a specific extension
+ */
+export interface ExtensionOptions {
+  /** Whether the extension is enabled */
+  enabled: boolean
+  /** Whether to auto-create the extension via CREATE EXTENSION */
+  autoCreate?: boolean
+}
+
+/**
+ * Extension configuration value - can be boolean or options object
+ */
+export type ExtensionValue = boolean | ExtensionOptions
+
+/**
+ * Configuration for PostgreSQL extensions
+ */
+export interface PostgresExtensionsConfig {
+  extensions?: {
+    [name: string]: ExtensionValue
+  }
+}
+
+/**
+ * Result of config validation
+ */
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+}
+
+/**
+ * Known extension names for validation
+ */
+const KNOWN_EXTENSIONS = new Set([
+  'vector',
+  'pg_trgm',
+  'hstore',
+  'citext',
+  'uuid_ossp',
+  'pgcrypto',
+  'btree_gin',
+  'btree_gist',
+  'fuzzystrmatch',
+  'intarray',
+  'ltree',
+  'tablefunc',
+  'unaccent',
+  'cube',
+  'earthdistance',
+  'isn',
+  'lo',
+  'seg',
+  'tcn',
+  'bloom',
+  'amcheck',
+  'auto_explain',
+  'dict_int',
+  'dict_xsyn',
+  'file_fdw',
+  'pageinspect',
+  'pg_buffercache',
+  'pg_freespacemap',
+  'pg_surgery',
+  'pg_visibility',
+  'pg_walinspect',
+  'tsm_system_rows',
+  'tsm_system_time',
+])
+
+/**
+ * Regex for valid extension names
+ */
+const VALID_NAME_REGEX = /^[a-z][a-z0-9_]*$/
+
+/**
+ * Create an extension configuration
+ */
+export function createExtensionConfig(
+  extensions?: Record<string, ExtensionValue>
+): PostgresExtensionsConfig {
+  return {
+    extensions: extensions ?? {},
+  }
+}
+
+/**
+ * Merge two extension configurations, with the second taking precedence
+ */
+export function mergeExtensionConfigs(
+  base: PostgresExtensionsConfig | undefined,
+  override: PostgresExtensionsConfig | undefined
+): PostgresExtensionsConfig {
+  const baseExtensions = base?.extensions ?? {}
+  const overrideExtensions = override?.extensions ?? {}
+
+  const merged: Record<string, ExtensionValue> = { ...baseExtensions }
+
+  for (const [name, value] of Object.entries(overrideExtensions)) {
+    const baseValue = baseExtensions[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 { extensions: merged }
+}
+
+/**
+ * Validate an extension configuration
+ */
+export function validateExtensionConfig(
+  config: PostgresExtensionsConfig
+): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  if (!config.extensions) {
+    return { valid: true, errors, warnings }
+  }
+
+  for (const [name, value] of Object.entries(config.extensions)) {
+    // Check name format
+    if (!VALID_NAME_REGEX.test(name)) {
+      errors.push(`Invalid extension name "${name}": must start with a letter and contain only lowercase letters, numbers, and underscores`)
+    }
+
+    // Check if known extension
+    if (!KNOWN_EXTENSIONS.has(name) && VALID_NAME_REGEX.test(name)) {
+      warnings.push(`Unknown extension "${name}": this extension may not be available`)
+    }
+
+    // Validate value
+    if (typeof value === 'object' && value !== null) {
+      if (typeof value.enabled !== 'boolean') {
+        errors.push(`Extension "${name}": "enabled" must be a boolean`)
+      }
+      if (value.autoCreate !== undefined && typeof value.autoCreate !== 'boolean') {
+        errors.push(`Extension "${name}": "autoCreate" must be a boolean`)
+      }
+    } else if (typeof value !== 'boolean') {
+      errors.push(`Extension "${name}": value must be a boolean or options object`)
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+/**
+ * Extension configuration presets for common use cases
+ */
+export const PRESETS = {
+  /**
+   * Minimal preset - no extensions enabled
+   */
+  MINIMAL: createExtensionConfig(),
+
+  /**
+   * Vector search preset - for AI/ML embeddings
+   */
+  VECTOR_SEARCH: createExtensionConfig({
+    vector: { enabled: true, autoCreate: true },
+  }),
+
+  /**
+   * Full-text search preset - for text search applications
+   */
+  FULL_TEXT_SEARCH: createExtensionConfig({
+    pg_trgm: { enabled: true, autoCreate: true },
+    fuzzystrmatch: { enabled: true, autoCreate: true },
+    unaccent: { enabled: true, autoCreate: true },
+  }),
+
+  /**
+   * Common preset - popular extensions for general use
+   */
+  COMMON: createExtensionConfig({
+    uuid_ossp: { enabled: true, autoCreate: true },
+    pgcrypto: { enabled: true, autoCreate: true },
+    citext: { enabled: true, autoCreate: true },
+    hstore: { enabled: true, autoCreate: true },
+  }),
+
+  /**
+   * Full preset - all commonly used extensions
+   */
+  FULL: createExtensionConfig({
+    vector: { enabled: true, autoCreate: true },
+    pg_trgm: { 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 const
+
+/**
+ * Helper to check if an extension is enabled in config
+ */
+export function isExtensionEnabled(
+  config: PostgresExtensionsConfig,
+  name: string
+): boolean {
+  const value = config.extensions?.[name]
+  if (value === undefined) return false
+  if (typeof value === 'boolean') return value
+  return value.enabled
+}
+
+/**
+ * Helper to check if an extension should be auto-created
+ */
+export function shouldAutoCreate(
+  config: PostgresExtensionsConfig,
+  name: string
+): boolean {
+  const value = config.extensions?.[name]
+  if (value === undefined) return false
+  if (typeof value === 'boolean') return false
+  return value.autoCreate ?? false
+}
+
+/**
+ * Get list of enabled extension names from config
+ */
+export function getEnabledExtensions(config: PostgresExtensionsConfig): string[] {
+  if (!config.extensions) return []
+
+  return Object.entries(config.extensions)
+    .filter(([_, value]) => {
+      if (typeof value === 'boolean') return value
+      return value.enabled
+    })
+    .map(([name]) => name)
+}
+
+/**
+ * Get list of extension names that should be auto-created
+ */
+export function getAutoCreateExtensions(config: PostgresExtensionsConfig): string[] {
+  if (!config.extensions) return []
+
+  return Object.entries(config.extensions)
+    .filter(([_, value]) => {
+      if (typeof value === 'boolean') return false
+      return value.enabled && value.autoCreate
+    })
+    .map(([name]) => name)
+}