@nicnocquee/dataqueue 1.24.0 → 1.26.0-beta.20260223195940

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(
@@ -137,6 +141,35 @@ describe('queue integration', () => {
     expect(job).toBeNull();
   });
 
+  it('should cleanup old completed jobs in batches', async () => {
+    // Add and complete 5 jobs
+    const ids: number[] = [];
+    for (let i = 0; i < 5; i++) {
+      const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(
+        pool,
+        {
+          jobType: 'email',
+          payload: { to: `batch-${i}@example.com` },
+        },
+      );
+      await queue.getNextBatch(pool, 'worker-batch-cleanup', 1);
+      await queue.completeJob(pool, jobId);
+      ids.push(jobId);
+    }
+    // Manually backdate all 5
+    await pool.query(
+      `UPDATE job_queue SET updated_at = NOW() - INTERVAL '31 days' WHERE id = ANY($1::int[])`,
+      [ids],
+    );
+    // Cleanup with batchSize=2 so it takes multiple iterations
+    const deleted = await queue.cleanupOldJobs(pool, 30, 2);
+    expect(deleted).toBe(5);
+    for (const id of ids) {
+      const job = await queue.getJob(pool, id);
+      expect(job).toBeNull();
+    }
+  });
+
   it('should cancel a scheduled job', async () => {
     const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
       jobType: 'email',
@@ -154,6 +187,7 @@ 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);
@@ -229,6 +263,7 @@ describe('queue integration', () => {
       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
@@ -367,7 +402,7 @@ describe('queue integration', () => {
         priority: 0,
       },
     );
-    // Add a completed job
+    // Add a completed job (set via SQL since this test is about edit behavior)
     const jobId4 = await queue.addJob<{ email: { to: string } }, 'email'>(
       pool,
       {
@@ -375,7 +410,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],
+    );
 
     // Edit all pending jobs
     const editedCount = await queue.editAllPendingJobs<
@@ -615,7 +653,11 @@ describe('queue integration', () => {
       payload: { to: 'completed@example.com' },
       priority: 0,
     });
-    await queue.completeJob(pool, completedJobId);
+    // 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<
@@ -705,7 +747,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,
       {
@@ -713,7 +755,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);
@@ -809,8 +854,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');
@@ -843,6 +892,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', () => {
@@ -1718,4 +1811,587 @@ 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);
+  });
+
+  // ── Configurable retry strategy tests ────────────────────────────────
+
+  it('uses legacy backoff when no retry config is set', async () => {
+    // Setup
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'legacy@example.com' },
+      maxAttempts: 3,
+    });
+
+    // Act
+    await queue.getNextBatch(pool, 'worker-1', 1);
+    await queue.failJob(pool, jobId, new Error('fail'));
+
+    // Assert — legacy formula: 2^1 * 60s = 120s from now
+    const job = await queue.getJob(pool, jobId);
+    expect(job?.nextAttemptAt).not.toBeNull();
+    const delaySec =
+      (job!.nextAttemptAt!.getTime() - job!.lastFailedAt!.getTime()) / 1000;
+    expect(delaySec).toBeGreaterThanOrEqual(115);
+    expect(delaySec).toBeLessThanOrEqual(125);
+  });
+
+  it('uses fixed delay when retryBackoff is false', async () => {
+    // Setup
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'fixed@example.com' },
+      maxAttempts: 3,
+      retryDelay: 10,
+      retryBackoff: false,
+    });
+
+    // Act
+    await queue.getNextBatch(pool, 'worker-1', 1);
+    await queue.failJob(pool, jobId, new Error('fail'));
+
+    // Assert — fixed 10s delay
+    const job = await queue.getJob(pool, jobId);
+    expect(job?.nextAttemptAt).not.toBeNull();
+    expect(job?.retryDelay).toBe(10);
+    expect(job?.retryBackoff).toBe(false);
+    const delaySec =
+      (job!.nextAttemptAt!.getTime() - job!.lastFailedAt!.getTime()) / 1000;
+    expect(delaySec).toBeGreaterThanOrEqual(9);
+    expect(delaySec).toBeLessThanOrEqual(11);
+  });
+
+  it('uses exponential backoff with custom retryDelay', async () => {
+    // Setup
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'expo@example.com' },
+      maxAttempts: 3,
+      retryDelay: 5,
+      retryBackoff: true,
+    });
+
+    // Act — attempt 1
+    await queue.getNextBatch(pool, 'worker-1', 1);
+    await queue.failJob(pool, jobId, new Error('fail'));
+
+    // Assert — exponential: 5 * 2^1 = 10s, with jitter [5, 10]
+    const job = await queue.getJob(pool, jobId);
+    expect(job?.nextAttemptAt).not.toBeNull();
+    const delaySec =
+      (job!.nextAttemptAt!.getTime() - job!.lastFailedAt!.getTime()) / 1000;
+    expect(delaySec).toBeGreaterThanOrEqual(4);
+    expect(delaySec).toBeLessThanOrEqual(11);
+  });
+
+  it('caps exponential backoff with retryDelayMax', async () => {
+    // Setup
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'capped@example.com' },
+      maxAttempts: 5,
+      retryDelay: 100,
+      retryBackoff: true,
+      retryDelayMax: 30,
+    });
+
+    // Act — attempt 1
+    await queue.getNextBatch(pool, 'worker-1', 1);
+    await queue.failJob(pool, jobId, new Error('fail'));
+
+    // Assert — 100 * 2^1 = 200s but capped at 30s, with jitter [15, 30]
+    const job = await queue.getJob(pool, jobId);
+    expect(job?.nextAttemptAt).not.toBeNull();
+    expect(job?.retryDelayMax).toBe(30);
+    const delaySec =
+      (job!.nextAttemptAt!.getTime() - job!.lastFailedAt!.getTime()) / 1000;
+    expect(delaySec).toBeGreaterThanOrEqual(14);
+    expect(delaySec).toBeLessThanOrEqual(31);
+  });
+
+  it('stores retry config on job record', async () => {
+    // Setup
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'config@example.com' },
+      retryDelay: 30,
+      retryBackoff: false,
+      retryDelayMax: 120,
+    });
+
+    // Act
+    const job = await queue.getJob(pool, jobId);
+
+    // Assert
+    expect(job?.retryDelay).toBe(30);
+    expect(job?.retryBackoff).toBe(false);
+    expect(job?.retryDelayMax).toBe(120);
+  });
+
+  it('returns null retry config for jobs without it', async () => {
+    // Setup
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'noconfig@example.com' },
+    });
+
+    // Act
+    const job = await queue.getJob(pool, jobId);
+
+    // Assert
+    expect(job?.retryDelay).toBeNull();
+    expect(job?.retryBackoff).toBeNull();
+    expect(job?.retryDelayMax).toBeNull();
+  });
+
+  it('allows editing retry config via editJob', async () => {
+    // Setup
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(pool, {
+      jobType: 'email',
+      payload: { to: 'edit@example.com' },
+    });
+
+    // Act
+    await queue.editJob(pool, jobId, {
+      retryDelay: 15,
+      retryBackoff: false,
+      retryDelayMax: 60,
+    });
+
+    // Assert
+    const job = await queue.getJob(pool, jobId);
+    expect(job?.retryDelay).toBe(15);
+    expect(job?.retryBackoff).toBe(false);
+    expect(job?.retryDelayMax).toBe(60);
+  });
+});
+
+describe('queue.addJob with db option (BYOC)', () => {
+  let pool: Pool;
+  let dbName: string;
+
+  beforeEach(async () => {
+    const setup = await createTestDbAndPool();
+    pool = setup.pool;
+    dbName = setup.dbName;
+  });
+
+  afterEach(async () => {
+    await pool.end();
+    await destroyTestDb(dbName);
+  });
+
+  it('rolls back the job when the transaction is rolled back', async () => {
+    // Setup
+    const client = await pool.connect();
+    await client.query('BEGIN');
+
+    // Act
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      { jobType: 'email', payload: { to: 'rollback@example.com' } },
+      { db: client },
+    );
+    await client.query('ROLLBACK');
+    client.release();
+
+    // Assert
+    const job = await queue.getJob(pool, jobId);
+    expect(job).toBeNull();
+  });
+
+  it('persists the job when the transaction is committed', async () => {
+    // Setup
+    const client = await pool.connect();
+    await client.query('BEGIN');
+
+    // Act
+    const jobId = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      { jobType: 'email', payload: { to: 'commit@example.com' } },
+      { db: client },
+    );
+    await client.query('COMMIT');
+    client.release();
+
+    // Assert
+    const job = await queue.getJob(pool, jobId);
+    expect(job).not.toBeNull();
+    expect(job?.payload).toEqual({ to: 'commit@example.com' });
+  });
+});
+
+describe('addJobs batch insert', () => {
+  let pool: Pool;
+  let dbName: string;
+
+  beforeEach(async () => {
+    const setup = await createTestDbAndPool();
+    pool = setup.pool;
+    dbName = setup.dbName;
+  });
+
+  afterEach(async () => {
+    await pool.end();
+    await destroyTestDb(dbName);
+  });
+
+  it('inserts multiple jobs and returns IDs in order', async () => {
+    // Act
+    const ids = await queue.addJobs<
+      { email: { to: string }; report: { id: string } },
+      'email' | 'report'
+    >(pool, [
+      { jobType: 'email', payload: { to: 'a@test.com' } },
+      { jobType: 'report', payload: { id: 'r1' } },
+      { jobType: 'email', payload: { to: 'b@test.com' } },
+    ]);
+
+    // Assert
+    expect(ids).toHaveLength(3);
+    expect(ids[0]).toBeLessThan(ids[1]);
+    expect(ids[1]).toBeLessThan(ids[2]);
+
+    const job0 = await queue.getJob(pool, ids[0]);
+    expect(job0?.jobType).toBe('email');
+    expect(job0?.payload).toEqual({ to: 'a@test.com' });
+
+    const job1 = await queue.getJob(pool, ids[1]);
+    expect(job1?.jobType).toBe('report');
+    expect(job1?.payload).toEqual({ id: 'r1' });
+
+    const job2 = await queue.getJob(pool, ids[2]);
+    expect(job2?.jobType).toBe('email');
+    expect(job2?.payload).toEqual({ to: 'b@test.com' });
+  });
+
+  it('returns empty array for empty input', async () => {
+    // Act
+    const ids = await queue.addJobs(pool, []);
+
+    // Assert
+    expect(ids).toEqual([]);
+  });
+
+  it('respects priority and runAt per job', async () => {
+    // Setup
+    const futureDate = new Date(Date.now() + 60_000);
+
+    // Act
+    const ids = await queue.addJobs<{ task: { n: number } }, 'task'>(pool, [
+      { jobType: 'task', payload: { n: 1 }, priority: 5 },
+      { jobType: 'task', payload: { n: 2 }, priority: 10, runAt: futureDate },
+    ]);
+
+    // Assert
+    const job0 = await queue.getJob(pool, ids[0]);
+    expect(job0?.priority).toBe(5);
+
+    const job1 = await queue.getJob(pool, ids[1]);
+    expect(job1?.priority).toBe(10);
+    expect(job1?.runAt.getTime()).toBeCloseTo(futureDate.getTime(), -3);
+  });
+
+  it('handles idempotency keys for new jobs', async () => {
+    // Act
+    const ids = await queue.addJobs<{ task: { n: number } }, 'task'>(pool, [
+      { jobType: 'task', payload: { n: 1 }, idempotencyKey: 'key-a' },
+      { jobType: 'task', payload: { n: 2 }, idempotencyKey: 'key-b' },
+    ]);
+
+    // Assert
+    expect(ids).toHaveLength(2);
+    expect(ids[0]).not.toBe(ids[1]);
+
+    const job0 = await queue.getJob(pool, ids[0]);
+    expect(job0?.idempotencyKey).toBe('key-a');
+
+    const job1 = await queue.getJob(pool, ids[1]);
+    expect(job1?.idempotencyKey).toBe('key-b');
+  });
+
+  it('returns existing IDs for conflicting idempotency keys', async () => {
+    // Setup — insert a job first
+    const existingId = await queue.addJob<{ task: { n: number } }, 'task'>(
+      pool,
+      { jobType: 'task', payload: { n: 0 }, idempotencyKey: 'dup-key' },
+    );
+
+    // Act — batch includes a duplicate key
+    const ids = await queue.addJobs<{ task: { n: number } }, 'task'>(pool, [
+      { jobType: 'task', payload: { n: 1 } },
+      { jobType: 'task', payload: { n: 2 }, idempotencyKey: 'dup-key' },
+      { jobType: 'task', payload: { n: 3 } },
+    ]);
+
+    // Assert
+    expect(ids).toHaveLength(3);
+    expect(ids[1]).toBe(existingId);
+    expect(ids[0]).not.toBe(existingId);
+    expect(ids[2]).not.toBe(existingId);
+  });
+
+  it('handles mix of keyed and non-keyed jobs', async () => {
+    // Act
+    const ids = await queue.addJobs<{ task: { n: number } }, 'task'>(pool, [
+      { jobType: 'task', payload: { n: 1 } },
+      { jobType: 'task', payload: { n: 2 }, idempotencyKey: 'mix-1' },
+      { jobType: 'task', payload: { n: 3 } },
+      { jobType: 'task', payload: { n: 4 }, idempotencyKey: 'mix-2' },
+      { jobType: 'task', payload: { n: 5 } },
+    ]);
+
+    // Assert
+    expect(ids).toHaveLength(5);
+    const uniqueIds = new Set(ids);
+    expect(uniqueIds.size).toBe(5);
+
+    const job1 = await queue.getJob(pool, ids[1]);
+    expect(job1?.idempotencyKey).toBe('mix-1');
+
+    const job3 = await queue.getJob(pool, ids[3]);
+    expect(job3?.idempotencyKey).toBe('mix-2');
+  });
+
+  it('records added events only for newly inserted jobs', async () => {
+    // Setup — pre-insert a job with a known key
+    const existingId = await queue.addJob<{ task: { n: number } }, 'task'>(
+      pool,
+      { jobType: 'task', payload: { n: 0 }, idempotencyKey: 'evt-key' },
+    );
+
+    // Act
+    const ids = await queue.addJobs<{ task: { n: number } }, 'task'>(pool, [
+      { jobType: 'task', payload: { n: 1 } },
+      { jobType: 'task', payload: { n: 2 }, idempotencyKey: 'evt-key' },
+    ]);
+
+    // Assert — the new job should have an event from addJobs
+    const events0 = await queue.getJobEvents(pool, ids[0]);
+    const addedEvents0 = events0.filter(
+      (e: JobEvent) => e.eventType === JobEventType.Added,
+    );
+    expect(addedEvents0).toHaveLength(1);
+
+    // The duplicate should only have the original event from addJob, not a second from addJobs
+    const eventsExisting = await queue.getJobEvents(pool, existingId);
+    const addedEventsExisting = eventsExisting.filter(
+      (e: JobEvent) => e.eventType === JobEventType.Added,
+    );
+    expect(addedEventsExisting).toHaveLength(1);
+  });
+
+  it('stores tags correctly per job', async () => {
+    // Act
+    const ids = await queue.addJobs<{ task: { n: number } }, 'task'>(pool, [
+      { jobType: 'task', payload: { n: 1 }, tags: ['urgent', 'billing'] },
+      { jobType: 'task', payload: { n: 2 }, tags: ['low-priority'] },
+      { jobType: 'task', payload: { n: 3 } },
+    ]);
+
+    // Assert
+    const job0 = await queue.getJob(pool, ids[0]);
+    expect(job0?.tags).toEqual(['urgent', 'billing']);
+
+    const job1 = await queue.getJob(pool, ids[1]);
+    expect(job1?.tags).toEqual(['low-priority']);
+
+    const job2 = await queue.getJob(pool, ids[2]);
+    expect(job2?.tags).toBeNull();
+  });
+
+  it('works with transactional db option — commit', async () => {
+    // Setup
+    const client = await pool.connect();
+    await client.query('BEGIN');
+
+    // Act
+    const ids = await queue.addJobs<{ task: { n: number } }, 'task'>(
+      pool,
+      [
+        { jobType: 'task', payload: { n: 1 } },
+        { jobType: 'task', payload: { n: 2 } },
+      ],
+      { db: client },
+    );
+    await client.query('COMMIT');
+    client.release();
+
+    // Assert
+    expect(ids).toHaveLength(2);
+    const job0 = await queue.getJob(pool, ids[0]);
+    expect(job0).not.toBeNull();
+    const job1 = await queue.getJob(pool, ids[1]);
+    expect(job1).not.toBeNull();
+  });
+
+  it('works with transactional db option — rollback', async () => {
+    // Setup
+    const client = await pool.connect();
+    await client.query('BEGIN');
+
+    // Act
+    const ids = await queue.addJobs<{ task: { n: number } }, 'task'>(
+      pool,
+      [
+        { jobType: 'task', payload: { n: 1 } },
+        { jobType: 'task', payload: { n: 2 } },
+      ],
+      { db: client },
+    );
+    await client.query('ROLLBACK');
+    client.release();
+
+    // Assert — jobs should not exist after rollback
+    const job0 = await queue.getJob(pool, ids[0]);
+    expect(job0).toBeNull();
+    const job1 = await queue.getJob(pool, ids[1]);
+    expect(job1).toBeNull();
+  });
 });