@nicnocquee/dataqueue 1.22.0 → 1.24.0

package/src/queue.ts

@@ -44,6 +44,7 @@ export const addJob = async <PayloadMap, T extends keyof PayloadMap & string>(
     priority = 0,
     runAt = null,
     timeoutMs = undefined,
+    forceKillOnTimeout = false,
     tags = undefined,
   }: JobOptions<PayloadMap, T>,
 ): Promise<number> => {
@@ -53,8 +54,8 @@ 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, tags) 
-         VALUES ($1, $2, $3, $4, $5, $6, $7) 
+          (job_type, payload, max_attempts, priority, run_at, timeout_ms, force_kill_on_timeout, tags) 
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8) 
          RETURNING id`,
         [
           jobType,
@@ -63,6 +64,7 @@ export const addJob = async <PayloadMap, T extends keyof PayloadMap & string>(
           priority,
           runAt,
           timeoutMs ?? null,
+          forceKillOnTimeout ?? false,
           tags ?? null,
         ],
       );
@@ -72,8 +74,8 @@ export const addJob = async <PayloadMap, T extends keyof PayloadMap & string>(
     } else {
       result = await client.query(
         `INSERT INTO job_queue 
-          (job_type, payload, max_attempts, priority, timeout_ms, tags) 
-         VALUES ($1, $2, $3, $4, $5, $6) 
+          (job_type, payload, max_attempts, priority, timeout_ms, force_kill_on_timeout, tags) 
+         VALUES ($1, $2, $3, $4, $5, $6, $7) 
          RETURNING id`,
         [
           jobType,
@@ -81,6 +83,7 @@ export const addJob = async <PayloadMap, T extends keyof PayloadMap & string>(
           maxAttempts,
           priority,
           timeoutMs ?? null,
+          forceKillOnTimeout ?? false,
           tags ?? null,
         ],
       );
@@ -112,7 +115,7 @@ export const getJob = async <PayloadMap, T extends keyof PayloadMap & string>(
   const client = await pool.connect();
   try {
     const result = await client.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" FROM job_queue WHERE id = $1`,
+      `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", 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 WHERE id = $1`,
       [id],
     );
 
@@ -129,6 +132,7 @@ export const getJob = async <PayloadMap, T extends keyof PayloadMap & string>(
       ...job,
       payload: job.payload,
       timeoutMs: job.timeoutMs,
+      forceKillOnTimeout: job.forceKillOnTimeout,
       failureReason: job.failureReason,
     };
   } catch (error) {
@@ -154,7 +158,7 @@ export const getJobsByStatus = async <
   const client = await pool.connect();
   try {
     const result = await client.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" FROM job_queue WHERE status = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`,
+      `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", 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" FROM job_queue WHERE status = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`,
       [status, limit, offset],
     );
 
@@ -164,6 +168,7 @@ export const getJobsByStatus = async <
       ...job,
       payload: job.payload,
       timeoutMs: job.timeoutMs,
+      forceKillOnTimeout: job.forceKillOnTimeout,
       failureReason: job.failureReason,
     }));
   } catch (error) {
@@ -230,7 +235,7 @@ export const getNextBatch = async <
         LIMIT $2
         FOR UPDATE SKIP LOCKED
       )
-      RETURNING 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_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason"
+      RETURNING id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", 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_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason"
     `,
       params,
     );
@@ -249,6 +254,7 @@ export const getNextBatch = async <
       ...job,
       payload: job.payload,
       timeoutMs: job.timeoutMs,
+      forceKillOnTimeout: job.forceKillOnTimeout,
     }));
   } catch (error) {
     log(`Error getting next batch: ${error}`);
@@ -413,6 +419,274 @@ export const cancelJob = async (pool: Pool, jobId: number): Promise<void> => {
   }
 };
 
+/**
+ * Edit a pending job (only if still pending)
+ */
+export const editJob = async <PayloadMap, T extends keyof PayloadMap & string>(
+  pool: Pool,
+  jobId: number,
+  updates: {
+    payload?: PayloadMap[T];
+    maxAttempts?: number;
+    priority?: number;
+    runAt?: Date | null;
+    timeoutMs?: number | null;
+    tags?: string[] | null;
+  },
+): Promise<void> => {
+  const client = await pool.connect();
+  try {
+    const updateFields: string[] = [];
+    const params: any[] = [];
+    let paramIdx = 1;
+
+    // Build dynamic UPDATE query based on provided fields
+    if (updates.payload !== undefined) {
+      updateFields.push(`payload = $${paramIdx++}`);
+      params.push(updates.payload);
+    }
+    if (updates.maxAttempts !== undefined) {
+      updateFields.push(`max_attempts = $${paramIdx++}`);
+      params.push(updates.maxAttempts);
+    }
+    if (updates.priority !== undefined) {
+      updateFields.push(`priority = $${paramIdx++}`);
+      params.push(updates.priority);
+    }
+    if (updates.runAt !== undefined) {
+      if (updates.runAt === null) {
+        // null means run now (use current timestamp)
+        updateFields.push(`run_at = NOW()`);
+      } else {
+        updateFields.push(`run_at = $${paramIdx++}`);
+        params.push(updates.runAt);
+      }
+    }
+    if (updates.timeoutMs !== undefined) {
+      updateFields.push(`timeout_ms = $${paramIdx++}`);
+      params.push(updates.timeoutMs ?? null);
+    }
+    if (updates.tags !== undefined) {
+      updateFields.push(`tags = $${paramIdx++}`);
+      params.push(updates.tags ?? null);
+    }
+
+    // If no fields to update, return early
+    if (updateFields.length === 0) {
+      log(`No fields to update for job ${jobId}`);
+      return;
+    }
+
+    // Always update updated_at timestamp
+    updateFields.push(`updated_at = NOW()`);
+
+    // Add jobId as the last parameter for WHERE clause
+    params.push(jobId);
+
+    const query = `
+      UPDATE job_queue
+      SET ${updateFields.join(', ')}
+      WHERE id = $${paramIdx} AND status = 'pending'
+    `;
+
+    await client.query(query, params);
+
+    // Record edit event with metadata containing updated fields
+    const metadata: any = {};
+    if (updates.payload !== undefined) metadata.payload = updates.payload;
+    if (updates.maxAttempts !== undefined)
+      metadata.maxAttempts = updates.maxAttempts;
+    if (updates.priority !== undefined) metadata.priority = updates.priority;
+    if (updates.runAt !== undefined) metadata.runAt = updates.runAt;
+    if (updates.timeoutMs !== undefined) metadata.timeoutMs = updates.timeoutMs;
+    if (updates.tags !== undefined) metadata.tags = updates.tags;
+
+    await recordJobEvent(pool, jobId, JobEventType.Edited, metadata);
+    log(`Edited job ${jobId}: ${JSON.stringify(metadata)}`);
+  } catch (error) {
+    log(`Error editing job ${jobId}: ${error}`);
+    throw error;
+  } finally {
+    client.release();
+  }
+};
+
+/**
+ * Edit all pending jobs matching the filters
+ */
+export const editAllPendingJobs = 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 };
+      }
+    | undefined = undefined,
+  updates: {
+    payload?: PayloadMap[T];
+    maxAttempts?: number;
+    priority?: number;
+    runAt?: Date | null;
+    timeoutMs?: number;
+    tags?: string[];
+  },
+): Promise<number> => {
+  const client = await pool.connect();
+  try {
+    // Build SET clause from updates
+    const updateFields: string[] = [];
+    const params: any[] = [];
+    let paramIdx = 1;
+
+    if (updates.payload !== undefined) {
+      updateFields.push(`payload = $${paramIdx++}`);
+      params.push(updates.payload);
+    }
+    if (updates.maxAttempts !== undefined) {
+      updateFields.push(`max_attempts = $${paramIdx++}`);
+      params.push(updates.maxAttempts);
+    }
+    if (updates.priority !== undefined) {
+      updateFields.push(`priority = $${paramIdx++}`);
+      params.push(updates.priority);
+    }
+    if (updates.runAt !== undefined) {
+      if (updates.runAt === null) {
+        // null means run now (use current timestamp)
+        updateFields.push(`run_at = NOW()`);
+      } else {
+        updateFields.push(`run_at = $${paramIdx++}`);
+        params.push(updates.runAt);
+      }
+    }
+    if (updates.timeoutMs !== undefined) {
+      updateFields.push(`timeout_ms = $${paramIdx++}`);
+      params.push(updates.timeoutMs ?? null);
+    }
+    if (updates.tags !== undefined) {
+      updateFields.push(`tags = $${paramIdx++}`);
+      params.push(updates.tags ?? null);
+    }
+
+    // If no fields to update, return early
+    if (updateFields.length === 0) {
+      log(`No fields to update for batch edit`);
+      return 0;
+    }
+
+    // Always update updated_at timestamp
+    updateFields.push(`updated_at = NOW()`);
+
+    // Build WHERE clause from filters
+    let query = `
+      UPDATE job_queue
+      SET ${updateFields.join(', ')}
+      WHERE status = 'pending'`;
+
+    if (filters) {
+      if (filters.jobType) {
+        query += ` AND job_type = $${paramIdx++}`;
+        params.push(filters.jobType);
+      }
+      if (filters.priority !== undefined) {
+        query += ` AND priority = $${paramIdx++}`;
+        params.push(filters.priority);
+      }
+      if (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';
+
+    const result = await client.query(query, params);
+    const editedCount = result.rowCount || 0;
+
+    // Record edit event with metadata containing updated fields for each job
+    const metadata: any = {};
+    if (updates.payload !== undefined) metadata.payload = updates.payload;
+    if (updates.maxAttempts !== undefined)
+      metadata.maxAttempts = updates.maxAttempts;
+    if (updates.priority !== undefined) metadata.priority = updates.priority;
+    if (updates.runAt !== undefined) metadata.runAt = updates.runAt;
+    if (updates.timeoutMs !== undefined) metadata.timeoutMs = updates.timeoutMs;
+    if (updates.tags !== undefined) metadata.tags = updates.tags;
+
+    // Record events for each affected job
+    for (const row of result.rows) {
+      await recordJobEvent(pool, row.id, JobEventType.Edited, metadata);
+    }
+
+    log(`Edited ${editedCount} pending jobs: ${JSON.stringify(metadata)}`);
+    return editedCount;
+  } catch (error) {
+    log(`Error editing pending jobs: ${error}`);
+    throw error;
+  } finally {
+    client.release();
+  }
+};
+
 /**
  * Cancel all upcoming jobs (pending and scheduled in the future) with optional filters
  */
@@ -526,7 +800,7 @@ export const getAllJobs = async <
   const client = await pool.connect();
   try {
     const result = await client.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" FROM job_queue ORDER BY created_at DESC LIMIT $1 OFFSET $2`,
+      `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", 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" FROM job_queue ORDER BY created_at DESC LIMIT $1 OFFSET $2`,
       [limit, offset],
     );
     log(`Found ${result.rows.length} jobs (all)`);
@@ -534,6 +808,7 @@ export const getAllJobs = async <
       ...job,
       payload: job.payload,
       timeoutMs: job.timeoutMs,
+      forceKillOnTimeout: job.forceKillOnTimeout,
     }));
   } catch (error) {
     log(`Error getting all jobs: ${error}`);
@@ -674,6 +949,7 @@ export const getJobsByTags = async <
       ...job,
       payload: job.payload,
       timeoutMs: job.timeoutMs,
+      forceKillOnTimeout: job.forceKillOnTimeout,
       failureReason: job.failureReason,
     }));
   } catch (error) {
@@ -699,7 +975,7 @@ export const getJobs = async <PayloadMap, T extends keyof PayloadMap & string>(
 ): 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 query = `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", 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;
@@ -796,6 +1072,7 @@ export const getJobs = async <PayloadMap, T extends keyof PayloadMap & string>(
       ...job,
       payload: job.payload,
       timeoutMs: job.timeoutMs,
+      forceKillOnTimeout: job.forceKillOnTimeout,
       failureReason: job.failureReason,
     }));
   } catch (error) {

package/src/types.ts

@@ -13,12 +13,71 @@ 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;
+  /**
+   * If true, the job will be forcefully terminated (using Worker Threads) when timeout is reached.
+   * If false (default), the job will only receive an AbortSignal and must handle the abort gracefully.
+   *
+   * **⚠️ RUNTIME REQUIREMENTS**: This option requires **Node.js** and uses the `worker_threads` module.
+   * It will **not work** in Bun or other runtimes that don't support Node.js worker threads.
+   *
+   * **IMPORTANT**: When `forceKillOnTimeout` is true, the handler must be serializable. This means:
+   * - The handler should be a standalone function (not a closure over external variables)
+   * - It should not capture variables from outer scopes that reference external dependencies
+   * - It should not use 'this' context unless it's a bound method
+   * - All dependencies must be importable in the worker thread context
+   *
+   * **Examples of serializable handlers:**
+   * ```ts
+   * // ✅ Good - standalone function
+   * const handler = async (payload, signal) => {
+   *   await doSomething(payload);
+   * };
+   *
+   * // ✅ Good - function that imports dependencies
+   * const handler = async (payload, signal) => {
+   *   const { api } = await import('./api');
+   *   await api.call(payload);
+   * };
+   *
+   * // ❌ Bad - closure over external variable
+   * const db = getDatabase();
+   * const handler = async (payload, signal) => {
+   *   await db.query(payload); // 'db' is captured from closure
+   * };
+   *
+   * // ❌ Bad - uses 'this' context
+   * class MyHandler {
+   *   async handle(payload, signal) {
+   *     await this.doSomething(payload); // 'this' won't work
+   *   }
+   * }
+   * ```
+   *
+   * If your handler doesn't meet these requirements, use `forceKillOnTimeout: false` (default)
+   * and ensure your handler checks `signal.aborted` to exit gracefully.
+   *
+   * Note: forceKillOnTimeout requires timeoutMs to be set.
+   */
+  forceKillOnTimeout?: boolean;
   /**
    * Tags for this job. Used for grouping, searching, or batch operations.
    */
   tags?: string[];
 }
 
+/**
+ * Options for editing a pending job.
+ * All fields are optional and only provided fields will be updated.
+ * Note: jobType cannot be changed.
+ * timeoutMs and tags can be set to null to clear them.
+ */
+export type EditJobOptions<PayloadMap, T extends JobType<PayloadMap>> = Partial<
+  Omit<JobOptions<PayloadMap, T>, 'jobType'>
+> & {
+  timeoutMs?: number | null;
+  tags?: string[] | null;
+};
+
 export enum JobEventType {
   Added = 'added',
   Processing = 'processing',
@@ -26,6 +85,7 @@ export enum JobEventType {
   Failed = 'failed',
   Cancelled = 'cancelled',
   Retried = 'retried',
+  Edited = 'edited',
 }
 
 export interface JobEvent {
@@ -69,6 +129,11 @@ export interface JobRecord<PayloadMap, T extends JobType<PayloadMap>> {
    * Timeout for this job in milliseconds (null means no timeout).
    */
   timeoutMs?: number | null;
+  /**
+   * If true, the job will be forcefully terminated (using Worker Threads) when timeout is reached.
+   * If false (default), the job will only receive an AbortSignal and must handle the abort gracefully.
+   */
+  forceKillOnTimeout?: boolean | null;
   /**
    * The reason for the last failure, if any.
    */
@@ -269,6 +334,43 @@ export interface JobQueue<PayloadMap> {
    * - This will set the job status to 'cancelled' and clear the locked_at and locked_by.
    */
   cancelJob: (jobId: number) => Promise<void>;
+  /**
+   * Edit a pending job given its ID.
+   * - Only works for jobs with status 'pending'. Silently fails for other statuses.
+   * - All fields in EditJobOptions are optional - only provided fields will be updated.
+   * - jobType cannot be changed.
+   * - Records an 'edited' event with the updated fields in metadata.
+   */
+  editJob: <T extends JobType<PayloadMap>>(
+    jobId: number,
+    updates: EditJobOptions<PayloadMap, T>,
+  ) => Promise<void>;
+  /**
+   * Edit all pending jobs that match the filters.
+   * - Only works for jobs with status 'pending'. Non-pending jobs are not affected.
+   * - All fields in EditJobOptions are optional - only provided fields will be updated.
+   * - jobType cannot be changed.
+   * - Records an 'edited' event with the updated fields in metadata for each affected job.
+   * - Returns the number of jobs that were edited.
+   * - The filters are:
+   *   - jobType: The job type to edit.
+   *   - priority: The priority of the job to edit.
+   *   - 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 editing.
+   */
+  editAllPendingJobs: <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 };
+        }
+      | undefined,
+    updates: EditJobOptions<PayloadMap, T>,
+  ) => Promise<number>;
   /**
    * Reclaim stuck jobs.
    * - If a process (e.g., API route or worker) crashes after marking a job as 'processing' but before completing it, the job can remain stuck in the 'processing' state indefinitely. This can happen if the process is killed or encounters an unhandled error after updating the job status but before marking it as 'completed' or 'failed'.