@dotdo/postgres 0.1.0

package/src/pglite/lifecycle.ts

@@ -0,0 +1,704 @@
+/**
+ * Unified Lifecycle Management for PGLite Initialization
+ *
+ * This module provides a consistent set of types and utilities for managing
+ * PGLite initialization lifecycle across all modules. It addresses the need
+ * for consistent:
+ *
+ * 1. Lifecycle state tracking
+ * 2. Lazy initialization with promise deduplication
+ * 3. Error handling during initialization
+ * 4. Event emission for lifecycle transitions
+ *
+ * ## State Machine
+ *
+ * ```
+ *                        ┌───────────────────────────────────────────────┐
+ *                        │              Lifecycle States                  │
+ *                        ├───────────────────────────────────────────────┤
+ *                        │                                               │
+ *   NOT_STARTED ──────► INITIALIZING ──────► READY ──────► CLOSING ──► CLOSED
+ *        │                    │                  │             │           │
+ *        │                    │                  │             │           │
+ *        └────────────────────┴──────► ERROR ◄───┴─────────────┘           │
+ *                                        │                                 │
+ *                                        └─────────────────────────────────┘
+ * ```
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import {
+ *   LifecycleManager,
+ *   createLifecycleManager,
+ *   LifecycleState,
+ * } from './lifecycle'
+ *
+ * // Create a lifecycle manager for your component
+ * const lifecycle = createLifecycleManager<MyResource>({
+ *   name: 'PGLite',
+ *   initializer: async () => await createPGLite(),
+ *   disposer: async (resource) => await resource.close(),
+ * })
+ *
+ * // Lazy initialization - only runs once
+ * const resource = await lifecycle.ensureInitialized()
+ *
+ * // Check state
+ * if (lifecycle.isReady()) {
+ *   // safe to use resource
+ * }
+ *
+ * // Graceful shutdown
+ * await lifecycle.close()
+ * ```
+ *
+ * @module pglite/lifecycle
+ * @issue postgres-ud8w.3
+ */
+
+// ============================================================================
+// Lifecycle State Types
+// ============================================================================
+
+/**
+ * Core lifecycle states for initialization
+ *
+ * These states represent the fundamental lifecycle of any initializable
+ * component, providing consistency across PGLite, DO managers, and cold
+ * start optimizers.
+ *
+ * | State | Description | Transitions |
+ * |-------|-------------|-------------|
+ * | `not_started` | Initial state, no initialization attempted | -> initializing |
+ * | `initializing` | Initialization in progress | -> ready, error |
+ * | `ready` | Fully initialized and operational | -> closing, error |
+ * | `closing` | Shutdown in progress | -> closed, error |
+ * | `closed` | Fully shut down, cannot be reused | - |
+ * | `error` | Initialization or operation failed | -> closed |
+ */
+export type LifecycleState =
+  | 'not_started'
+  | 'initializing'
+  | 'ready'
+  | 'closing'
+  | 'closed'
+  | 'error'
+
+/**
+ * Extended lifecycle states for detailed phase tracking
+ *
+ * Use these when you need more granular visibility into the
+ * initialization process (e.g., for observability or debugging).
+ */
+export type DetailedLifecycleState =
+  | 'not_started'
+  | 'loading_wasm'           // WASM module loading
+  | 'initializing_postgres'   // PostgreSQL server initialization
+  | 'running_extensions'      // Extension loading and setup
+  | 'ready'
+  | 'draining'               // Waiting for in-flight operations
+  | 'closing'
+  | 'closed'
+  | 'error'
+
+/**
+ * Map detailed states to core states
+ */
+export function toCoreState(detailed: DetailedLifecycleState): LifecycleState {
+  switch (detailed) {
+    case 'not_started':
+      return 'not_started'
+    case 'loading_wasm':
+    case 'initializing_postgres':
+    case 'running_extensions':
+      return 'initializing'
+    case 'ready':
+      return 'ready'
+    case 'draining':
+    case 'closing':
+      return 'closing'
+    case 'closed':
+      return 'closed'
+    case 'error':
+      return 'error'
+  }
+}
+
+// ============================================================================
+// Lifecycle Events
+// ============================================================================
+
+/**
+ * Lifecycle event types
+ */
+export type LifecycleEventType =
+  | 'state_change'
+  | 'initialized'
+  | 'error'
+  | 'closing'
+  | 'closed'
+
+/**
+ * Lifecycle event payload
+ */
+export interface LifecycleEvent {
+  /** Event type */
+  type: LifecycleEventType
+  /** Previous state (for state_change events) */
+  previousState?: LifecycleState
+  /** Current state */
+  currentState: LifecycleState
+  /** Error (for error events) */
+  error?: Error
+  /** Timestamp of the event */
+  timestamp: number
+  /** Duration of initialization (for initialized events) */
+  durationMs?: number
+}
+
+/**
+ * Lifecycle event listener callback
+ */
+export type LifecycleEventListener = (event: LifecycleEvent) => void
+
+// ============================================================================
+// Lifecycle Manager Interface
+// ============================================================================
+
+/**
+ * Configuration for lifecycle manager
+ */
+export interface LifecycleManagerConfig<T> {
+  /**
+   * Name for logging and debugging
+   */
+  name?: string
+
+  /**
+   * Initialize the resource
+   * Called once when initialization is triggered
+   */
+  initializer: () => Promise<T>
+
+  /**
+   * Dispose of the resource
+   * Called during close()
+   */
+  disposer?: (resource: T) => Promise<void>
+
+  /**
+   * Enable lazy initialization (default: true)
+   * When true, initialization is deferred until first use
+   */
+  lazy?: boolean
+
+  /**
+   * Timeout for initialization in milliseconds (default: 30000)
+   */
+  initTimeoutMs?: number
+
+  /**
+   * Timeout for close in milliseconds (default: 5000)
+   */
+  closeTimeoutMs?: number
+
+  /**
+   * Event listener for lifecycle events
+   */
+  onEvent?: LifecycleEventListener
+}
+
+/**
+ * Lifecycle manager interface
+ *
+ * Provides consistent lifecycle management for any initializable resource.
+ */
+export interface ILifecycleManager<T> {
+  /**
+   * Get current lifecycle state
+   */
+  getState(): LifecycleState
+
+  /**
+   * Check if resource is ready
+   */
+  isReady(): boolean
+
+  /**
+   * Check if resource is in a terminal state (closed or error)
+   */
+  isTerminal(): boolean
+
+  /**
+   * Initialize the resource (idempotent, deduplicates concurrent calls)
+   */
+  initialize(): Promise<void>
+
+  /**
+   * Ensure resource is initialized and return it
+   */
+  ensureInitialized(): Promise<T>
+
+  /**
+   * Get the resource (throws if not initialized)
+   */
+  getResource(): T
+
+  /**
+   * Get the resource or null if not initialized
+   */
+  getResourceOrNull(): T | null
+
+  /**
+   * Close the resource (idempotent)
+   */
+  close(): Promise<void>
+
+  /**
+   * Add an event listener
+   * @returns Unsubscribe function
+   */
+  on(listener: LifecycleEventListener): () => void
+
+  /**
+   * Reset the manager (for testing or recovery)
+   */
+  reset(): void
+}
+
+// ============================================================================
+// Lifecycle Manager Implementation
+// ============================================================================
+
+/**
+ * Lifecycle manager implementation
+ *
+ * Provides a consistent pattern for managing the lifecycle of any
+ * initializable resource with:
+ *
+ * - Promise deduplication for concurrent initialization calls
+ * - State tracking and event emission
+ * - Timeout protection
+ * - Proper error handling
+ *
+ * @example
+ * ```typescript
+ * const lifecycle = new LifecycleManager({
+ *   name: 'PGLite',
+ *   initializer: async () => {
+ *     const pg = await PGlite.create()
+ *     return pg
+ *   },
+ *   disposer: async (pg) => await pg.close(),
+ * })
+ *
+ * // First call triggers initialization
+ * const pg1 = await lifecycle.ensureInitialized()
+ *
+ * // Subsequent calls return cached instance immediately
+ * const pg2 = await lifecycle.ensureInitialized()
+ * // pg1 === pg2
+ * ```
+ */
+export class LifecycleManager<T> implements ILifecycleManager<T> {
+  private config: Required<
+    Pick<LifecycleManagerConfig<T>, 'lazy' | 'initTimeoutMs' | 'closeTimeoutMs'>
+  > & LifecycleManagerConfig<T>
+
+  private state: LifecycleState = 'not_started'
+  private resource: T | null = null
+  private initPromise: Promise<void> | null = null
+  private closePromise: Promise<void> | null = null
+  private listeners: LifecycleEventListener[] = []
+  private initStartTime: number = 0
+  private error: Error | null = null
+
+  constructor(config: LifecycleManagerConfig<T>) {
+    this.config = {
+      ...config,
+      name: config.name ?? 'LifecycleManager',
+      lazy: config.lazy ?? true,
+      initTimeoutMs: config.initTimeoutMs ?? 30000,
+      closeTimeoutMs: config.closeTimeoutMs ?? 5000,
+    }
+
+    if (config.onEvent) {
+      this.listeners.push(config.onEvent)
+    }
+
+    // Start initialization immediately if not lazy
+    if (!this.config.lazy) {
+      this.initPromise = this.performInitialization()
+    }
+  }
+
+  // ==========================================================================
+  // State Getters
+  // ==========================================================================
+
+  getState(): LifecycleState {
+    return this.state
+  }
+
+  isReady(): boolean {
+    return this.state === 'ready'
+  }
+
+  isTerminal(): boolean {
+    return this.state === 'closed' || this.state === 'error'
+  }
+
+  /**
+   * Check if initialization is in progress
+   */
+  isInitializing(): boolean {
+    return this.state === 'initializing'
+  }
+
+  /**
+   * Get the error if in error state
+   */
+  getError(): Error | null {
+    return this.error
+  }
+
+  // ==========================================================================
+  // Initialization
+  // ==========================================================================
+
+  async initialize(): Promise<void> {
+    // Already initialized
+    if (this.state === 'ready') {
+      return
+    }
+
+    // Terminal state
+    if (this.isTerminal()) {
+      throw new Error(
+        `Cannot initialize ${this.config.name}: already in ${this.state} state`
+      )
+    }
+
+    // Initialization in progress - return existing promise
+    if (this.initPromise) {
+      return this.initPromise
+    }
+
+    // Start initialization
+    this.initPromise = this.performInitialization()
+    return this.initPromise
+  }
+
+  async ensureInitialized(): Promise<T> {
+    await this.initialize()
+    return this.resource!
+  }
+
+  getResource(): T {
+    if (!this.resource) {
+      throw new Error(`${this.config.name} not initialized`)
+    }
+    return this.resource
+  }
+
+  getResourceOrNull(): T | null {
+    return this.resource
+  }
+
+  // ==========================================================================
+  // Close
+  // ==========================================================================
+
+  async close(): Promise<void> {
+    // Already closed
+    if (this.state === 'closed') {
+      return
+    }
+
+    // Close in progress - return existing promise
+    if (this.closePromise) {
+      return this.closePromise
+    }
+
+    // Can only close from ready or error state
+    if (this.state !== 'ready' && this.state !== 'error') {
+      // If initializing, wait for it then close
+      if (this.initPromise) {
+        try {
+          await this.initPromise
+        } catch {
+          // Ignore init error, we're closing anyway
+        }
+      }
+    }
+
+    this.closePromise = this.performClose()
+    return this.closePromise
+  }
+
+  // ==========================================================================
+  // Event Handling
+  // ==========================================================================
+
+  on(listener: LifecycleEventListener): () => void {
+    this.listeners.push(listener)
+    return () => {
+      const idx = this.listeners.indexOf(listener)
+      if (idx >= 0) {
+        this.listeners.splice(idx, 1)
+      }
+    }
+  }
+
+  // ==========================================================================
+  // Reset (for testing)
+  // ==========================================================================
+
+  reset(): void {
+    this.state = 'not_started'
+    this.resource = null
+    this.initPromise = null
+    this.closePromise = null
+    this.error = null
+    this.initStartTime = 0
+  }
+
+  // ==========================================================================
+  // Private Methods
+  // ==========================================================================
+
+  /**
+   * Perform initialization with timeout and error handling
+   */
+  private async performInitialization(): Promise<void> {
+    this.initStartTime = performance.now()
+    this.setState('initializing')
+
+    try {
+      // Create timeout promise
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(
+          () => reject(new Error(`${this.config.name} initialization timeout`)),
+          this.config.initTimeoutMs
+        )
+      })
+
+      // Race initialization against timeout
+      this.resource = await Promise.race([
+        this.config.initializer(),
+        timeoutPromise,
+      ])
+
+      const durationMs = performance.now() - this.initStartTime
+      this.setState('ready')
+      this.emitEvent({
+        type: 'initialized',
+        currentState: 'ready',
+        timestamp: Date.now(),
+        durationMs,
+      })
+    } catch (err) {
+      this.error = err instanceof Error ? err : new Error(String(err))
+      this.setState('error')
+      this.emitEvent({
+        type: 'error',
+        currentState: 'error',
+        timestamp: Date.now(),
+        error: this.error,
+      })
+      throw this.error
+    }
+  }
+
+  /**
+   * Perform close with timeout
+   */
+  private async performClose(): Promise<void> {
+    const previousState = this.state
+    this.setState('closing')
+    this.emitEvent({
+      type: 'closing',
+      currentState: 'closing',
+      previousState,
+      timestamp: Date.now(),
+    })
+
+    try {
+      if (this.resource && this.config.disposer) {
+        const timeoutPromise = new Promise<never>((_, reject) => {
+          setTimeout(
+            () => reject(new Error(`${this.config.name} close timeout`)),
+            this.config.closeTimeoutMs
+          )
+        })
+
+        await Promise.race([
+          this.config.disposer(this.resource),
+          timeoutPromise,
+        ])
+      }
+
+      this.resource = null
+      this.setState('closed')
+      this.emitEvent({
+        type: 'closed',
+        currentState: 'closed',
+        timestamp: Date.now(),
+      })
+    } catch (err) {
+      // Even on close error, transition to closed state
+      this.resource = null
+      this.setState('closed')
+      this.emitEvent({
+        type: 'closed',
+        currentState: 'closed',
+        timestamp: Date.now(),
+      })
+    }
+  }
+
+  /**
+   * Update state and emit state_change event
+   */
+  private setState(newState: LifecycleState): void {
+    const previousState = this.state
+    if (previousState !== newState) {
+      this.state = newState
+      this.emitEvent({
+        type: 'state_change',
+        previousState,
+        currentState: newState,
+        timestamp: Date.now(),
+      })
+    }
+  }
+
+  /**
+   * Emit an event to all listeners
+   */
+  private emitEvent(event: LifecycleEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event)
+      } catch {
+        // Ignore listener errors
+      }
+    }
+  }
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Create a lifecycle manager
+ *
+ * @example
+ * ```typescript
+ * const lifecycle = createLifecycleManager({
+ *   name: 'PGLite',
+ *   initializer: async () => await PGlite.create(),
+ *   disposer: async (pg) => await pg.close(),
+ * })
+ * ```
+ */
+export function createLifecycleManager<T>(
+  config: LifecycleManagerConfig<T>
+): LifecycleManager<T> {
+  return new LifecycleManager(config)
+}
+
+// ============================================================================
+// Utility Types and Functions
+// ============================================================================
+
+/**
+ * Check if a state allows operations
+ */
+export function isOperationalState(state: LifecycleState): boolean {
+  return state === 'ready'
+}
+
+/**
+ * Check if a state is terminal (cannot recover)
+ */
+export function isTerminalState(state: LifecycleState): boolean {
+  return state === 'closed' || state === 'error'
+}
+
+/**
+ * Check if a state allows initialization
+ */
+export function canInitialize(state: LifecycleState): boolean {
+  return state === 'not_started' || state === 'initializing'
+}
+
+/**
+ * Get a human-readable description of a state
+ */
+export function getStateDescription(state: LifecycleState): string {
+  switch (state) {
+    case 'not_started':
+      return 'Not started - initialization has not been triggered'
+    case 'initializing':
+      return 'Initializing - setup in progress'
+    case 'ready':
+      return 'Ready - fully operational'
+    case 'closing':
+      return 'Closing - shutdown in progress'
+    case 'closed':
+      return 'Closed - resources released'
+    case 'error':
+      return 'Error - initialization or operation failed'
+  }
+}
+
+// ============================================================================
+// Error Classes
+// ============================================================================
+
+/**
+ * Error thrown when an operation is attempted on a non-ready lifecycle
+ */
+export class NotReadyError extends Error {
+  constructor(
+    public readonly componentName: string,
+    public readonly currentState: LifecycleState,
+    public readonly operation: string
+  ) {
+    super(
+      `Cannot ${operation} on ${componentName}: component is in ${currentState} state`
+    )
+    this.name = 'NotReadyError'
+  }
+}
+
+/**
+ * Error thrown when initialization fails
+ */
+export class InitializationError extends Error {
+  constructor(
+    public readonly componentName: string,
+    public readonly cause?: Error
+  ) {
+    super(
+      `${componentName} initialization failed${cause ? `: ${cause.message}` : ''}`
+    )
+    this.name = 'InitializationError'
+  }
+}
+
+/**
+ * Error thrown when initialization times out
+ */
+export class InitializationTimeoutError extends Error {
+  constructor(
+    public readonly componentName: string,
+    public readonly timeoutMs: number
+  ) {
+    super(`${componentName} initialization timed out after ${timeoutMs}ms`)
+    this.name = 'InitializationTimeoutError'
+  }
+}