@sprqvntrs/workflows 0.2.4

package/src/infrastructure/pgboss-queries.ts

@@ -0,0 +1,320 @@
+/**
+ * pg-boss introspection queries.
+ *
+ * This module provides utility functions for querying pg-boss internal tables
+ * directly, useful for debugging, monitoring, and administration without
+ * needing a separate database client.
+ *
+ * @example
+ * ```typescript
+ * import { createPgBossQueries } from '@sprqvntrs/workflows';
+ * import { Pool } from 'pg';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const queries = createPgBossQueries(pool);
+ *
+ * // Get job statistics
+ * const stats = await queries.getJobStats();
+ * console.log(stats);
+ *
+ * // Get all schedules
+ * const schedules = await queries.getSchedules();
+ *
+ * // Get recent job history for specific queues
+ * const history = await queries.getJobHistory(['content-generation', 'data-sync']);
+ * ```
+ */
+
+import type { Pool, PoolClient } from 'pg';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * pg-boss job states.
+ */
+export type PgBossJobState = 'created' | 'active' | 'retry' | 'completed' | 'failed' | 'cancelled';
+
+/**
+ * pg-boss archive job states (terminal states).
+ */
+export type PgBossArchiveState = 'completed' | 'failed' | 'expired' | 'cancelled';
+
+/**
+ * Simplified job item from pgboss.job table.
+ */
+export interface PgBossJobItem {
+  id: string;
+  name: string;
+  state: PgBossJobState;
+}
+
+/**
+ * Job statistics grouped by queue name and state.
+ */
+export interface PgBossJobStats {
+  name: string;
+  state: PgBossJobState;
+  count: number;
+}
+
+/**
+ * Schedule item from pgboss.schedule table.
+ */
+export interface PgBossScheduleItem {
+  name: string;
+  cron: string;
+  timezone: string | null;
+  data: Record<string, unknown> | null;
+  created_on: Date;
+  updated_on: Date;
+}
+
+/**
+ * Archive item from pgboss.archive table.
+ */
+export interface PgBossArchiveItem {
+  id: string;
+  name: string;
+  state: PgBossArchiveState;
+  output: Record<string, unknown> | null;
+  completed_on: Date;
+}
+
+/**
+ * Result of deleting workflow jobs.
+ */
+export interface DeleteWorkflowJobsResult {
+  cancelledCount: number;
+  deletedCount: number;
+}
+
+/**
+ * Result of deleting or cancelling pending jobs.
+ */
+export interface PendingJobsResult {
+  count: number;
+}
+
+/**
+ * pg-boss query interface.
+ */
+export interface PgBossQueries {
+  /**
+   * Gets all jobs from pgboss.job table.
+   * Returns simplified job items with id, name, and state.
+   */
+  getJobs: () => Promise<PgBossJobItem[]>;
+
+  /**
+   * Gets job statistics grouped by queue name and state.
+   * Useful for monitoring job distribution across queues.
+   */
+  getJobStats: () => Promise<PgBossJobStats[]>;
+
+  /**
+   * Gets all schedules from pgboss.schedule table.
+   * Returns schedules sorted by creation time (newest first).
+   */
+  getSchedules: () => Promise<PgBossScheduleItem[]>;
+
+  /**
+   * Gets job history from pgboss.archive for given queue names.
+   * Returns up to 50 most recent archived jobs.
+   *
+   * @param names - Queue names to filter by
+   */
+  getJobHistory: (names: string[]) => Promise<PgBossArchiveItem[]>;
+
+  /**
+   * Cancels and deletes all jobs associated with a workflow ID.
+   * Searches jobs where data.workflowId matches the given ID.
+   *
+   * @param workflowId - Workflow ID to cancel/delete jobs for
+   */
+  deleteWorkflowJobs: (workflowId: string) => Promise<DeleteWorkflowJobsResult>;
+
+  /**
+   * Deletes all pending jobs (state = 'created').
+   * Optionally filter by queue name.
+   *
+   * @param queueName - Optional queue name to filter by
+   */
+  deletePendingJobs: (queueName?: string) => Promise<PendingJobsResult>;
+
+  /**
+   * Cancels all pending jobs (state = 'created') by setting state to 'cancelled'.
+   * Jobs remain in the database but won't be processed.
+   * Optionally filter by queue name.
+   *
+   * @param queueName - Optional queue name to filter by
+   */
+  cancelPendingJobs: (queueName?: string) => Promise<PendingJobsResult>;
+
+  /**
+   * Purges all jobs in a specific state.
+   * WARNING: This permanently deletes jobs.
+   *
+   * @param state - Job state to purge
+   * @param queueName - Optional queue name to filter by
+   */
+  purgeJobsByState: (state: PgBossJobState, queueName?: string) => Promise<PendingJobsResult>;
+}
+
+/**
+ * Configuration for pg-boss queries.
+ */
+export interface PgBossQueriesConfig {
+  /**
+   * pg-boss schema name.
+   * @default 'pgboss'
+   */
+  schema?: string;
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/**
+ * Creates a pg-boss queries instance.
+ *
+ * Provides utility functions for introspecting pg-boss internal tables
+ * directly via raw SQL queries. Useful for debugging and monitoring.
+ *
+ * @param pool - PostgreSQL connection pool
+ * @param config - Optional configuration
+ * @returns pg-boss queries interface
+ *
+ * @example
+ * ```typescript
+ * import { createPgBossQueries } from '@sprqvntrs/workflows';
+ * import { Pool } from 'pg';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const queries = createPgBossQueries(pool);
+ *
+ * // Monitor active jobs
+ * const stats = await queries.getJobStats();
+ * const activeJobs = stats.filter(s => s.state === 'active');
+ * console.log('Active jobs by queue:', activeJobs);
+ *
+ * // Check schedules
+ * const schedules = await queries.getSchedules();
+ * console.log('Configured schedules:', schedules.map(s => s.name));
+ *
+ * // View recent failures for a queue
+ * const history = await queries.getJobHistory(['my-workflow-queue']);
+ * const failures = history.filter(h => h.state === 'failed');
+ * console.log('Recent failures:', failures);
+ *
+ * // Clean up jobs for a cancelled workflow
+ * const result = await queries.deleteWorkflowJobs('workflow-123');
+ * console.log(`Cancelled ${result.cancelledCount}, deleted ${result.deletedCount} jobs`);
+ * ```
+ */
+export function createPgBossQueries(
+  pool: Pool | PoolClient,
+  config?: PgBossQueriesConfig,
+): PgBossQueries {
+  const schema = config?.schema ?? 'pgboss';
+
+  return {
+    async getJobs(): Promise<PgBossJobItem[]> {
+      const result = await pool.query<PgBossJobItem>(
+        `SELECT id, name, state FROM ${schema}.job ORDER BY createdon DESC`,
+      );
+      return result.rows;
+    },
+
+    async getJobStats(): Promise<PgBossJobStats[]> {
+      const result = await pool.query<PgBossJobStats>(
+        `SELECT name, state, COUNT(*)::int as count
+         FROM ${schema}.job
+         GROUP BY name, state
+         ORDER BY name, state`,
+      );
+      return result.rows;
+    },
+
+    async getSchedules(): Promise<PgBossScheduleItem[]> {
+      const result = await pool.query<PgBossScheduleItem>(
+        `SELECT name, cron, timezone, data, created_on, updated_on
+         FROM ${schema}.schedule
+         ORDER BY created_on DESC`,
+      );
+      return result.rows;
+    },
+
+    async getJobHistory(names: string[]): Promise<PgBossArchiveItem[]> {
+      if (names.length === 0) {
+        return [];
+      }
+
+      const result = await pool.query<PgBossArchiveItem>(
+        `SELECT id, name, state, output, completedon as completed_on
+         FROM ${schema}.archive
+         WHERE name = ANY($1::text[])
+         ORDER BY completedon DESC
+         LIMIT 50`,
+        [names],
+      );
+      return result.rows;
+    },
+
+    async deleteWorkflowJobs(workflowId: string): Promise<DeleteWorkflowJobsResult> {
+      // Cancel active/pending jobs for this workflow
+      const cancelResult = await pool.query(
+        `UPDATE ${schema}.job
+         SET state = 'cancelled'
+         WHERE data::jsonb ? 'workflowId'
+         AND (data::jsonb->>'workflowId') = $1
+         AND state NOT IN ('completed', 'failed', 'cancelled')
+         RETURNING id`,
+        [workflowId],
+      );
+
+      // Delete all jobs for this workflow (including completed/failed ones)
+      const deleteResult = await pool.query(
+        `DELETE FROM ${schema}.job
+         WHERE data::jsonb ? 'workflowId'
+         AND (data::jsonb->>'workflowId') = $1
+         RETURNING id`,
+        [workflowId],
+      );
+
+      return {
+        cancelledCount: cancelResult.rowCount ?? 0,
+        deletedCount: deleteResult.rowCount ?? 0,
+      };
+    },
+
+    async deletePendingJobs(queueName?: string): Promise<PendingJobsResult> {
+      const query = queueName
+        ? `DELETE FROM ${schema}.job WHERE state = 'created' AND name = $1 RETURNING id`
+        : `DELETE FROM ${schema}.job WHERE state = 'created' RETURNING id`;
+
+      const result = await pool.query(query, queueName ? [queueName] : []);
+      return { count: result.rowCount ?? 0 };
+    },
+
+    async cancelPendingJobs(queueName?: string): Promise<PendingJobsResult> {
+      const query = queueName
+        ? `UPDATE ${schema}.job SET state = 'cancelled' WHERE state = 'created' AND name = $1 RETURNING id`
+        : `UPDATE ${schema}.job SET state = 'cancelled' WHERE state = 'created' RETURNING id`;
+
+      const result = await pool.query(query, queueName ? [queueName] : []);
+      return { count: result.rowCount ?? 0 };
+    },
+
+    async purgeJobsByState(state: PgBossJobState, queueName?: string): Promise<PendingJobsResult> {
+      const query = queueName
+        ? `DELETE FROM ${schema}.job WHERE state = $1 AND name = $2 RETURNING id`
+        : `DELETE FROM ${schema}.job WHERE state = $1 RETURNING id`;
+
+      const result = await pool.query(query, queueName ? [state, queueName] : [state]);
+      return { count: result.rowCount ?? 0 };
+    },
+  };
+}

package/src/infrastructure/schema.ts

@@ -0,0 +1,342 @@
+/**
+ * Drizzle ORM schema for workflow orchestration.
+ *
+ * This module exports the database schema required for workflow persistence.
+ * Import this schema into your application's Drizzle configuration.
+ *
+ * @example
+ * ```typescript
+ * // In your drizzle schema file
+ * import { workflows, workflowOperations, workflowLocks } from '@sprqvntrs/workflows/schema';
+ *
+ * export { workflows, workflowOperations, workflowLocks };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Running migrations
+ * // Add these tables to your Drizzle migrations
+ * ```
+ */
+
+import { pgTable, uuid, text, timestamp, jsonb, integer, unique, index } from 'drizzle-orm/pg-core';
+
+// =============================================================================
+// Workflows Table
+// =============================================================================
+
+/**
+ * Main workflows table storing workflow instances.
+ *
+ * Each row represents a single workflow execution with its current state
+ * and accumulated context from completed operations.
+ *
+ * @remarks
+ * The `context` column stores a JSONB object that grows as operations complete.
+ * Consider monitoring context size for workflows with many operations.
+ */
+export const workflows = pgTable(
+  'workflows',
+  {
+    /**
+     * Unique identifier for the workflow instance.
+     */
+    id: uuid('id').primaryKey().defaultRandom(),
+
+    /**
+     * Workflow type matching a registered template.
+     * @example 'content-generation', 'data-processing'
+     */
+    type: text('type').notNull(),
+
+    /**
+     * Current workflow status.
+     * @see WorkflowStatus type for possible values
+     */
+    status: text('status').notNull().default('pending'),
+
+    /**
+     * Accumulated workflow context (initial + operation results).
+     * This JSONB column stores all data flowing through the workflow.
+     */
+    context: jsonb('context').notNull().default({}),
+
+    /**
+     * Currently executing stage name.
+     * Null when workflow hasn't started or is completed.
+     */
+    currentStage: text('current_stage'),
+
+    /**
+     * Checkpoint status when workflow is paused.
+     * Used by UI to display appropriate actions.
+     * @example 'data_ready', 'content_review', 'approval_pending'
+     */
+    checkpointStatus: text('checkpoint_status'),
+
+    /**
+     * Error message if workflow failed.
+     * Contains the error that caused terminal failure.
+     */
+    errorMessage: text('error_message'),
+
+    /**
+     * Template version used for this workflow.
+     * Useful for debugging and migration.
+     */
+    templateVersion: text('template_version').notNull(),
+
+    /**
+     * When the workflow record was created.
+     */
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+
+    /**
+     * When workflow execution actually started.
+     * Set when worker picks up the job.
+     */
+    startedAt: timestamp('started_at', { withTimezone: true }),
+
+    /**
+     * When workflow completed (success, failure, or cancellation).
+     */
+    completedAt: timestamp('completed_at', { withTimezone: true }),
+
+    /**
+     * pg-boss job ID for this workflow.
+     * Used to correlate with job queue.
+     */
+    jobId: text('job_id'),
+  },
+  (table) => [
+    /**
+     * Index for querying workflows by status.
+     * Common query: find all active/pending workflows.
+     */
+    index('workflows_status_idx').on(table.status),
+
+    /**
+     * Index for querying workflows by type.
+     * Common query: find all workflows of a specific type.
+     */
+    index('workflows_type_idx').on(table.type),
+
+    /**
+     * Index for querying workflows by creation time.
+     * Common query: find recent workflows.
+     */
+    index('workflows_created_at_idx').on(table.createdAt),
+
+    /**
+     * Composite index for filtering by type and status.
+     * Common query: find active workflows of a specific type.
+     */
+    index('workflows_type_status_idx').on(table.type, table.status),
+  ],
+);
+
+// =============================================================================
+// Workflow Operations Table
+// =============================================================================
+
+/**
+ * Operations table storing individual operation executions.
+ *
+ * Each row represents a single operation within a workflow stage.
+ * Operations track their own status, results, and retry attempts.
+ */
+export const workflowOperations = pgTable(
+  'workflow_operations',
+  {
+    /**
+     * Unique identifier for the operation instance.
+     */
+    id: uuid('id').primaryKey().defaultRandom(),
+
+    /**
+     * Parent workflow ID.
+     * References the workflows table.
+     */
+    workflowId: uuid('workflow_id')
+      .notNull()
+      .references(() => workflows.id, { onDelete: 'cascade' }),
+
+    /**
+     * Operation type matching a registered handler.
+     * @example 'gather.data', 'analyze.content'
+     */
+    type: text('type').notNull(),
+
+    /**
+     * Stage name this operation belongs to.
+     */
+    stage: text('stage').notNull(),
+
+    /**
+     * Current operation status.
+     * @see OperationStatus type for possible values
+     */
+    status: text('status').notNull().default('pending'),
+
+    /**
+     * Operation result data (on success).
+     * This data gets merged into the workflow context.
+     */
+    result: jsonb('result'),
+
+    /**
+     * Error message if operation failed.
+     */
+    errorMessage: text('error_message'),
+
+    /**
+     * Current attempt count (1-indexed).
+     */
+    attempts: integer('attempts').notNull().default(0),
+
+    /**
+     * Maximum allowed attempts.
+     */
+    maxAttempts: integer('max_attempts').notNull().default(3),
+
+    /**
+     * When the operation record was created.
+     */
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+
+    /**
+     * When operation execution started.
+     */
+    startedAt: timestamp('started_at', { withTimezone: true }),
+
+    /**
+     * When operation completed (success or failure).
+     */
+    completedAt: timestamp('completed_at', { withTimezone: true }),
+  },
+  (table) => [
+    /**
+     * Index for querying operations by workflow.
+     * Common query: get all operations for a workflow.
+     */
+    index('workflow_operations_workflow_id_idx').on(table.workflowId),
+
+    /**
+     * Index for querying operations by status.
+     * Common query: find pending operations.
+     */
+    index('workflow_operations_status_idx').on(table.status),
+
+    /**
+     * Composite index for finding operations by workflow and stage.
+     * Common query: get operations for a specific stage.
+     */
+    index('workflow_operations_workflow_stage_idx').on(table.workflowId, table.stage),
+  ],
+);
+
+// =============================================================================
+// Workflow Locks Table
+// =============================================================================
+
+/**
+ * Locks table for coordination and race condition prevention.
+ *
+ * Uses database unique constraints to ensure only one workflow
+ * can hold a lock on a given entity at a time.
+ *
+ * @remarks
+ * Lock acquisition is done via INSERT. If insert fails due to unique
+ * constraint violation, another workflow holds the lock.
+ */
+export const workflowLocks = pgTable(
+  'workflow_locks',
+  {
+    /**
+     * Unique identifier for the lock.
+     */
+    id: uuid('id').primaryKey().defaultRandom(),
+
+    /**
+     * Type of entity being locked.
+     * @example 'document', 'user', 'order'
+     */
+    entityType: text('entity_type').notNull(),
+
+    /**
+     * ID of the entity being locked.
+     */
+    entityId: text('entity_id').notNull(),
+
+    /**
+     * Workflow holding this lock.
+     */
+    workflowId: uuid('workflow_id')
+      .notNull()
+      .references(() => workflows.id, { onDelete: 'cascade' }),
+
+    /**
+     * When the lock was acquired.
+     */
+    acquiredAt: timestamp('acquired_at', { withTimezone: true }).notNull().defaultNow(),
+
+    /**
+     * Optional lock expiration time.
+     * Allows stale locks to be cleaned up.
+     */
+    expiresAt: timestamp('expires_at', { withTimezone: true }),
+  },
+  (table) => [
+    /**
+     * Unique constraint ensuring only one lock per entity.
+     * This is the core mechanism for mutual exclusion.
+     */
+    unique('workflow_locks_entity_unique').on(table.entityType, table.entityId),
+
+    /**
+     * Index for finding locks by workflow.
+     * Used during workflow cleanup.
+     */
+    index('workflow_locks_workflow_id_idx').on(table.workflowId),
+
+    /**
+     * Index for finding expired locks.
+     * Used by lock cleanup job.
+     */
+    index('workflow_locks_expires_at_idx').on(table.expiresAt),
+  ],
+);
+
+// =============================================================================
+// Type Exports for Drizzle
+// =============================================================================
+
+/**
+ * TypeScript type for workflow table row.
+ */
+export type Workflow = typeof workflows.$inferSelect;
+
+/**
+ * TypeScript type for workflow insert.
+ */
+export type NewWorkflow = typeof workflows.$inferInsert;
+
+/**
+ * TypeScript type for operation table row.
+ */
+export type WorkflowOperation = typeof workflowOperations.$inferSelect;
+
+/**
+ * TypeScript type for operation insert.
+ */
+export type NewWorkflowOperation = typeof workflowOperations.$inferInsert;
+
+/**
+ * TypeScript type for lock table row.
+ */
+export type WorkflowLock = typeof workflowLocks.$inferSelect;
+
+/**
+ * TypeScript type for lock insert.
+ */
+export type NewWorkflowLock = typeof workflowLocks.$inferInsert;