@checkstack/queue-api 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# @checkstack/queue-api
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+
+## 1.0.1
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+
+## 1.0.0
+
+### Major Changes
+
+- 8e889b4: Add consumer group support to Queue API for distributed event system. BREAKING: consume() now requires ConsumeOptions with consumerGroup parameter.
+
+### Minor Changes
+
+- e4d83fc: Add BullMQ queue plugin with orphaned job cleanup
+
+  - **queue-api**: Added `listRecurringJobs()` method to Queue interface for detecting orphaned jobs
+  - **queue-bullmq-backend**: New plugin implementing BullMQ (Redis) queue backend with job schedulers, consumer groups, and distributed job persistence
+  - **queue-bullmq-common**: New common package with queue permissions
+  - **queue-memory-backend**: Implemented `listRecurringJobs()` for in-memory queue
+  - **healthcheck-backend**: Enhanced `bootstrapHealthChecks` to clean up orphaned job schedulers using `listRecurringJobs()`
+  - **test-utils-backend**: Added `listRecurringJobs()` to mock queue factory
+
+  This enables production-ready distributed queue processing with Redis persistence and automatic cleanup of orphaned jobs when health checks are deleted.
+
+### Patch Changes
+
+- 81f3f85: ## Breaking: Unified Versioned<T> Architecture
+
+  Refactored the versioning system to use a unified `Versioned<T>` class instead of separate `VersionedSchema`, `VersionedData`, and `VersionedConfig` types.
+
+  ### Breaking Changes
+
+  - **`VersionedSchema<T>`** is replaced by `Versioned<T>` class
+  - **`VersionedData<T>`** is replaced by `VersionedRecord<T>` interface
+  - **`VersionedConfig<T>`** is replaced by `VersionedPluginRecord<T>` interface
+  - **`ConfigMigration<F, T>`** is replaced by `Migration<F, T>` interface
+  - **`MigrationChain<T>`** is removed (use `Migration<unknown, unknown>[]`)
+  - **`migrateVersionedData()`** is removed (use `versioned.parse()`)
+  - **`ConfigMigrationRunner`** is removed (migrations are internal to Versioned)
+
+  ### Migration Guide
+
+  Before:
+
+  ```typescript
+  const strategy: HealthCheckStrategy = {
+    config: {
+      version: 1,
+      schema: mySchema,
+      migrations: [],
+    },
+  };
+  const data = await migrateVersionedData(stored, 1, migrations);
+  ```
+
+  After:
+
+  ```typescript
+  const strategy: HealthCheckStrategy = {
+    config: new Versioned({
+      version: 1,
+      schema: mySchema,
+      migrations: [],
+    }),
+  };
+  const data = await strategy.config.parse(stored);
+  ```
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/backend-api@1.0.0

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@checkstack/queue-api",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./queue";
+export * from "./queue-plugin";

package/src/queue-plugin.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import type { Queue } from "./queue";
+import type { Migration } from "@checkstack/backend-api";
+
+export interface QueuePlugin<Config = unknown> {
+  id: string;
+  displayName: string;
+  description?: string;
+
+  /** Current version of the configuration schema */
+  configVersion: number;
+
+  /** Validation schema for the plugin-specific config */
+  configSchema: z.ZodType<Config>;
+
+  /** Optional migrations for backward compatibility */
+  migrations?: Migration<unknown, unknown>[];
+
+  createQueue<T>(name: string, config: Config): Queue<T>;
+}
+
+export interface QueuePluginRegistry {
+  register(plugin: QueuePlugin<unknown>): void;
+  getPlugin(id: string): QueuePlugin<unknown> | undefined;
+  getPlugins(): QueuePlugin<unknown>[];
+}
+
+/**
+ * Result of switching queue backends
+ */
+export interface SwitchResult {
+  success: boolean;
+  migratedRecurringJobs: number;
+  warnings: string[];
+}
+
+/**
+ * Info about a recurring job across all queues
+ */
+export interface RecurringJobInfo {
+  queueName: string;
+  jobId: string;
+  intervalSeconds: number;
+  nextRunAt?: Date;
+}
+
+/**
+ * QueueManager handles queue creation, backend switching, and multi-instance coordination.
+ *
+ * Key features:
+ * - Returns stable QueueProxy instances that survive backend switches
+ * - Polls config for changes to support multi-instance coordination
+ * - Handles graceful migration of recurring jobs when switching backends
+ */
+export interface QueueManager {
+  /**
+   * Get or create a queue proxy.
+   * Returns a stable reference that survives backend switches.
+   * Subscriptions are automatically re-applied when backend changes.
+   */
+  getQueue<T>(name: string): Queue<T>;
+
+  /**
+   * Get the currently active queue plugin ID
+   */
+  getActivePlugin(): string;
+
+  /**
+   * Get the currently active queue plugin configuration
+   */
+  getActiveConfig(): unknown;
+
+  /**
+   * Switch to a different queue backend with job migration.
+   *
+   * @throws Error if connection test fails
+   * @throws Error if migration fails
+   */
+  setActiveBackend(pluginId: string, config: unknown): Promise<SwitchResult>;
+
+  /**
+   * Get total number of in-flight jobs across all queues.
+   * Used to warn users before switching backends.
+   */
+  getInFlightJobCount(): Promise<number>;
+
+  /**
+   * List all recurring jobs across all queues.
+   * Used for migration preview.
+   */
+  listAllRecurringJobs(): Promise<RecurringJobInfo[]>;
+
+  /**
+   * Start polling for configuration changes.
+   * Required for multi-instance coordination.
+   * @param intervalMs - Polling interval in milliseconds (default: 5000)
+   */
+  startPolling(intervalMs?: number): void;
+
+  /**
+   * Stop polling and gracefully shutdown all queues.
+   */
+  shutdown(): Promise<void>;
+}

package/src/queue.ts

@@ -0,0 +1,160 @@
+export interface QueueJob<T = unknown> {
+  id: string;
+  data: T;
+  priority?: number;
+  timestamp: Date;
+  /**
+   * Number of processing attempts (for retry logic)
+   */
+  attempts?: number;
+}
+
+/**
+ * Details of a recurring job for migration purposes
+ */
+export interface RecurringJobDetails<T = unknown> {
+  jobId: string;
+  data: T;
+  intervalSeconds: number;
+  priority?: number;
+  nextRunAt?: Date;
+}
+
+export interface QueueConsumer<T = unknown> {
+  (job: QueueJob<T>): Promise<void>;
+}
+
+export interface ConsumeOptions {
+  /**
+   * Consumer group ID for load balancing.
+   *
+   * Messages are distributed across consumers in the same group (competing consumers).
+   * Each consumer group receives a copy of each message (broadcast).
+   *
+   * Example:
+   * - Same group ID = work queue (only one consumer per group gets the message)
+   * - Unique group ID per instance = broadcast (all instances get the message)
+   */
+  consumerGroup: string;
+
+  /**
+   * Maximum retry attempts on failure
+   * @default 3
+   */
+  maxRetries?: number;
+}
+
+export interface Queue<T = unknown> {
+  /**
+   * Enqueue a job for processing
+   */
+  enqueue(
+    data: T,
+    options?: {
+      priority?: number;
+      /**
+       * Delay in seconds before the job becomes available for processing
+       * Queue backends should not make this job available until the delay expires
+       */
+      startDelay?: number;
+      /**
+       * Optional unique job ID for deduplication
+       * If provided and a job with this ID already exists, behavior depends on queue implementation
+       */
+      jobId?: string;
+    }
+  ): Promise<string>;
+
+  /**
+   * Register a consumer to process jobs
+   *
+   * BREAKING CHANGE: Now requires ConsumeOptions with consumerGroup
+   */
+  consume(consumer: QueueConsumer<T>, options: ConsumeOptions): Promise<void>;
+
+  /**
+   * Schedule a recurring job that executes at regular intervals.
+   *
+   * UPDATE SEMANTICS: Calling this method with an existing jobId will UPDATE
+   * the recurring job configuration (interval, payload, priority, etc.).
+   * The queue implementation MUST:
+   * 1. Cancel any pending scheduled execution of the old job
+   * 2. Apply the new configuration
+   * 3. Schedule the next execution with the new startDelay (or immediately if not provided)
+   *
+   * @param data - Job payload
+   * @param options - Recurring job options
+   * @returns Job ID
+   */
+  scheduleRecurring(
+    data: T,
+    options: {
+      /**
+       * Unique job ID for deduplication and updates.
+       * Calling scheduleRecurring with the same jobId updates the existing job.
+       */
+      jobId: string;
+      /** Interval in seconds between executions */
+      intervalSeconds: number;
+      /** Optional delay before first execution (for delta-based scheduling) */
+      startDelay?: number;
+      /** Optional priority */
+      priority?: number;
+    }
+  ): Promise<string>;
+
+  /**
+   * Cancel a recurring job
+   * @param jobId - Job ID to cancel
+   */
+  cancelRecurring(jobId: string): Promise<void>;
+
+  /**
+   * List all recurring job IDs
+   * Used for reconciliation to detect orphaned jobs
+   * @returns Array of job IDs for all recurring jobs
+   */
+  listRecurringJobs(): Promise<string[]>;
+
+  /**
+   * Get details of a recurring job for migration purposes
+   * @param jobId - Job ID
+   * @returns Job details or undefined if not found
+   */
+  getRecurringJobDetails(
+    jobId: string
+  ): Promise<RecurringJobDetails<T> | undefined>;
+
+  /**
+   * Get the number of jobs currently being processed
+   * Used to warn users before switching backends
+   */
+  getInFlightCount(): Promise<number>;
+
+  /**
+   * Test connection to the queue backend
+   * @throws Error if connection fails
+   */
+  testConnection(): Promise<void>;
+
+  /**
+   * Stop consuming jobs and cleanup
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Get queue statistics
+   */
+  getStats(): Promise<QueueStats>;
+}
+
+export interface QueueStats {
+  pending: number;
+  processing: number;
+  completed: number;
+  failed: number;
+  /**
+   * Number of active consumer groups
+   */
+  consumerGroups: number;
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}