@nicnocquee/dataqueue 1.22.0 → 1.25.0

package/src/queue.test.ts

@@ -72,6 +72,8 @@ describe('queue integration', () => {
       jobType: 'email',
       payload: { to: 'done@example.com' },
     });
+    // Claim the job first (sets status to 'processing')
+    await queue.getNextBatch(pool, 'worker-complete', 1);
     await queue.completeJob(pool, jobId);
     const job = await queue.getJob(pool, jobId);
     expect(job?.status).toBe('completed');
@@ -124,6 +126,8 @@ describe('queue integration', () => {
       jobType: 'email',
       payload: { to: 'cleanup@example.com' },
     });
+    // Claim then complete the job
+    await queue.getNextBatch(pool, 'worker-cleanup', 1);
     await queue.completeJob(pool, jobId);
     // Manually update updated_at to be old
     await pool.query(
@@ -154,12 +158,543 @@ describe('queue integration', () => {
         payload: { to: 'done@example.com' },
       },
     );
+    await queue.getNextBatch(pool, 'worker-cancel-done', 1);
     await queue.completeJob(pool, jobId2);
     await queue.cancelJob(pool, jobId2);
     const completedJob = await queue.getJob(pool, jobId2);
     expect(completedJob?.status).toBe('completed');
   });
 
+  it('should edit a pending job with all fields', async () => {
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'original@example.com' },
+      priority: 0,
+      maxAttempts: 3,
+      timeoutMs: 10000,
+      tags: ['original'],
+    });
+    const originalJob = await queue.getJob(pool, jobId);
+    const originalUpdatedAt = originalJob?.updatedAt;
+
+    // Wait a bit to ensure updated_at changes
+    await new Promise((r) => setTimeout(r, 10));
+
+    await queue.editJob<{ email: { to: string } }, 'email'>(pool, jobId, {
+      payload: { to: 'updated@example.com' },
+      priority: 10,
+      maxAttempts: 5,
+      runAt: new Date(Date.now() + 60000),
+      timeoutMs: 20000,
+      tags: ['updated', 'priority'],
+    });
+
+    const updatedJob = await queue.getJob(pool, jobId);
+    expect(updatedJob?.payload).toEqual({ to: 'updated@example.com' });
+    expect(updatedJob?.priority).toBe(10);
+    expect(updatedJob?.maxAttempts).toBe(5);
+    expect(updatedJob?.timeoutMs).toBe(20000);
+    expect(updatedJob?.tags).toEqual(['updated', 'priority']);
+    expect(updatedJob?.status).toBe('pending');
+    expect(updatedJob?.updatedAt.getTime()).toBeGreaterThan(
+      originalUpdatedAt?.getTime() || 0,
+    );
+  });
+
+  it('should edit a pending job with partial fields', async () => {
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'original@example.com' },
+      priority: 0,
+      maxAttempts: 3,
+    });
+
+    // Only update payload
+    await queue.editJob<{ email: { to: string } }, 'email'>(pool, jobId, {
+      payload: { to: 'updated@example.com' },
+    });
+
+    const updatedJob = await queue.getJob(pool, jobId);
+    expect(updatedJob?.payload).toEqual({ to: 'updated@example.com' });
+    expect(updatedJob?.priority).toBe(0); // Unchanged
+    expect(updatedJob?.maxAttempts).toBe(3); // Unchanged
+
+    // Only update priority
+    await queue.editJob<{ email: { to: string } }, 'email'>(pool, jobId, {
+      priority: 5,
+    });
+
+    const updatedJob2 = await queue.getJob(pool, jobId);
+    expect(updatedJob2?.payload).toEqual({ to: 'updated@example.com' }); // Still updated
+    expect(updatedJob2?.priority).toBe(5); // Now updated
+  });
+
+  it('should silently fail when editing a non-pending job', async () => {
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'original@example.com' },
+    });
+    await queue.getNextBatch(pool, 'worker-edit-noop', 1);
+    await queue.completeJob(pool, jobId);
+
+    // Try to edit a completed job - should silently fail
+    await queue.editJob<{ email: { to: string } }, 'email'>(pool, jobId, {
+      payload: { to: 'updated@example.com' },
+    });
+
+    const job = await queue.getJob(pool, jobId);
+    expect(job?.status).toBe('completed');
+    expect(job?.payload).toEqual({ to: 'original@example.com' }); // Unchanged
+
+    // Try to edit a processing job
+    const jobId2 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'processing@example.com' },
+      },
+    );
+    await queue.getNextBatch(pool, 'worker-edit', 1);
+    await queue.editJob<{ email: { to: string } }, 'email'>(pool, jobId2, {
+      payload: { to: 'updated@example.com' },
+    });
+
+    const job2 = await queue.getJob(pool, jobId2);
+    expect(job2?.status).toBe('processing');
+    expect(job2?.payload).toEqual({ to: 'processing@example.com' }); // Unchanged
+  });
+
+  it('should record edited event when editing a job', async () => {
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'original@example.com' },
+    });
+
+    await queue.editJob<{ email: { to: string } }, 'email'>(pool, jobId, {
+      payload: { to: 'updated@example.com' },
+      priority: 10,
+    });
+
+    const res = await pool.query(
+      'SELECT * FROM job_events WHERE job_id = $1 ORDER BY created_at ASC',
+      [jobId],
+    );
+    const events = res.rows.map(
+      (row) => objectKeysToCamelCase(row) as JobEvent,
+    );
+    const editEvent = events.find((e) => e.eventType === JobEventType.Edited);
+    expect(editEvent).not.toBeUndefined();
+    expect(editEvent?.metadata).toMatchObject({
+      payload: { to: 'updated@example.com' },
+      priority: 10,
+    });
+  });
+
+  it('should update updated_at timestamp when editing', async () => {
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'original@example.com' },
+    });
+    const originalJob = await queue.getJob(pool, jobId);
+    const originalUpdatedAt = originalJob?.updatedAt;
+
+    // Wait a bit to ensure timestamp difference
+    await new Promise((r) => setTimeout(r, 10));
+
+    await queue.editJob<{ email: { to: string } }, 'email'>(pool, jobId, {
+      priority: 5,
+    });
+
+    const updatedJob = await queue.getJob(pool, jobId);
+    expect(updatedJob?.updatedAt.getTime()).toBeGreaterThan(
+      originalUpdatedAt?.getTime() || 0,
+    );
+  });
+
+  it('should handle editing with null values', async () => {
+    const futureDate = new Date(Date.now() + 60000);
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'original@example.com' },
+      runAt: futureDate,
+      timeoutMs: 10000,
+      tags: ['original'],
+    });
+
+    await queue.editJob<{ email: { to: string } }, 'email'>(pool, jobId, {
+      runAt: null,
+      timeoutMs: null,
+      tags: null,
+    });
+
+    const updatedJob = await queue.getJob(pool, jobId);
+    expect(updatedJob?.runAt).not.toBeNull(); // runAt null means use default (now)
+    expect(updatedJob?.timeoutMs).toBeNull();
+    expect(updatedJob?.tags).toBeNull();
+  });
+
+  it('should do nothing when editing with no fields', async () => {
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'original@example.com' },
+    });
+    const originalJob = await queue.getJob(pool, jobId);
+
+    await queue.editJob<{ email: { to: string } }, 'email'>(pool, jobId, {});
+
+    const job = await queue.getJob(pool, jobId);
+    expect(job?.payload).toEqual(originalJob?.payload);
+    expect(job?.priority).toBe(originalJob?.priority);
+  });
+
+  it('should edit all pending jobs without filters', async () => {
+    // Add three pending jobs
+    const jobId1 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'batch1@example.com' },
+        priority: 0,
+      },
+    );
+    const jobId2 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'batch2@example.com' },
+        priority: 0,
+      },
+    );
+    const jobId3 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'batch3@example.com' },
+        priority: 0,
+      },
+    );
+    // Add a completed job (set via SQL since this test is about edit behavior)
+    const jobId4 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'done@example.com' },
+      },
+    );
+    await pool.query(
+      `UPDATE job_queue SET status = 'completed' WHERE id = $1`,
+      [jobId4],
+    );
+
+    // Edit all pending jobs
+    const editedCount = await queue.editAllPendingJobs<
+      { email: { to: string } },
+      'email'
+    >(pool, undefined, {
+      priority: 10,
+    });
+    expect(editedCount).toBeGreaterThanOrEqual(3);
+
+    // Check that all pending jobs are updated
+    const job1 = await queue.getJob(pool, jobId1);
+    const job2 = await queue.getJob(pool, jobId2);
+    const job3 = await queue.getJob(pool, jobId3);
+    expect(job1?.priority).toBe(10);
+    expect(job2?.priority).toBe(10);
+    expect(job3?.priority).toBe(10);
+
+    // Completed job should remain unchanged
+    const completedJob = await queue.getJob(pool, jobId4);
+    expect(completedJob?.priority).toBe(0);
+  });
+
+  it('should edit pending jobs filtered by jobType', async () => {
+    const emailJobId1 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'email1@example.com' },
+        priority: 0,
+      },
+    );
+    const emailJobId2 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'email2@example.com' },
+        priority: 0,
+      },
+    );
+    const smsJobId = await queue.addJob<{ sms: { to: string } }, 'sms'>(pool, {
+      jobType: 'sms',
+      payload: { to: 'sms@example.com' },
+      priority: 0,
+    });
+
+    // Edit only email jobs
+    const editedCount = await queue.editAllPendingJobs<
+      { email: { to: string }; sms: { to: string } },
+      'email'
+    >(
+      pool,
+      { jobType: 'email' },
+      {
+        priority: 5,
+      },
+    );
+    expect(editedCount).toBeGreaterThanOrEqual(2);
+
+    const emailJob1 = await queue.getJob(pool, emailJobId1);
+    const emailJob2 = await queue.getJob(pool, emailJobId2);
+    const smsJob = await queue.getJob(pool, smsJobId);
+    expect(emailJob1?.priority).toBe(5);
+    expect(emailJob2?.priority).toBe(5);
+    expect(smsJob?.priority).toBe(0);
+  });
+
+  it('should edit pending jobs filtered by priority', async () => {
+    const lowPriorityJobId1 = await queue.addJob<
+      { email: { to: string } },
+      'email'
+    >(pool, {
+      jobType: 'email',
+      payload: { to: 'low1@example.com' },
+      priority: 1,
+    });
+    const lowPriorityJobId2 = await queue.addJob<
+      { email: { to: string } },
+      'email'
+    >(pool, {
+      jobType: 'email',
+      payload: { to: 'low2@example.com' },
+      priority: 1,
+    });
+    const highPriorityJobId = await queue.addJob<
+      { email: { to: string } },
+      'email'
+    >(pool, {
+      jobType: 'email',
+      payload: { to: 'high@example.com' },
+      priority: 10,
+    });
+
+    // Edit only low priority jobs
+    const editedCount = await queue.editAllPendingJobs<
+      { email: { to: string } },
+      'email'
+    >(
+      pool,
+      { priority: 1 },
+      {
+        priority: 5,
+      },
+    );
+    expect(editedCount).toBeGreaterThanOrEqual(2);
+
+    const lowJob1 = await queue.getJob(pool, lowPriorityJobId1);
+    const lowJob2 = await queue.getJob(pool, lowPriorityJobId2);
+    const highJob = await queue.getJob(pool, highPriorityJobId);
+    expect(lowJob1?.priority).toBe(5);
+    expect(lowJob2?.priority).toBe(5);
+    expect(highJob?.priority).toBe(10);
+  });
+
+  it('should edit pending jobs filtered by tags', async () => {
+    const taggedJobId1 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'tagged1@example.com' },
+        tags: ['urgent', 'priority'],
+      },
+    );
+    const taggedJobId2 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'tagged2@example.com' },
+        tags: ['urgent', 'priority'],
+      },
+    );
+    const untaggedJobId = await queue.addJob<
+      { email: { to: string } },
+      'email'
+    >(pool, {
+      jobType: 'email',
+      payload: { to: 'untagged@example.com' },
+      tags: ['other'],
+    });
+
+    // Edit only jobs with 'urgent' tag
+    const editedCount = await queue.editAllPendingJobs<
+      { email: { to: string } },
+      'email'
+    >(
+      pool,
+      { tags: { values: ['urgent'], mode: 'any' } },
+      {
+        priority: 10,
+      },
+    );
+    expect(editedCount).toBeGreaterThanOrEqual(2);
+
+    const taggedJob1 = await queue.getJob(pool, taggedJobId1);
+    const taggedJob2 = await queue.getJob(pool, taggedJobId2);
+    const untaggedJob = await queue.getJob(pool, untaggedJobId);
+    expect(taggedJob1?.priority).toBe(10);
+    expect(taggedJob2?.priority).toBe(10);
+    expect(untaggedJob?.priority).toBe(0);
+  });
+
+  it('should edit pending jobs filtered by runAt', async () => {
+    const futureDate = new Date(Date.now() + 60000);
+    const pastDate = new Date(Date.now() - 60000);
+
+    const futureJobId1 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'future1@example.com' },
+        runAt: futureDate,
+      },
+    );
+    const futureJobId2 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'future2@example.com' },
+        runAt: futureDate,
+      },
+    );
+    const pastJobId = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'past@example.com' },
+        runAt: pastDate,
+      },
+    );
+
+    // Edit only jobs scheduled in the future
+    const editedCount = await queue.editAllPendingJobs<
+      { email: { to: string } },
+      'email'
+    >(
+      pool,
+      { runAt: { gte: new Date() } },
+      {
+        priority: 10,
+      },
+    );
+    expect(editedCount).toBeGreaterThanOrEqual(2);
+
+    const futureJob1 = await queue.getJob(pool, futureJobId1);
+    const futureJob2 = await queue.getJob(pool, futureJobId2);
+    const pastJob = await queue.getJob(pool, pastJobId);
+    expect(futureJob1?.priority).toBe(10);
+    expect(futureJob2?.priority).toBe(10);
+    expect(pastJob?.priority).toBe(0);
+  });
+
+  it('should not edit non-pending jobs', async () => {
+    // Create processingJobId first so it gets picked up by getNextBatch
+    const processingJobId = await queue.addJob<
+      { email: { to: string } },
+      'email'
+    >(pool, {
+      jobType: 'email',
+      payload: { to: 'processing@example.com' },
+      priority: 0,
+    });
+    const pendingJobId = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'pending@example.com' },
+        priority: 0,
+      },
+    );
+    // Mark as processing (this will pick up processingJobId since it was created first)
+    await queue.getNextBatch(pool, 'worker-batch', 1);
+    const completedJobId = await queue.addJob<
+      { email: { to: string } },
+      'email'
+    >(pool, {
+      jobType: 'email',
+      payload: { to: 'completed@example.com' },
+      priority: 0,
+    });
+    // Set to completed via SQL (bypassing status check since we're testing edit behavior)
+    await pool.query(
+      `UPDATE job_queue SET status = 'completed' WHERE id = $1`,
+      [completedJobId],
+    );
+
+    // Edit all pending jobs
+    const editedCount = await queue.editAllPendingJobs<
+      { email: { to: string } },
+      'email'
+    >(pool, undefined, {
+      priority: 10,
+    });
+
+    const pendingJob = await queue.getJob(pool, pendingJobId);
+    const processingJob = await queue.getJob(pool, processingJobId);
+    const completedJob = await queue.getJob(pool, completedJobId);
+    expect(pendingJob?.priority).toBe(10);
+    expect(processingJob?.priority).toBe(0);
+    expect(completedJob?.priority).toBe(0);
+    expect(editedCount).toBeGreaterThanOrEqual(1);
+  });
+
+  it('should record edit events for each edited job', async () => {
+    const jobId1 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'event1@example.com' },
+      },
+    );
+    const jobId2 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'event2@example.com' },
+      },
+    );
+
+    await queue.editAllPendingJobs<{ email: { to: string } }, 'email'>(
+      pool,
+      undefined,
+      {
+        priority: 10,
+      },
+    );
+
+    const events1 = await queue.getJobEvents(pool, jobId1);
+    const events2 = await queue.getJobEvents(pool, jobId2);
+    const editEvent1 = events1.find((e) => e.eventType === JobEventType.Edited);
+    const editEvent2 = events2.find((e) => e.eventType === JobEventType.Edited);
+    expect(editEvent1).not.toBeUndefined();
+    expect(editEvent2).not.toBeUndefined();
+    expect(editEvent1?.metadata).toMatchObject({ priority: 10 });
+    expect(editEvent2?.metadata).toMatchObject({ priority: 10 });
+  });
+
+  it('should return 0 when no fields to update', async () => {
+    await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'empty@example.com' },
+    });
+
+    const editedCount = await queue.editAllPendingJobs<
+      { email: { to: string } },
+      'email'
+    >(pool, undefined, {});
+
+    expect(editedCount).toBe(0);
+  });
+
   it('should cancel all upcoming jobs', async () => {
     // Add three pending jobs
     const jobId1 = await queue.addJob<{ email: { to: string } }, 'email'>(
@@ -183,7 +718,7 @@ describe('queue integration', () => {
         payload: { to: 'cancelall3@example.com' },
       },
     );
-    // Add a completed job
+    // Add a completed job (set via SQL since this test is about cancel behavior)
     const jobId4 = await queue.addJob<{ email: { to: string } }, 'email'>(
       pool,
       {
@@ -191,7 +726,10 @@ describe('queue integration', () => {
         payload: { to: 'done@example.com' },
       },
     );
-    await queue.completeJob(pool, jobId4);
+    await pool.query(
+      `UPDATE job_queue SET status = 'completed' WHERE id = $1`,
+      [jobId4],
+    );
 
     // Cancel all upcoming jobs
     const cancelledCount = await queue.cancelAllUpcomingJobs(pool);
@@ -287,8 +825,12 @@ describe('queue integration', () => {
       jobType: 'email',
       payload: { to: 'failhistory@example.com' },
     });
-    // Fail the job twice with different errors
+    // Claim and fail the job (first error)
+    await queue.getNextBatch(pool, 'worker-fail-1', 1);
     await queue.failJob(pool, jobId, new Error('first error'));
+    // Retry, claim again, and fail again (second error)
+    await queue.retryJob(pool, jobId);
+    await queue.getNextBatch(pool, 'worker-fail-2', 1);
     await queue.failJob(pool, jobId, new Error('second error'));
     const job = await queue.getJob(pool, jobId);
     expect(job?.status).toBe('failed');
@@ -321,6 +863,50 @@ describe('queue integration', () => {
     expect(job?.lockedAt).toBeNull();
     expect(job?.lockedBy).toBeNull();
   });
+
+  it('should not reclaim a job whose timeoutMs exceeds the reclaim threshold', async () => {
+    // Add a job with a 30-minute timeout
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'long-timeout@example.com' },
+      timeoutMs: 30 * 60 * 1000, // 30 minutes
+    });
+    // Simulate: processing for 15 minutes (exceeds 10-min global threshold but within 30-min job timeout)
+    await pool.query(
+      `UPDATE job_queue SET status = 'processing', locked_at = NOW() - INTERVAL '15 minutes' WHERE id = $1`,
+      [jobId],
+    );
+    let job = await queue.getJob(pool, jobId);
+    expect(job?.status).toBe('processing');
+
+    // Reclaim with 10-minute global threshold — should NOT reclaim this job
+    const reclaimed = await queue.reclaimStuckJobs(pool, 10);
+    expect(reclaimed).toBe(0);
+    job = await queue.getJob(pool, jobId);
+    expect(job?.status).toBe('processing');
+  });
+
+  it('should reclaim a job whose timeoutMs has also been exceeded', async () => {
+    // Add a job with a 20-minute timeout
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'expired-timeout@example.com' },
+      timeoutMs: 20 * 60 * 1000, // 20 minutes
+    });
+    // Simulate: processing for 25 minutes (exceeds both 10-min threshold and 20-min job timeout)
+    await pool.query(
+      `UPDATE job_queue SET status = 'processing', locked_at = NOW() - INTERVAL '25 minutes' WHERE id = $1`,
+      [jobId],
+    );
+    let job = await queue.getJob(pool, jobId);
+    expect(job?.status).toBe('processing');
+
+    // Reclaim with 10-minute global threshold — should reclaim since 25 min > 20 min timeout
+    const reclaimed = await queue.reclaimStuckJobs(pool, 10);
+    expect(reclaimed).toBeGreaterThanOrEqual(1);
+    job = await queue.getJob(pool, jobId);
+    expect(job?.status).toBe('pending');
+  });
 });
 
 describe('job event tracking', () => {
@@ -1196,4 +1782,151 @@ describe('getJobs', () => {
     expect(jobs.map((j) => j.id)).toContain(id1);
     expect(jobs.map((j) => j.id)).not.toContain(id2);
   });
+
+  // --- Idempotency tests ---
+
+  it('should store and return idempotencyKey when provided', async () => {
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'test@example.com' },
+      idempotencyKey: 'unique-key-1',
+    });
+    const job = await queue.getJob(pool, jobId);
+    expect(job).not.toBeNull();
+    expect(job?.idempotencyKey).toBe('unique-key-1');
+  });
+
+  it('should return the same job ID when adding a job with a duplicate idempotencyKey', async () => {
+    const jobId1 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'first@example.com' },
+        idempotencyKey: 'dedup-key',
+      },
+    );
+    const jobId2 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'second@example.com' },
+        idempotencyKey: 'dedup-key',
+      },
+    );
+    expect(jobId1).toBe(jobId2);
+
+    // The original job's payload should be preserved (not updated)
+    const job = await queue.getJob(pool, jobId1);
+    expect(job?.payload).toEqual({ to: 'first@example.com' });
+  });
+
+  it('should create separate jobs when no idempotencyKey is provided', async () => {
+    const jobId1 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'a@example.com' },
+      },
+    );
+    const jobId2 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'a@example.com' },
+      },
+    );
+    expect(jobId1).not.toBe(jobId2);
+  });
+
+  it('should create separate jobs when different idempotencyKeys are provided', async () => {
+    const jobId1 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'same@example.com' },
+        idempotencyKey: 'key-a',
+      },
+    );
+    const jobId2 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'same@example.com' },
+        idempotencyKey: 'key-b',
+      },
+    );
+    expect(jobId1).not.toBe(jobId2);
+  });
+
+  it('should only record the added event once for duplicate idempotencyKey', async () => {
+    const jobId1 = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'once@example.com' },
+        idempotencyKey: 'event-dedup-key',
+      },
+    );
+    // Add again with same key
+    await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'twice@example.com' },
+      idempotencyKey: 'event-dedup-key',
+    });
+
+    const events = await queue.getJobEvents(pool, jobId1);
+    const addedEvents = events.filter(
+      (e: JobEvent) => e.eventType === JobEventType.Added,
+    );
+    expect(addedEvents.length).toBe(1);
+  });
+
+  it('should return null idempotencyKey for jobs created without one', async () => {
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'nokey@example.com' },
+    });
+    const job = await queue.getJob(pool, jobId);
+    expect(job).not.toBeNull();
+    expect(job?.idempotencyKey).toBeNull();
+  });
+
+  it('should permanently fail a job when max attempts are exhausted', async () => {
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'exhaust@example.com' },
+      maxAttempts: 2,
+    });
+
+    // Claim the job (attempt 1)
+    const batch1 = await queue.getNextBatch(pool, 'worker-1', 1);
+    expect(batch1.length).toBe(1);
+    expect(batch1[0].attempts).toBe(1);
+
+    // Fail it
+    await queue.failJob(pool, jobId, new Error('attempt 1 failed'));
+    let job = await queue.getJob(pool, jobId);
+    expect(job?.status).toBe('failed');
+    expect(job?.nextAttemptAt).not.toBeNull(); // Should have a retry scheduled
+
+    // Wait a moment so next_attempt_at <= NOW() and claim again (attempt 2)
+    await pool.query(
+      `UPDATE job_queue SET next_attempt_at = NOW() WHERE id = $1`,
+      [jobId],
+    );
+    const batch2 = await queue.getNextBatch(pool, 'worker-1', 1);
+    expect(batch2.length).toBe(1);
+    expect(batch2[0].attempts).toBe(2);
+
+    // Fail it again — now attempts === maxAttempts
+    await queue.failJob(pool, jobId, new Error('attempt 2 failed'));
+    job = await queue.getJob(pool, jobId);
+    expect(job?.status).toBe('failed');
+    expect(job?.nextAttemptAt).toBeNull(); // No more retries
+    expect(job?.errorHistory?.length).toBe(2);
+
+    // Should NOT be picked up again
+    const batch3 = await queue.getNextBatch(pool, 'worker-1', 1);
+    expect(batch3.length).toBe(0);
+  });
 });