@nicnocquee/dataqueue 1.25.0 → 1.26.0-beta.20260223202259

package/src/index.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { initJobQueue, JobQueueConfig } from './index.js';
 import { createTestDbAndPool, destroyTestDb } from './test-util.js';
 import { Pool } from 'pg';
+import type { CronScheduleRecord, AddJobOptions } from './types.js';
 
 // Integration tests for index.ts
 
@@ -77,9 +78,7 @@ describe('index integration', () => {
       },
       { pollInterval: 100 },
     );
-    processor.start();
-    await new Promise((r) => setTimeout(r, 300));
-    processor.stop();
+    await processor.start();
     const job = await jobQueue.getJob(jobId);
     expect(handler).toHaveBeenCalledWith(
       { foo: 'bar' },
@@ -431,9 +430,7 @@ describe('index integration', () => {
       },
       { pollInterval: 100 },
     );
-    processor.start();
-    await new Promise((r) => setTimeout(r, 300));
-    processor.stop();
+    await processor.start();
 
     expect(handler).toHaveBeenCalledWith(
       { foo: 'updated@example.com' },
@@ -458,9 +455,7 @@ describe('index integration', () => {
       },
       { pollInterval: 100 },
     );
-    processor.start();
-    await new Promise((r) => setTimeout(r, 300));
-    processor.stop();
+    await processor.start();
 
     const originalJob = await jobQueue.getJob(jobId1);
     expect(originalJob?.status).toBe('completed');
@@ -493,7 +488,7 @@ describe('index integration', () => {
       jobType: 'email',
       payload: { to: 'processing@example.com' },
     });
-    processor2.start();
+    const startPromise = processor2.start();
     // Wait a bit for job to be picked up
     await new Promise((r) => setTimeout(r, 150));
     // Job should be processing now
@@ -509,7 +504,7 @@ describe('index integration', () => {
         expect(job2?.payload).toEqual({ to: 'processing@example.com' });
       }
     }
-    processor2.stop();
+    await startPromise;
   });
 
   it('should record edited event when editing via JobQueue API', async () => {
@@ -531,4 +526,1032 @@ describe('index integration', () => {
       priority: 10,
     });
   });
+
+  // ── Configurable retry strategy integration tests ────────────────────
+
+  it('should store and return retry config through public API', async () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'retry-api@example.com' },
+      retryDelay: 20,
+      retryBackoff: true,
+      retryDelayMax: 300,
+    });
+
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.retryDelay).toBe(20);
+    expect(job?.retryBackoff).toBe(true);
+    expect(job?.retryDelayMax).toBe(300);
+  });
+
+  it('should use fixed delay on failure through public API', async () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'fixed-api@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);
+  });
+});
+
+describe('cron schedules integration', () => {
+  let pool: Pool;
+  let dbName: string;
+  let testDbUrl: string;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+
+  beforeEach(async () => {
+    const setup = await createTestDbAndPool();
+    pool = setup.pool;
+    dbName = setup.dbName;
+    testDbUrl = setup.testDbUrl;
+    const config: JobQueueConfig = {
+      databaseConfig: {
+        connectionString: testDbUrl,
+      },
+    };
+    jobQueue = initJobQueue<TestPayloadMap>(config);
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    jobQueue.getPool().end();
+    await pool.end();
+    await destroyTestDb(dbName);
+  });
+
+  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 — insert a schedule with nextRunAt in the past
+    const id = await jobQueue.addCronJob({
+      scheduleName: 'due-now',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'due@example.com' },
+    });
+    // Force nextRunAt to be in the past
+    await pool.query(
+      `UPDATE cron_schedules SET next_run_at = NOW() - INTERVAL '1 minute' WHERE id = $1`,
+      [id],
+    );
+
+    // 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' },
+    });
+    await pool.query(
+      `UPDATE cron_schedules SET next_run_at = NOW() - INTERVAL '1 minute' WHERE id = $1`,
+      [id],
+    );
+
+    // 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' },
+    });
+    await pool.query(
+      `UPDATE cron_schedules SET next_run_at = NOW() - INTERVAL '1 minute' WHERE id = $1`,
+      [id],
+    );
+    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 calculated to the future by addCronJob
+    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,
+    });
+    await pool.query(
+      `UPDATE cron_schedules SET next_run_at = NOW() - INTERVAL '1 minute' WHERE id = $1`,
+      [id],
+    );
+
+    // First enqueue should succeed
+    const count1 = await jobQueue.enqueueDueCronJobs();
+    expect(count1).toBe(1);
+
+    // Set nextRunAt to past again (simulating next tick)
+    await pool.query(
+      `UPDATE cron_schedules SET next_run_at = NOW() - INTERVAL '1 minute' WHERE id = $1`,
+      [id],
+    );
+
+    // Act — second enqueue should be skipped because previous job is still 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,
+    });
+    await pool.query(
+      `UPDATE cron_schedules SET next_run_at = NOW() - INTERVAL '1 minute' WHERE id = $1`,
+      [id],
+    );
+
+    // First enqueue
+    const count1 = await jobQueue.enqueueDueCronJobs();
+    expect(count1).toBe(1);
+
+    // Set nextRunAt to past again
+    await pool.query(
+      `UPDATE cron_schedules SET next_run_at = NOW() - INTERVAL '1 minute' WHERE id = $1`,
+      [id],
+    );
+
+    // Act — second enqueue should succeed because allowOverlap=true
+    const count2 = await jobQueue.enqueueDueCronJobs();
+
+    // Assert
+    expect(count2).toBe(1);
+
+    // Verify there are 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);
+  });
+
+  it('should propagate retry config from cron schedule to enqueued jobs', async () => {
+    const cronId = await jobQueue.addCronJob({
+      scheduleName: 'retry-cron',
+      cronExpression: '* * * * *',
+      jobType: 'email',
+      payload: { to: 'cron-retry@example.com' },
+      retryDelay: 15,
+      retryBackoff: false,
+      retryDelayMax: 90,
+    });
+
+    // Force next_run_at to the past
+    await pool.query(
+      `UPDATE cron_schedules SET next_run_at = NOW() - INTERVAL '1 minute' WHERE id = $1`,
+      [cronId],
+    );
+
+    const count = await jobQueue.enqueueDueCronJobs();
+    expect(count).toBe(1);
+
+    const jobs = await jobQueue.getJobsByStatus('pending');
+    const cronJob = jobs.find(
+      (j) => (j.payload as any).to === 'cron-retry@example.com',
+    );
+    expect(cronJob).toBeDefined();
+    expect(cronJob?.retryDelay).toBe(15);
+    expect(cronJob?.retryBackoff).toBe(false);
+    expect(cronJob?.retryDelayMax).toBe(90);
+  });
+
+  it('should store retry config on cron schedule record', async () => {
+    const cronId = await jobQueue.addCronJob({
+      scheduleName: 'retry-cron-record',
+      cronExpression: '0 */2 * * *',
+      jobType: 'email',
+      payload: { to: 'cron-record@example.com' },
+      retryDelay: 30,
+      retryBackoff: true,
+      retryDelayMax: 600,
+    });
+
+    const schedule = await jobQueue.getCronJob(cronId);
+    expect(schedule?.retryDelay).toBe(30);
+    expect(schedule?.retryBackoff).toBe(true);
+    expect(schedule?.retryDelayMax).toBe(600);
+  });
+});
+
+// ── BYOC (Bring Your Own Connection) tests ──────────────────────────────
+
+describe('BYOC: init with external pool', () => {
+  let pool: Pool;
+  let dbName: string;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+
+  beforeEach(async () => {
+    const setup = await createTestDbAndPool();
+    pool = setup.pool;
+    dbName = setup.dbName;
+    jobQueue = initJobQueue<TestPayloadMap>({ pool });
+  });
+
+  afterEach(async () => {
+    await pool.end();
+    await destroyTestDb(dbName);
+  });
+
+  it('uses the provided pool for addJob and getJob', async () => {
+    // Act
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'byoc@example.com' },
+    });
+
+    // Assert
+    const job = await jobQueue.getJob(jobId);
+    expect(job).not.toBeNull();
+    expect(job?.jobType).toBe('email');
+    expect(job?.payload).toEqual({ to: 'byoc@example.com' });
+  });
+
+  it('returns the same pool instance from getPool()', () => {
+    // Act
+    const returnedPool = jobQueue.getPool();
+
+    // Assert
+    expect(returnedPool).toBe(pool);
+  });
+});
+
+describe('BYOC: transactional addJob with db option', () => {
+  let pool: Pool;
+  let dbName: string;
+  let testDbUrl: string;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+
+  beforeEach(async () => {
+    const setup = await createTestDbAndPool();
+    pool = setup.pool;
+    dbName = setup.dbName;
+    testDbUrl = setup.testDbUrl;
+    jobQueue = initJobQueue<TestPayloadMap>({
+      databaseConfig: { connectionString: testDbUrl },
+    });
+  });
+
+  afterEach(async () => {
+    jobQueue.getPool().end();
+    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 jobQueue.addJob(
+      { jobType: 'email', payload: { to: 'rollback@example.com' } },
+      { db: client },
+    );
+    await client.query('ROLLBACK');
+    client.release();
+
+    // Assert — job should not exist after rollback
+    const job = await jobQueue.getJob(jobId);
+    expect(job).toBeNull();
+  });
+
+  it('persists the job and event when the transaction is committed', async () => {
+    // Setup
+    const client = await pool.connect();
+    await client.query('BEGIN');
+
+    // Act
+    const jobId = await jobQueue.addJob(
+      { jobType: 'email', payload: { to: 'commit@example.com' } },
+      { db: client },
+    );
+    await client.query('COMMIT');
+    client.release();
+
+    // Assert — job exists
+    const job = await jobQueue.getJob(jobId);
+    expect(job).not.toBeNull();
+    expect(job?.payload).toEqual({ to: 'commit@example.com' });
+
+    // Assert — event was recorded in the same transaction
+    const events = await jobQueue.getJobEvents(jobId);
+    expect(events.length).toBeGreaterThanOrEqual(1);
+    expect(events[0].eventType).toBe('added');
+  });
+
+  it('job is visible within the transaction before commit', async () => {
+    // Setup
+    const client = await pool.connect();
+    await client.query('BEGIN');
+
+    // Act
+    const jobId = await jobQueue.addJob(
+      { jobType: 'sms', payload: { to: 'in-tx@example.com' } },
+      { db: client },
+    );
+
+    // Assert — visible within the transaction
+    const res = await client.query('SELECT id FROM job_queue WHERE id = $1', [
+      jobId,
+    ]);
+    expect(res.rows).toHaveLength(1);
+
+    await client.query('ROLLBACK');
+    client.release();
+  });
+});
+
+describe('addJobs batch insert', () => {
+  let pool: Pool;
+  let dbName: string;
+  let testDbUrl: string;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+
+  beforeEach(async () => {
+    const setup = await createTestDbAndPool();
+    pool = setup.pool;
+    dbName = setup.dbName;
+    testDbUrl = setup.testDbUrl;
+    const config: JobQueueConfig = {
+      databaseConfig: {
+        connectionString: testDbUrl,
+      },
+    };
+    jobQueue = initJobQueue<TestPayloadMap>(config);
+  });
+
+  afterEach(async () => {
+    jobQueue.getPool().end();
+    await pool.end();
+    await destroyTestDb(dbName);
+  });
+
+  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');
+
+    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 correctly', async () => {
+    // Setup
+    const existingId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'existing@test.com' },
+      idempotencyKey: 'batch-dup',
+    });
+
+    // Act
+    const ids = await jobQueue.addJobs([
+      { jobType: 'email', payload: { to: 'new@test.com' } },
+      {
+        jobType: 'email',
+        payload: { to: 'dup@test.com' },
+        idempotencyKey: 'batch-dup',
+      },
+    ]);
+
+    // Assert
+    expect(ids).toHaveLength(2);
+    expect(ids[1]).toBe(existingId);
+    expect(ids[0]).not.toBe(existingId);
+  });
+});
+
+describe('BYOC: validation errors', () => {
+  it('throws when neither databaseConfig nor pool is provided for postgres', () => {
+    // Act & Assert
+    expect(() =>
+      initJobQueue<TestPayloadMap>({ backend: 'postgres' } as any),
+    ).toThrow(
+      'PostgreSQL backend requires either "databaseConfig" or "pool" to be provided.',
+    );
+  });
+
+  it('throws when neither redisConfig nor client is provided for redis', () => {
+    // Act & Assert
+    expect(() =>
+      initJobQueue<TestPayloadMap>({ backend: 'redis' } as any),
+    ).toThrow(
+      'Redis backend requires either "redisConfig" or "client" to be provided.',
+    );
+  });
+});
+
+describe('event hooks', () => {
+  let pool: Pool;
+  let dbName: string;
+  let testDbUrl: string;
+  let jobQueue: ReturnType<typeof initJobQueue<TestPayloadMap>>;
+
+  beforeEach(async () => {
+    const setup = await createTestDbAndPool();
+    pool = setup.pool;
+    dbName = setup.dbName;
+    testDbUrl = setup.testDbUrl;
+    const config: JobQueueConfig = {
+      databaseConfig: {
+        connectionString: testDbUrl,
+      },
+    };
+    jobQueue = initJobQueue<TestPayloadMap>(config);
+  });
+
+  afterEach(async () => {
+    jobQueue.removeAllListeners();
+    jobQueue.getPool().end();
+    await pool.end();
+    await destroyTestDb(dbName);
+  });
+
+  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 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();
+
+    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 true when attempts remain', async () => {
+    const listener = vi.fn();
+    jobQueue.on('job:failed', listener);
+
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'test@example.com' },
+      maxAttempts: 3,
+    });
+
+    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: true,
+        error: expect.any(Error),
+      }),
+    );
+  });
+
+  it('emits job:failed with willRetry false when no attempts remain', 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,
+      }),
+    );
+  });
+
+  it('emits job:waiting when handler calls ctx.waitFor', async () => {
+    const listener = vi.fn();
+    jobQueue.on('job:waiting', listener);
+
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'test@example.com' },
+    });
+
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async (_payload, _signal, ctx) => {
+        await ctx.waitFor({ hours: 1 });
+      }),
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener).toHaveBeenCalledWith({ jobId, jobType: 'email' });
+  });
+
+  it('emits job:progress when handler calls ctx.setProgress', async () => {
+    const listener = vi.fn();
+    jobQueue.on('job:progress', listener);
+
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'test@example.com' },
+    });
+
+    const processor = jobQueue.createProcessor({
+      email: vi.fn(async (_payload, _signal, ctx) => {
+        await ctx.setProgress(50);
+        await ctx.setProgress(100);
+      }),
+      sms: vi.fn(async () => {}),
+      test: vi.fn(async () => {}),
+    });
+    await processor.start();
+
+    expect(listener).toHaveBeenCalledTimes(2);
+    expect(listener).toHaveBeenCalledWith({ jobId, progress: 50 });
+    expect(listener).toHaveBeenCalledWith({ jobId, progress: 100 });
+  });
+
+  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);
+  });
+
+  it('removeAllListeners clears all listeners for a specific event', async () => {
+    const listener1 = vi.fn();
+    const listener2 = vi.fn();
+    const otherListener = vi.fn();
+    jobQueue.on('job:added', listener1);
+    jobQueue.on('job:added', listener2);
+    jobQueue.on('job:cancelled', otherListener);
+
+    jobQueue.removeAllListeners('job:added');
+
+    await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'a@test.com' },
+    });
+    const jobId = await jobQueue.addJob({
+      jobType: 'sms',
+      payload: { to: '+1234' },
+    });
+    await jobQueue.cancelJob(jobId);
+
+    expect(listener1).not.toHaveBeenCalled();
+    expect(listener2).not.toHaveBeenCalled();
+    expect(otherListener).toHaveBeenCalledTimes(1);
+  });
+
+  it('removeAllListeners with no args clears everything', async () => {
+    const addedListener = vi.fn();
+    const cancelledListener = vi.fn();
+    jobQueue.on('job:added', addedListener);
+    jobQueue.on('job:cancelled', cancelledListener);
+
+    jobQueue.removeAllListeners();
+
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'a@test.com' },
+    });
+    await jobQueue.cancelJob(jobId);
+
+    expect(addedListener).not.toHaveBeenCalled();
+    expect(cancelledListener).not.toHaveBeenCalled();
+  });
+
+  it('onError callback still works alongside error event', async () => {
+    const onErrorSpy = vi.fn();
+    const errorListener = vi.fn();
+    jobQueue.on('error', errorListener);
+
+    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 () => {}),
+      },
+      { onError: onErrorSpy },
+    );
+    await processor.start();
+
+    // job:failed fires for individual job failures; error fires for
+    // batch-level errors caught in processBatchWithHandlers. In this case
+    // the job failure is handled inside processJobWithHandlers and doesn't
+    // propagate to the batch-level error handler. So we verify that
+    // onError still works as configured and job:failed events fire.
+    const failedListener = vi.fn();
+    jobQueue.on('job:failed', failedListener);
+
+    await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'test2@example.com' },
+      maxAttempts: 1,
+    });
+    await processor.start();
+
+    expect(failedListener).toHaveBeenCalledTimes(1);
+  });
 });