@nicnocquee/dataqueue 1.31.0 → 1.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicnocquee/dataqueue",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "description": "PostgreSQL or Redis-backed job queue for Node.js applications with support for serverless environments",
   "type": "module",
   "main": "dist/index.js",

package/src/backend.ts

@@ -9,6 +9,8 @@ import {
   CronScheduleRecord,
   CronScheduleStatus,
   EditCronScheduleOptions,
+  WaitpointRecord,
+  CreateTokenOptions,
 } from './types.js';
 
 /**
@@ -149,11 +151,11 @@ export interface QueueBackend {
     updates: JobUpdates,
   ): Promise<number>;
 
-  /** Delete completed jobs older than N days. Returns count deleted. */
-  cleanupOldJobs(daysToKeep?: number): Promise<number>;
+  /** Delete completed jobs older than N days. Deletes in batches for scale safety. Returns count deleted. */
+  cleanupOldJobs(daysToKeep?: number, batchSize?: number): Promise<number>;
 
-  /** Delete job events older than N days. Returns count deleted. */
-  cleanupOldJobEvents(daysToKeep?: number): Promise<number>;
+  /** Delete job events older than N days. Deletes in batches for scale safety. Returns count deleted. */
+  cleanupOldJobEvents(daysToKeep?: number, batchSize?: number): Promise<number>;
 
   /** Reclaim jobs stuck in 'processing' for too long. Returns count. */
   reclaimStuckJobs(maxProcessingTimeMinutes?: number): Promise<number>;
@@ -222,6 +224,70 @@ export interface QueueBackend {
     nextRunAt: Date | null,
   ): Promise<void>;
 
+  // ── Wait / step-data support ────────────────────────────────────────
+
+  /**
+   * Transition a job from 'processing' to 'waiting' status.
+   * Persists step data so the handler can resume from where it left off.
+   *
+   * @param jobId - The job to pause.
+   * @param options - Wait configuration including optional waitUntil date, token ID, and step data.
+   */
+  waitJob(
+    jobId: number,
+    options: {
+      waitUntil?: Date;
+      waitTokenId?: string;
+      stepData: Record<string, any>;
+    },
+  ): Promise<void>;
+
+  /**
+   * Persist step data for a job. Called after each `ctx.run()` step completes
+   * to save intermediate progress. Best-effort: should not throw.
+   *
+   * @param jobId - The job to update.
+   * @param stepData - The step data to persist.
+   */
+  updateStepData(jobId: number, stepData: Record<string, any>): Promise<void>;
+
+  /**
+   * Create a waitpoint token that can pause a job until an external signal completes it.
+   *
+   * @param jobId - The job ID to associate with the token (null if created outside a handler).
+   * @param options - Optional timeout string (e.g. '10m', '1h') and tags.
+   * @returns The created waitpoint with its unique ID.
+   */
+  createWaitpoint(
+    jobId: number | null,
+    options?: CreateTokenOptions,
+  ): Promise<{ id: string }>;
+
+  /**
+   * Complete a waitpoint token, optionally providing output data.
+   * Moves the associated job from 'waiting' back to 'pending' so it gets picked up.
+   *
+   * @param tokenId - The waitpoint token ID to complete.
+   * @param data - Optional data to pass to the waiting handler.
+   */
+  completeWaitpoint(tokenId: string, data?: any): Promise<void>;
+
+  /**
+   * Retrieve a waitpoint token by its ID.
+   *
+   * @param tokenId - The waitpoint token ID to look up.
+   * @returns The waitpoint record, or null if not found.
+   */
+  getWaitpoint(tokenId: string): Promise<WaitpointRecord | null>;
+
+  /**
+   * Expire timed-out waitpoint tokens and move their associated jobs back to 'pending'.
+   * Should be called periodically (e.g., alongside reclaimStuckJobs).
+   *
+   * @returns The number of tokens that were expired.
+   */
+  expireTimedOutWaitpoints(): Promise<number>;
+
   // ── Internal helpers ──────────────────────────────────────────────────
 
   /** Set a pending reason for unpicked jobs of a given type. */

package/src/backends/postgres.ts

@@ -10,7 +10,10 @@ import {
   CronScheduleRecord,
   CronScheduleStatus,
   EditCronScheduleOptions,
+  WaitpointRecord,
+  CreateTokenOptions,
 } from '../types.js';
+import { randomUUID } from 'crypto';
 import {
   QueueBackend,
   JobFilters,
@@ -19,6 +22,43 @@ import {
 } from '../backend.js';
 import { log } from '../log-context.js';
 
+const MAX_TIMEOUT_MS = 365 * 24 * 60 * 60 * 1000;
+
+/** Parse a timeout string like '10m', '1h', '24h', '7d' into milliseconds. */
+function parseTimeoutString(timeout: string): number {
+  const match = timeout.match(/^(\d+)(s|m|h|d)$/);
+  if (!match) {
+    throw new Error(
+      `Invalid timeout format: "${timeout}". Expected format like "10m", "1h", "24h", "7d".`,
+    );
+  }
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  let ms: number;
+  switch (unit) {
+    case 's':
+      ms = value * 1000;
+      break;
+    case 'm':
+      ms = value * 60 * 1000;
+      break;
+    case 'h':
+      ms = value * 60 * 60 * 1000;
+      break;
+    case 'd':
+      ms = value * 24 * 60 * 60 * 1000;
+      break;
+    default:
+      throw new Error(`Unknown timeout unit: "${unit}"`);
+  }
+  if (!Number.isFinite(ms) || ms > MAX_TIMEOUT_MS) {
+    throw new Error(
+      `Timeout value "${timeout}" is too large. Maximum allowed is 365 days.`,
+    );
+  }
+  return ms;
+}
+
 export class PostgresBackend implements QueueBackend {
   constructor(private pool: Pool) {}
 
@@ -987,46 +1027,93 @@ export class PostgresBackend implements QueueBackend {
     }
   }
 
-  async cleanupOldJobs(daysToKeep = 30): Promise<number> {
-    const client = await this.pool.connect();
+  /**
+   * Delete completed jobs older than the given number of days.
+   * Deletes in batches of 1000 to avoid long-running transactions
+   * and excessive WAL bloat at scale.
+   *
+   * @param daysToKeep - Number of days to retain completed jobs (default 30).
+   * @param batchSize - Number of rows to delete per batch (default 1000).
+   * @returns Total number of deleted jobs.
+   */
+  async cleanupOldJobs(daysToKeep = 30, batchSize = 1000): Promise<number> {
+    let totalDeleted = 0;
+
     try {
-      const result = await client.query(
-        `
-        DELETE FROM job_queue
-        WHERE status = 'completed'
-        AND updated_at < NOW() - INTERVAL '1 day' * $1::int
-        RETURNING id
-      `,
-        [daysToKeep],
-      );
-      log(`Deleted ${result.rowCount} old jobs`);
-      return result.rowCount || 0;
+      let deletedInBatch: number;
+      do {
+        const client = await this.pool.connect();
+        try {
+          const result = await client.query(
+            `
+            DELETE FROM job_queue
+            WHERE id IN (
+              SELECT id FROM job_queue
+              WHERE status = 'completed'
+              AND updated_at < NOW() - INTERVAL '1 day' * $1::int
+              LIMIT $2
+            )
+          `,
+            [daysToKeep, batchSize],
+          );
+          deletedInBatch = result.rowCount || 0;
+          totalDeleted += deletedInBatch;
+        } finally {
+          client.release();
+        }
+      } while (deletedInBatch === batchSize);
+
+      log(`Deleted ${totalDeleted} old jobs`);
+      return totalDeleted;
     } catch (error) {
       log(`Error cleaning up old jobs: ${error}`);
       throw error;
-    } finally {
-      client.release();
     }
   }
 
-  async cleanupOldJobEvents(daysToKeep = 30): Promise<number> {
-    const client = await this.pool.connect();
+  /**
+   * Delete job events older than the given number of days.
+   * Deletes in batches of 1000 to avoid long-running transactions
+   * and excessive WAL bloat at scale.
+   *
+   * @param daysToKeep - Number of days to retain events (default 30).
+   * @param batchSize - Number of rows to delete per batch (default 1000).
+   * @returns Total number of deleted events.
+   */
+  async cleanupOldJobEvents(
+    daysToKeep = 30,
+    batchSize = 1000,
+  ): Promise<number> {
+    let totalDeleted = 0;
+
     try {
-      const result = await client.query(
-        `
-        DELETE FROM job_events
-        WHERE created_at < NOW() - INTERVAL '1 day' * $1::int
-        RETURNING id
-      `,
-        [daysToKeep],
-      );
-      log(`Deleted ${result.rowCount} old job events`);
-      return result.rowCount || 0;
+      let deletedInBatch: number;
+      do {
+        const client = await this.pool.connect();
+        try {
+          const result = await client.query(
+            `
+            DELETE FROM job_events
+            WHERE id IN (
+              SELECT id FROM job_events
+              WHERE created_at < NOW() - INTERVAL '1 day' * $1::int
+              LIMIT $2
+            )
+          `,
+            [daysToKeep, batchSize],
+          );
+          deletedInBatch = result.rowCount || 0;
+          totalDeleted += deletedInBatch;
+        } finally {
+          client.release();
+        }
+      } while (deletedInBatch === batchSize);
+
+      log(`Deleted ${totalDeleted} old job events`);
+      return totalDeleted;
     } catch (error) {
       log(`Error cleaning up old job events: ${error}`);
       throw error;
-    } finally {
-      client.release();
     }
   }
 
@@ -1411,6 +1498,235 @@ export class PostgresBackend implements QueueBackend {
     }
   }
 
+  // ── Wait / step-data support ────────────────────────────────────────
+
+  /**
+   * Transition a job from 'processing' to 'waiting' status.
+   * Persists step data so the handler can resume from where it left off.
+   *
+   * @param jobId - The job to pause.
+   * @param options - Wait configuration including optional waitUntil date, token ID, and step data.
+   */
+  async waitJob(
+    jobId: number,
+    options: {
+      waitUntil?: Date;
+      waitTokenId?: string;
+      stepData: Record<string, any>;
+    },
+  ): Promise<void> {
+    const client = await this.pool.connect();
+    try {
+      const result = await client.query(
+        `
+        UPDATE job_queue
+        SET status = 'waiting',
+            wait_until = $2,
+            wait_token_id = $3,
+            step_data = $4,
+            locked_at = NULL,
+            locked_by = NULL,
+            updated_at = NOW()
+        WHERE id = $1 AND status = 'processing'
+      `,
+        [
+          jobId,
+          options.waitUntil ?? null,
+          options.waitTokenId ?? null,
+          JSON.stringify(options.stepData),
+        ],
+      );
+      if (result.rowCount === 0) {
+        log(
+          `Job ${jobId} could not be set to waiting (may have been reclaimed or is no longer processing)`,
+        );
+        return;
+      }
+      await this.recordJobEvent(jobId, JobEventType.Waiting, {
+        waitUntil: options.waitUntil?.toISOString() ?? null,
+        waitTokenId: options.waitTokenId ?? null,
+      });
+      log(`Job ${jobId} set to waiting`);
+    } catch (error) {
+      log(`Error setting job ${jobId} to waiting: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  /**
+   * Persist step data for a job. Called after each ctx.run() step completes.
+   * Best-effort: does not throw to avoid killing the running handler.
+   *
+   * @param jobId - The job to update.
+   * @param stepData - The step data to persist.
+   */
+  async updateStepData(
+    jobId: number,
+    stepData: Record<string, any>,
+  ): Promise<void> {
+    const client = await this.pool.connect();
+    try {
+      await client.query(
+        `UPDATE job_queue SET step_data = $2, updated_at = NOW() WHERE id = $1`,
+        [jobId, JSON.stringify(stepData)],
+      );
+    } catch (error) {
+      log(`Error updating step_data for job ${jobId}: ${error}`);
+    } finally {
+      client.release();
+    }
+  }
+
+  /**
+   * Create a waitpoint token in the database.
+   *
+   * @param jobId - The job ID to associate with the token (null if created outside a handler).
+   * @param options - Optional timeout string (e.g. '10m', '1h') and tags.
+   * @returns The created waitpoint with its unique ID.
+   */
+  async createWaitpoint(
+    jobId: number | null,
+    options?: CreateTokenOptions,
+  ): Promise<{ id: string }> {
+    const client = await this.pool.connect();
+    try {
+      const id = `wp_${randomUUID()}`;
+      let timeoutAt: Date | null = null;
+
+      if (options?.timeout) {
+        const ms = parseTimeoutString(options.timeout);
+        timeoutAt = new Date(Date.now() + ms);
+      }
+
+      await client.query(
+        `INSERT INTO waitpoints (id, job_id, status, timeout_at, tags) VALUES ($1, $2, 'waiting', $3, $4)`,
+        [id, jobId, timeoutAt, options?.tags ?? null],
+      );
+
+      log(`Created waitpoint ${id} for job ${jobId}`);
+      return { id };
+    } catch (error) {
+      log(`Error creating waitpoint: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  /**
+   * Complete a waitpoint token and move the associated job back to 'pending'.
+   *
+   * @param tokenId - The waitpoint token ID to complete.
+   * @param data - Optional data to pass to the waiting handler.
+   */
+  async completeWaitpoint(tokenId: string, data?: any): Promise<void> {
+    const client = await this.pool.connect();
+    try {
+      await client.query('BEGIN');
+
+      const wpResult = await client.query(
+        `UPDATE waitpoints SET status = 'completed', output = $2, completed_at = NOW()
+         WHERE id = $1 AND status = 'waiting'
+         RETURNING job_id`,
+        [tokenId, data != null ? JSON.stringify(data) : null],
+      );
+
+      if (wpResult.rows.length === 0) {
+        await client.query('ROLLBACK');
+        log(`Waitpoint ${tokenId} not found or already completed`);
+        return;
+      }
+
+      const jobId = wpResult.rows[0].job_id;
+
+      if (jobId != null) {
+        await client.query(
+          `UPDATE job_queue
+           SET status = 'pending', wait_token_id = NULL, wait_until = NULL, updated_at = NOW()
+           WHERE id = $1 AND status = 'waiting'`,
+          [jobId],
+        );
+      }
+
+      await client.query('COMMIT');
+      log(`Completed waitpoint ${tokenId} for job ${jobId}`);
+    } catch (error) {
+      await client.query('ROLLBACK');
+      log(`Error completing waitpoint ${tokenId}: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  /**
+   * Retrieve a waitpoint token by its ID.
+   *
+   * @param tokenId - The waitpoint token ID to look up.
+   * @returns The waitpoint record, or null if not found.
+   */
+  async getWaitpoint(tokenId: string): Promise<WaitpointRecord | null> {
+    const client = await this.pool.connect();
+    try {
+      const result = await client.query(
+        `SELECT id, job_id AS "jobId", status, output, timeout_at AS "timeoutAt", created_at AS "createdAt", completed_at AS "completedAt", tags FROM waitpoints WHERE id = $1`,
+        [tokenId],
+      );
+      if (result.rows.length === 0) return null;
+      return result.rows[0] as WaitpointRecord;
+    } catch (error) {
+      log(`Error getting waitpoint ${tokenId}: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  /**
+   * Expire timed-out waitpoint tokens and move their associated jobs back to 'pending'.
+   *
+   * @returns The number of tokens that were expired.
+   */
+  async expireTimedOutWaitpoints(): Promise<number> {
+    const client = await this.pool.connect();
+    try {
+      await client.query('BEGIN');
+
+      const result = await client.query(
+        `UPDATE waitpoints
+         SET status = 'timed_out'
+         WHERE status = 'waiting' AND timeout_at IS NOT NULL AND timeout_at <= NOW()
+         RETURNING id, job_id`,
+      );
+
+      for (const row of result.rows) {
+        if (row.job_id != null) {
+          await client.query(
+            `UPDATE job_queue
+             SET status = 'pending', wait_token_id = NULL, wait_until = NULL, updated_at = NOW()
+             WHERE id = $1 AND status = 'waiting'`,
+            [row.job_id],
+          );
+        }
+      }
+
+      await client.query('COMMIT');
+      const count = result.rowCount || 0;
+      if (count > 0) {
+        log(`Expired ${count} timed-out waitpoints`);
+      }
+      return count;
+    } catch (error) {
+      await client.query('ROLLBACK');
+      log(`Error expiring timed-out waitpoints: ${error}`);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
   // ── Internal helpers ──────────────────────────────────────────────────
 
   async setPendingReasonForUnpickedJobs(