@nicnocquee/dataqueue 1.25.0 → 1.26.0-beta.20260223202259

package/src/backends/redis.test.ts

@@ -383,6 +383,46 @@ describe('Redis backend integration', () => {
     expect(job).toBeNull();
   });
 
+  it('should cleanup old completed jobs in batches', async () => {
+    const ids: number[] = [];
+    for (let i = 0; i < 5; i++) {
+      const jobId = await jobQueue.addJob({
+        jobType: 'test',
+        payload: { foo: `batch-${i}` },
+      });
+      ids.push(jobId);
+    }
+    // Complete all jobs
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {}),
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+    for (const id of ids) {
+      const job = await jobQueue.getJob(id);
+      expect(job?.status).toBe('completed');
+    }
+
+    // Backdate all to 31 days ago
+    const oldMs = Date.now() - 31 * 24 * 60 * 60 * 1000;
+    for (const id of ids) {
+      await redisClient.hset(
+        `${prefix}job:${id}`,
+        'updatedAt',
+        oldMs.toString(),
+      );
+    }
+
+    // Cleanup with small batchSize to force multiple SSCAN iterations
+    const deleted = await jobQueue.cleanupOldJobs(30, 2);
+    expect(deleted).toBe(5);
+    for (const id of ids) {
+      const job = await jobQueue.getJob(id);
+      expect(job).toBeNull();
+    }
+  });
+
   it('should reclaim stuck jobs', async () => {
     const jobId = await jobQueue.addJob({
       jobType: 'email',
@@ -540,4 +580,1496 @@ describe('Redis backend integration', () => {
     const job = await jobQueue.getJob(jobId);
     expect(job?.status).toBe('pending');
   });
+
+  // ── Configurable retry strategy tests ────────────────────────────────
+
+  it('stores retry config on a job', async () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'retry-config@example.com' },
+      retryDelay: 30,
+      retryBackoff: false,
+      retryDelayMax: 120,
+    });
+
+    const job = await jobQueue.getJob(jobId);
+    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 () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'no-retry-config@example.com' },
+    });
+
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.retryDelay).toBeNull();
+    expect(job?.retryBackoff).toBeNull();
+    expect(job?.retryDelayMax).toBeNull();
+  });
+
+  it('uses legacy backoff when no retry config is set', async () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'legacy-retry@example.com' },
+      maxAttempts: 3,
+    });
+
+    const handler = vi.fn(async () => {
+      throw new Error('fail');
+    });
+    const processor = jobQueue.createProcessor({
+      email: handler,
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('failed');
+    expect(job?.nextAttemptAt).not.toBeNull();
+    const delayMs =
+      job!.nextAttemptAt!.getTime() - job!.lastFailedAt!.getTime();
+    // Legacy: 2^1 * 60s = 120s = 120000ms
+    expect(delayMs).toBeGreaterThanOrEqual(115000);
+    expect(delayMs).toBeLessThanOrEqual(125000);
+  });
+
+  it('uses fixed delay when retryBackoff is false', async () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'fixed-retry@example.com' },
+      maxAttempts: 3,
+      retryDelay: 10,
+      retryBackoff: false,
+    });
+
+    const handler = vi.fn(async () => {
+      throw new Error('fail');
+    });
+    const processor = jobQueue.createProcessor({
+      email: handler,
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('failed');
+    expect(job?.nextAttemptAt).not.toBeNull();
+    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 () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'expo-retry@example.com' },
+      maxAttempts: 3,
+      retryDelay: 5,
+      retryBackoff: true,
+    });
+
+    const handler = vi.fn(async () => {
+      throw new Error('fail');
+    });
+    const processor = jobQueue.createProcessor({
+      email: handler,
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('failed');
+    expect(job?.nextAttemptAt).not.toBeNull();
+    // 5 * 2^1 = 10s, with jitter [5, 10]
+    const delaySec =
+      (job!.nextAttemptAt!.getTime() - job!.lastFailedAt!.getTime()) / 1000;
+    expect(delaySec).toBeGreaterThanOrEqual(4);
+    expect(delaySec).toBeLessThanOrEqual(11);
+  });
+
+  it('caps exponential backoff with retryDelayMax', async () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'capped-retry@example.com' },
+      maxAttempts: 5,
+      retryDelay: 100,
+      retryBackoff: true,
+      retryDelayMax: 30,
+    });
+
+    const handler = vi.fn(async () => {
+      throw new Error('fail');
+    });
+    const processor = jobQueue.createProcessor({
+      email: handler,
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('failed');
+    expect(job?.nextAttemptAt).not.toBeNull();
+    // 100 * 2^1 = 200 capped to 30, with jitter [15, 30]
+    const delaySec =
+      (job!.nextAttemptAt!.getTime() - job!.lastFailedAt!.getTime()) / 1000;
+    expect(delaySec).toBeGreaterThanOrEqual(14);
+    expect(delaySec).toBeLessThanOrEqual(31);
+  });
+
+  it('allows editing retry config via editJob', async () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'edit-retry@example.com' },
+    });
+
+    await jobQueue.editJob(jobId, {
+      retryDelay: 15,
+      retryBackoff: false,
+      retryDelayMax: 60,
+    });
+
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.retryDelay).toBe(15);
+    expect(job?.retryBackoff).toBe(false);
+    expect(job?.retryDelayMax).toBe(60);
+  });
+});
+
+describe('Redis cron schedules integration', () => {
+  let prefix: string;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+  let redisClient: any;
+
+  beforeEach(async () => {
+    prefix = createRedisTestPrefix();
+    const config: RedisJobQueueConfig = {
+      backend: 'redis',
+      redisConfig: {
+        url: REDIS_URL,
+        keyPrefix: prefix,
+      },
+    };
+    jobQueue = initJobQueue<TestPayloadMap>(config);
+    redisClient = jobQueue.getRedisClient();
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await cleanupRedisPrefix(redisClient, prefix);
+    await redisClient.quit();
+  });
+
+  it('creates a cron schedule and retrieves it by ID', async () => {
+    // Act
+    const id = await jobQueue.addCronJob({
+      scheduleName: 'every-5-min-email',
+      cronExpression: '*/5 * * * *',
+      jobType: 'email',
+      payload: { to: 'cron@example.com' },
+    });
+
+    // Assert
+    const schedule = await jobQueue.getCronJob(id);
+    expect(schedule).not.toBeNull();
+    expect(schedule!.scheduleName).toBe('every-5-min-email');
+    expect(schedule!.cronExpression).toBe('*/5 * * * *');
+    expect(schedule!.jobType).toBe('email');
+    expect(schedule!.payload).toEqual({ to: 'cron@example.com' });
+    expect(schedule!.status).toBe('active');
+    expect(schedule!.allowOverlap).toBe(false);
+    expect(schedule!.timezone).toBe('UTC');
+    expect(schedule!.nextRunAt).toBeInstanceOf(Date);
+  });
+
+  it('retrieves a cron schedule by name', async () => {
+    // Setup
+    await jobQueue.addCronJob({
+      scheduleName: 'my-schedule',
+      cronExpression: '0 * * * *',
+      jobType: 'email',
+      payload: { to: 'test@example.com' },
+    });
+
+    // Act
+    const schedule = await jobQueue.getCronJobByName('my-schedule');
+
+    // Assert
+    expect(schedule).not.toBeNull();
+    expect(schedule!.scheduleName).toBe('my-schedule');
+  });
+
+  it('returns null for nonexistent schedule', async () => {
+    // Act
+    const byId = await jobQueue.getCronJob(99999);
+    const byName = await jobQueue.getCronJobByName('nonexistent');
+
+    // Assert
+    expect(byId).toBeNull();
+    expect(byName).toBeNull();
+  });
+
+  it('rejects duplicate schedule names', async () => {
+    // Setup
+    await jobQueue.addCronJob({
+      scheduleName: 'unique-name',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'a@example.com' },
+    });
+
+    // Act & Assert
+    await expect(
+      jobQueue.addCronJob({
+        scheduleName: 'unique-name',
+        cronExpression: '*/5 * * * *',
+        jobType: 'sms',
+        payload: { to: 'b@example.com' },
+      }),
+    ).rejects.toThrow();
+  });
+
+  it('rejects invalid cron expressions', async () => {
+    // Act & Assert
+    await expect(
+      jobQueue.addCronJob({
+        scheduleName: 'bad-cron',
+        cronExpression: 'not a cron',
+        jobType: 'email',
+        payload: { to: 'a@example.com' },
+      }),
+    ).rejects.toThrow('Invalid cron expression');
+  });
+
+  it('lists active and paused schedules', async () => {
+    // Setup
+    const id1 = await jobQueue.addCronJob({
+      scheduleName: 'schedule-1',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'a@example.com' },
+    });
+    await jobQueue.addCronJob({
+      scheduleName: 'schedule-2',
+      cronExpression: '*/5 * * * *',
+      jobType: 'sms',
+      payload: { to: 'b@example.com' },
+    });
+    await jobQueue.pauseCronJob(id1);
+
+    // Act
+    const all = await jobQueue.listCronJobs();
+    const active = await jobQueue.listCronJobs('active');
+    const paused = await jobQueue.listCronJobs('paused');
+
+    // Assert
+    expect(all).toHaveLength(2);
+    expect(active).toHaveLength(1);
+    expect(active[0].scheduleName).toBe('schedule-2');
+    expect(paused).toHaveLength(1);
+    expect(paused[0].scheduleName).toBe('schedule-1');
+  });
+
+  it('pauses and resumes a schedule', async () => {
+    // Setup
+    const id = await jobQueue.addCronJob({
+      scheduleName: 'pausable',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'a@example.com' },
+    });
+
+    // Act — pause
+    await jobQueue.pauseCronJob(id);
+    const paused = await jobQueue.getCronJob(id);
+
+    // Assert
+    expect(paused!.status).toBe('paused');
+
+    // Act — resume
+    await jobQueue.resumeCronJob(id);
+    const resumed = await jobQueue.getCronJob(id);
+
+    // Assert
+    expect(resumed!.status).toBe('active');
+  });
+
+  it('edits a schedule and recalculates nextRunAt when expression changes', async () => {
+    // Setup
+    const id = await jobQueue.addCronJob({
+      scheduleName: 'editable',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'old@example.com' },
+    });
+    const before = await jobQueue.getCronJob(id);
+
+    // Act
+    await jobQueue.editCronJob(id, {
+      cronExpression: '0 0 * * *',
+      payload: { to: 'new@example.com' },
+    });
+
+    // Assert
+    const after = await jobQueue.getCronJob(id);
+    expect(after!.cronExpression).toBe('0 0 * * *');
+    expect(after!.payload).toEqual({ to: 'new@example.com' });
+    expect(after!.nextRunAt!.getTime()).not.toBe(before!.nextRunAt!.getTime());
+  });
+
+  it('removes a schedule', async () => {
+    // Setup
+    const id = await jobQueue.addCronJob({
+      scheduleName: 'removable',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'a@example.com' },
+    });
+
+    // Act
+    await jobQueue.removeCronJob(id);
+
+    // Assert
+    const removed = await jobQueue.getCronJob(id);
+    expect(removed).toBeNull();
+  });
+
+  it('enqueueDueCronJobs enqueues a job when nextRunAt is due', async () => {
+    // Setup — create schedule then force nextRunAt into the past
+    const id = await jobQueue.addCronJob({
+      scheduleName: 'due-now',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'due@example.com' },
+    });
+    const pastMs = (Date.now() - 60_000).toString();
+    await redisClient.hset(`${prefix}cron:${id}`, 'nextRunAt', pastMs);
+    await redisClient.zadd(`${prefix}cron_due`, Number(pastMs), id.toString());
+
+    // Act
+    const count = await jobQueue.enqueueDueCronJobs();
+
+    // Assert
+    expect(count).toBe(1);
+    const jobs = await jobQueue.getJobsByStatus('pending');
+    const cronJob = jobs.find(
+      (j) =>
+        j.jobType === 'email' && (j.payload as any).to === 'due@example.com',
+    );
+    expect(cronJob).toBeDefined();
+  });
+
+  it('enqueueDueCronJobs advances nextRunAt and sets lastJobId', async () => {
+    // Setup
+    const id = await jobQueue.addCronJob({
+      scheduleName: 'advance-test',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'advance@example.com' },
+    });
+    const pastMs = (Date.now() - 60_000).toString();
+    await redisClient.hset(`${prefix}cron:${id}`, 'nextRunAt', pastMs);
+    await redisClient.zadd(`${prefix}cron_due`, Number(pastMs), id.toString());
+
+    // Act
+    await jobQueue.enqueueDueCronJobs();
+
+    // Assert
+    const schedule = await jobQueue.getCronJob(id);
+    expect(schedule!.lastJobId).not.toBeNull();
+    expect(schedule!.lastEnqueuedAt).toBeInstanceOf(Date);
+    expect(schedule!.nextRunAt).toBeInstanceOf(Date);
+    expect(schedule!.nextRunAt!.getTime()).toBeGreaterThan(Date.now() - 5000);
+  });
+
+  it('enqueueDueCronJobs skips paused schedules', async () => {
+    // Setup
+    const id = await jobQueue.addCronJob({
+      scheduleName: 'paused-skip',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'paused@example.com' },
+    });
+    const pastMs = (Date.now() - 60_000).toString();
+    await redisClient.hset(`${prefix}cron:${id}`, 'nextRunAt', pastMs);
+    await redisClient.zadd(`${prefix}cron_due`, Number(pastMs), id.toString());
+    await jobQueue.pauseCronJob(id);
+
+    // Act
+    const count = await jobQueue.enqueueDueCronJobs();
+
+    // Assert
+    expect(count).toBe(0);
+  });
+
+  it('enqueueDueCronJobs skips schedules not yet due', async () => {
+    // Setup — nextRunAt is in the future by default
+    await jobQueue.addCronJob({
+      scheduleName: 'future-schedule',
+      cronExpression: '0 0 1 1 *',
+      jobType: 'email',
+      payload: { to: 'future@example.com' },
+    });
+
+    // Act
+    const count = await jobQueue.enqueueDueCronJobs();
+
+    // Assert
+    expect(count).toBe(0);
+  });
+
+  it('enqueueDueCronJobs skips when allowOverlap=false and last job is still active', async () => {
+    // Setup
+    const id = await jobQueue.addCronJob({
+      scheduleName: 'no-overlap',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'overlap@example.com' },
+      allowOverlap: false,
+    });
+    const pastMs = (Date.now() - 60_000).toString();
+    await redisClient.hset(`${prefix}cron:${id}`, 'nextRunAt', pastMs);
+    await redisClient.zadd(`${prefix}cron_due`, Number(pastMs), id.toString());
+
+    // First enqueue should succeed
+    const count1 = await jobQueue.enqueueDueCronJobs();
+    expect(count1).toBe(1);
+
+    // Force nextRunAt into the past again
+    const pastMs2 = (Date.now() - 60_000).toString();
+    await redisClient.hset(`${prefix}cron:${id}`, 'nextRunAt', pastMs2);
+    await redisClient.zadd(`${prefix}cron_due`, Number(pastMs2), id.toString());
+
+    // Act — second enqueue should be skipped because previous job is pending
+    const count2 = await jobQueue.enqueueDueCronJobs();
+
+    // Assert
+    expect(count2).toBe(0);
+  });
+
+  it('enqueueDueCronJobs enqueues when allowOverlap=true even if last job is still active', async () => {
+    // Setup
+    const id = await jobQueue.addCronJob({
+      scheduleName: 'with-overlap',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'overlap@example.com' },
+      allowOverlap: true,
+    });
+    const pastMs = (Date.now() - 60_000).toString();
+    await redisClient.hset(`${prefix}cron:${id}`, 'nextRunAt', pastMs);
+    await redisClient.zadd(`${prefix}cron_due`, Number(pastMs), id.toString());
+
+    // First enqueue
+    const count1 = await jobQueue.enqueueDueCronJobs();
+    expect(count1).toBe(1);
+
+    // Force nextRunAt into the past again
+    const pastMs2 = (Date.now() - 60_000).toString();
+    await redisClient.hset(`${prefix}cron:${id}`, 'nextRunAt', pastMs2);
+    await redisClient.zadd(`${prefix}cron_due`, Number(pastMs2), id.toString());
+
+    // Act — second enqueue should succeed because allowOverlap=true
+    const count2 = await jobQueue.enqueueDueCronJobs();
+
+    // Assert
+    expect(count2).toBe(1);
+
+    // Verify two pending jobs
+    const jobs = await jobQueue.getJobsByStatus('pending');
+    const cronJobs = jobs.filter(
+      (j) =>
+        j.jobType === 'email' &&
+        (j.payload as any).to === 'overlap@example.com',
+    );
+    expect(cronJobs).toHaveLength(2);
+  });
+});
+
+describe('Redis parity features', () => {
+  let prefix: string;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+  let redisClient: any;
+
+  beforeEach(async () => {
+    prefix = createRedisTestPrefix();
+    const config: RedisJobQueueConfig = {
+      backend: 'redis',
+      redisConfig: {
+        url: REDIS_URL,
+        keyPrefix: prefix,
+      },
+    };
+    jobQueue = initJobQueue<TestPayloadMap>(config);
+    redisClient = jobQueue.getRedisClient();
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await cleanupRedisPrefix(redisClient, prefix);
+    await redisClient.quit();
+  });
+
+  // ── Cursor-based pagination ─────────────────────────────────────────
+
+  it('getJobs supports cursor-based pagination', async () => {
+    // Setup
+    const id1 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'a@example.com' },
+    });
+    const id2 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'b@example.com' },
+    });
+    const id3 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'c@example.com' },
+    });
+
+    // Act — first page (no cursor, limit 2)
+    const page1 = await jobQueue.getJobs({}, 2);
+
+    // Assert
+    expect(page1).toHaveLength(2);
+    // Descending by id: id3, id2
+    expect(page1[0].id).toBe(id3);
+    expect(page1[1].id).toBe(id2);
+
+    // Act — second page using cursor
+    const page2 = await jobQueue.getJobs({ cursor: page1[1].id }, 2);
+
+    // Assert
+    expect(page2).toHaveLength(1);
+    expect(page2[0].id).toBe(id1);
+  });
+
+  // ── retryJob status validation ──────────────────────────────────────
+
+  it('retryJob only retries failed or processing jobs', async () => {
+    // Setup — completed job
+    const jobId = await jobQueue.addJob({
+      jobType: 'test',
+      payload: { foo: 'retry-test' },
+    });
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {}),
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+    const completedJob = await jobQueue.getJob(jobId);
+    expect(completedJob?.status).toBe('completed');
+
+    // Act — retry a completed job (should be a no-op)
+    await jobQueue.retryJob(jobId);
+
+    // Assert — still completed
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('completed');
+  });
+
+  it('retryJob retries a failed job', async () => {
+    // Setup
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'fail-retry@example.com' },
+    });
+    const processor = jobQueue.createProcessor({
+      email: async () => {
+        throw new Error('boom');
+      },
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+    const failedJob = await jobQueue.getJob(jobId);
+    expect(failedJob?.status).toBe('failed');
+
+    // Act
+    await jobQueue.retryJob(jobId);
+
+    // Assert
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('pending');
+  });
+
+  // ── cancelJob with waiting status ───────────────────────────────────
+
+  it('cancelJob cancels a waiting job', async () => {
+    // Setup — add a job and manually set it to waiting
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'waiting-cancel@example.com' },
+    });
+    const futureMs = Date.now() + 60_000;
+    await redisClient.hmset(
+      `${prefix}job:${jobId}`,
+      'status',
+      'waiting',
+      'waitUntil',
+      futureMs.toString(),
+    );
+    await redisClient.srem(`${prefix}status:pending`, jobId.toString());
+    await redisClient.sadd(`${prefix}status:waiting`, jobId.toString());
+    await redisClient.zrem(`${prefix}queue`, jobId.toString());
+
+    // Act
+    await jobQueue.cancelJob(jobId);
+
+    // Assert
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('cancelled');
+    expect(job?.waitUntil).toBeNull();
+    expect(job?.waitTokenId).toBeNull();
+  });
+
+  // ── completeJob clears wait fields ──────────────────────────────────
+
+  it('completeJob clears wait-related fields', async () => {
+    // Setup
+    const jobId = await jobQueue.addJob({
+      jobType: 'test',
+      payload: { foo: 'wait-clear' },
+    });
+    // Manually set wait fields
+    await redisClient.hmset(
+      `${prefix}job:${jobId}`,
+      'stepData',
+      JSON.stringify({ step1: { __completed: true, result: 42 } }),
+      'waitUntil',
+      (Date.now() + 60000).toString(),
+      'waitTokenId',
+      'wp_test',
+    );
+
+    // Process the job to completion
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {}),
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+
+    // Assert
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('completed');
+    expect(job?.stepData).toBeUndefined();
+    expect(job?.waitUntil).toBeNull();
+    expect(job?.waitTokenId).toBeNull();
+  });
+
+  // ── cleanupOldJobEvents ─────────────────────────────────────────────
+
+  it('cleanupOldJobEvents removes old events', async () => {
+    // Setup
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'events-cleanup@example.com' },
+    });
+
+    // Create an old event (31 days ago)
+    const oldMs = Date.now() - 31 * 24 * 60 * 60 * 1000;
+    const oldEvent = JSON.stringify({
+      id: 999,
+      jobId,
+      eventType: 'added',
+      createdAt: oldMs,
+      metadata: null,
+    });
+    await redisClient.rpush(`${prefix}events:${jobId}`, oldEvent);
+
+    // Get events before cleanup
+    const eventsBefore = await jobQueue.getJobEvents(jobId);
+    const countBefore = eventsBefore.length;
+    expect(countBefore).toBeGreaterThanOrEqual(2); // at least the original 'added' + our old event
+
+    // Act
+    const deleted = await jobQueue.cleanupOldJobEvents(30);
+
+    // Assert
+    expect(deleted).toBeGreaterThanOrEqual(1);
+    const eventsAfter = await jobQueue.getJobEvents(jobId);
+    expect(eventsAfter.length).toBeLessThan(countBefore);
+  });
+
+  it('cleanupOldJobEvents removes orphaned event lists', async () => {
+    // Setup — create events for a non-existent job
+    const orphanEvent = JSON.stringify({
+      id: 888,
+      jobId: 99999,
+      eventType: 'added',
+      createdAt: Date.now(),
+      metadata: null,
+    });
+    await redisClient.rpush(`${prefix}events:99999`, orphanEvent);
+
+    // Act
+    const deleted = await jobQueue.cleanupOldJobEvents(30);
+
+    // Assert
+    expect(deleted).toBe(1);
+    const remaining = await redisClient.llen(`${prefix}events:99999`);
+    expect(remaining).toBe(0);
+  });
+
+  // ── Waiting system ──────────────────────────────────────────────────
+
+  it('createToken and getToken work via the public API', async () => {
+    // Act
+    const token = await jobQueue.createToken({ timeout: '10m' });
+
+    // Assert
+    expect(token.id).toMatch(/^wp_/);
+    const record = await jobQueue.getToken(token.id);
+    expect(record).not.toBeNull();
+    expect(record!.status).toBe('waiting');
+    expect(record!.timeoutAt).toBeInstanceOf(Date);
+  });
+
+  it('completeToken completes the token and provides data', async () => {
+    // Setup
+    const token = await jobQueue.createToken();
+
+    // Act
+    await jobQueue.completeToken(token.id, { result: 'success' });
+
+    // Assert
+    const record = await jobQueue.getToken(token.id);
+    expect(record!.status).toBe('completed');
+    expect(record!.output).toEqual({ result: 'success' });
+  });
+
+  it('completeToken resumes a waiting job', async () => {
+    // Setup — add a job, process it to create a token, then manually put it in waiting
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'token-resume@example.com' },
+    });
+
+    // Create a token associated with this job
+    // We need to use the backend directly since createToken from public API uses null jobId
+    const backend = jobQueue as any; // accessing the backend is tricky from the public API
+    // Instead, create a token, then manually associate it
+    const token = await jobQueue.createToken();
+
+    // Manually update the token's jobId and put the job in waiting state
+    await redisClient.hset(
+      `${prefix}waitpoint:${token.id}`,
+      'jobId',
+      jobId.toString(),
+    );
+    await redisClient.hmset(
+      `${prefix}job:${jobId}`,
+      'status',
+      'waiting',
+      'waitTokenId',
+      token.id,
+    );
+    await redisClient.srem(`${prefix}status:pending`, jobId.toString());
+    await redisClient.sadd(`${prefix}status:waiting`, jobId.toString());
+    await redisClient.zrem(`${prefix}queue`, jobId.toString());
+
+    // Act
+    await jobQueue.completeToken(token.id, { data: 42 });
+
+    // Assert
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('pending');
+    expect(job?.waitTokenId).toBeNull();
+  });
+
+  it('expireTimedOutTokens expires tokens past their timeout', async () => {
+    // Setup — create a token with a very short timeout, then backdate it
+    const token = await jobQueue.createToken({ timeout: '1s' });
+    // Force the timeout to be in the past
+    const pastMs = Date.now() - 10_000;
+    await redisClient.hset(
+      `${prefix}waitpoint:${token.id}`,
+      'timeoutAt',
+      pastMs.toString(),
+    );
+    await redisClient.zadd(`${prefix}waitpoint_timeout`, pastMs, token.id);
+
+    // Act
+    const expired = await jobQueue.expireTimedOutTokens();
+
+    // Assert
+    expect(expired).toBe(1);
+    const record = await jobQueue.getToken(token.id);
+    expect(record!.status).toBe('timed_out');
+  });
+
+  it('expireTimedOutTokens resumes a waiting job when its token times out', async () => {
+    // Setup
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'timeout-resume@example.com' },
+    });
+    const token = await jobQueue.createToken({ timeout: '1s' });
+
+    // Associate token with job and put job in waiting
+    await redisClient.hset(
+      `${prefix}waitpoint:${token.id}`,
+      'jobId',
+      jobId.toString(),
+    );
+    await redisClient.hmset(
+      `${prefix}job:${jobId}`,
+      'status',
+      'waiting',
+      'waitTokenId',
+      token.id,
+    );
+    await redisClient.srem(`${prefix}status:pending`, jobId.toString());
+    await redisClient.sadd(`${prefix}status:waiting`, jobId.toString());
+    await redisClient.zrem(`${prefix}queue`, jobId.toString());
+
+    // Force the timeout to be in the past
+    const pastMs = Date.now() - 10_000;
+    await redisClient.hset(
+      `${prefix}waitpoint:${token.id}`,
+      'timeoutAt',
+      pastMs.toString(),
+    );
+    await redisClient.zadd(`${prefix}waitpoint_timeout`, pastMs, token.id);
+
+    // Act
+    await jobQueue.expireTimedOutTokens();
+
+    // Assert
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('pending');
+    expect(job?.waitTokenId).toBeNull();
+  });
+
+  it('getNextBatch promotes time-based waiting jobs', async () => {
+    // Setup — add a job and manually set it to waiting with a past waitUntil
+    const jobId = await jobQueue.addJob({
+      jobType: 'test',
+      payload: { foo: 'wait-promote' },
+    });
+    const pastMs = Date.now() - 5000;
+    await redisClient.hmset(
+      `${prefix}job:${jobId}`,
+      'status',
+      'waiting',
+      'waitUntil',
+      pastMs.toString(),
+      'waitTokenId',
+      'null',
+    );
+    await redisClient.srem(`${prefix}status:pending`, jobId.toString());
+    await redisClient.sadd(`${prefix}status:waiting`, jobId.toString());
+    await redisClient.zrem(`${prefix}queue`, jobId.toString());
+    await redisClient.zadd(`${prefix}waiting`, pastMs, jobId.toString());
+
+    // Act — process jobs, the waiting job should get promoted and processed
+    const handler = vi.fn(async () => {});
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {}),
+      sms: vi.fn(async () => {}),
+      test: handler,
+    });
+    const processed = await processor.start();
+
+    // Assert
+    expect(processed).toBe(1);
+    expect(handler).toHaveBeenCalled();
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('completed');
+  });
+
+  it('getNextBatch does NOT promote token-based waiting jobs', async () => {
+    // Setup — add a job waiting for a token
+    const jobId = await jobQueue.addJob({
+      jobType: 'test',
+      payload: { foo: 'token-wait-nopromote' },
+    });
+    const pastMs = Date.now() - 5000;
+    await redisClient.hmset(
+      `${prefix}job:${jobId}`,
+      'status',
+      'waiting',
+      'waitUntil',
+      pastMs.toString(),
+      'waitTokenId',
+      'wp_some_token',
+    );
+    await redisClient.srem(`${prefix}status:pending`, jobId.toString());
+    await redisClient.sadd(`${prefix}status:waiting`, jobId.toString());
+    await redisClient.zrem(`${prefix}queue`, jobId.toString());
+    await redisClient.zadd(`${prefix}waiting`, pastMs, jobId.toString());
+
+    // Act
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {}),
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    const processed = await processor.start();
+
+    // Assert — should not pick up the token-based waiting job
+    expect(processed).toBe(0);
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('waiting');
+  });
+
+  it('waitFor pauses a job and resumes after time elapses', async () => {
+    // Setup
+    let invocationCount = 0;
+    const jobId = await jobQueue.addJob({
+      jobType: 'test',
+      payload: { foo: 'waitfor-test' },
+    });
+
+    // First invocation: handler calls ctx.waitFor
+    const handler = vi.fn(async (_payload: any, _signal: any, ctx: any) => {
+      invocationCount++;
+      if (invocationCount === 1) {
+        await ctx.waitFor({ seconds: 1 });
+      }
+    });
+
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {}),
+      sms: vi.fn(async () => {}),
+      test: handler,
+    });
+    await processor.start();
+
+    // Assert — job should be in waiting state
+    let job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('waiting');
+    expect(job?.waitUntil).toBeInstanceOf(Date);
+    expect(job?.stepData).toBeDefined();
+
+    // Manually advance: set waitUntil to past and add to waiting sorted set
+    const pastMs = Date.now() - 5000;
+    await redisClient.hset(
+      `${prefix}job:${jobId}`,
+      'waitUntil',
+      pastMs.toString(),
+    );
+    await redisClient.zadd(`${prefix}waiting`, pastMs, jobId.toString());
+
+    // Second invocation: job resumes and completes
+    await processor.start();
+
+    // Assert
+    job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('completed');
+    expect(invocationCount).toBe(2);
+  });
+
+  it('ctx.run memoizes step results across re-invocations', async () => {
+    // Setup
+    let invocationCount = 0;
+    let stepCallCount = 0;
+    const jobId = await jobQueue.addJob({
+      jobType: 'test',
+      payload: { foo: 'memoize-test' },
+    });
+
+    const handler = vi.fn(async (_payload: any, _signal: any, ctx: any) => {
+      invocationCount++;
+      const result = await ctx.run('step1', async () => {
+        stepCallCount++;
+        return 42;
+      });
+      expect(result).toBe(42);
+
+      if (invocationCount === 1) {
+        await ctx.waitFor({ seconds: 1 });
+      }
+    });
+
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {}),
+      sms: vi.fn(async () => {}),
+      test: handler,
+    });
+
+    // First invocation
+    await processor.start();
+    let job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('waiting');
+    expect(stepCallCount).toBe(1);
+
+    // Advance time
+    const pastMs = Date.now() - 5000;
+    await redisClient.hset(
+      `${prefix}job:${jobId}`,
+      'waitUntil',
+      pastMs.toString(),
+    );
+    await redisClient.zadd(`${prefix}waiting`, pastMs, jobId.toString());
+
+    // Second invocation
+    await processor.start();
+
+    // Assert — step1 should NOT have been called again (memoized)
+    job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('completed');
+    expect(stepCallCount).toBe(1);
+    expect(invocationCount).toBe(2);
+  });
+
+  it('waitForToken pauses and resumes on token completion', async () => {
+    // Setup
+    let invocationCount = 0;
+    let tokenId: string;
+    const jobId = await jobQueue.addJob({
+      jobType: 'test',
+      payload: { foo: 'token-wait-test' },
+    });
+
+    const handler = vi.fn(async (_payload: any, _signal: any, ctx: any) => {
+      invocationCount++;
+      if (invocationCount === 1) {
+        const token = await ctx.createToken({ timeout: '1h' });
+        tokenId = token.id;
+        const result = await ctx.waitForToken(token.id);
+        // Should not reach here on first invocation (throws WaitSignal)
+        expect(result.ok).toBe(true);
+      } else {
+        // Second invocation: token should be completed
+        // The step data should have the result cached
+      }
+    });
+
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {}),
+      sms: vi.fn(async () => {}),
+      test: handler,
+    });
+
+    // First invocation — should pause on waitForToken
+    await processor.start();
+
+    let job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('waiting');
+    expect(job?.waitTokenId).toBe(tokenId!);
+
+    // Complete the token externally
+    await jobQueue.completeToken(tokenId!, { answer: 'yes' });
+
+    // Verify job is back to pending
+    job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('pending');
+
+    // Second invocation — should complete
+    await processor.start();
+
+    job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('completed');
+    expect(invocationCount).toBe(2);
+  });
+});
+
+// ── BYOC (Bring Your Own Connection) tests for Redis ────────────────────
+
+describe('Redis BYOC: init with external client', () => {
+  let prefix: string;
+  let externalClient: any;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+
+  beforeEach(async () => {
+    prefix = createRedisTestPrefix();
+    const { default: IORedis } = await import('ioredis');
+    externalClient = new (IORedis as any)(REDIS_URL);
+    jobQueue = initJobQueue<TestPayloadMap>({
+      backend: 'redis',
+      client: externalClient,
+      keyPrefix: prefix,
+    });
+  });
+
+  afterEach(async () => {
+    await cleanupRedisPrefix(externalClient, prefix);
+    await externalClient.quit();
+  });
+
+  it('uses the provided client for addJob and getJob', async () => {
+    // Act
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'byoc-redis@example.com' },
+    });
+
+    // Assert
+    const job = await jobQueue.getJob(jobId);
+    expect(job).not.toBeNull();
+    expect(job?.jobType).toBe('email');
+    expect(job?.payload).toEqual({ to: 'byoc-redis@example.com' });
+  });
+
+  it('returns the same client instance from getRedisClient()', () => {
+    // Act
+    const returned = jobQueue.getRedisClient();
+
+    // Assert
+    expect(returned).toBe(externalClient);
+  });
+});
+
+describe('Redis BYOC: addJob with db option throws', () => {
+  let prefix: string;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+  let redisClient: any;
+
+  beforeEach(async () => {
+    prefix = createRedisTestPrefix();
+    jobQueue = initJobQueue<TestPayloadMap>({
+      backend: 'redis',
+      redisConfig: { url: REDIS_URL, keyPrefix: prefix },
+    });
+    redisClient = jobQueue.getRedisClient();
+  });
+
+  afterEach(async () => {
+    await cleanupRedisPrefix(redisClient, prefix);
+    await redisClient.quit();
+  });
+
+  it('throws a clear error when db option is provided', async () => {
+    // Setup — fake db client
+    const fakeDb = { query: async () => ({ rows: [], rowCount: 0 }) };
+
+    // Act & Assert
+    await expect(
+      jobQueue.addJob(
+        { jobType: 'email', payload: { to: 'fail@example.com' } },
+        { db: fakeDb },
+      ),
+    ).rejects.toThrow('The db option is not supported with the Redis backend.');
+  });
+});
+
+describe('Redis addJobs batch insert', () => {
+  let prefix: string;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+  let redisClient: any;
+
+  beforeEach(async () => {
+    prefix = createRedisTestPrefix();
+    jobQueue = initJobQueue<TestPayloadMap>({
+      backend: 'redis',
+      redisConfig: { url: REDIS_URL, keyPrefix: prefix },
+    });
+    redisClient = jobQueue.getRedisClient();
+  });
+
+  afterEach(async () => {
+    await cleanupRedisPrefix(redisClient, prefix);
+    await redisClient.quit();
+  });
+
+  it('inserts multiple jobs and returns IDs in order', async () => {
+    // Act
+    const ids = await jobQueue.addJobs([
+      { jobType: 'email', payload: { to: 'a@test.com' } },
+      { jobType: 'sms', payload: { to: '+1234' } },
+      { jobType: 'email', payload: { to: 'b@test.com' } },
+    ]);
+
+    // Assert
+    expect(ids).toHaveLength(3);
+
+    const job0 = await jobQueue.getJob(ids[0]);
+    expect(job0?.jobType).toBe('email');
+    expect(job0?.payload).toEqual({ to: 'a@test.com' });
+
+    const job1 = await jobQueue.getJob(ids[1]);
+    expect(job1?.jobType).toBe('sms');
+    expect(job1?.payload).toEqual({ to: '+1234' });
+
+    const job2 = await jobQueue.getJob(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 jobQueue.addJobs([]);
+
+    // Assert
+    expect(ids).toEqual([]);
+  });
+
+  it('handles idempotency keys for new jobs', async () => {
+    // Act
+    const ids = await jobQueue.addJobs([
+      {
+        jobType: 'email',
+        payload: { to: 'a@test.com' },
+        idempotencyKey: 'r-key-a',
+      },
+      {
+        jobType: 'email',
+        payload: { to: 'b@test.com' },
+        idempotencyKey: 'r-key-b',
+      },
+    ]);
+
+    // Assert
+    expect(ids).toHaveLength(2);
+    expect(ids[0]).not.toBe(ids[1]);
+
+    const job0 = await jobQueue.getJob(ids[0]);
+    expect(job0?.idempotencyKey).toBe('r-key-a');
+  });
+
+  it('returns existing IDs for conflicting idempotency keys', async () => {
+    // Setup
+    const existingId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'existing@test.com' },
+      idempotencyKey: 'r-dup',
+    });
+
+    // Act
+    const ids = await jobQueue.addJobs([
+      { jobType: 'email', payload: { to: 'new@test.com' } },
+      {
+        jobType: 'email',
+        payload: { to: 'dup@test.com' },
+        idempotencyKey: 'r-dup',
+      },
+    ]);
+
+    // Assert
+    expect(ids).toHaveLength(2);
+    expect(ids[1]).toBe(existingId);
+    expect(ids[0]).not.toBe(existingId);
+  });
+
+  it('records added events for each inserted job', async () => {
+    // Act
+    const ids = await jobQueue.addJobs([
+      { jobType: 'email', payload: { to: 'a@test.com' } },
+      { jobType: 'sms', payload: { to: '+999' } },
+    ]);
+
+    // Assert
+    const events0 = await jobQueue.getJobEvents(ids[0]);
+    expect(events0.filter((e) => e.eventType === 'added')).toHaveLength(1);
+
+    const events1 = await jobQueue.getJobEvents(ids[1]);
+    expect(events1.filter((e) => e.eventType === 'added')).toHaveLength(1);
+  });
+
+  it('throws when db option is used with addJobs', async () => {
+    // Setup
+    const fakeDb = { query: async () => ({ rows: [], rowCount: 0 }) };
+
+    // Act & Assert
+    await expect(
+      jobQueue.addJobs(
+        [{ jobType: 'email', payload: { to: 'fail@test.com' } }],
+        { db: fakeDb },
+      ),
+    ).rejects.toThrow('The db option is not supported with the Redis backend.');
+  });
+
+  it('stores tags and priority correctly per job', async () => {
+    // Act
+    const ids = await jobQueue.addJobs([
+      {
+        jobType: 'email',
+        payload: { to: 'a@test.com' },
+        tags: ['urgent'],
+        priority: 10,
+      },
+      { jobType: 'sms', payload: { to: '+1' }, priority: 5 },
+      { jobType: 'email', payload: { to: 'c@test.com' }, tags: ['low'] },
+    ]);
+
+    // Assert
+    const job0 = await jobQueue.getJob(ids[0]);
+    expect(job0?.tags).toEqual(['urgent']);
+    expect(job0?.priority).toBe(10);
+
+    const job1 = await jobQueue.getJob(ids[1]);
+    expect(job1?.priority).toBe(5);
+
+    const job2 = await jobQueue.getJob(ids[2]);
+    expect(job2?.tags).toEqual(['low']);
+  });
+});
+
+describe('Redis event hooks', () => {
+  let prefix: string;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+  let redisClient: any;
+
+  beforeEach(async () => {
+    prefix = createRedisTestPrefix();
+    jobQueue = initJobQueue<TestPayloadMap>({
+      backend: 'redis',
+      redisConfig: { url: REDIS_URL, keyPrefix: prefix },
+    });
+    redisClient = jobQueue.getRedisClient();
+  });
+
+  afterEach(async () => {
+    jobQueue.removeAllListeners();
+    await cleanupRedisPrefix(redisClient, prefix);
+    await redisClient.quit();
+  });
+
+  it('emits job:added on addJob', async () => {
+    const listener = vi.fn();
+    jobQueue.on('job:added', listener);
+
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'test@example.com' },
+    });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener).toHaveBeenCalledWith({ jobId, jobType: 'email' });
+  });
+
+  it('emits job:added for each job in addJobs', async () => {
+    const listener = vi.fn();
+    jobQueue.on('job:added', listener);
+
+    const ids = await jobQueue.addJobs([
+      { jobType: 'email', payload: { to: 'a@test.com' } },
+      { jobType: 'sms', payload: { to: '+1234' } },
+    ]);
+
+    expect(listener).toHaveBeenCalledTimes(2);
+    expect(listener).toHaveBeenCalledWith({ jobId: ids[0], jobType: 'email' });
+    expect(listener).toHaveBeenCalledWith({ jobId: ids[1], jobType: 'sms' });
+  });
+
+  it('emits job:cancelled on cancelJob', async () => {
+    const listener = vi.fn();
+    jobQueue.on('job:cancelled', listener);
+
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'test@example.com' },
+    });
+    await jobQueue.cancelJob(jobId);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener).toHaveBeenCalledWith({ jobId });
+  });
+
+  it('emits job:retried on retryJob', async () => {
+    const listener = vi.fn();
+    jobQueue.on('job:retried', listener);
+
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'test@example.com' },
+    });
+
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {
+        throw new Error('fail');
+      }),
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+
+    await jobQueue.retryJob(jobId);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener).toHaveBeenCalledWith({ jobId });
+  });
+
+  it('emits job:processing and job:completed on successful processing', async () => {
+    const processingListener = vi.fn();
+    const completedListener = vi.fn();
+    jobQueue.on('job:processing', processingListener);
+    jobQueue.on('job:completed', completedListener);
+
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'test@example.com' },
+    });
+
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {}),
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+
+    expect(processingListener).toHaveBeenCalledTimes(1);
+    expect(processingListener).toHaveBeenCalledWith({
+      jobId,
+      jobType: 'email',
+    });
+    expect(completedListener).toHaveBeenCalledTimes(1);
+    expect(completedListener).toHaveBeenCalledWith({
+      jobId,
+      jobType: 'email',
+    });
+  });
+
+  it('emits job:failed with willRetry flag', async () => {
+    const listener = vi.fn();
+    jobQueue.on('job:failed', listener);
+
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'test@example.com' },
+      maxAttempts: 1,
+    });
+
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async () => {
+        throw new Error('boom');
+      }),
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener).toHaveBeenCalledWith(
+      expect.objectContaining({
+        jobId,
+        jobType: 'email',
+        willRetry: false,
+        error: expect.any(Error),
+      }),
+    );
+  });
+
+  it('once fires only once then auto-unsubscribes', async () => {
+    const listener = vi.fn();
+    jobQueue.once('job:added', listener);
+
+    await jobQueue.addJob({ jobType: 'email', payload: { to: 'a@test.com' } });
+    await jobQueue.addJob({ jobType: 'sms', payload: { to: '+1234' } });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('off removes a listener', async () => {
+    const listener = vi.fn();
+    jobQueue.on('job:added', listener);
+
+    await jobQueue.addJob({ jobType: 'email', payload: { to: 'a@test.com' } });
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    jobQueue.off('job:added', listener);
+
+    await jobQueue.addJob({ jobType: 'sms', payload: { to: '+1234' } });
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
 });