@nicnocquee/dataqueue 1.30.0 → 1.31.0

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 } from './types.js';
 
 // Integration tests for index.ts
 
@@ -532,3 +533,363 @@ describe('index integration', () => {
     });
   });
 });
+
+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);
+  });
+});

package/src/index.ts

@@ -14,12 +14,16 @@ import {
   JobType,
   PostgresJobQueueConfig,
   RedisJobQueueConfig,
+  CronScheduleOptions,
+  CronScheduleStatus,
+  EditCronScheduleOptions,
 } from './types.js';
-import { QueueBackend } from './backend.js';
+import { QueueBackend, CronScheduleInput } 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';
+import { getNextCronOccurrence, validateCronExpression } from './cron.js';
 
 /**
  * Initialize the job queue system.
@@ -56,6 +60,66 @@ export const initJobQueue = <PayloadMap = any>(
     return pool;
   };
 
+  /**
+   * Enqueue due cron jobs. Shared by the public API and the processor hook.
+   */
+  const enqueueDueCronJobsImpl = async (): Promise<number> => {
+    const dueSchedules = await backend.getDueCronSchedules();
+    let count = 0;
+
+    for (const schedule of dueSchedules) {
+      // Overlap check: skip if allowOverlap is false and last job is still active
+      if (!schedule.allowOverlap && schedule.lastJobId !== null) {
+        const lastJob = await backend.getJob(schedule.lastJobId);
+        if (
+          lastJob &&
+          (lastJob.status === 'pending' ||
+            lastJob.status === 'processing' ||
+            lastJob.status === 'waiting')
+        ) {
+          // Still active — advance nextRunAt but don't enqueue
+          const nextRunAt = getNextCronOccurrence(
+            schedule.cronExpression,
+            schedule.timezone,
+          );
+          await backend.updateCronScheduleAfterEnqueue(
+            schedule.id,
+            new Date(),
+            schedule.lastJobId,
+            nextRunAt,
+          );
+          continue;
+        }
+      }
+
+      // Enqueue a new job instance
+      const jobId = await backend.addJob<any, any>({
+        jobType: schedule.jobType,
+        payload: schedule.payload,
+        maxAttempts: schedule.maxAttempts,
+        priority: schedule.priority,
+        timeoutMs: schedule.timeoutMs ?? undefined,
+        forceKillOnTimeout: schedule.forceKillOnTimeout,
+        tags: schedule.tags,
+      });
+
+      // Advance to next occurrence
+      const nextRunAt = getNextCronOccurrence(
+        schedule.cronExpression,
+        schedule.timezone,
+      );
+      await backend.updateCronScheduleAfterEnqueue(
+        schedule.id,
+        new Date(),
+        jobId,
+        nextRunAt,
+      );
+      count++;
+    }
+
+    return count;
+  };
+
   // Return the job queue API
   return {
     // Job queue operations
@@ -153,11 +217,14 @@ export const initJobQueue = <PayloadMap = any>(
       config.verbose ?? false,
     ),
 
-    // Job processing
+    // Job processing — automatically enqueues due cron jobs before each batch
     createProcessor: (
       handlers: JobHandlers<PayloadMap>,
       options?: ProcessorOptions,
-    ) => createProcessor<PayloadMap>(backend, handlers, options),
+    ) =>
+      createProcessor<PayloadMap>(backend, handlers, options, async () => {
+        await enqueueDueCronJobsImpl();
+      }),
 
     // Job events
     getJobEvents: withLogContext(
@@ -185,6 +252,91 @@ export const initJobQueue = <PayloadMap = any>(
       config.verbose ?? false,
     ),
 
+    // Cron schedule operations
+    addCronJob: withLogContext(
+      <T extends JobType<PayloadMap>>(
+        options: CronScheduleOptions<PayloadMap, T>,
+      ) => {
+        if (!validateCronExpression(options.cronExpression)) {
+          return Promise.reject(
+            new Error(`Invalid cron expression: "${options.cronExpression}"`),
+          );
+        }
+        const nextRunAt = getNextCronOccurrence(
+          options.cronExpression,
+          options.timezone ?? 'UTC',
+        );
+        const input: CronScheduleInput = {
+          scheduleName: options.scheduleName,
+          cronExpression: options.cronExpression,
+          jobType: options.jobType as string,
+          payload: options.payload,
+          maxAttempts: options.maxAttempts ?? 3,
+          priority: options.priority ?? 0,
+          timeoutMs: options.timeoutMs ?? null,
+          forceKillOnTimeout: options.forceKillOnTimeout ?? false,
+          tags: options.tags,
+          timezone: options.timezone ?? 'UTC',
+          allowOverlap: options.allowOverlap ?? false,
+          nextRunAt,
+        };
+        return backend.addCronSchedule(input);
+      },
+      config.verbose ?? false,
+    ),
+    getCronJob: withLogContext(
+      (id: number) => backend.getCronSchedule(id),
+      config.verbose ?? false,
+    ),
+    getCronJobByName: withLogContext(
+      (name: string) => backend.getCronScheduleByName(name),
+      config.verbose ?? false,
+    ),
+    listCronJobs: withLogContext(
+      (status?: CronScheduleStatus) => backend.listCronSchedules(status),
+      config.verbose ?? false,
+    ),
+    removeCronJob: withLogContext(
+      (id: number) => backend.removeCronSchedule(id),
+      config.verbose ?? false,
+    ),
+    pauseCronJob: withLogContext(
+      (id: number) => backend.pauseCronSchedule(id),
+      config.verbose ?? false,
+    ),
+    resumeCronJob: withLogContext(
+      (id: number) => backend.resumeCronSchedule(id),
+      config.verbose ?? false,
+    ),
+    editCronJob: withLogContext(
+      async (id: number, updates: EditCronScheduleOptions) => {
+        if (
+          updates.cronExpression !== undefined &&
+          !validateCronExpression(updates.cronExpression)
+        ) {
+          throw new Error(
+            `Invalid cron expression: "${updates.cronExpression}"`,
+          );
+        }
+        let nextRunAt: Date | null | undefined;
+        if (
+          updates.cronExpression !== undefined ||
+          updates.timezone !== undefined
+        ) {
+          const existing = await backend.getCronSchedule(id);
+          const expr = updates.cronExpression ?? existing?.cronExpression ?? '';
+          const tz = updates.timezone ?? existing?.timezone ?? 'UTC';
+          nextRunAt = getNextCronOccurrence(expr, tz);
+        }
+        await backend.editCronSchedule(id, updates, nextRunAt);
+      },
+      config.verbose ?? false,
+    ),
+    enqueueDueCronJobs: withLogContext(
+      () => enqueueDueCronJobsImpl(),
+      config.verbose ?? false,
+    ),
+
     // Advanced access
     getPool: () => {
       if (backendType !== 'postgres') {
@@ -213,9 +365,10 @@ const withLogContext =
   };
 
 export * from './types.js';
-export { QueueBackend } from './backend.js';
+export { QueueBackend, CronScheduleInput } from './backend.js';
 export { PostgresBackend } from './backends/postgres.js';
 export {
   validateHandlerSerializable,
   testHandlerSerialization,
 } from './handler-validation.js';
+export { getNextCronOccurrence, validateCronExpression } from './cron.js';

package/src/processor.ts

@@ -818,16 +818,18 @@ export async function processBatchWithHandlers<PayloadMap>(
 }
 
 /**
- * Start a job processor that continuously processes jobs
- * @param backend - The queue backend
- * @param handlers - The job handlers for this processor instance
+ * Start a job processor that continuously processes jobs.
+ * @param backend - The queue backend.
+ * @param handlers - The job handlers for this processor instance.
  * @param options - The processor options. Leave pollInterval empty to run only once. Use jobType to filter jobs by type.
- * @returns {Processor} The processor instance
+ * @param onBeforeBatch - Optional callback invoked before each batch. Used internally to enqueue due cron jobs.
+ * @returns {Processor} The processor instance.
  */
 export const createProcessor = <PayloadMap = any>(
   backend: QueueBackend,
   handlers: JobHandlers<PayloadMap>,
   options: ProcessorOptions = {},
+  onBeforeBatch?: () => Promise<void>,
 ): Processor => {
   const {
     workerId = `worker-${Math.random().toString(36).substring(2, 9)}`,
@@ -847,6 +849,22 @@ export const createProcessor = <PayloadMap = any>(
   const processJobs = async (): Promise<number> => {
     if (!running) return 0;
 
+    // Run pre-batch hook (e.g. enqueue due cron jobs) before processing
+    if (onBeforeBatch) {
+      try {
+        await onBeforeBatch();
+      } catch (hookError) {
+        log(`onBeforeBatch hook error: ${hookError}`);
+        if (onError) {
+          onError(
+            hookError instanceof Error
+              ? hookError
+              : new Error(String(hookError)),
+          );
+        }
+      }
+    }
+
     log(
       `Processing jobs with workerId: ${workerId}${jobType ? ` and jobType: ${Array.isArray(jobType) ? jobType.join(',') : jobType}` : ''}`,
     );