@nicnocquee/dataqueue 1.19.3 → 1.21.0

package/dist/index.d.cts

@@ -11,6 +11,10 @@ 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[];
 }
 declare enum JobEventType {
     Added = "added",
@@ -80,6 +84,10 @@ 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[];
 }
 type JobHandler<PayloadMap, T extends keyof PayloadMap> = (payload: PayloadMap[T], signal: AbortSignal) => Promise<void>;
 type JobHandlers<PayloadMap> = {
@@ -151,6 +159,7 @@ interface JobQueueConfig {
     };
     verbose?: boolean;
 }
+type TagQueryMode = 'exact' | 'all' | 'any' | 'none';
 interface JobQueue<PayloadMap> {
     /**
      * Add a job to the job queue.
@@ -167,10 +176,40 @@ interface JobQueue<PayloadMap> {
      * - The jobs are returned in descending order of createdAt.
      */
     getJobsByStatus: <T extends JobType<PayloadMap>>(status: JobStatus, 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.
      */
     getAllJobs: <T extends JobType<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.
@@ -199,12 +238,23 @@ 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.
@@ -225,4 +275,4 @@ interface JobQueue<PayloadMap> {
  */
 declare const initJobQueue: <PayloadMap = any>(config: JobQueueConfig) => JobQueue<PayloadMap>;
 
-export { FailureReason, type JobEvent, JobEventType, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobRecord, type JobStatus, type JobType, type Processor, type ProcessorOptions, initJobQueue };
+export { FailureReason, type JobEvent, JobEventType, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobRecord, type JobStatus, type JobType, type Processor, type ProcessorOptions, type TagQueryMode, initJobQueue };

package/dist/index.d.ts

@@ -11,6 +11,10 @@ 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[];
 }
 declare enum JobEventType {
     Added = "added",
@@ -80,6 +84,10 @@ 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[];
 }
 type JobHandler<PayloadMap, T extends keyof PayloadMap> = (payload: PayloadMap[T], signal: AbortSignal) => Promise<void>;
 type JobHandlers<PayloadMap> = {
@@ -151,6 +159,7 @@ interface JobQueueConfig {
     };
     verbose?: boolean;
 }
+type TagQueryMode = 'exact' | 'all' | 'any' | 'none';
 interface JobQueue<PayloadMap> {
     /**
      * Add a job to the job queue.
@@ -167,10 +176,40 @@ interface JobQueue<PayloadMap> {
      * - The jobs are returned in descending order of createdAt.
      */
     getJobsByStatus: <T extends JobType<PayloadMap>>(status: JobStatus, 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.
      */
     getAllJobs: <T extends JobType<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.
@@ -199,12 +238,23 @@ 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.
@@ -225,4 +275,4 @@ interface JobQueue<PayloadMap> {
  */
 declare const initJobQueue: <PayloadMap = any>(config: JobQueueConfig) => JobQueue<PayloadMap>;
 
-export { FailureReason, type JobEvent, JobEventType, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobRecord, type JobStatus, type JobType, type Processor, type ProcessorOptions, initJobQueue };
+export { FailureReason, type JobEvent, JobEventType, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobRecord, type JobStatus, type JobType, type Processor, type ProcessorOptions, type TagQueryMode, initJobQueue };

package/dist/index.js

@@ -52,7 +52,8 @@ var addJob = async (pool, {
   maxAttempts = 3,
   priority = 0,
   runAt = null,
-  timeoutMs = void 0
+  timeoutMs = void 0,
+  tags = void 0
 }) => {
   const client = await pool.connect();
   try {
@@ -60,29 +61,45 @@ var addJob = async (pool, {
     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, "added" /* Added */, {
       jobType,
-      payload
+      payload,
+      tags
     });
     return result.rows[0].id;
   } catch (error) {
@@ -339,8 +356,57 @@ var cancelAllUpcomingJobs = async (pool, filters) => {
         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";
@@ -429,6 +495,145 @@ var getJobEvents = async (pool, jobId) => {
     client.release();
   }
 };
+var getJobsByTags = async (pool, tags, mode = "all", limit = 100, offset = 0) => {
+  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 = [];
+    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();
+  }
+};
+var getJobs = async (pool, filters, limit = 100, offset = 0) => {
+  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 = [];
+    let where = [];
+    let paramIdx = 1;
+    if (filters) {
+      if (filters.jobType) {
+        where.push(`job_type = $${paramIdx++}`);
+        params.push(filters.jobType);
+      }
+      if (filters.priority !== void 0) {
+        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 !== void 0 || filters.runAt.gte !== void 0 || filters.runAt.lt !== void 0 || filters.runAt.lte !== void 0 || filters.runAt.eq !== void 0)) {
+          const ops = filters.runAt;
+          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 ")}`;
+    }
+    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();
+  }
+};
 
 // src/processor.ts
 async function processJobWithHandlers(pool, job, jobHandlers) {
@@ -648,6 +853,10 @@ var initJobQueue = (config) => {
       (limit, offset) => getAllJobs(pool, limit, offset),
       config.verbose ?? false
     ),
+    getJobs: withLogContext(
+      (filters, limit, offset) => getJobs(pool, filters, limit, offset),
+      config.verbose ?? false
+    ),
     retryJob: (jobId) => retryJob(pool, jobId),
     cleanupOldJobs: (daysToKeep) => cleanupOldJobs(pool, daysToKeep),
     cancelJob: withLogContext(
@@ -662,6 +871,10 @@ var initJobQueue = (config) => {
       (maxProcessingTimeMinutes) => reclaimStuckJobs(pool, maxProcessingTimeMinutes),
       config.verbose ?? false
     ),
+    getJobsByTags: withLogContext(
+      (tags, mode = "all", limit, offset) => getJobsByTags(pool, tags, mode, limit, offset),
+      config.verbose ?? false
+    ),
     // Job processing
     createProcessor: (handlers, options) => createProcessor(pool, handlers, options),
     // Advanced access (for custom operations)