@onebun/core 0.2.11 → 0.2.13

package/src/queue/scheduler.test.ts

@@ -239,6 +239,286 @@ describe('QueueScheduler', () => {
     });
   });
 
+  describe('addJob', () => {
+    it('should add a cron job visible via getJob', () => {
+      scheduler.addJob({
+        type: 'cron',
+        name: 'my-cron',
+        expression: '0 0 * * * *',
+        pattern: 'test.cron',
+      });
+
+      const job = scheduler.getJob('my-cron');
+      expect(job).toBeDefined();
+      expect(job!.type).toBe('cron');
+      expect(job!.paused).toBe(false);
+      expect(job!.declarative).toBe(false);
+      expect(job!.schedule.cron).toBe('0 0 * * * *');
+    });
+
+    it('should add an interval job visible via getJob', () => {
+      scheduler.addJob({
+        type: 'interval',
+        name: 'my-interval',
+        intervalMs: 5000,
+        pattern: 'test.interval',
+      });
+
+      const job = scheduler.getJob('my-interval');
+      expect(job).toBeDefined();
+      expect(job!.type).toBe('interval');
+      expect(job!.paused).toBe(false);
+      expect(job!.declarative).toBe(false);
+      expect(job!.schedule.every).toBe(5000);
+    });
+
+    it('should add a timeout job visible via getJob', () => {
+      scheduler.addJob({
+        type: 'timeout',
+        name: 'my-timeout',
+        timeoutMs: 3000,
+        pattern: 'test.timeout',
+      });
+
+      const job = scheduler.getJob('my-timeout');
+      expect(job).toBeDefined();
+      expect(job!.type).toBe('timeout');
+      expect(job!.paused).toBe(false);
+      expect(job!.declarative).toBe(false);
+      expect(job!.schedule.timeout).toBe(3000);
+    });
+  });
+
+  describe('getJobs returns type, paused, and timeout', () => {
+    it('should return correct type, paused, and schedule for all job types', () => {
+      scheduler.addJob({
+        type: 'cron', name: 'c1', expression: '* * * * *', pattern: 'p', 
+      });
+      scheduler.addJob({
+        type: 'interval', name: 'i1', intervalMs: 1000, pattern: 'p', 
+      });
+      scheduler.addJob({
+        type: 'timeout', name: 't1', timeoutMs: 2000, pattern: 'p', 
+      });
+
+      const jobs = scheduler.getJobs();
+      expect(jobs.length).toBe(3);
+
+      const cronJob = jobs.find((j) => j.name === 'c1');
+      expect(cronJob!.type).toBe('cron');
+      expect(cronJob!.paused).toBe(false);
+
+      const intervalJob = jobs.find((j) => j.name === 'i1');
+      expect(intervalJob!.type).toBe('interval');
+      expect(intervalJob!.paused).toBe(false);
+      expect(intervalJob!.schedule.every).toBe(1000);
+
+      const timeoutJob = jobs.find((j) => j.name === 't1');
+      expect(timeoutJob!.type).toBe('timeout');
+      expect(timeoutJob!.paused).toBe(false);
+      expect(timeoutJob!.schedule.timeout).toBe(2000);
+    });
+  });
+
+  describe('declarative field', () => {
+    it('should mark jobs added via addCronJob with declarative option as declarative', () => {
+      scheduler.addCronJob('dec-cron', '* * * * *', 'p', undefined, { declarative: true });
+
+      const job = scheduler.getJob('dec-cron');
+      expect(job).toBeDefined();
+      expect(job!.declarative).toBe(true);
+    });
+
+    it('should mark jobs added via addIntervalJob with declarative option as declarative', () => {
+      scheduler.addIntervalJob('dec-interval', 1000, 'p', undefined, { declarative: true });
+
+      const job = scheduler.getJob('dec-interval');
+      expect(job).toBeDefined();
+      expect(job!.declarative).toBe(true);
+    });
+
+    it('should mark jobs added via addTimeoutJob with declarative option as declarative', () => {
+      scheduler.addTimeoutJob('dec-timeout', 1000, 'p', undefined, { declarative: true });
+
+      const job = scheduler.getJob('dec-timeout');
+      expect(job).toBeDefined();
+      expect(job!.declarative).toBe(true);
+    });
+
+    it('should mark jobs added via addJob as not declarative', () => {
+      scheduler.addJob({
+        type: 'cron', name: 'dyn-cron', expression: '* * * * *', pattern: 'p', 
+      });
+
+      const job = scheduler.getJob('dyn-cron');
+      expect(job).toBeDefined();
+      expect(job!.declarative).toBe(false);
+    });
+  });
+
+  describe('pauseJob', () => {
+    it('should pause an existing job and return true', () => {
+      scheduler.addJob({
+        type: 'interval', name: 'j1', intervalMs: 1000, pattern: 'p', 
+      });
+
+      const result = scheduler.pauseJob('j1');
+      expect(result).toBe(true);
+
+      const job = scheduler.getJob('j1');
+      expect(job!.paused).toBe(true);
+    });
+
+    it('should return false for nonexistent job', () => {
+      const result = scheduler.pauseJob('nonexistent');
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('resumeJob', () => {
+    it('should resume a paused job and return true', () => {
+      scheduler.addJob({
+        type: 'interval', name: 'j1', intervalMs: 1000, pattern: 'p', 
+      });
+      scheduler.pauseJob('j1');
+
+      const result = scheduler.resumeJob('j1');
+      expect(result).toBe(true);
+
+      const job = scheduler.getJob('j1');
+      expect(job!.paused).toBe(false);
+    });
+
+    it('should return false for nonexistent job', () => {
+      const result = scheduler.resumeJob('nonexistent');
+      expect(result).toBe(false);
+    });
+
+    it('should return false for non-paused job', () => {
+      scheduler.addJob({
+        type: 'interval', name: 'j1', intervalMs: 1000, pattern: 'p', 
+      });
+
+      const result = scheduler.resumeJob('j1');
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('updateJob', () => {
+    it('should update cron expression', () => {
+      scheduler.addJob({
+        type: 'cron',
+        name: 'c1',
+        expression: '0 0 * * * *',
+        pattern: 'p',
+      });
+
+      const result = scheduler.updateJob({ type: 'cron', name: 'c1', expression: '*/5 * * * *' });
+      expect(result).toBe(true);
+
+      const job = scheduler.getJob('c1');
+      expect(job!.schedule.cron).toBe('*/5 * * * *');
+    });
+
+    it('should update interval', () => {
+      scheduler.addJob({
+        type: 'interval', name: 'i1', intervalMs: 1000, pattern: 'p', 
+      });
+
+      const result = scheduler.updateJob({ type: 'interval', name: 'i1', intervalMs: 5000 });
+      expect(result).toBe(true);
+
+      const job = scheduler.getJob('i1');
+      expect(job!.schedule.every).toBe(5000);
+    });
+
+    it('should update timeout', () => {
+      scheduler.addJob({
+        type: 'timeout', name: 't1', timeoutMs: 1000, pattern: 'p', 
+      });
+
+      const result = scheduler.updateJob({ type: 'timeout', name: 't1', timeoutMs: 9000 });
+      expect(result).toBe(true);
+
+      const job = scheduler.getJob('t1');
+      expect(job!.schedule.timeout).toBe(9000);
+    });
+
+    it('should return false when type does not match', () => {
+      scheduler.addJob({
+        type: 'interval', name: 'i1', intervalMs: 1000, pattern: 'p', 
+      });
+
+      const result = scheduler.updateJob({ type: 'cron', name: 'i1', expression: '* * * * *' });
+      expect(result).toBe(false);
+    });
+
+    it('should return false for nonexistent job', () => {
+      const result = scheduler.updateJob({ type: 'cron', name: 'nope', expression: '* * * * *' });
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('paused jobs do not fire', () => {
+    it('should not fire paused cron job', async () => {
+      const received: Message[] = [];
+      await adapter.subscribe('test.cron', async (message) => {
+        received.push(message);
+      });
+
+      // Every second cron
+      scheduler.addJob({
+        type: 'cron',
+        name: 'cron-paused',
+        expression: '* * * * * *',
+        pattern: 'test.cron',
+      });
+      scheduler.pauseJob('cron-paused');
+      scheduler.start();
+
+      // Advance time well past when cron would fire
+      advanceTime(5000);
+      await Promise.resolve();
+
+      expect(received.length).toBe(0);
+    });
+
+    it('should not fire paused interval job, and resume restarts it', async () => {
+      const received: Message[] = [];
+      await adapter.subscribe('test.interval', async (message) => {
+        received.push(message);
+      });
+
+      scheduler.addJob({
+        type: 'interval',
+        name: 'int-paused',
+        intervalMs: 100,
+        pattern: 'test.interval',
+      });
+      scheduler.start();
+
+      // Should fire immediately on start
+      advanceTime(10);
+      await Promise.resolve();
+      expect(received.length).toBe(1);
+
+      // Pause the job
+      scheduler.pauseJob('int-paused');
+
+      // Advance time — no new messages
+      advanceTime(500);
+      await Promise.resolve();
+      expect(received.length).toBe(1);
+
+      // Resume — should restart interval and fire immediately
+      scheduler.resumeJob('int-paused');
+
+      advanceTime(10);
+      await Promise.resolve();
+      expect(received.length).toBe(2);
+    });
+  });
+
   describe('createQueueScheduler', () => {
     it('should create scheduler instance', () => {
       const created = createQueueScheduler(adapter);

package/src/queue/scheduler.ts

@@ -6,6 +6,8 @@
  */
 
 import type {
+  AddJobOptions,
+  UpdateJobOptions,
   QueueAdapter,
   ScheduledJobInfo,
   OverlapStrategy,
@@ -42,6 +44,12 @@ interface ScheduledJob {
   // Timeout-specific
   timeoutMs?: number;
 
+  // Pause state
+  paused?: boolean;
+
+  // Whether created via decorator
+  declarative?: boolean;
+
   // Runtime state
   timer?: ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>;
   isRunning?: boolean;
@@ -64,9 +72,17 @@ export class QueueScheduler {
   private running = false;
   private cronCheckInterval?: ReturnType<typeof setInterval>;
   private readonly cronCheckIntervalMs = 1000; // Check cron jobs every second
+  private onJobError?: (jobName: string, error: unknown) => void;
 
   constructor(private readonly adapter: QueueAdapter) {}
 
+  /**
+   * Set error handler for scheduled job failures
+   */
+  setErrorHandler(handler: (jobName: string, error: unknown) => void): void {
+    this.onJobError = handler;
+  }
+
   /**
    * Start the scheduler
    */
@@ -82,8 +98,12 @@ export class QueueScheduler {
       this.checkCronJobs();
     }, this.cronCheckIntervalMs);
 
-    // Start all interval and timeout jobs
+    // Start all interval and timeout jobs (skip paused)
     for (const job of this.jobs.values()) {
+      if (job.paused) {
+        continue;
+      }
+
       if (job.type === 'interval' && job.intervalMs) {
         this.startIntervalJob(job);
       } else if (job.type === 'timeout' && job.timeoutMs) {
@@ -129,6 +149,7 @@ export class QueueScheduler {
     options?: {
       metadata?: Partial<MessageMetadata>;
       overlapStrategy?: OverlapStrategy;
+      declarative?: boolean;
     },
   ): void {
     const schedule = parseCronExpression(expression);
@@ -144,6 +165,7 @@ export class QueueScheduler {
       getDataFn,
       metadata: options?.metadata,
       overlapStrategy: options?.overlapStrategy ?? 'skip',
+      declarative: options?.declarative,
     };
 
     this.jobs.set(name, job);
@@ -159,6 +181,7 @@ export class QueueScheduler {
     getDataFn?: () => unknown | Promise<unknown>,
     options?: {
       metadata?: Partial<MessageMetadata>;
+      declarative?: boolean;
     },
   ): void {
     const job: ScheduledJob = {
@@ -168,6 +191,7 @@ export class QueueScheduler {
       intervalMs,
       getDataFn,
       metadata: options?.metadata,
+      declarative: options?.declarative,
     };
 
     this.jobs.set(name, job);
@@ -188,6 +212,7 @@ export class QueueScheduler {
     getDataFn?: () => unknown | Promise<unknown>,
     options?: {
       metadata?: Partial<MessageMetadata>;
+      declarative?: boolean;
     },
   ): void {
     const job: ScheduledJob = {
@@ -197,6 +222,7 @@ export class QueueScheduler {
       timeoutMs,
       getDataFn,
       metadata: options?.metadata,
+      declarative: options?.declarative,
     };
 
     this.jobs.set(name, job);
@@ -207,6 +233,118 @@ export class QueueScheduler {
     }
   }
 
+  /**
+   * Add a job using the unified API
+   */
+  addJob(options: AddJobOptions): void {
+    switch (options.type) {
+      case 'cron':
+        this.addCronJob(options.name, options.expression, options.pattern, options.getDataFn, {
+          metadata: options.metadata,
+          overlapStrategy: options.overlapStrategy,
+        });
+        break;
+      case 'interval':
+        this.addIntervalJob(options.name, options.intervalMs, options.pattern, options.getDataFn, {
+          metadata: options.metadata,
+        });
+        break;
+      case 'timeout':
+        this.addTimeoutJob(options.name, options.timeoutMs, options.pattern, options.getDataFn, {
+          metadata: options.metadata,
+        });
+        break;
+    }
+  }
+
+  /**
+   * Pause a scheduled job
+   */
+  pauseJob(name: string): boolean {
+    const job = this.jobs.get(name);
+    if (!job) {
+      return false;
+    }
+
+    job.paused = true;
+
+    if (job.timer) {
+      clearTimeout(job.timer);
+      clearInterval(job.timer);
+      job.timer = undefined;
+    }
+
+    return true;
+  }
+
+  /**
+   * Resume a paused job
+   */
+  resumeJob(name: string): boolean {
+    const job = this.jobs.get(name);
+    if (!job || !job.paused) {
+      return false;
+    }
+
+    job.paused = false;
+
+    if (this.running) {
+      if (job.type === 'interval' && job.intervalMs) {
+        this.startIntervalJob(job);
+      } else if (job.type === 'timeout' && job.timeoutMs) {
+        this.startTimeoutJob(job);
+      } else if (job.type === 'cron' && job.cronSchedule) {
+        job.nextRun = getNextRun(job.cronSchedule) ?? undefined;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Update a scheduled job's timing configuration
+   */
+  updateJob(options: UpdateJobOptions): boolean {
+    const job = this.jobs.get(options.name);
+    if (!job || job.type !== options.type) {
+      return false;
+    }
+
+    switch (options.type) {
+      case 'cron': {
+        const schedule = parseCronExpression(options.expression);
+        job.cronExpression = options.expression;
+        job.cronSchedule = schedule;
+        job.nextRun = getNextRun(schedule) ?? undefined;
+        break;
+      }
+      case 'interval': {
+        if (job.timer) {
+          clearInterval(job.timer);
+          job.timer = undefined;
+        }
+        job.intervalMs = options.intervalMs;
+        if (this.running && !job.paused) {
+          this.startIntervalJob(job);
+        }
+        break;
+      }
+      case 'timeout': {
+        if (job.timer) {
+          clearTimeout(job.timer);
+          job.timer = undefined;
+        }
+        job.timeoutMs = options.timeoutMs;
+        if (this.running && !job.paused) {
+          this.startTimeoutJob(job);
+        }
+        break;
+      }
+    }
+
+    return true;
+  }
+
   /**
    * Remove a job
    */
@@ -236,10 +374,14 @@ export class QueueScheduler {
     for (const job of this.jobs.values()) {
       result.push({
         name: job.name,
+        type: job.type,
+        paused: job.paused ?? false,
+        declarative: job.declarative ?? false,
         pattern: job.pattern,
         schedule: {
           cron: job.cronExpression,
           every: job.intervalMs,
+          timeout: job.timeoutMs,
         },
         nextRun: job.nextRun,
         lastRun: job.lastRun,
@@ -261,10 +403,14 @@ export class QueueScheduler {
 
     return {
       name: job.name,
+      type: job.type,
+      paused: job.paused ?? false,
+      declarative: job.declarative ?? false,
       pattern: job.pattern,
       schedule: {
         cron: job.cronExpression,
         every: job.intervalMs,
+        timeout: job.timeoutMs,
       },
       nextRun: job.nextRun,
       lastRun: job.lastRun,
@@ -294,6 +440,10 @@ export class QueueScheduler {
         continue;
       }
 
+      if (job.paused) {
+        continue;
+      }
+
       // Check if it's time to run
       if (job.nextRun && now >= job.nextRun) {
         // Handle overlap strategy
@@ -363,8 +513,11 @@ export class QueueScheduler {
       await this.adapter.publish(job.pattern, data, {
         metadata: job.metadata,
       });
-    } catch {
-      // Error executing job - silently continue (error handling should be done via events)
+    } catch (error) {
+      // Report error via handler if set, otherwise silently continue
+      if (this.onJobError) {
+        this.onJobError(job.name, error);
+      }
     } finally {
       job.isRunning = false;
     }

package/src/queue/types.ts

@@ -224,30 +224,79 @@ export interface Subscription {
 export type OverlapStrategy = 'skip' | 'queue';
 
 /**
- * Options for scheduled jobs
+ * Add a cron job
  */
-export interface ScheduledJobOptions {
-  /** Pattern to publish to */
+export interface AddCronJob {
+  type: 'cron';
+  name: string;
+  expression: string;
   pattern: string;
+  getDataFn?: () => unknown | Promise<unknown>;
+  metadata?: Partial<MessageMetadata>;
+  overlapStrategy?: OverlapStrategy;
+}
 
-  /** Data to include in the message */
-  data?: unknown;
-
-  /** Schedule configuration */
-  schedule: {
-    /** Cron expression */
-    cron?: string;
-    /** Interval in milliseconds */
-    every?: number;
-  };
+/**
+ * Add an interval job
+ */
+export interface AddIntervalJob {
+  type: 'interval';
+  name: string;
+  intervalMs: number;
+  pattern: string;
+  getDataFn?: () => unknown | Promise<unknown>;
+  metadata?: Partial<MessageMetadata>;
+}
 
-  /** Metadata to include in messages */
+/**
+ * Add a timeout job
+ */
+export interface AddTimeoutJob {
+  type: 'timeout';
+  name: string;
+  timeoutMs: number;
+  pattern: string;
+  getDataFn?: () => unknown | Promise<unknown>;
   metadata?: Partial<MessageMetadata>;
+}
 
-  /** What to do if previous job is still running */
-  overlapStrategy?: OverlapStrategy;
+/**
+ * Discriminated union for adding any scheduled job type
+ */
+export type AddJobOptions = AddCronJob | AddIntervalJob | AddTimeoutJob;
+
+/**
+ * Update a cron job's expression
+ */
+export interface UpdateCronJob {
+  type: 'cron';
+  name: string;
+  expression: string;
 }
 
+/**
+ * Update an interval job's interval
+ */
+export interface UpdateIntervalJob {
+  type: 'interval';
+  name: string;
+  intervalMs: number;
+}
+
+/**
+ * Update a timeout job's delay
+ */
+export interface UpdateTimeoutJob {
+  type: 'timeout';
+  name: string;
+  timeoutMs: number;
+}
+
+/**
+ * Discriminated union for updating any scheduled job type
+ */
+export type UpdateJobOptions = UpdateCronJob | UpdateIntervalJob | UpdateTimeoutJob;
+
 /**
  * Information about a scheduled job
  */
@@ -255,13 +304,23 @@ export interface ScheduledJobInfo {
   /** Job name */
   name: string;
 
+  /** Job type */
+  type: 'cron' | 'interval' | 'timeout';
+
   /** Pattern to publish to */
   pattern: string;
 
+  /** Whether the job is paused */
+  paused: boolean;
+
+  /** Whether the job was created via decorator (@Cron, @Interval, @Timeout) */
+  declarative: boolean;
+
   /** Schedule configuration */
   schedule: {
     cron?: string;
     every?: number;
+    timeout?: number;
   };
 
   /** Next scheduled run time */
@@ -286,7 +345,6 @@ export type QueueFeature =
   | 'priority'
   | 'dead-letter-queue'
   | 'retry'
-  | 'scheduled-jobs'
   | 'consumer-groups'
   | 'pattern-subscriptions';
 
@@ -353,16 +411,6 @@ export interface QueueAdapter {
     options?: SubscribeOptions
   ): Promise<Subscription>;
 
-  // Scheduled Jobs
-  /** Add a scheduled job */
-  addScheduledJob(name: string, options: ScheduledJobOptions): Promise<void>;
-
-  /** Remove a scheduled job */
-  removeScheduledJob(name: string): Promise<boolean>;
-
-  /** Get all scheduled jobs */
-  getScheduledJobs(): Promise<ScheduledJobInfo[]>;
-
   // Feature Support
   /** Check if a feature is supported by this adapter */
   supports(feature: QueueFeature): boolean;

package/src/testing/test-utils.ts

@@ -232,7 +232,7 @@ export const fakeTimers = new FakeTimers();
  * 
  * @example
  * ```typescript
- * import { useFakeTimers } from '@onebun/core';
+ * import { useFakeTimers } from '@onebun/core/testing';
  * 
  * describe('My tests', () => {
  *   const { advanceTime, restore } = useFakeTimers();