@dotdo/postgres 0.1.0

package/dist/worker/types.d.ts

@@ -0,0 +1,738 @@
+/**
+ * Worker Types for PostgresDO
+ * Task: postgres-6u6.1 - Worker Types (Env, QueryRequest, QueryResponse, WSMessage, PostgresConfig)
+ */
+/**
+ * Environment bindings for the Cloudflare Worker
+ */
+export interface Env {
+    POSTGRES_DO: DurableObjectNamespace;
+    POSTGRES_DEFAULT_DB?: string;
+    POSTGRES_MAX_CONNECTIONS?: string;
+}
+/**
+ * SQL query parameter types
+ */
+export type QueryParam = string | number | boolean | null | Uint8Array | Date;
+/**
+ * Query method hints
+ */
+export type QueryMethod = 'all' | 'one' | 'run' | 'exec';
+/**
+ * Request to execute a SQL query
+ */
+export interface QueryRequest {
+    sql: string;
+    params?: QueryParam[] | undefined;
+    preserveCase?: boolean | undefined;
+    method?: QueryMethod | undefined;
+}
+/**
+ * Field metadata from query results
+ */
+export interface QueryField {
+    name: string;
+    dataTypeID: number;
+    tableID?: number | undefined;
+    columnID?: number | undefined;
+    dataTypeSize?: number | undefined;
+    dataTypeModifier?: number | undefined;
+    format?: string | undefined;
+}
+/**
+ * Generic row type for query results
+ */
+export type QueryResultRow = Record<string, unknown>;
+/**
+ * Response from a SQL query
+ */
+export interface QueryResponse<T extends QueryResultRow = QueryResultRow> {
+    rows: T[];
+    fields: QueryField[];
+    rowCount: number;
+    durationMs?: number | undefined;
+}
+/**
+ * Batch query request
+ */
+export interface BatchRequest {
+    queries: QueryRequest[];
+    transaction?: boolean | undefined;
+}
+/**
+ * Batch query response
+ */
+export interface BatchResponse {
+    results: QueryResponse[];
+    durationMs?: number | undefined;
+}
+/**
+ * Transaction isolation levels
+ */
+export type IsolationLevel = 'READ UNCOMMITTED' | 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE';
+/**
+ * Transaction actions
+ */
+export type TransactionAction = 'begin' | 'commit' | 'rollback';
+/**
+ * Transaction request
+ */
+export interface TransactionRequest {
+    action: TransactionAction;
+    transactionId?: string | undefined;
+    isolationLevel?: IsolationLevel | undefined;
+}
+/**
+ * Error response structure
+ */
+export interface ErrorResponse {
+    error: true;
+    code: string;
+    message: string;
+    details?: Record<string, unknown> | undefined;
+}
+/**
+ * WebSocket message types
+ */
+export type WSMessageType = 'query' | 'subscribe' | 'unsubscribe' | 'ping' | 'pong' | 'result' | 'error' | 'change' | 'subscribed' | 'unsubscribed' | 'heartbeat' | 'heartbeat_ack' | 'reconnect' | 'welcome';
+/**
+ * CDC event types
+ */
+export type CDCEventType = 'INSERT' | 'UPDATE' | 'DELETE';
+/**
+ * Subscription payload
+ */
+export interface SubscribePayload {
+    table: string;
+    events?: CDCEventType[] | undefined;
+    filter?: string | undefined;
+}
+/**
+ * Unsubscription payload
+ */
+export interface UnsubscribePayload {
+    subscriptionId: string;
+}
+/**
+ * Change notification payload (CDC)
+ */
+export interface ChangePayload {
+    table: string;
+    operation: CDCEventType;
+    newRow?: QueryResultRow | undefined;
+    oldRow?: QueryResultRow | undefined;
+    timestamp?: number | undefined;
+    /** Subscription ID that matched this change */
+    subscriptionId?: string | undefined;
+    /** Log Sequence Number for ordering */
+    lsn?: string | undefined;
+}
+/**
+ * Heartbeat payload for connection keepalive
+ */
+export interface HeartbeatPayload {
+    /** Timestamp when heartbeat was sent */
+    timestamp: number;
+    /** Server-side sequence number for ordering */
+    seq?: number | undefined;
+}
+/**
+ * Welcome payload sent on initial connection
+ */
+export interface WelcomePayload {
+    /** Connection ID for reconnection */
+    connectionId: string;
+    /** Server timestamp */
+    timestamp: number;
+    /** Heartbeat interval in milliseconds */
+    heartbeatInterval: number;
+    /** Server version */
+    version: string;
+}
+/**
+ * Reconnect payload for restoring subscriptions
+ */
+export interface ReconnectPayload {
+    /** Previous connection ID */
+    connectionId: string;
+    /** Last received LSN for resumption */
+    lastLsn?: string | undefined;
+    /** Subscription IDs to restore */
+    subscriptionIds?: string[] | undefined;
+}
+/**
+ * Subscribed payload confirming subscription
+ */
+export interface SubscribedPayload {
+    /** Generated subscription ID */
+    subscriptionId: string;
+    /** Table being subscribed to */
+    table: string;
+    /** Events being subscribed to */
+    events: CDCEventType[];
+    /** Filter expression if provided */
+    filter?: string | undefined;
+}
+/**
+ * Unsubscribed payload confirming unsubscription
+ */
+export interface UnsubscribedPayload {
+    /** Subscription ID that was removed */
+    subscriptionId: string;
+}
+/**
+ * Error payload
+ */
+export interface ErrorPayload {
+    code: string;
+    message: string;
+    details?: Record<string, unknown> | undefined;
+}
+/**
+ * WebSocket message structure
+ */
+export interface WSMessage {
+    type: WSMessageType;
+    id: string;
+    payload?: QueryRequest | QueryResponse | SubscribePayload | UnsubscribePayload | ChangePayload | ErrorPayload | HeartbeatPayload | WelcomePayload | ReconnectPayload | SubscribedPayload | UnsubscribedPayload | Record<string, unknown> | undefined;
+}
+/**
+ * CDC WebSocket configuration
+ */
+export interface CDCWebSocketConfig {
+    /** Heartbeat interval in milliseconds (default: 30000) */
+    heartbeatInterval?: number;
+    /** Heartbeat timeout - close connection if no response (default: 10000) */
+    heartbeatTimeout?: number;
+    /** Max reconnection attempts (default: 5) */
+    maxReconnectAttempts?: number;
+    /** Reconnection delay in milliseconds (default: 1000) */
+    reconnectDelay?: number;
+    /** Max subscriptions per connection (default: 100) */
+    maxSubscriptions?: number;
+    /** Enable change buffering during reconnection (default: true) */
+    bufferChanges?: boolean;
+    /** Max buffered changes per subscription (default: 1000) */
+    maxBufferedChanges?: number;
+}
+/**
+ * Plugin configuration value - boolean or options object
+ */
+export type PluginValue = boolean | {
+    enabled: boolean;
+    autoCreate?: boolean;
+    config?: Record<string, unknown>;
+};
+/**
+ * Supported plugin names for PostgresDO
+ */
+export type SupportedPlugin = 'vector' | 'pgsearch' | 'postgis' | 'pg_lake' | 'pgmq' | 'pg_trgm' | 'hstore' | 'citext' | 'uuid_ossp' | 'pgcrypto' | 'btree_gin' | 'btree_gist' | 'fuzzystrmatch' | 'intarray' | 'ltree' | 'tablefunc' | 'unaccent';
+/**
+ * PostgreSQL configuration for PGlite
+ */
+export interface PostgresConfig {
+    database: string;
+    extensions?: string[];
+    memoryLimitMB?: number;
+    preserveCase?: boolean;
+    dataDir?: string;
+    debug?: boolean;
+    /** Migration configuration for automatic schema management */
+    migrations?: MigrationConfig;
+    /**
+     * Plugin/extension configuration for PGLite
+     *
+     * Enable extensions using simple flags or configuration objects.
+     * Extensions are loaded during PGLite initialization.
+     *
+     * @example
+     * ```typescript
+     * // Simple boolean flags
+     * plugins: {
+     *   vector: true,
+     *   pg_trgm: true,
+     * }
+     *
+     * // With auto-create option
+     * plugins: {
+     *   vector: { enabled: true, autoCreate: true },
+     *   hstore: { enabled: true, autoCreate: true },
+     * }
+     * ```
+     */
+    plugins?: Partial<Record<SupportedPlugin, PluginValue>>;
+    /**
+     * Injected concerns for dependency injection and testing.
+     * Each concern can be independently instantiated and injected
+     * for modularity and testability.
+     */
+    concerns?: {
+        auth?: unknown;
+        queryExecution?: unknown;
+        cdc?: unknown;
+        storageOrchestration?: unknown;
+    };
+}
+/**
+ * Migration status values
+ */
+export type MigrationStatus = 'pending' | 'applied' | 'failed' | 'rolled_back';
+/**
+ * Individual migration record stored in the migrations table
+ */
+export interface MigrationRecord {
+    /** Migration identifier (e.g., '0001_initial') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Numeric version for ordering */
+    version: number;
+    /** SHA-256 checksum of migration content */
+    checksum: string;
+    /** ISO timestamp when migration was applied */
+    applied_at: string;
+    /** Execution time in milliseconds */
+    execution_time_ms: number;
+    /** Current status of the migration */
+    status: MigrationStatus;
+}
+/**
+ * Schema version metadata for a DO instance
+ */
+export interface SchemaVersion {
+    /** Current schema version number (highest applied migration) */
+    currentVersion: number;
+    /** Total number of applied migrations */
+    appliedCount: number;
+    /** Timestamp of last migration */
+    lastMigrationAt: string | null;
+    /** List of all migration records */
+    migrations: MigrationRecord[];
+}
+/**
+ * Migration input for applying a new migration
+ */
+export interface MigrationInput {
+    /** Migration identifier (e.g., '0001_initial') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Numeric version for ordering */
+    version: number;
+    /** SQL to execute for this migration */
+    sql: string;
+}
+/**
+ * Result of applying a migration
+ */
+export interface MigrationResult {
+    /** Whether the migration was successful */
+    success: boolean;
+    /** Migration ID */
+    id: string;
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+    /** Error message if failed */
+    error?: string;
+    /** Whether this migration was already applied (skipped) */
+    skipped?: boolean;
+}
+/**
+ * Version comparison result
+ */
+export interface VersionComparison {
+    /** Current schema version in the DO */
+    current: number;
+    /** Target version being compared against */
+    target: number;
+    /** Whether the schema needs migration */
+    needsMigration: boolean;
+    /** Number of migrations needed to reach target */
+    pendingCount: number;
+    /** List of missing migration versions */
+    missingVersions: number[];
+}
+/**
+ * Migration progress event for callbacks
+ */
+export interface MigrationProgressEvent {
+    /** The migration being processed */
+    migration: MigrationInput;
+    /** Zero-based index of current migration */
+    index: number;
+    /** Total number of migrations to run */
+    total: number;
+    /** Phase of the migration */
+    phase: 'starting' | 'executing' | 'completed' | 'failed';
+    /** Duration in milliseconds (only set on completion) */
+    durationMs?: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Migration timing strategy
+ *
+ * - 'on-create': Run migrations during DO initialization (default)
+ * - 'on-demand': Defer migrations until first query (lazy migration)
+ */
+export type MigrationStrategy = 'on-create' | 'on-demand';
+/**
+ * Migration state tracked in DO storage
+ */
+export interface MigrationState {
+    /** Current migration status */
+    status: 'pending' | 'in-progress' | 'completed' | 'failed';
+    /** Schema version after migrations */
+    version: number;
+    /** Last migration attempt timestamp (ISO string) */
+    lastAttemptAt?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Duration of last migration run in ms */
+    durationMs?: number;
+}
+/**
+ * Migration configuration for PostgresDO
+ */
+export interface MigrationConfig {
+    /** Migrations to run (will be sorted by version) */
+    migrations: MigrationInput[];
+    /** Callback when migration progress changes */
+    onProgress?: (event: MigrationProgressEvent) => void;
+    /** Timeout for each individual migration in milliseconds (default: 30000) */
+    migrationTimeoutMs?: number;
+    /** Whether to run migrations automatically on first connection (default: true) */
+    autoMigrate?: boolean;
+    /**
+     * Migration timing strategy (default: 'on-create')
+     *
+     * - 'on-create': Run migrations during DO initialization (immediate)
+     * - 'on-demand': Defer migrations until first query (lazy)
+     *
+     * Use 'on-demand' to reduce cold start latency when migrations are expensive.
+     * The first query will incur the migration cost.
+     */
+    strategy?: MigrationStrategy;
+}
+/**
+ * Batch migration result
+ */
+export interface BatchMigrationResult {
+    /** Whether all migrations completed successfully */
+    success: boolean;
+    /** Starting schema version */
+    fromVersion: number;
+    /** Ending schema version */
+    toVersion: number;
+    /** Total duration in milliseconds */
+    durationMs: number;
+    /** Individual migration results */
+    results: MigrationResult[];
+    /** Number of migrations executed */
+    migrationsRun: number;
+    /** Number of migrations skipped (already applied) */
+    migrationsSkipped: number;
+}
+/**
+ * Plugin status information
+ */
+export interface PluginStatus {
+    /** Plugin name */
+    name: string;
+    /** Display name for UI */
+    displayName: string;
+    /** Plugin description */
+    description: string;
+    /** Plugin category */
+    category: string;
+    /** Whether the plugin is available in PGLite WASM */
+    available: boolean;
+    /** Whether the plugin is enabled in configuration */
+    enabled: boolean;
+    /** Whether the extension has been created in the database */
+    created: boolean;
+    /** PostgreSQL extension name */
+    extensionName: string;
+    /** Dependencies on other plugins */
+    dependencies?: string[];
+}
+/**
+ * Response for listing all plugins
+ */
+export interface PluginListResponse {
+    /** All available plugins with their status */
+    plugins: PluginStatus[];
+    /** Number of enabled plugins */
+    enabledCount: number;
+    /** Number of available plugins */
+    availableCount: number;
+    /** Timestamp of the response */
+    timestamp: string;
+}
+/**
+ * Request to enable or disable a plugin
+ */
+export interface PluginToggleRequest {
+    /** Plugin name to enable/disable */
+    name: string;
+    /** Whether to enable or disable */
+    enabled: boolean;
+    /** Whether to auto-create the extension */
+    autoCreate?: boolean;
+}
+/**
+ * Response for plugin toggle operation
+ */
+export interface PluginToggleResponse {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** Plugin name */
+    name: string;
+    /** New enabled state */
+    enabled: boolean;
+    /** Whether the extension was created */
+    created?: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Timestamp of the response */
+    timestamp: string;
+}
+/**
+ * Request to enable multiple plugins
+ */
+export interface PluginBatchToggleRequest {
+    /** Plugins to enable */
+    enable?: string[];
+    /** Plugins to disable */
+    disable?: string[];
+    /** Whether to auto-create enabled extensions */
+    autoCreate?: boolean;
+}
+/**
+ * Response for batch plugin toggle operation
+ */
+export interface PluginBatchToggleResponse {
+    /** Whether all operations were successful */
+    success: boolean;
+    /** Results for each plugin */
+    results: PluginToggleResponse[];
+    /** Timestamp of the response */
+    timestamp: string;
+}
+/**
+ * Memory pressure levels for OOM protection
+ *
+ * - 'normal': Memory usage is within acceptable bounds
+ * - 'warning': Memory usage is elevated, consider reducing allocations
+ * - 'critical': Memory usage is near the limit, take immediate action
+ * - 'oom': Out of memory - operations may fail
+ */
+export type MemoryPressureLevel = 'normal' | 'warning' | 'critical' | 'oom';
+/**
+ * Memory usage statistics
+ */
+export interface MemoryStats {
+    /** Estimated WASM heap size in bytes */
+    heapUsed: number;
+    /** Maximum heap size in bytes (Cloudflare Workers: 128MB) */
+    heapLimit: number;
+    /** Memory usage as a percentage (0-100) */
+    usagePercent: number;
+    /** Current memory pressure level */
+    pressureLevel: MemoryPressureLevel;
+    /** Timestamp of measurement */
+    timestamp: Date;
+}
+/**
+ * Memory pressure event for callbacks
+ */
+export interface MemoryPressureEvent {
+    /** Previous pressure level */
+    previousLevel: MemoryPressureLevel;
+    /** Current pressure level */
+    currentLevel: MemoryPressureLevel;
+    /** Memory statistics at time of event */
+    stats: MemoryStats;
+    /** Actions taken in response to pressure */
+    actionsTaken: MemoryPressureAction[];
+    /** Timestamp of event */
+    timestamp: Date;
+}
+/**
+ * Actions that can be taken under memory pressure
+ */
+export type MemoryPressureAction = 'extension_unloaded' | 'cache_cleared' | 'query_cancelled' | 'gc_triggered' | 'warning_emitted';
+/**
+ * Result of a memory pressure action
+ */
+export interface MemoryPressureActionResult {
+    /** Action type */
+    action: MemoryPressureAction;
+    /** Whether the action was successful */
+    success: boolean;
+    /** Bytes freed (if applicable) */
+    bytesFreed?: number;
+    /** Extension name (if action was extension_unloaded) */
+    extensionName?: string;
+    /** Error message if action failed */
+    error?: string;
+}
+/**
+ * Memory pressure configuration
+ */
+export interface MemoryPressureConfig {
+    /** Enable memory pressure monitoring (default: true) */
+    enabled?: boolean;
+    /** Memory limit in bytes (default: 128MB for Cloudflare Workers) */
+    memoryLimitBytes?: number;
+    /** Warning threshold as percentage (default: 70) */
+    warningThresholdPercent?: number;
+    /** Critical threshold as percentage (default: 85) */
+    criticalThresholdPercent?: number;
+    /** OOM threshold as percentage (default: 95) */
+    oomThresholdPercent?: number;
+    /** How often to check memory pressure in ms (default: 5000) */
+    checkIntervalMs?: number;
+    /** Auto-unload extensions under critical pressure (default: true) */
+    autoUnloadExtensions?: boolean;
+    /** Extensions to prioritize for unloading (lowest priority first) */
+    extensionUnloadPriority?: string[];
+    /** Maximum number of listeners (default: 50) */
+    maxListeners?: number;
+}
+/**
+ * Listener for memory pressure events
+ */
+export type MemoryPressureListener = (event: MemoryPressureEvent) => void;
+/**
+ * Query message - client requests SQL execution
+ */
+export interface WSQueryMessage {
+    type: 'query';
+    id: string;
+    payload: QueryRequest;
+}
+/**
+ * Subscribe message - client subscribes to CDC events
+ */
+export interface WSSubscribeMessage {
+    type: 'subscribe';
+    id: string;
+    payload: SubscribePayload;
+}
+/**
+ * Unsubscribe message - client unsubscribes from CDC events
+ */
+export interface WSUnsubscribeMessage {
+    type: 'unsubscribe';
+    id: string;
+    payload: UnsubscribePayload;
+}
+/**
+ * Ping message - client keepalive
+ */
+export interface WSPingMessage {
+    type: 'ping';
+    id: string;
+    payload?: undefined;
+}
+/**
+ * Pong message - server response to ping
+ */
+export interface WSPongMessage {
+    type: 'pong';
+    id: string;
+    payload?: undefined;
+}
+/**
+ * Result message - server response with query results
+ */
+export interface WSResultMessage {
+    type: 'result';
+    id: string;
+    payload: QueryResponse;
+}
+/**
+ * Error message - server error response
+ */
+export interface WSErrorMessage {
+    type: 'error';
+    id: string;
+    payload: ErrorPayload;
+}
+/**
+ * Change message - CDC change notification
+ */
+export interface WSChangeMessage {
+    type: 'change';
+    id: string;
+    payload: ChangePayload;
+}
+/**
+ * Subscribed message - confirmation of subscription
+ */
+export interface WSSubscribedMessage {
+    type: 'subscribed';
+    id: string;
+    payload: SubscribedPayload;
+}
+/**
+ * Unsubscribed message - confirmation of unsubscription
+ */
+export interface WSUnsubscribedMessage {
+    type: 'unsubscribed';
+    id: string;
+    payload?: UnsubscribedPayload;
+}
+/**
+ * Heartbeat message - server keepalive
+ */
+export interface WSHeartbeatMessage {
+    type: 'heartbeat';
+    id: string;
+    payload?: HeartbeatPayload;
+}
+/**
+ * Heartbeat acknowledgment message - client response to heartbeat
+ */
+export interface WSHeartbeatAckMessage {
+    type: 'heartbeat_ack';
+    id: string;
+    payload?: HeartbeatPayload;
+}
+/**
+ * Reconnect message - client reconnection request
+ */
+export interface WSReconnectMessage {
+    type: 'reconnect';
+    id: string;
+    payload: ReconnectPayload;
+}
+/**
+ * Welcome message - server greeting on connection
+ */
+export interface WSWelcomeMessage {
+    type: 'welcome';
+    id: string;
+    payload: WelcomePayload;
+}
+/**
+ * Discriminated union of all WebSocket message types
+ *
+ * This enables exhaustive switch checking and clean type narrowing:
+ * ```typescript
+ * function handleMessage(msg: WSTypedMessage) {
+ *   switch (msg.type) {
+ *     case 'query':
+ *       // TypeScript knows msg.payload is QueryRequest
+ *       return handleQuery(msg.payload)
+ *     case 'result':
+ *       // TypeScript knows msg.payload is QueryResponse
+ *       return handleResult(msg.payload)
+ *     // ... other cases
+ *   }
+ * }
+ * ```
+ */
+export type WSTypedMessage = WSQueryMessage | WSSubscribeMessage | WSUnsubscribeMessage | WSPingMessage | WSPongMessage | WSResultMessage | WSErrorMessage | WSChangeMessage | WSSubscribedMessage | WSUnsubscribedMessage | WSHeartbeatMessage | WSHeartbeatAckMessage | WSReconnectMessage | WSWelcomeMessage;
+//# sourceMappingURL=types.d.ts.map