ai-workflows 2.1.1 → 2.3.0

package/test/cron-parser.test.ts

@@ -0,0 +1,314 @@
+import { describe, it, expect } from 'vitest'
+import {
+  parseCron,
+  matchesCron,
+  getNextCronDate,
+  getNextCronMs,
+  type ParsedCron,
+} from '../src/cron-parser.js'
+
+describe('parseCron', () => {
+  describe('basic parsing', () => {
+    it('should parse * * * * * (every minute)', () => {
+      const cron = parseCron('* * * * *')
+      expect(cron.minutes).toHaveLength(60) // 0-59
+      expect(cron.hours).toHaveLength(24) // 0-23
+      expect(cron.daysOfMonth).toHaveLength(31) // 1-31
+      expect(cron.months).toHaveLength(12) // 1-12
+      expect(cron.daysOfWeek).toHaveLength(7) // 0-6
+    })
+
+    it('should parse 0 * * * * (every hour at minute 0)', () => {
+      const cron = parseCron('0 * * * *')
+      expect(cron.minutes).toEqual([0])
+      expect(cron.hours).toHaveLength(24)
+    })
+
+    it('should parse 0 9 * * * (every day at 9am)', () => {
+      const cron = parseCron('0 9 * * *')
+      expect(cron.minutes).toEqual([0])
+      expect(cron.hours).toEqual([9])
+    })
+
+    it('should parse 0 9 * * 1 (every Monday at 9am)', () => {
+      const cron = parseCron('0 9 * * 1')
+      expect(cron.minutes).toEqual([0])
+      expect(cron.hours).toEqual([9])
+      expect(cron.daysOfWeek).toEqual([1])
+    })
+
+    it('should parse 0 0 1 * * (first of every month at midnight)', () => {
+      const cron = parseCron('0 0 1 * *')
+      expect(cron.minutes).toEqual([0])
+      expect(cron.hours).toEqual([0])
+      expect(cron.daysOfMonth).toEqual([1])
+    })
+  })
+
+  describe('ranges', () => {
+    it('should parse 0 9-17 * * * (every hour from 9am to 5pm)', () => {
+      const cron = parseCron('0 9-17 * * *')
+      expect(cron.hours).toEqual([9, 10, 11, 12, 13, 14, 15, 16, 17])
+    })
+
+    it('should parse 0 0 * * 1-5 (weekdays)', () => {
+      const cron = parseCron('0 0 * * 1-5')
+      expect(cron.daysOfWeek).toEqual([1, 2, 3, 4, 5])
+    })
+  })
+
+  describe('lists', () => {
+    it('should parse 0 9,12,17 * * * (at 9am, noon, and 5pm)', () => {
+      const cron = parseCron('0 9,12,17 * * *')
+      expect(cron.hours).toEqual([9, 12, 17])
+    })
+
+    it('should parse 0 0 * * 0,6 (weekends)', () => {
+      const cron = parseCron('0 0 * * 0,6')
+      expect(cron.daysOfWeek).toEqual([0, 6])
+    })
+  })
+
+  describe('steps', () => {
+    it('should parse */5 * * * * (every 5 minutes)', () => {
+      const cron = parseCron('*/5 * * * *')
+      expect(cron.minutes).toEqual([0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55])
+    })
+
+    it('should parse */15 * * * * (every 15 minutes)', () => {
+      const cron = parseCron('*/15 * * * *')
+      expect(cron.minutes).toEqual([0, 15, 30, 45])
+    })
+
+    it('should parse 0-30/5 * * * * (every 5 minutes for first half hour)', () => {
+      const cron = parseCron('0-30/5 * * * *')
+      expect(cron.minutes).toEqual([0, 5, 10, 15, 20, 25, 30])
+    })
+
+    it('should parse 0 */2 * * * (every 2 hours)', () => {
+      const cron = parseCron('0 */2 * * *')
+      expect(cron.hours).toEqual([0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22])
+    })
+  })
+
+  describe('day names', () => {
+    it('should parse 0 9 * * Mon (Monday at 9am)', () => {
+      const cron = parseCron('0 9 * * Mon')
+      expect(cron.daysOfWeek).toEqual([1])
+    })
+
+    it('should parse 0 9 * * Mon-Fri (weekdays)', () => {
+      const cron = parseCron('0 9 * * Mon-Fri')
+      expect(cron.daysOfWeek).toEqual([1, 2, 3, 4, 5])
+    })
+
+    it('should parse 0 9 * * Sat,Sun (weekends)', () => {
+      const cron = parseCron('0 9 * * Sat,Sun')
+      expect(cron.daysOfWeek).toEqual([0, 6])
+    })
+  })
+
+  describe('month names', () => {
+    it('should parse 0 0 1 Jan * (New Year)', () => {
+      const cron = parseCron('0 0 1 Jan *')
+      expect(cron.months).toEqual([1])
+    })
+
+    it('should parse 0 0 1 Jan,Jul * (Jan and July)', () => {
+      const cron = parseCron('0 0 1 Jan,Jul *')
+      expect(cron.months).toEqual([1, 7])
+    })
+  })
+
+  describe('6-field expressions with seconds', () => {
+    it('should parse * * * * * * (every second)', () => {
+      const cron = parseCron('* * * * * *')
+      expect(cron.seconds).toHaveLength(60)
+    })
+
+    it('should parse 0 0 9 * * 1 (Monday at 9am, second 0)', () => {
+      const cron = parseCron('0 0 9 * * 1')
+      expect(cron.seconds).toEqual([0])
+      expect(cron.minutes).toEqual([0])
+      expect(cron.hours).toEqual([9])
+      expect(cron.daysOfWeek).toEqual([1])
+    })
+
+    it('should parse */10 * * * * * (every 10 seconds)', () => {
+      const cron = parseCron('*/10 * * * * *')
+      expect(cron.seconds).toEqual([0, 10, 20, 30, 40, 50])
+    })
+  })
+
+  describe('error handling', () => {
+    it('should throw for invalid field count', () => {
+      expect(() => parseCron('* * *')).toThrow('expected 5 or 6 fields')
+      expect(() => parseCron('* * * * * * *')).toThrow('expected 5 or 6 fields')
+    })
+
+    it('should throw for invalid field values', () => {
+      expect(() => parseCron('60 * * * *')).toThrow('Invalid cron field value')
+      expect(() => parseCron('* 24 * * *')).toThrow('Invalid cron field value')
+      expect(() => parseCron('* * 32 * *')).toThrow('Invalid cron field value')
+      expect(() => parseCron('* * * 13 *')).toThrow('Invalid cron field value')
+      expect(() => parseCron('* * * * 7')).toThrow('Invalid cron field value')
+    })
+  })
+
+  describe('wildcard tracking', () => {
+    it('should track day-of-month wildcard', () => {
+      const cron = parseCron('0 9 * * 1')
+      expect(cron.dayOfMonthWildcard).toBe(true)
+      expect(cron.dayOfWeekWildcard).toBe(false)
+    })
+
+    it('should track day-of-week wildcard', () => {
+      const cron = parseCron('0 9 15 * *')
+      expect(cron.dayOfMonthWildcard).toBe(false)
+      expect(cron.dayOfWeekWildcard).toBe(true)
+    })
+
+    it('should track both wildcards', () => {
+      const cron = parseCron('0 9 * * *')
+      expect(cron.dayOfMonthWildcard).toBe(true)
+      expect(cron.dayOfWeekWildcard).toBe(true)
+    })
+  })
+})
+
+describe('matchesCron', () => {
+  it('should match * * * * * for any time', () => {
+    const cron = parseCron('* * * * *')
+    expect(matchesCron(new Date('2024-01-15T10:30:00'), cron)).toBe(true)
+    expect(matchesCron(new Date('2024-06-20T23:59:00'), cron)).toBe(true)
+  })
+
+  it('should match specific minute', () => {
+    const cron = parseCron('30 * * * *')
+    expect(matchesCron(new Date('2024-01-15T10:30:00'), cron)).toBe(true)
+    expect(matchesCron(new Date('2024-01-15T10:31:00'), cron)).toBe(false)
+  })
+
+  it('should match specific hour', () => {
+    const cron = parseCron('0 9 * * *')
+    expect(matchesCron(new Date('2024-01-15T09:00:00'), cron)).toBe(true)
+    expect(matchesCron(new Date('2024-01-15T10:00:00'), cron)).toBe(false)
+  })
+
+  it('should match specific day of week', () => {
+    const cron = parseCron('0 9 * * 1') // Monday
+    // Jan 15, 2024 is a Monday
+    expect(matchesCron(new Date('2024-01-15T09:00:00'), cron)).toBe(true)
+    // Jan 16, 2024 is a Tuesday
+    expect(matchesCron(new Date('2024-01-16T09:00:00'), cron)).toBe(false)
+  })
+
+  it('should match specific day of month', () => {
+    const cron = parseCron('0 9 15 * *')
+    expect(matchesCron(new Date('2024-01-15T09:00:00'), cron)).toBe(true)
+    expect(matchesCron(new Date('2024-01-16T09:00:00'), cron)).toBe(false)
+  })
+
+  it('should match specific month', () => {
+    const cron = parseCron('0 9 15 6 *') // June 15 at 9am
+    expect(matchesCron(new Date('2024-06-15T09:00:00'), cron)).toBe(true)
+    expect(matchesCron(new Date('2024-07-15T09:00:00'), cron)).toBe(false)
+  })
+
+  it('should use OR logic when both day-of-month and day-of-week are specified', () => {
+    // 15th of month OR Monday
+    const cron = parseCron('0 9 15 * 1')
+    // Jan 15, 2024 is a Monday (matches both)
+    expect(matchesCron(new Date('2024-01-15T09:00:00'), cron)).toBe(true)
+    // Jan 22, 2024 is a Monday (day of week matches)
+    expect(matchesCron(new Date('2024-01-22T09:00:00'), cron)).toBe(true)
+    // Feb 15, 2024 is a Thursday (day of month matches)
+    expect(matchesCron(new Date('2024-02-15T09:00:00'), cron)).toBe(true)
+    // Jan 23, 2024 is a Tuesday, not the 15th (neither matches)
+    expect(matchesCron(new Date('2024-01-23T09:00:00'), cron)).toBe(false)
+  })
+
+  it('should match 6-field expression with seconds', () => {
+    const cron = parseCron('30 * * * * *') // At second 30
+    expect(matchesCron(new Date('2024-01-15T10:30:30'), cron)).toBe(true)
+    expect(matchesCron(new Date('2024-01-15T10:30:31'), cron)).toBe(false)
+  })
+})
+
+describe('getNextCronDate', () => {
+  it('should find next minute for * * * * *', () => {
+    const cron = parseCron('* * * * *')
+    const from = new Date('2024-01-15T10:30:00')
+    const next = getNextCronDate(cron, from)
+    expect(next).not.toBeNull()
+    expect(next!.getTime()).toBeGreaterThan(from.getTime())
+  })
+
+  it('should find next occurrence of 0 * * * *', () => {
+    const cron = parseCron('0 * * * *')
+    const from = new Date('2024-01-15T10:30:00')
+    const next = getNextCronDate(cron, from)
+    expect(next).not.toBeNull()
+    expect(next!.getMinutes()).toBe(0)
+    expect(next!.getHours()).toBe(11) // Next hour
+  })
+
+  it('should find next Monday for 0 9 * * 1', () => {
+    const cron = parseCron('0 9 * * 1')
+    // Jan 16, 2024 is a Tuesday
+    const from = new Date('2024-01-16T10:00:00')
+    const next = getNextCronDate(cron, from)
+    expect(next).not.toBeNull()
+    expect(next!.getDay()).toBe(1) // Monday
+    expect(next!.getHours()).toBe(9)
+    expect(next!.getMinutes()).toBe(0)
+    // Should be Jan 22, 2024
+    expect(next!.getDate()).toBe(22)
+  })
+
+  it('should find next 15th for 0 9 15 * *', () => {
+    const cron = parseCron('0 9 15 * *')
+    const from = new Date('2024-01-16T10:00:00')
+    const next = getNextCronDate(cron, from)
+    expect(next).not.toBeNull()
+    expect(next!.getDate()).toBe(15)
+    expect(next!.getMonth()).toBe(1) // February
+    expect(next!.getHours()).toBe(9)
+  })
+
+  it('should handle year rollover', () => {
+    const cron = parseCron('0 0 1 1 *') // Jan 1 at midnight
+    const from = new Date('2024-06-15T10:00:00')
+    const next = getNextCronDate(cron, from)
+    expect(next).not.toBeNull()
+    expect(next!.getFullYear()).toBe(2025)
+    expect(next!.getMonth()).toBe(0) // January
+    expect(next!.getDate()).toBe(1)
+  })
+
+  it('should handle */5 step', () => {
+    const cron = parseCron('*/5 * * * *')
+    const from = new Date('2024-01-15T10:32:00')
+    const next = getNextCronDate(cron, from)
+    expect(next).not.toBeNull()
+    expect(next!.getMinutes()).toBe(35) // Next 5-minute mark
+  })
+})
+
+describe('getNextCronMs', () => {
+  it('should return milliseconds until next occurrence', () => {
+    const cron = parseCron('0 * * * *') // Every hour at minute 0
+    const from = new Date('2024-01-15T10:30:00')
+    const ms = getNextCronMs(cron, from)
+    expect(ms).not.toBeNull()
+    // Should be ~30 minutes (1800000ms)
+    expect(ms).toBe(30 * 60 * 1000)
+  })
+
+  it('should return positive milliseconds', () => {
+    const cron = parseCron('* * * * *')
+    const ms = getNextCronMs(cron)
+    expect(ms).not.toBeNull()
+    expect(ms).toBeGreaterThan(0)
+  })
+})

package/test/cron-scheduler.test.ts

@@ -0,0 +1,291 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  createCronJob,
+  stopCronJob,
+  startCronJob,
+  getActiveCronJobs,
+  stopAllCronJobs,
+  getActiveCronJobCount,
+  schedule,
+} from '../src/cron-scheduler.js'
+
+describe('cron-scheduler', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    stopAllCronJobs() // Clean up any existing jobs
+  })
+
+  afterEach(() => {
+    stopAllCronJobs()
+    vi.useRealTimers()
+  })
+
+  describe('createCronJob', () => {
+    it('should create a cron job with valid expression', () => {
+      const handler = vi.fn()
+      const job = createCronJob('0 * * * *', handler)
+
+      expect(job).toBeDefined()
+      expect(job.expression).toBe('0 * * * *')
+      expect(job.stopped).toBe(false)
+      expect(job.running).toBe(false)
+    })
+
+    it('should allow custom job ID', () => {
+      const job = createCronJob('* * * * *', () => {}, { id: 'my-custom-job' })
+      expect(job.id).toBe('my-custom-job')
+    })
+
+    it('should add job to active jobs', () => {
+      const job = createCronJob('* * * * *', () => {})
+      const active = getActiveCronJobs()
+      expect(active).toContain(job)
+    })
+
+    it('should calculate next run time', () => {
+      const job = createCronJob('0 * * * *', () => {})
+      expect(job.nextRun).not.toBeNull()
+      expect(job.nextRun!.getMinutes()).toBe(0)
+    })
+
+    it('should execute handler on cron schedule', async () => {
+      const handler = vi.fn()
+      // Every minute
+      createCronJob('* * * * *', handler)
+
+      // Advance time to next minute
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+
+      expect(handler).toHaveBeenCalledTimes(1)
+    })
+
+    it('should execute multiple times on recurring schedule', async () => {
+      const handler = vi.fn()
+      // Every minute
+      createCronJob('* * * * *', handler)
+
+      // Advance time by 3 minutes
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+
+      expect(handler).toHaveBeenCalledTimes(3)
+    })
+
+    it('should handle async handlers', async () => {
+      const results: number[] = []
+      const handler = async () => {
+        await new Promise((resolve) => setTimeout(resolve, 10))
+        results.push(Date.now())
+      }
+
+      createCronJob('* * * * *', handler)
+
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+      expect(results.length).toBeGreaterThanOrEqual(1)
+    })
+
+    it('should call error handler on error', async () => {
+      const error = new Error('Test error')
+      const handler = vi.fn(() => {
+        throw error
+      })
+      const errorHandler = vi.fn()
+
+      createCronJob('* * * * *', handler, { onError: errorHandler })
+
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+
+      expect(handler).toHaveBeenCalled()
+      expect(errorHandler).toHaveBeenCalledWith(error)
+    })
+
+    it('should continue scheduling after error', async () => {
+      const handler = vi.fn(() => {
+        throw new Error('Test error')
+      })
+      const errorHandler = vi.fn()
+
+      createCronJob('* * * * *', handler, { onError: errorHandler })
+
+      // Advance 3 minutes
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+
+      // Handler should have been called 3 times despite errors
+      expect(handler).toHaveBeenCalledTimes(3)
+      expect(errorHandler).toHaveBeenCalledTimes(3)
+    })
+
+    it('should not start if startImmediately is false', () => {
+      const handler = vi.fn()
+      const job = createCronJob('* * * * *', handler, { startImmediately: false })
+
+      expect(job.timer).toBeNull()
+      expect(job.nextRun).toBeNull()
+    })
+  })
+
+  describe('stopCronJob', () => {
+    it('should stop a cron job', () => {
+      const handler = vi.fn()
+      const job = createCronJob('* * * * *', handler)
+
+      stopCronJob(job)
+
+      expect(job.stopped).toBe(true)
+      expect(job.timer).toBeNull()
+      expect(job.nextRun).toBeNull()
+    })
+
+    it('should remove job from active jobs', () => {
+      const job = createCronJob('* * * * *', () => {})
+      expect(getActiveCronJobCount()).toBe(1)
+
+      stopCronJob(job)
+      expect(getActiveCronJobCount()).toBe(0)
+    })
+
+    it('should prevent future executions', async () => {
+      const handler = vi.fn()
+      const job = createCronJob('* * * * *', handler)
+
+      // Stop before first execution
+      stopCronJob(job)
+
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+      expect(handler).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('startCronJob', () => {
+    it('should start a stopped job', () => {
+      const handler = vi.fn()
+      const job = createCronJob('* * * * *', handler, { startImmediately: false })
+
+      expect(job.nextRun).toBeNull()
+
+      startCronJob(job)
+
+      expect(job.stopped).toBe(false)
+      expect(job.nextRun).not.toBeNull()
+    })
+
+    it('should resume execution after restart', async () => {
+      const handler = vi.fn()
+      const job = createCronJob('* * * * *', handler)
+
+      stopCronJob(job)
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+      expect(handler).not.toHaveBeenCalled()
+
+      startCronJob(job)
+      await vi.advanceTimersByTimeAsync(60 * 1000)
+      expect(handler).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('getActiveCronJobs', () => {
+    it('should return all active jobs', () => {
+      const job1 = createCronJob('* * * * *', () => {})
+      const job2 = createCronJob('0 * * * *', () => {})
+
+      const active = getActiveCronJobs()
+      expect(active).toHaveLength(2)
+      expect(active).toContain(job1)
+      expect(active).toContain(job2)
+    })
+
+    it('should not include stopped jobs', () => {
+      const job1 = createCronJob('* * * * *', () => {})
+      const job2 = createCronJob('0 * * * *', () => {})
+
+      stopCronJob(job1)
+
+      const active = getActiveCronJobs()
+      expect(active).toHaveLength(1)
+      expect(active).not.toContain(job1)
+      expect(active).toContain(job2)
+    })
+  })
+
+  describe('stopAllCronJobs', () => {
+    it('should stop all active jobs', () => {
+      createCronJob('* * * * *', () => {})
+      createCronJob('0 * * * *', () => {})
+      createCronJob('0 0 * * *', () => {})
+
+      expect(getActiveCronJobCount()).toBe(3)
+
+      stopAllCronJobs()
+
+      expect(getActiveCronJobCount()).toBe(0)
+    })
+  })
+
+  describe('getActiveCronJobCount', () => {
+    it('should return count of active jobs', () => {
+      expect(getActiveCronJobCount()).toBe(0)
+
+      createCronJob('* * * * *', () => {})
+      expect(getActiveCronJobCount()).toBe(1)
+
+      createCronJob('0 * * * *', () => {})
+      expect(getActiveCronJobCount()).toBe(2)
+    })
+  })
+
+  describe('schedule', () => {
+    it('should be an alias for createCronJob', () => {
+      const handler = vi.fn()
+      const job = schedule('0 9 * * 1', handler)
+
+      expect(job).toBeDefined()
+      expect(job.expression).toBe('0 9 * * 1')
+    })
+
+    it('should support options', () => {
+      const errorHandler = vi.fn()
+      const job = schedule('* * * * *', () => {}, {
+        id: 'my-schedule',
+        onError: errorHandler,
+      })
+
+      expect(job.id).toBe('my-schedule')
+      expect(job.onError).toBe(errorHandler)
+    })
+  })
+
+  describe('complex cron expressions', () => {
+    it('should handle */5 * * * * (every 5 minutes)', async () => {
+      const handler = vi.fn()
+      // Set a specific time: 10:02
+      vi.setSystemTime(new Date('2024-01-15T10:02:00'))
+
+      createCronJob('*/5 * * * *', handler)
+
+      // Advance to 10:05 (next 5-minute mark)
+      await vi.advanceTimersByTimeAsync(3 * 60 * 1000)
+
+      expect(handler).toHaveBeenCalledTimes(1)
+
+      // Advance another 5 minutes to 10:10
+      await vi.advanceTimersByTimeAsync(5 * 60 * 1000)
+      expect(handler).toHaveBeenCalledTimes(2)
+    })
+
+    it('should handle 0 9 * * 1-5 (weekdays at 9am)', async () => {
+      const handler = vi.fn()
+      // Set to Monday 8am
+      vi.setSystemTime(new Date('2024-01-15T08:00:00'))
+
+      createCronJob('0 9 * * 1-5', handler)
+
+      // Advance 1 hour to 9am Monday
+      await vi.advanceTimersByTimeAsync(60 * 60 * 1000)
+
+      expect(handler).toHaveBeenCalledTimes(1)
+    })
+  })
+})