@nicnocquee/dataqueue 1.22.0 → 1.25.0

package/src/index.test.ts

@@ -81,7 +81,11 @@ describe('index integration', () => {
     await new Promise((r) => setTimeout(r, 300));
     processor.stop();
     const job = await jobQueue.getJob(jobId);
-    expect(handler).toHaveBeenCalledWith({ foo: 'bar' }, expect.any(Object));
+    expect(handler).toHaveBeenCalledWith(
+      { foo: 'bar' },
+      expect.any(Object),
+      expect.any(Object),
+    );
     expect(job?.status).toBe('completed');
   });
 
@@ -228,6 +232,87 @@ describe('index integration', () => {
     expect(job2?.status).toBe('cancelled');
   });
 
+  it('should edit all pending jobs via JobQueue API', async () => {
+    // Add three pending jobs
+    const jobId1 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'batch1@example.com' },
+      priority: 0,
+    });
+    const jobId2 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'batch2@example.com' },
+      priority: 0,
+    });
+    const jobId3 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'batch3@example.com' },
+      priority: 0,
+    });
+    // Add a completed job
+    const jobId4 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'done@example.com' },
+      priority: 0,
+    });
+    await pool.query(
+      `UPDATE job_queue SET status = 'completed' WHERE id = $1`,
+      [jobId4],
+    );
+
+    // Edit all pending jobs
+    const editedCount = await jobQueue.editAllPendingJobs(undefined, {
+      priority: 10,
+    });
+    expect(editedCount).toBeGreaterThanOrEqual(3);
+
+    // Check that all pending jobs are updated
+    const job1 = await jobQueue.getJob(jobId1);
+    const job2 = await jobQueue.getJob(jobId2);
+    const job3 = await jobQueue.getJob(jobId3);
+    expect(job1?.priority).toBe(10);
+    expect(job2?.priority).toBe(10);
+    expect(job3?.priority).toBe(10);
+
+    // Completed job should remain unchanged
+    const completedJob = await jobQueue.getJob(jobId4);
+    expect(completedJob?.priority).toBe(0);
+  });
+
+  it('should edit pending jobs with filters via JobQueue API', async () => {
+    const emailJobId1 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'email1@example.com' },
+      priority: 0,
+    });
+    const emailJobId2 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'email2@example.com' },
+      priority: 0,
+    });
+    const smsJobId = await jobQueue.addJob({
+      jobType: 'sms',
+      payload: { to: 'sms@example.com' },
+      priority: 0,
+    });
+
+    // Edit only email jobs
+    const editedCount = await jobQueue.editAllPendingJobs(
+      { jobType: 'email' },
+      {
+        priority: 5,
+      },
+    );
+    expect(editedCount).toBeGreaterThanOrEqual(2);
+
+    const emailJob1 = await jobQueue.getJob(emailJobId1);
+    const emailJob2 = await jobQueue.getJob(emailJobId2);
+    const smsJob = await jobQueue.getJob(smsJobId);
+    expect(emailJob1?.priority).toBe(5);
+    expect(emailJob2?.priority).toBe(5);
+    expect(smsJob?.priority).toBe(0);
+  });
+
   it('should cancel all upcoming jobs by runAt', async () => {
     const runAt = new Date(Date.now() + 60 * 60 * 1000); // 1 hour in future
     const jobId1 = await jobQueue.addJob({
@@ -302,4 +387,148 @@ describe('index integration', () => {
     expect(job1?.status).toBe('cancelled');
     expect(job2?.status).toBe('pending');
   });
+
+  it('should edit a pending job via JobQueue API', async () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'original@example.com' },
+      priority: 0,
+      maxAttempts: 3,
+    });
+
+    await jobQueue.editJob(jobId, {
+      payload: { to: 'updated@example.com' },
+      priority: 10,
+      maxAttempts: 5,
+    });
+
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.payload).toEqual({ to: 'updated@example.com' });
+    expect(job?.priority).toBe(10);
+    expect(job?.maxAttempts).toBe(5);
+    expect(job?.status).toBe('pending');
+  });
+
+  it('should edit a job and then process it correctly', async () => {
+    const handler = vi.fn(async (payload: { foo: string }, _signal) => {
+      expect(payload.foo).toBe('updated@example.com');
+    });
+    const jobId = await jobQueue.addJob({
+      jobType: 'test',
+      payload: { foo: 'original@example.com' },
+    });
+
+    // Edit the job before processing
+    await jobQueue.editJob(jobId, {
+      payload: { foo: 'updated@example.com' },
+    });
+
+    const processor = jobQueue.createProcessor(
+      {
+        email: vi.fn(async () => {}),
+        sms: vi.fn(async () => {}),
+        test: handler,
+      },
+      { pollInterval: 100 },
+    );
+    processor.start();
+    await new Promise((r) => setTimeout(r, 300));
+    processor.stop();
+
+    expect(handler).toHaveBeenCalledWith(
+      { foo: 'updated@example.com' },
+      expect.any(Object),
+      expect.any(Object),
+    );
+    const job = await jobQueue.getJob(jobId);
+    expect(job?.status).toBe('completed');
+  });
+
+  it('should silently fail when editing non-pending jobs', async () => {
+    // Try to edit a completed job
+    const jobId1 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'original@example.com' },
+    });
+    const processor = jobQueue.createProcessor(
+      {
+        email: vi.fn(async () => {}),
+        sms: vi.fn(async () => {}),
+        test: vi.fn(async () => {}),
+      },
+      { pollInterval: 100 },
+    );
+    processor.start();
+    await new Promise((r) => setTimeout(r, 300));
+    processor.stop();
+
+    const originalJob = await jobQueue.getJob(jobId1);
+    expect(originalJob?.status).toBe('completed');
+
+    await jobQueue.editJob(jobId1, {
+      payload: { to: 'updated@example.com' },
+    });
+
+    const job = await jobQueue.getJob(jobId1);
+    expect(job?.status).toBe('completed');
+    expect(job?.payload).toEqual({ to: 'original@example.com' });
+
+    // Try to edit a processing job
+    // Use a handler that takes longer to ensure job stays in processing state
+    const slowHandler = vi.fn(async (payload: { to: string }, _signal) => {
+      await new Promise((r) => setTimeout(r, 200));
+    });
+    const slowHandlerTest = vi.fn(async (payload: { foo: string }, _signal) => {
+      await new Promise((r) => setTimeout(r, 200));
+    });
+    const processor2 = jobQueue.createProcessor(
+      {
+        email: slowHandler,
+        sms: slowHandler,
+        test: slowHandlerTest,
+      },
+      { pollInterval: 100 },
+    );
+    const jobId2 = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'processing@example.com' },
+    });
+    processor2.start();
+    // Wait a bit for job to be picked up
+    await new Promise((r) => setTimeout(r, 150));
+    // Job should be processing now
+    const processingJob = await jobQueue.getJob(jobId2);
+    if (processingJob?.status === 'processing') {
+      await jobQueue.editJob(jobId2, {
+        payload: { to: 'updated@example.com' },
+      });
+
+      const job2 = await jobQueue.getJob(jobId2);
+      // If still processing, payload should be unchanged
+      if (job2?.status === 'processing') {
+        expect(job2?.payload).toEqual({ to: 'processing@example.com' });
+      }
+    }
+    processor2.stop();
+  });
+
+  it('should record edited event when editing via JobQueue API', async () => {
+    const jobId = await jobQueue.addJob({
+      jobType: 'email',
+      payload: { to: 'original@example.com' },
+    });
+
+    await jobQueue.editJob(jobId, {
+      payload: { to: 'updated@example.com' },
+      priority: 10,
+    });
+
+    const events = await jobQueue.getJobEvents(jobId);
+    const editEvent = events.find((e) => e.eventType === 'edited');
+    expect(editEvent).not.toBeUndefined();
+    expect(editEvent?.metadata).toMatchObject({
+      payload: { to: 'updated@example.com' },
+      priority: 10,
+    });
+  });
 });

package/src/index.ts

@@ -1,16 +1,8 @@
 import {
-  addJob,
-  getJob,
-  getJobsByStatus,
-  retryJob,
-  cleanupOldJobs,
-  cancelJob,
-  cancelAllUpcomingJobs,
-  getAllJobs,
-  reclaimStuckJobs,
-  getJobEvents,
-  getJobsByTags,
-  getJobs,
+  createWaitpoint,
+  completeWaitpoint,
+  getWaitpoint,
+  expireTimedOutWaitpoints,
 } from './queue.js';
 import { createProcessor } from './processor.js';
 import {
@@ -19,42 +11,71 @@ import {
   JobOptions,
   ProcessorOptions,
   JobHandlers,
+  JobType,
+  PostgresJobQueueConfig,
+  RedisJobQueueConfig,
 } from './types.js';
+import { QueueBackend } from './backend.js';
 import { setLogContext } from './log-context.js';
 import { createPool } from './db-util.js';
+import { PostgresBackend } from './backends/postgres.js';
+import { RedisBackend } from './backends/redis.js';
 
 /**
- * Initialize the job queue system
+ * Initialize the job queue system.
+ *
+ * Defaults to PostgreSQL when `backend` is omitted.
  */
 export const initJobQueue = <PayloadMap = any>(
   config: JobQueueConfig,
 ): JobQueue<PayloadMap> => {
-  const { databaseConfig } = config;
+  const backendType = config.backend ?? 'postgres';
+  setLogContext(config.verbose ?? false);
 
-  // Create database pool
-  const pool = createPool(databaseConfig);
+  let backend: QueueBackend;
+  let pool: import('pg').Pool | undefined;
 
-  setLogContext(config.verbose ?? false);
+  if (backendType === 'postgres') {
+    const pgConfig = config as PostgresJobQueueConfig;
+    pool = createPool(pgConfig.databaseConfig);
+    backend = new PostgresBackend(pool);
+  } else if (backendType === 'redis') {
+    const redisConfig = (config as RedisJobQueueConfig).redisConfig;
+    // RedisBackend constructor will throw if ioredis is not installed
+    backend = new RedisBackend(redisConfig);
+  } else {
+    throw new Error(`Unknown backend: ${backendType}`);
+  }
+
+  const requirePool = () => {
+    if (!pool) {
+      throw new Error(
+        'Wait/Token features require the PostgreSQL backend. Configure with backend: "postgres" to use these features.',
+      );
+    }
+    return pool;
+  };
 
   // Return the job queue API
   return {
     // Job queue operations
     addJob: withLogContext(
-      (job: JobOptions<PayloadMap, any>) => addJob<PayloadMap, any>(pool, job),
+      (job: JobOptions<PayloadMap, any>) =>
+        backend.addJob<PayloadMap, any>(job),
       config.verbose ?? false,
     ),
     getJob: withLogContext(
-      (id: number) => getJob<PayloadMap, any>(pool, id),
+      (id: number) => backend.getJob<PayloadMap, any>(id),
       config.verbose ?? false,
     ),
     getJobsByStatus: withLogContext(
       (status: string, limit?: number, offset?: number) =>
-        getJobsByStatus<PayloadMap, any>(pool, status, limit, offset),
+        backend.getJobsByStatus<PayloadMap, any>(status, limit, offset),
       config.verbose ?? false,
     ),
     getAllJobs: withLogContext(
       (limit?: number, offset?: number) =>
-        getAllJobs<PayloadMap, any>(pool, limit, offset),
+        backend.getAllJobs<PayloadMap, any>(limit, offset),
       config.verbose ?? false,
     ),
     getJobs: withLogContext(
@@ -69,13 +90,45 @@ export const initJobQueue = <PayloadMap = any>(
         },
         limit?: number,
         offset?: number,
-      ) => getJobs<PayloadMap, any>(pool, filters, limit, offset),
+      ) => backend.getJobs<PayloadMap, any>(filters, limit, offset),
       config.verbose ?? false,
     ),
-    retryJob: (jobId: number) => retryJob(pool, jobId),
-    cleanupOldJobs: (daysToKeep?: number) => cleanupOldJobs(pool, daysToKeep),
+    retryJob: (jobId: number) => backend.retryJob(jobId),
+    cleanupOldJobs: (daysToKeep?: number) => backend.cleanupOldJobs(daysToKeep),
+    cleanupOldJobEvents: (daysToKeep?: number) =>
+      backend.cleanupOldJobEvents(daysToKeep),
     cancelJob: withLogContext(
-      (jobId: number) => cancelJob(pool, jobId),
+      (jobId: number) => backend.cancelJob(jobId),
+      config.verbose ?? false,
+    ),
+    editJob: withLogContext(
+      <T extends JobType<PayloadMap>>(
+        jobId: number,
+        updates: import('./types.js').EditJobOptions<PayloadMap, T>,
+      ) => backend.editJob(jobId, updates as import('./backend.js').JobUpdates),
+      config.verbose ?? false,
+    ),
+    editAllPendingJobs: withLogContext(
+      <T extends JobType<PayloadMap>>(
+        filters:
+          | {
+              jobType?: string;
+              priority?: number;
+              runAt?:
+                | Date
+                | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
+              tags?: {
+                values: string[];
+                mode?: import('./types.js').TagQueryMode;
+              };
+            }
+          | undefined,
+        updates: import('./types.js').EditJobOptions<PayloadMap, T>,
+      ) =>
+        backend.editAllPendingJobs(
+          filters,
+          updates as import('./backend.js').JobUpdates,
+        ),
       config.verbose ?? false,
     ),
     cancelAllUpcomingJobs: withLogContext(
@@ -86,17 +139,17 @@ export const initJobQueue = <PayloadMap = any>(
           | Date
           | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
         tags?: { values: string[]; mode?: import('./types.js').TagQueryMode };
-      }) => cancelAllUpcomingJobs(pool, filters),
+      }) => backend.cancelAllUpcomingJobs(filters),
       config.verbose ?? false,
     ),
     reclaimStuckJobs: withLogContext(
       (maxProcessingTimeMinutes?: number) =>
-        reclaimStuckJobs(pool, maxProcessingTimeMinutes),
+        backend.reclaimStuckJobs(maxProcessingTimeMinutes),
       config.verbose ?? false,
     ),
     getJobsByTags: withLogContext(
       (tags: string[], mode = 'all', limit?: number, offset?: number) =>
-        getJobsByTags<PayloadMap, any>(pool, tags, mode, limit, offset),
+        backend.getJobsByTags<PayloadMap, any>(tags, mode, limit, offset),
       config.verbose ?? false,
     ),
 
@@ -104,14 +157,51 @@ export const initJobQueue = <PayloadMap = any>(
     createProcessor: (
       handlers: JobHandlers<PayloadMap>,
       options?: ProcessorOptions,
-    ) => createProcessor<PayloadMap>(pool, handlers, options),
-    // Advanced access (for custom operations)
-    getPool: () => pool,
+    ) => createProcessor<PayloadMap>(backend, handlers, options),
+
     // Job events
     getJobEvents: withLogContext(
-      (jobId: number) => getJobEvents(pool, jobId),
+      (jobId: number) => backend.getJobEvents(jobId),
       config.verbose ?? false,
     ),
+
+    // Wait / Token support (PostgreSQL-only for now)
+    createToken: withLogContext(
+      (options?: import('./types.js').CreateTokenOptions) =>
+        createWaitpoint(requirePool(), null, options),
+      config.verbose ?? false,
+    ),
+    completeToken: withLogContext(
+      (tokenId: string, data?: any) =>
+        completeWaitpoint(requirePool(), tokenId, data),
+      config.verbose ?? false,
+    ),
+    getToken: withLogContext(
+      (tokenId: string) => getWaitpoint(requirePool(), tokenId),
+      config.verbose ?? false,
+    ),
+    expireTimedOutTokens: withLogContext(
+      () => expireTimedOutWaitpoints(requirePool()),
+      config.verbose ?? false,
+    ),
+
+    // Advanced access
+    getPool: () => {
+      if (backendType !== 'postgres') {
+        throw new Error(
+          'getPool() is only available with the PostgreSQL backend.',
+        );
+      }
+      return (backend as PostgresBackend).getPool();
+    },
+    getRedisClient: () => {
+      if (backendType !== 'redis') {
+        throw new Error(
+          'getRedisClient() is only available with the Redis backend.',
+        );
+      }
+      return (backend as RedisBackend).getClient();
+    },
   };
 };
 
@@ -123,3 +213,9 @@ const withLogContext =
   };
 
 export * from './types.js';
+export { QueueBackend } from './backend.js';
+export { PostgresBackend } from './backends/postgres.js';
+export {
+  validateHandlerSerializable,
+  testHandlerSerialization,
+} from './handler-validation.js';