@nicnocquee/dataqueue 1.19.3 → 1.21.0

package/src/queue.ts

@@ -5,6 +5,7 @@ import {
   FailureReason,
   JobEvent,
   JobEventType,
+  TagQueryMode,
 } from './types.js';
 import { log } from './log-context.js';
 
@@ -43,6 +44,7 @@ export const addJob = async <PayloadMap, T extends keyof PayloadMap & string>(
     priority = 0,
     runAt = null,
     timeoutMs = undefined,
+    tags = undefined,
   }: JobOptions<PayloadMap, T>,
 ): Promise<number> => {
   const client = await pool.connect();
@@ -51,29 +53,45 @@ export const addJob = async <PayloadMap, T extends keyof PayloadMap & string>(
     if (runAt) {
       result = await client.query(
         `INSERT INTO job_queue 
-          (job_type, payload, max_attempts, priority, run_at, timeout_ms) 
-         VALUES ($1, $2, $3, $4, $5, $6) 
+          (job_type, payload, max_attempts, priority, run_at, timeout_ms, tags) 
+         VALUES ($1, $2, $3, $4, $5, $6, $7) 
          RETURNING id`,
-        [jobType, payload, maxAttempts, priority, runAt, timeoutMs ?? null],
+        [
+          jobType,
+          payload,
+          maxAttempts,
+          priority,
+          runAt,
+          timeoutMs ?? null,
+          tags ?? null,
+        ],
       );
       log(
-        `Added job ${result.rows[0].id}: payload ${JSON.stringify(payload)}, runAt ${runAt.toISOString()}, priority ${priority}, maxAttempts ${maxAttempts} jobType ${jobType}`,
+        `Added job ${result.rows[0].id}: payload ${JSON.stringify(payload)}, runAt ${runAt.toISOString()}, priority ${priority}, maxAttempts ${maxAttempts} jobType ${jobType}, tags ${JSON.stringify(tags)}`,
       );
     } else {
       result = await client.query(
         `INSERT INTO job_queue 
-          (job_type, payload, max_attempts, priority, timeout_ms) 
-         VALUES ($1, $2, $3, $4, $5) 
+          (job_type, payload, max_attempts, priority, timeout_ms, tags) 
+         VALUES ($1, $2, $3, $4, $5, $6) 
          RETURNING id`,
-        [jobType, payload, maxAttempts, priority, timeoutMs ?? null],
+        [
+          jobType,
+          payload,
+          maxAttempts,
+          priority,
+          timeoutMs ?? null,
+          tags ?? null,
+        ],
       );
       log(
-        `Added job ${result.rows[0].id}: payload ${JSON.stringify(payload)}, priority ${priority}, maxAttempts ${maxAttempts} jobType ${jobType}`,
+        `Added job ${result.rows[0].id}: payload ${JSON.stringify(payload)}, priority ${priority}, maxAttempts ${maxAttempts} jobType ${jobType}, tags ${JSON.stringify(tags)}`,
       );
     }
     await recordJobEvent(pool, result.rows[0].id, JobEventType.Added, {
       jobType,
       payload,
+      tags,
     });
     return result.rows[0].id;
   } catch (error) {
@@ -400,7 +418,12 @@ export const cancelJob = async (pool: Pool, jobId: number): Promise<void> => {
  */
 export const cancelAllUpcomingJobs = async (
   pool: Pool,
-  filters?: { jobType?: string; priority?: number; runAt?: Date },
+  filters?: {
+    jobType?: string;
+    priority?: number;
+    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
+    tags?: { values: string[]; mode?: TagQueryMode };
+  },
 ): Promise<number> => {
   const client = await pool.connect();
   try {
@@ -420,8 +443,61 @@ export const cancelAllUpcomingJobs = async (
         params.push(filters.priority);
       }
       if (filters.runAt) {
-        query += ` AND run_at = $${paramIdx++}`;
-        params.push(filters.runAt);
+        if (filters.runAt instanceof Date) {
+          query += ` AND run_at = $${paramIdx++}`;
+          params.push(filters.runAt);
+        } else if (typeof filters.runAt === 'object') {
+          const ops = filters.runAt;
+          if (ops.gt) {
+            query += ` AND run_at > $${paramIdx++}`;
+            params.push(ops.gt);
+          }
+          if (ops.gte) {
+            query += ` AND run_at >= $${paramIdx++}`;
+            params.push(ops.gte);
+          }
+          if (ops.lt) {
+            query += ` AND run_at < $${paramIdx++}`;
+            params.push(ops.lt);
+          }
+          if (ops.lte) {
+            query += ` AND run_at <= $${paramIdx++}`;
+            params.push(ops.lte);
+          }
+          if (ops.eq) {
+            query += ` AND run_at = $${paramIdx++}`;
+            params.push(ops.eq);
+          }
+        }
+      }
+      if (
+        filters.tags &&
+        filters.tags.values &&
+        filters.tags.values.length > 0
+      ) {
+        const mode = filters.tags.mode || 'all';
+        const tagValues = filters.tags.values;
+        switch (mode) {
+          case 'exact':
+            query += ` AND tags = $${paramIdx++}`;
+            params.push(tagValues);
+            break;
+          case 'all':
+            query += ` AND tags @> $${paramIdx++}`;
+            params.push(tagValues);
+            break;
+          case 'any':
+            query += ` AND tags && $${paramIdx++}`;
+            params.push(tagValues);
+            break;
+          case 'none':
+            query += ` AND NOT (tags && $${paramIdx++})`;
+            params.push(tagValues);
+            break;
+          default:
+            query += ` AND tags @> $${paramIdx++}`;
+            params.push(tagValues);
+        }
       }
     }
     query += '\nRETURNING id';
@@ -548,3 +624,184 @@ export const getJobEvents = async (
     client.release();
   }
 };
+
+/**
+ * Get jobs by tags (matches all specified tags)
+ */
+export const getJobsByTags = async <
+  PayloadMap,
+  T extends keyof PayloadMap & string,
+>(
+  pool: Pool,
+  tags: string[],
+  mode: TagQueryMode = 'all',
+  limit = 100,
+  offset = 0,
+): Promise<JobRecord<PayloadMap, T>[]> => {
+  const client = await pool.connect();
+  try {
+    let query = `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags
+       FROM job_queue`;
+    let params: any[] = [];
+    switch (mode) {
+      case 'exact':
+        query += ' WHERE tags = $1';
+        params = [tags];
+        break;
+      case 'all':
+        query += ' WHERE tags @> $1';
+        params = [tags];
+        break;
+      case 'any':
+        query += ' WHERE tags && $1';
+        params = [tags];
+        break;
+      case 'none':
+        query += ' WHERE NOT (tags && $1)';
+        params = [tags];
+        break;
+      default:
+        query += ' WHERE tags @> $1';
+        params = [tags];
+    }
+    query += ' ORDER BY created_at DESC LIMIT $2 OFFSET $3';
+    params.push(limit, offset);
+    const result = await client.query(query, params);
+    log(
+      `Found ${result.rows.length} jobs by tags ${JSON.stringify(tags)} (mode: ${mode})`,
+    );
+    return result.rows.map((job) => ({
+      ...job,
+      payload: job.payload,
+      timeoutMs: job.timeoutMs,
+      failureReason: job.failureReason,
+    }));
+  } catch (error) {
+    log(
+      `Error getting jobs by tags ${JSON.stringify(tags)} (mode: ${mode}): ${error}`,
+    );
+    throw error;
+  } finally {
+    client.release();
+  }
+};
+
+export const getJobs = async <PayloadMap, T extends keyof PayloadMap & string>(
+  pool: Pool,
+  filters?: {
+    jobType?: string;
+    priority?: number;
+    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
+    tags?: { values: string[]; mode?: TagQueryMode };
+  },
+  limit = 100,
+  offset = 0,
+): Promise<JobRecord<PayloadMap, T>[]> => {
+  const client = await pool.connect();
+  try {
+    let query = `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags FROM job_queue`;
+    const params: any[] = [];
+    let where: string[] = [];
+    let paramIdx = 1;
+    if (filters) {
+      if (filters.jobType) {
+        where.push(`job_type = $${paramIdx++}`);
+        params.push(filters.jobType);
+      }
+      if (filters.priority !== undefined) {
+        where.push(`priority = $${paramIdx++}`);
+        params.push(filters.priority);
+      }
+      if (filters.runAt) {
+        if (filters.runAt instanceof Date) {
+          where.push(`run_at = $${paramIdx++}`);
+          params.push(filters.runAt);
+        } else if (
+          typeof filters.runAt === 'object' &&
+          (filters.runAt.gt !== undefined ||
+            filters.runAt.gte !== undefined ||
+            filters.runAt.lt !== undefined ||
+            filters.runAt.lte !== undefined ||
+            filters.runAt.eq !== undefined)
+        ) {
+          const ops = filters.runAt as {
+            gt?: Date;
+            gte?: Date;
+            lt?: Date;
+            lte?: Date;
+            eq?: Date;
+          };
+          if (ops.gt) {
+            where.push(`run_at > $${paramIdx++}`);
+            params.push(ops.gt);
+          }
+          if (ops.gte) {
+            where.push(`run_at >= $${paramIdx++}`);
+            params.push(ops.gte);
+          }
+          if (ops.lt) {
+            where.push(`run_at < $${paramIdx++}`);
+            params.push(ops.lt);
+          }
+          if (ops.lte) {
+            where.push(`run_at <= $${paramIdx++}`);
+            params.push(ops.lte);
+          }
+          if (ops.eq) {
+            where.push(`run_at = $${paramIdx++}`);
+            params.push(ops.eq);
+          }
+        }
+      }
+      if (
+        filters.tags &&
+        filters.tags.values &&
+        filters.tags.values.length > 0
+      ) {
+        const mode = filters.tags.mode || 'all';
+        const tagValues = filters.tags.values;
+        switch (mode) {
+          case 'exact':
+            where.push(`tags = $${paramIdx++}`);
+            params.push(tagValues);
+            break;
+          case 'all':
+            where.push(`tags @> $${paramIdx++}`);
+            params.push(tagValues);
+            break;
+          case 'any':
+            where.push(`tags && $${paramIdx++}`);
+            params.push(tagValues);
+            break;
+          case 'none':
+            where.push(`NOT (tags && $${paramIdx++})`);
+            params.push(tagValues);
+            break;
+          default:
+            where.push(`tags @> $${paramIdx++}`);
+            params.push(tagValues);
+        }
+      }
+    }
+    if (where.length > 0) {
+      query += ` WHERE ${where.join(' AND ')}`;
+    }
+    // Always add LIMIT and OFFSET as the last parameters
+    paramIdx = params.length + 1;
+    query += ` ORDER BY created_at DESC LIMIT $${paramIdx++} OFFSET $${paramIdx}`;
+    params.push(limit, offset);
+    const result = await client.query(query, params);
+    log(`Found ${result.rows.length} jobs`);
+    return result.rows.map((job) => ({
+      ...job,
+      payload: job.payload,
+      timeoutMs: job.timeoutMs,
+      failureReason: job.failureReason,
+    }));
+  } catch (error) {
+    log(`Error getting jobs: ${error}`);
+    throw error;
+  } finally {
+    client.release();
+  }
+};

package/src/types.ts

@@ -13,6 +13,10 @@ export interface JobOptions<PayloadMap, T extends JobType<PayloadMap>> {
    * Timeout for this job in milliseconds. If not set, uses the processor default or unlimited.
    */
   timeoutMs?: number;
+  /**
+   * Tags for this job. Used for grouping, searching, or batch operations.
+   */
+  tags?: string[];
 }
 
 export enum JobEventType {
@@ -89,6 +93,10 @@ export interface JobRecord<PayloadMap, T extends JobType<PayloadMap>> {
    * The time the job was last cancelled.
    */
   lastCancelledAt: Date | null;
+  /**
+   * Tags for this job. Used for grouping, searching, or batch operations.
+   */
+  tags?: string[];
 }
 
 export type JobHandler<PayloadMap, T extends keyof PayloadMap> = (
@@ -169,6 +177,8 @@ export interface JobQueueConfig {
   verbose?: boolean;
 }
 
+export type TagQueryMode = 'exact' | 'all' | 'any' | 'none';
+
 export interface JobQueue<PayloadMap> {
   /**
    * Add a job to the job queue.
@@ -193,6 +203,21 @@ export interface JobQueue<PayloadMap> {
     limit?: number,
     offset?: number,
   ) => Promise<JobRecord<PayloadMap, T>[]>;
+  /**
+   * Get jobs by tag(s).
+   * - Modes:
+   *   - 'exact': Jobs with exactly the same tags (no more, no less)
+   *   - 'all': Jobs that have all the given tags (can have more)
+   *   - 'any': Jobs that have at least one of the given tags
+   *   - 'none': Jobs that have none of the given tags
+   * - Default mode is 'all'.
+   */
+  getJobsByTags: <T extends JobType<PayloadMap>>(
+    tags: string[],
+    mode?: TagQueryMode,
+    limit?: number,
+    offset?: number,
+  ) => Promise<JobRecord<PayloadMap, T>[]>;
   /**
    * Get all jobs.
    */
@@ -200,6 +225,17 @@ export interface JobQueue<PayloadMap> {
     limit?: number,
     offset?: number,
   ) => Promise<JobRecord<PayloadMap, T>[]>;
+  /**
+   * Get jobs by filters.
+  /**
+   * Get jobs by filters.
+   */
+  getJobs: <T extends JobType<PayloadMap>>(filters?: {
+    jobType?: string;
+    priority?: number;
+    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
+    tags?: { values: string[]; mode?: TagQueryMode };
+  }) => Promise<JobRecord<PayloadMap, T>[]>;
   /**
    * Retry a job given its ID.
    * - This will set the job status back to 'pending', clear the locked_at and locked_by, and allow it to be picked up by other workers.
@@ -228,12 +264,14 @@ export interface JobQueue<PayloadMap> {
    * - The filters are:
    *   - jobType: The job type to cancel.
    *   - priority: The priority of the job to cancel.
-   *   - runAt: The time the job is scheduled to run at.
+   *   - runAt: The time the job is scheduled to run at (now supports gt/gte/lt/lte/eq).
+   *   - tags: An object with 'values' (string[]) and 'mode' (TagQueryMode) for tag-based cancellation.
    */
   cancelAllUpcomingJobs: (filters?: {
     jobType?: string;
     priority?: number;
-    runAt?: Date;
+    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
+    tags?: { values: string[]; mode?: TagQueryMode };
   }) => Promise<number>;
   /**
    * Create a job processor. Handlers must be provided per-processor.