@onebun/core 0.2.11 → 0.2.13

package/src/queue/docs-examples.test.ts

@@ -49,6 +49,8 @@ import {
   getIntervalMetadata,
   getTimeoutMetadata,
   hasQueueDecorators,
+  QueueScheduler,
+  QueueService,
 } from './index';
 
 /**
@@ -456,13 +458,6 @@ describe('Custom adapter NATS JetStream (docs/api/queue.md)', () => {
           isActive: true,
         };
       }
-      async addScheduledJob(): Promise<void> {}
-      async removeScheduledJob(): Promise<boolean> {
-        return false;
-      }
-      async getScheduledJobs(): Promise<import('./types').ScheduledJobInfo[]> {
-        return [];
-      }
       supports(): boolean {
         return false;
       }
@@ -585,11 +580,227 @@ describe('Feature Support Matrix (docs/api/queue.md)', () => {
     expect(adapter.supports('pattern-subscriptions')).toBe(true);
     expect(adapter.supports('delayed-messages')).toBe(true);
     expect(adapter.supports('priority')).toBe(true);
-    expect(adapter.supports('scheduled-jobs')).toBe(true);
-
     // Not supported
     expect(adapter.supports('consumer-groups')).toBe(false);
     expect(adapter.supports('dead-letter-queue')).toBe(false);
     expect(adapter.supports('retry')).toBe(false);
   });
 });
+
+/**
+ * @source docs/api/queue.md#setup (scheduled-only tip)
+ */
+describe('Scheduled-only Controllers (docs/api/queue.md)', () => {
+  it('should auto-detect queue decorators on controller with only @Interval', () => {
+    // From docs/api/queue.md: Scheduled-only Controllers tip
+    class ScheduledOnlyController {
+      @Interval(60000, { pattern: 'metrics.collect' })
+      getMetrics() {
+        return { cpu: process.cpuUsage() };
+      }
+    }
+
+    // No @Subscribe — only scheduling decorators
+    expect(hasQueueDecorators(ScheduledOnlyController)).toBe(true);
+    expect(getSubscribeMetadata(ScheduledOnlyController).length).toBe(0);
+    expect(getIntervalMetadata(ScheduledOnlyController).length).toBe(1);
+  });
+
+  it('should auto-detect queue decorators on controller with only @Cron', () => {
+    class CronOnlyController {
+      @Cron(CronExpression.EVERY_HOUR, { pattern: 'cleanup.expired' })
+      getCleanupData() {
+        return { timestamp: Date.now() };
+      }
+    }
+
+    expect(hasQueueDecorators(CronOnlyController)).toBe(true);
+    expect(getSubscribeMetadata(CronOnlyController).length).toBe(0);
+    expect(getCronMetadata(CronOnlyController).length).toBe(1);
+  });
+
+  it('should auto-detect queue decorators on controller with only @Timeout', () => {
+    class TimeoutOnlyController {
+      @Timeout(5000, { pattern: 'startup.warmup' })
+      getWarmupData() {
+        return { type: 'warmup' };
+      }
+    }
+
+    expect(hasQueueDecorators(TimeoutOnlyController)).toBe(true);
+    expect(getSubscribeMetadata(TimeoutOnlyController).length).toBe(0);
+    expect(getTimeoutMetadata(TimeoutOnlyController).length).toBe(1);
+  });
+});
+
+/**
+ * @source docs/api/queue.md#setup (error handling info)
+ */
+describe('Scheduled Job Error Handling (docs/api/queue.md)', () => {
+  let adapter: InMemoryQueueAdapter;
+
+  beforeEach(async () => {
+    adapter = new InMemoryQueueAdapter();
+    await adapter.connect();
+  });
+
+  afterEach(async () => {
+    await adapter.disconnect();
+  });
+
+  it('should continue scheduler after handler error via setErrorHandler', async () => {
+    // From docs/api/queue.md: Scheduled Job Error Handling info
+    const scheduler = new QueueScheduler(adapter);
+
+    const errors: Array<{ name: string; error: unknown }> = [];
+    scheduler.setErrorHandler((name: string, error: unknown) => {
+      errors.push({ name, error });
+    });
+
+    // Add a job that will fail
+    scheduler.addIntervalJob('failing-job', 60000, 'test.fail', () => {
+      throw new Error('Job failed');
+    });
+
+    scheduler.start();
+
+    // executeJob is async fire-and-forget, wait for it
+    await new Promise(r => setTimeout(r, 50));
+
+    // Error handler should have been called (immediate execution)
+    expect(errors.length).toBe(1);
+    expect(errors[0].name).toBe('failing-job');
+    expect((errors[0].error as Error).message).toBe('Job failed');
+
+    scheduler.stop();
+  });
+});
+
+/**
+ * @source docs/api/queue.md#dynamic-job-management
+ */
+describe('Dynamic Job Management (docs/api/queue.md)', () => {
+  let queueService: QueueService;
+
+  beforeEach(async () => {
+    queueService = new QueueService({ adapter: 'memory' });
+    const adapter = new InMemoryQueueAdapter();
+    await queueService.initialize(adapter);
+    await queueService.start();
+  });
+
+  afterEach(async () => {
+    await queueService.stop();
+  });
+
+  it('should add and get a cron job', () => {
+    // From docs/api/queue.md: Dynamic Job Management - addJob (cron)
+    queueService.addJob({
+      type: 'cron',
+      name: 'cleanup',
+      expression: '0 * * * *',
+      pattern: 'jobs.cleanup',
+    });
+
+    const job = queueService.getJob('cleanup');
+    expect(job).toBeDefined();
+    expect(job!.type).toBe('cron');
+    expect(job!.schedule.cron).toBe('0 * * * *');
+    expect(job!.paused).toBe(false);
+  });
+
+  it('should add and get an interval job', () => {
+    // From docs/api/queue.md: Dynamic Job Management - addJob (interval)
+    queueService.addJob({
+      type: 'interval',
+      name: 'heartbeat',
+      intervalMs: 5000,
+      pattern: 'jobs.heartbeat',
+    });
+
+    const job = queueService.getJob('heartbeat');
+    expect(job).toBeDefined();
+    expect(job!.type).toBe('interval');
+    expect(job!.schedule.every).toBe(5000);
+  });
+
+  it('should add and get a timeout job', () => {
+    // From docs/api/queue.md: Dynamic Job Management - addJob (timeout)
+    queueService.addJob({
+      type: 'timeout',
+      name: 'warmup',
+      timeoutMs: 3000,
+      pattern: 'jobs.warmup',
+    });
+
+    const job = queueService.getJob('warmup');
+    expect(job).toBeDefined();
+    expect(job!.type).toBe('timeout');
+    expect(job!.schedule.timeout).toBe(3000);
+  });
+
+  it('should pause and resume a job', () => {
+    // From docs/api/queue.md: Dynamic Job Management - pauseJob / resumeJob
+    queueService.addJob({
+      type: 'interval',
+      name: 'metrics',
+      intervalMs: 10000,
+      pattern: 'jobs.metrics',
+    });
+
+    expect(queueService.pauseJob('metrics')).toBe(true);
+    expect(queueService.getJob('metrics')!.paused).toBe(true);
+
+    expect(queueService.resumeJob('metrics')).toBe(true);
+    expect(queueService.getJob('metrics')!.paused).toBe(false);
+  });
+
+  it('should update a cron job expression', () => {
+    // From docs/api/queue.md: Dynamic Job Management - updateJob
+    queueService.addJob({
+      type: 'cron',
+      name: 'report',
+      expression: '0 0 * * *',
+      pattern: 'jobs.report',
+    });
+
+    expect(queueService.getJob('report')!.schedule.cron).toBe('0 0 * * *');
+
+    queueService.updateJob({
+      type: 'cron',
+      name: 'report',
+      expression: '0 */2 * * *',
+    });
+
+    expect(queueService.getJob('report')!.schedule.cron).toBe('0 */2 * * *');
+  });
+
+  it('should list and remove jobs', () => {
+    // From docs/api/queue.md: Dynamic Job Management - getJobs / removeJob
+    queueService.addJob({
+      type: 'cron',
+      name: 'job-a',
+      expression: '0 * * * *',
+      pattern: 'jobs.a',
+    });
+    queueService.addJob({
+      type: 'interval',
+      name: 'job-b',
+      intervalMs: 5000,
+      pattern: 'jobs.b',
+    });
+    queueService.addJob({
+      type: 'timeout',
+      name: 'job-c',
+      timeoutMs: 1000,
+      pattern: 'jobs.c',
+    });
+
+    const jobs = queueService.getJobs();
+    expect(jobs.length).toBe(3);
+
+    expect(queueService.removeJob('job-b')).toBe(true);
+    expect(queueService.hasJob('job-b')).toBe(false);
+    expect(queueService.getJobs().length).toBe(2);
+  });
+});

package/src/queue/index.ts

@@ -17,7 +17,14 @@ export type {
   QueueEvents,
   Subscription,
   OverlapStrategy,
-  ScheduledJobOptions,
+  AddCronJob,
+  AddIntervalJob,
+  AddTimeoutJob,
+  AddJobOptions,
+  UpdateCronJob,
+  UpdateIntervalJob,
+  UpdateTimeoutJob,
+  UpdateJobOptions,
   ScheduledJobInfo,
   QueueFeature,
   QueueAdapterType,

package/src/queue/queue-service-proxy.test.ts

@@ -27,11 +27,20 @@ describe('QueueServiceProxy', () => {
         /* no-op for throw test */
       }),
     ).rejects.toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
-    await expect(proxy.addScheduledJob('j', { pattern: 'e', schedule: { every: 1000 } })).rejects.toThrow(
+    expect(() => proxy.addJob({
+      type: 'cron', name: 'j', expression: '* * * * *', pattern: 'e', 
+    })).toThrow(
+      QUEUE_NOT_ENABLED_ERROR_MESSAGE,
+    );
+    expect(() => proxy.removeJob('j')).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    expect(() => proxy.getJob('j')).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    expect(() => proxy.getJobs()).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    expect(() => proxy.hasJob('j')).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    expect(() => proxy.pauseJob('j')).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    expect(() => proxy.resumeJob('j')).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    expect(() => proxy.updateJob({ type: 'cron', name: 'j', expression: '* * * * *' })).toThrow(
       QUEUE_NOT_ENABLED_ERROR_MESSAGE,
     );
-    await expect(proxy.removeScheduledJob('j')).rejects.toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
-    await expect(proxy.getScheduledJobs()).rejects.toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
     expect(() => proxy.supports('pattern-subscriptions')).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
     expect(() =>
       proxy.on('onReady', () => {

package/src/queue/queue-service-proxy.ts

@@ -8,14 +8,15 @@ import type { QueueService } from './queue.service';
 import type { QueueScheduler } from './scheduler';
 import type { QueueAdapter } from './types';
 import type {
+  AddJobOptions,
   MessageHandler,
   PublishOptions,
   QueueEvents,
   ScheduledJobInfo,
-  ScheduledJobOptions,
   SubscribeOptions,
   Subscription,
   QueueFeature,
+  UpdateJobOptions,
 } from './types';
 
 const QUEUE_NOT_ENABLED_MESSAGE =
@@ -74,22 +75,51 @@ export class QueueServiceProxy {
     return await this.delegate.subscribe(pattern, handler, options);
   }
 
-  async addScheduledJob(name: string, options: ScheduledJobOptions): Promise<void> {
+  addJob(options: AddJobOptions): void {
+    throwIfNoDelegate(this.delegate);
+    this.delegate.addJob(options);
+  }
+
+  removeJob(name: string): boolean {
+    throwIfNoDelegate(this.delegate);
+
+    return this.delegate.removeJob(name);
+  }
+
+  getJob(name: string): ScheduledJobInfo | undefined {
+    throwIfNoDelegate(this.delegate);
+
+    return this.delegate.getJob(name);
+  }
+
+  getJobs(): ScheduledJobInfo[] {
+    throwIfNoDelegate(this.delegate);
+
+    return this.delegate.getJobs();
+  }
+
+  hasJob(name: string): boolean {
+    throwIfNoDelegate(this.delegate);
+
+    return this.delegate.hasJob(name);
+  }
+
+  pauseJob(name: string): boolean {
     throwIfNoDelegate(this.delegate);
 
-    return await this.delegate.addScheduledJob(name, options);
+    return this.delegate.pauseJob(name);
   }
 
-  async removeScheduledJob(name: string): Promise<boolean> {
+  resumeJob(name: string): boolean {
     throwIfNoDelegate(this.delegate);
 
-    return await this.delegate.removeScheduledJob(name);
+    return this.delegate.resumeJob(name);
   }
 
-  async getScheduledJobs(): Promise<ScheduledJobInfo[]> {
+  updateJob(options: UpdateJobOptions): boolean {
     throwIfNoDelegate(this.delegate);
 
-    return await this.delegate.getScheduledJobs();
+    return this.delegate.updateJob(options);
   }
 
   supports(feature: QueueFeature): boolean {

package/src/queue/queue.service.test.ts

@@ -192,30 +192,152 @@ describe('QueueService', () => {
     });
   });
 
-  describe('scheduled jobs via adapter', () => {
-    test('should add and remove scheduled jobs', async () => {
-      await service.start();
-
-      await service.addScheduledJob('test-scheduled', {
-        pattern: 'scheduled.pattern',
-        schedule: { every: 60000 },
+  describe('scheduled jobs', () => {
+    test('addJob should delegate to scheduler addJob', () => {
+      service.addJob({
+        type: 'interval',
+        name: 'test-interval',
+        intervalMs: 5000,
+        pattern: 'test.pattern',
       });
 
-      const jobs = await service.getScheduledJobs();
-      expect(jobs.some((j) => j.name === 'test-scheduled')).toBe(true);
+      expect(service.hasJob('test-interval')).toBe(true);
+    });
+
+    test('removeJob should delegate to scheduler removeJob', () => {
+      service.addJob({
+        type: 'interval',
+        name: 'remove-me',
+        intervalMs: 5000,
+        pattern: 'test.pattern',
+      });
 
-      const removed = await service.removeScheduledJob('test-scheduled');
+      const removed = service.removeJob('remove-me');
       expect(removed).toBe(true);
+      expect(service.hasJob('remove-me')).toBe(false);
+    });
 
-      const jobsAfter = await service.getScheduledJobs();
-      expect(jobsAfter.some((j) => j.name === 'test-scheduled')).toBe(false);
+    test('removeJob should return false for non-existent job', () => {
+      expect(service.removeJob('nonexistent')).toBe(false);
     });
 
-    test('should return false when removing non-existent job', async () => {
-      await service.start();
+    test('getJob should delegate to scheduler getJob', () => {
+      service.addJob({
+        type: 'cron',
+        name: 'my-cron',
+        expression: '*/5 * * * *',
+        pattern: 'cron.pattern',
+      });
+
+      const job = service.getJob('my-cron');
+      expect(job).toBeDefined();
+      expect(job!.name).toBe('my-cron');
+      expect(job!.type).toBe('cron');
+      expect(job!.pattern).toBe('cron.pattern');
+    });
+
+    test('getJob should return undefined for non-existent job', () => {
+      expect(service.getJob('nonexistent')).toBeUndefined();
+    });
+
+    test('getJobs should delegate to scheduler getJobs', () => {
+      service.addJob({
+        type: 'interval',
+        name: 'job-a',
+        intervalMs: 1000,
+        pattern: 'a.pattern',
+      });
+      service.addJob({
+        type: 'timeout',
+        name: 'job-b',
+        timeoutMs: 2000,
+        pattern: 'b.pattern',
+      });
+
+      const jobs = service.getJobs();
+      expect(jobs.length).toBe(2);
+      expect(jobs.some((j) => j.name === 'job-a')).toBe(true);
+      expect(jobs.some((j) => j.name === 'job-b')).toBe(true);
+    });
+
+    test('hasJob should delegate to scheduler hasJob', () => {
+      expect(service.hasJob('nope')).toBe(false);
+
+      service.addJob({
+        type: 'interval',
+        name: 'exists',
+        intervalMs: 1000,
+        pattern: 'test.pattern',
+      });
+
+      expect(service.hasJob('exists')).toBe(true);
+    });
 
-      const removed = await service.removeScheduledJob('nonexistent');
-      expect(removed).toBe(false);
+    test('pauseJob should delegate to scheduler pauseJob', () => {
+      service.addJob({
+        type: 'interval',
+        name: 'pausable',
+        intervalMs: 1000,
+        pattern: 'test.pattern',
+      });
+
+      const paused = service.pauseJob('pausable');
+      expect(paused).toBe(true);
+
+      const job = service.getJob('pausable');
+      expect(job!.paused).toBe(true);
+    });
+
+    test('pauseJob should return false for non-existent job', () => {
+      expect(service.pauseJob('nonexistent')).toBe(false);
+    });
+
+    test('resumeJob should delegate to scheduler resumeJob', () => {
+      service.addJob({
+        type: 'interval',
+        name: 'resumable',
+        intervalMs: 1000,
+        pattern: 'test.pattern',
+      });
+
+      service.pauseJob('resumable');
+      const resumed = service.resumeJob('resumable');
+      expect(resumed).toBe(true);
+
+      const job = service.getJob('resumable');
+      expect(job!.paused).toBe(false);
+    });
+
+    test('resumeJob should return false for non-existent job', () => {
+      expect(service.resumeJob('nonexistent')).toBe(false);
+    });
+
+    test('updateJob should delegate to scheduler updateJob', () => {
+      service.addJob({
+        type: 'interval',
+        name: 'updatable',
+        intervalMs: 1000,
+        pattern: 'test.pattern',
+      });
+
+      const updated = service.updateJob({
+        type: 'interval',
+        name: 'updatable',
+        intervalMs: 5000,
+      });
+      expect(updated).toBe(true);
+
+      const job = service.getJob('updatable');
+      expect(job!.schedule.every).toBe(5000);
+    });
+
+    test('updateJob should return false for non-existent job', () => {
+      const updated = service.updateJob({
+        type: 'interval',
+        name: 'nonexistent',
+        intervalMs: 1000,
+      });
+      expect(updated).toBe(false);
     });
   });
 

package/src/queue/queue.service.ts

@@ -18,7 +18,8 @@ import type {
   PublishOptions,
   SubscribeOptions,
   Subscription,
-  ScheduledJobOptions,
+  AddJobOptions,
+  UpdateJobOptions,
   ScheduledJobInfo,
   QueueFeature,
   QueueEvents,
@@ -184,24 +185,59 @@ export class QueueService {
   // ============================================================================
 
   /**
-   * Add a scheduled job
+   * Add a scheduled job dynamically
    */
-  async addScheduledJob(name: string, options: ScheduledJobOptions): Promise<void> {
-    return await this.getAdapter().addScheduledJob(name, options);
+  addJob(options: AddJobOptions): void {
+    this.getScheduler().addJob(options);
   }
 
   /**
-   * Remove a scheduled job
+   * Remove a scheduled job by name
    */
-  async removeScheduledJob(name: string): Promise<boolean> {
-    return await this.getAdapter().removeScheduledJob(name);
+  removeJob(name: string): boolean {
+    return this.getScheduler().removeJob(name);
+  }
+
+  /**
+   * Get information about a specific scheduled job
+   */
+  getJob(name: string): ScheduledJobInfo | undefined {
+    return this.getScheduler().getJob(name);
   }
 
   /**
    * Get all scheduled jobs
    */
-  async getScheduledJobs(): Promise<ScheduledJobInfo[]> {
-    return await this.getAdapter().getScheduledJobs();
+  getJobs(): ScheduledJobInfo[] {
+    return this.getScheduler().getJobs();
+  }
+
+  /**
+   * Check if a scheduled job exists
+   */
+  hasJob(name: string): boolean {
+    return this.getScheduler().hasJob(name);
+  }
+
+  /**
+   * Pause a scheduled job
+   */
+  pauseJob(name: string): boolean {
+    return this.getScheduler().pauseJob(name);
+  }
+
+  /**
+   * Resume a paused scheduled job
+   */
+  resumeJob(name: string): boolean {
+    return this.getScheduler().resumeJob(name);
+  }
+
+  /**
+   * Update a scheduled job's timing configuration
+   */
+  updateJob(options: UpdateJobOptions): boolean {
+    return this.getScheduler().updateJob(options);
   }
 
   // ============================================================================
@@ -288,6 +324,7 @@ export class QueueService {
         {
           metadata: cron.options.metadata,
           overlapStrategy: cron.options.overlapStrategy,
+          declarative: true,
         },
       );
     }
@@ -301,7 +338,7 @@ export class QueueService {
         interval.milliseconds,
         interval.options.pattern,
         method,
-        { metadata: interval.options.metadata },
+        { metadata: interval.options.metadata, declarative: true },
       );
     }
 
@@ -314,7 +351,7 @@ export class QueueService {
         timeout.milliseconds,
         timeout.options.pattern,
         method,
-        { metadata: timeout.options.metadata },
+        { metadata: timeout.options.metadata, declarative: true },
       );
     }