@onebun/core 0.1.2 → 0.1.3

package/src/queue/cron-expression.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Cron Expression Constants Tests
+ */
+
+import {
+  describe,
+  it,
+  expect,
+} from 'bun:test';
+
+import { CronExpression } from './cron-expression';
+import { isValidCronExpression } from './cron-parser';
+
+describe('CronExpression', () => {
+  describe('seconds patterns', () => {
+    it('EVERY_SECOND should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_SECOND)).toBe(true);
+    });
+
+    it('EVERY_5_SECONDS should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_5_SECONDS)).toBe(true);
+    });
+
+    it('EVERY_10_SECONDS should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_10_SECONDS)).toBe(true);
+    });
+
+    it('EVERY_30_SECONDS should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_30_SECONDS)).toBe(true);
+    });
+  });
+
+  describe('minutes patterns', () => {
+    it('EVERY_MINUTE should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_MINUTE)).toBe(true);
+    });
+
+    it('EVERY_5_MINUTES should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_5_MINUTES)).toBe(true);
+    });
+
+    it('EVERY_10_MINUTES should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_10_MINUTES)).toBe(true);
+    });
+
+    it('EVERY_15_MINUTES should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_15_MINUTES)).toBe(true);
+    });
+
+    it('EVERY_30_MINUTES should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_30_MINUTES)).toBe(true);
+    });
+  });
+
+  describe('hours patterns', () => {
+    it('EVERY_HOUR should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_HOUR)).toBe(true);
+    });
+
+    it('EVERY_2_HOURS should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_2_HOURS)).toBe(true);
+    });
+
+    it('EVERY_6_HOURS should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_6_HOURS)).toBe(true);
+    });
+
+    it('EVERY_12_HOURS should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_12_HOURS)).toBe(true);
+    });
+  });
+
+  describe('daily patterns', () => {
+    it('EVERY_DAY_AT_MIDNIGHT should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_DAY_AT_MIDNIGHT)).toBe(true);
+    });
+
+    it('EVERY_DAY_AT_NOON should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_DAY_AT_NOON)).toBe(true);
+    });
+
+    it('EVERY_DAY_AT_9AM should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_DAY_AT_9AM)).toBe(true);
+    });
+  });
+
+  describe('weekly patterns', () => {
+    it('EVERY_WEEK should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_WEEK)).toBe(true);
+    });
+
+    it('EVERY_MONDAY should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_MONDAY)).toBe(true);
+    });
+
+    it('EVERY_FRIDAY should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_FRIDAY)).toBe(true);
+    });
+
+    it('EVERY_WEEKDAY should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_WEEKDAY)).toBe(true);
+    });
+
+    it('EVERY_WEEKEND should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_WEEKEND)).toBe(true);
+    });
+  });
+
+  describe('monthly/yearly patterns', () => {
+    it('EVERY_MONTH should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_MONTH)).toBe(true);
+    });
+
+    it('EVERY_QUARTER should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_QUARTER)).toBe(true);
+    });
+
+    it('EVERY_YEAR should be valid', () => {
+      expect(isValidCronExpression(CronExpression.EVERY_YEAR)).toBe(true);
+    });
+  });
+
+  describe('pattern relationships', () => {
+    it('EVERY_WEEK and EVERY_SUNDAY should be the same (Sunday at midnight)', () => {
+      // Both represent Sunday at midnight
+      expect(CronExpression.EVERY_WEEK).toBe(CronExpression.EVERY_SUNDAY);
+    });
+
+    it('should have mostly unique values', () => {
+      const values = Object.values(CronExpression);
+      const uniqueValues = new Set(values);
+      // EVERY_WEEK and EVERY_SUNDAY are intentionally the same
+      expect(uniqueValues.size).toBe(values.length - 1);
+    });
+  });
+
+  describe('all patterns have 6 fields', () => {
+    it('should have 6 space-separated fields', () => {
+      for (const [_name, pattern] of Object.entries(CronExpression)) {
+        const fields = pattern.split(' ');
+        expect(fields.length).toBe(6);
+      }
+    });
+  });
+});

package/src/queue/cron-expression.ts

@@ -0,0 +1,115 @@
+/**
+ * Common Cron Expressions
+ *
+ * Pre-defined cron expressions for common scheduling patterns.
+ * All expressions use 6 fields (with seconds).
+ */
+
+/**
+ * Common cron expression patterns
+ *
+ * @example
+ * ```typescript
+ * import { CronExpression } from '@onebun/core';
+ *
+ * @Cron(CronExpression.EVERY_MINUTE, { pattern: 'health.check' })
+ * getHealthData() {
+ *   return { status: 'ok' };
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const CronExpression = {
+  // Seconds
+  /** Every second */
+  EVERY_SECOND: '* * * * * *',
+  /** Every 5 seconds */
+  EVERY_5_SECONDS: '*/5 * * * * *',
+  /** Every 10 seconds */
+  EVERY_10_SECONDS: '*/10 * * * * *',
+  /** Every 30 seconds */
+  EVERY_30_SECONDS: '*/30 * * * * *',
+
+  // Minutes
+  /** Every minute (at second 0) */
+  EVERY_MINUTE: '0 * * * * *',
+  /** Every 5 minutes */
+  EVERY_5_MINUTES: '0 */5 * * * *',
+  /** Every 10 minutes */
+  EVERY_10_MINUTES: '0 */10 * * * *',
+  /** Every 15 minutes */
+  EVERY_15_MINUTES: '0 */15 * * * *',
+  /** Every 30 minutes */
+  EVERY_30_MINUTES: '0 */30 * * * *',
+  /** Every 45 minutes */
+  EVERY_45_MINUTES: '0 */45 * * * *',
+
+  // Hours
+  /** Every hour (at minute 0, second 0) */
+  EVERY_HOUR: '0 0 * * * *',
+  /** Every 2 hours */
+  EVERY_2_HOURS: '0 0 */2 * * *',
+  /** Every 3 hours */
+  EVERY_3_HOURS: '0 0 */3 * * *',
+  /** Every 4 hours */
+  EVERY_4_HOURS: '0 0 */4 * * *',
+  /** Every 6 hours */
+  EVERY_6_HOURS: '0 0 */6 * * *',
+  /** Every 12 hours */
+  EVERY_12_HOURS: '0 0 */12 * * *',
+
+  // Daily
+  /** Every day at midnight (00:00:00) */
+  EVERY_DAY_AT_MIDNIGHT: '0 0 0 * * *',
+  /** Every day at 1 AM */
+  EVERY_DAY_AT_1AM: '0 0 1 * * *',
+  /** Every day at 2 AM */
+  EVERY_DAY_AT_2AM: '0 0 2 * * *',
+  /** Every day at 3 AM */
+  EVERY_DAY_AT_3AM: '0 0 3 * * *',
+  /** Every day at 6 AM */
+  EVERY_DAY_AT_6AM: '0 0 6 * * *',
+  /** Every day at 9 AM */
+  EVERY_DAY_AT_9AM: '0 0 9 * * *',
+  /** Every day at noon (12:00:00) */
+  EVERY_DAY_AT_NOON: '0 0 12 * * *',
+  /** Every day at 6 PM */
+  EVERY_DAY_AT_6PM: '0 0 18 * * *',
+
+  // Weekly
+  /** Every week (Sunday at midnight) */
+  EVERY_WEEK: '0 0 0 * * 0',
+  /** Every Monday at midnight */
+  EVERY_MONDAY: '0 0 0 * * 1',
+  /** Every Tuesday at midnight */
+  EVERY_TUESDAY: '0 0 0 * * 2',
+  /** Every Wednesday at midnight */
+  EVERY_WEDNESDAY: '0 0 0 * * 3',
+  /** Every Thursday at midnight */
+  EVERY_THURSDAY: '0 0 0 * * 4',
+  /** Every Friday at midnight */
+  EVERY_FRIDAY: '0 0 0 * * 5',
+  /** Every Saturday at midnight */
+  EVERY_SATURDAY: '0 0 0 * * 6',
+  /** Every Sunday at midnight */
+  EVERY_SUNDAY: '0 0 0 * * 0',
+  /** Every weekday (Monday-Friday) at midnight */
+  EVERY_WEEKDAY: '0 0 0 * * 1-5',
+  /** Every weekend (Saturday-Sunday) at midnight */
+  EVERY_WEEKEND: '0 0 0 * * 0,6',
+
+  // Monthly
+  /** First day of every month at midnight */
+  EVERY_MONTH: '0 0 0 1 * *',
+  /** First day of every quarter (Jan, Apr, Jul, Oct) at midnight */
+  EVERY_QUARTER: '0 0 0 1 1,4,7,10 *',
+
+  // Yearly
+  /** First day of the year at midnight (January 1st) */
+  EVERY_YEAR: '0 0 0 1 1 *',
+} as const;
+
+/**
+ * Type for CronExpression values
+ */
+export type CronExpressionValue = (typeof CronExpression)[keyof typeof CronExpression];

package/src/queue/cron-parser.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Cron Parser Tests
+ */
+
+import {
+  describe,
+  it,
+  expect,
+} from 'bun:test';
+
+import {
+  parseCronExpression,
+  getNextRun,
+  getNextRuns,
+  getMillisecondsUntilNextRun,
+  isValidCronExpression,
+} from './cron-parser';
+
+describe('cron-parser', () => {
+  describe('parseCronExpression', () => {
+    it('should parse 5-field expression (without seconds)', () => {
+      const schedule = parseCronExpression('* * * * *');
+      expect(schedule.seconds).toEqual([0]); // Default seconds = 0
+      expect(schedule.minutes.length).toBe(60);
+      expect(schedule.hours.length).toBe(24);
+      expect(schedule.daysOfMonth.length).toBe(31);
+      expect(schedule.months.length).toBe(12);
+      expect(schedule.daysOfWeek.length).toBe(7);
+    });
+
+    it('should parse 6-field expression (with seconds)', () => {
+      const schedule = parseCronExpression('* * * * * *');
+      expect(schedule.seconds.length).toBe(60);
+      expect(schedule.minutes.length).toBe(60);
+    });
+
+    it('should parse specific values', () => {
+      const schedule = parseCronExpression('0 30 9 15 6 *');
+      expect(schedule.seconds).toEqual([0]);
+      expect(schedule.minutes).toEqual([30]);
+      expect(schedule.hours).toEqual([9]);
+      expect(schedule.daysOfMonth).toEqual([15]);
+      expect(schedule.months).toEqual([6]);
+    });
+
+    it('should parse step values (*/N)', () => {
+      const schedule = parseCronExpression('*/5 */10 * * * *');
+      expect(schedule.seconds).toEqual([0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55]);
+      expect(schedule.minutes).toEqual([0, 10, 20, 30, 40, 50]);
+    });
+
+    it('should parse ranges (N-M)', () => {
+      const schedule = parseCronExpression('0 0 9-17 * * 1-5');
+      expect(schedule.hours).toEqual([9, 10, 11, 12, 13, 14, 15, 16, 17]);
+      expect(schedule.daysOfWeek).toEqual([1, 2, 3, 4, 5]);
+    });
+
+    it('should parse lists (N,M,O)', () => {
+      const schedule = parseCronExpression('0 0,15,30,45 * * * *');
+      expect(schedule.minutes).toEqual([0, 15, 30, 45]);
+    });
+
+    it('should parse combined range and step (N-M/S)', () => {
+      const schedule = parseCronExpression('0 0 0-23/2 * * *');
+      expect(schedule.hours).toEqual([0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22]);
+    });
+
+    it('should throw error for invalid expression', () => {
+      expect(() => parseCronExpression('invalid')).toThrow();
+      expect(() => parseCronExpression('* * *')).toThrow();
+      expect(() => parseCronExpression('* * * * * * *')).toThrow();
+    });
+
+    it('should throw error for out of bounds values', () => {
+      expect(() => parseCronExpression('60 * * * * *')).toThrow();
+      expect(() => parseCronExpression('* 60 * * * *')).toThrow();
+      expect(() => parseCronExpression('* * 24 * * *')).toThrow();
+      expect(() => parseCronExpression('* * * 32 * *')).toThrow();
+      expect(() => parseCronExpression('* * * * 13 *')).toThrow();
+      expect(() => parseCronExpression('* * * * * 7')).toThrow();
+    });
+  });
+
+  describe('getNextRun', () => {
+    it('should find next run time for every minute schedule', () => {
+      const schedule = parseCronExpression('0 * * * * *');
+      const from = new Date('2024-01-15T10:30:45');
+      const next = getNextRun(schedule, from);
+
+      expect(next).not.toBeNull();
+      expect(next!.getMinutes()).toBe(31);
+      expect(next!.getSeconds()).toBe(0);
+    });
+
+    it('should find next run time for specific time', () => {
+      const schedule = parseCronExpression('0 0 9 * * *');
+      const from = new Date('2024-01-15T08:00:00');
+      const next = getNextRun(schedule, from);
+
+      expect(next).not.toBeNull();
+      expect(next!.getHours()).toBe(9);
+      expect(next!.getMinutes()).toBe(0);
+      expect(next!.getDate()).toBe(15);
+    });
+
+    it('should advance to next day if time has passed', () => {
+      const schedule = parseCronExpression('0 0 9 * * *');
+      const from = new Date('2024-01-15T10:00:00');
+      const next = getNextRun(schedule, from);
+
+      expect(next).not.toBeNull();
+      expect(next!.getHours()).toBe(9);
+      expect(next!.getDate()).toBe(16);
+    });
+
+    it('should respect day of week constraint', () => {
+      const schedule = parseCronExpression('0 0 9 * * 1'); // Monday
+      const from = new Date('2024-01-15T08:00:00'); // Monday
+      const next = getNextRun(schedule, from);
+
+      expect(next).not.toBeNull();
+      expect(next!.getDay()).toBe(1); // Monday
+    });
+
+    it('should find next run for every 5 seconds', () => {
+      const schedule = parseCronExpression('*/5 * * * * *');
+      const from = new Date('2024-01-15T10:30:42');
+      const next = getNextRun(schedule, from);
+
+      expect(next).not.toBeNull();
+      expect(next!.getSeconds()).toBe(45);
+    });
+  });
+
+  describe('getNextRuns', () => {
+    it('should return multiple future run times', () => {
+      const schedule = parseCronExpression('0 * * * * *');
+      const from = new Date('2024-01-15T10:30:00');
+      const runs = getNextRuns(schedule, 3, from);
+
+      expect(runs.length).toBe(3);
+      expect(runs[0].getMinutes()).toBe(31);
+      expect(runs[1].getMinutes()).toBe(32);
+      expect(runs[2].getMinutes()).toBe(33);
+    });
+
+    it('should return empty array for impossible schedule', () => {
+      // February 31st doesn't exist
+      const schedule = parseCronExpression('0 0 0 31 2 *');
+      const runs = getNextRuns(schedule, 3, new Date('2024-01-01'));
+
+      expect(runs.length).toBe(0);
+    });
+  });
+
+  describe('getMillisecondsUntilNextRun', () => {
+    it('should calculate milliseconds until next run', () => {
+      const from = new Date('2024-01-15T10:30:30.000');
+      const ms = getMillisecondsUntilNextRun('0 31 10 * * *', from);
+
+      expect(ms).not.toBeNull();
+      // Should be 30 seconds (from 10:30:30 to 10:31:00)
+      expect(ms).toBe(30000);
+    });
+
+    it('should return null for invalid expression', () => {
+      expect(() => getMillisecondsUntilNextRun('invalid', new Date())).toThrow();
+    });
+  });
+
+  describe('isValidCronExpression', () => {
+    it('should return true for valid expressions', () => {
+      expect(isValidCronExpression('* * * * *')).toBe(true);
+      expect(isValidCronExpression('0 0 9 * * *')).toBe(true);
+      expect(isValidCronExpression('*/5 * * * * *')).toBe(true);
+      expect(isValidCronExpression('0 0 9-17 * * 1-5')).toBe(true);
+    });
+
+    it('should return false for invalid expressions', () => {
+      expect(isValidCronExpression('invalid')).toBe(false);
+      expect(isValidCronExpression('* * *')).toBe(false);
+      expect(isValidCronExpression('60 * * * * *')).toBe(false);
+    });
+  });
+});