chore: wip

Author: chrisbbreuer

docs/cron-expressions.md

@@ -0,0 +1,131 @@
+# Cron Expressions Guide
+
+`bun-queue` supports native cron syntax for scheduling recurring jobs with timezone support. This guide helps you understand how to write cron expressions and provides common examples you can use in your applications.
+
+## Cron Expression Format
+
+A cron expression consists of five fields that specify when a job should run:
+
+```
+┌───────────── minute (0 - 59)
+│ ┌───────────── hour (0 - 23)
+│ │ ┌───────────── day of month (1 - 31)
+│ │ │ ┌───────────── month (1 - 12)
+│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
+│ │ │ │ │
+│ │ │ │ │
+* * * * *
+```
+
+### Special Characters
+
+- `*`: Matches any value (wildcard)
+- `,`: Separates multiple values (e.g., `1,3,5`)
+- `-`: Specifies a range (e.g., `1-5`)
+- `/`: Specifies a step value (e.g., `*/2` means every 2 units)
+
+## Common Cron Expressions
+
+Here are some commonly used cron expressions:
+
+| Expression | Description |
+|------------|-------------|
+| `* * * * *` | Every minute |
+| `0 * * * *` | Every hour (at minute 0) |
+| `0 0 * * *` | Every day at midnight |
+| `0 0 * * 0` | Every Sunday at midnight |
+| `0 0 1 * *` | First day of every month at midnight |
+| `0 0 1 1 *` | January 1st at midnight (once a year) |
+| `0 12 * * 1-5` | Every weekday at noon |
+| `0 */2 * * *` | Every 2 hours |
+| `*/15 * * * *` | Every 15 minutes |
+| `0 8-17 * * 1-5` | Every hour from 8am to 5pm on weekdays |
+| `0 9 * * 1` | Every Monday at 9am |
+
+## Timezone Support
+
+Bun Bull supports timezone specifications for cron jobs. This allows you to schedule jobs according to a specific timezone rather than server time.
+
+Example with timezone:
+
+```typescript
+await queue.scheduleCron({
+  cronExpression: '30 9 * * *', // Every day at 9:30am
+  timezone: 'America/New_York', // Eastern Time
+  data: {
+    // job data
+  }
+})
+```
+
+### Common Timezones
+
+- `UTC`: Coordinated Universal Time
+- `America/New_York`: Eastern Time (US & Canada)
+- `America/Chicago`: Central Time (US & Canada)
+- `America/Denver`: Mountain Time (US & Canada)
+- `America/Los_Angeles`: Pacific Time (US & Canada)
+- `Europe/London`: UK time
+- `Europe/Paris`: Central European Time
+- `Asia/Tokyo`: Japan Standard Time
+- `Australia/Sydney`: Australian Eastern Time
+
+## Advanced Examples
+
+### First Monday of the Month
+
+To schedule a job to run on the first Monday of each month:
+
+```
+0 12 1-7 * 1
+```
+
+This runs at 12:00pm on Mondays (day of week = 1) that occur between the 1st and 7th day of the month.
+
+### Last Day of the Month
+
+This is trickier and is not directly supported by cron syntax. Instead, you might need to:
+
+1. Schedule a daily job
+2. Check in your job handler if it's the last day of the month
+
+### Specific Complex Schedules
+
+For more complex scheduling needs, you might need to combine multiple cron expressions or use custom logic in your job handler.
+
+## Using Cron Jobs in Bun Bull
+
+```typescript
+import { Queue, type CronJobOptions } from 'bun-queue'
+
+// Create a queue
+const queue = new Queue('my-queue')
+
+// Schedule a cron job
+await queue.scheduleCron({
+  cronExpression: '0 0 * * *', // Daily at midnight
+  timezone: 'UTC',
+  data: {
+    // Your job data
+  },
+  // Other job options
+  limit: 30, // Run at most 30 times
+  jobId: 'daily-job' // Custom job ID
+})
+
+// Unschedule a cron job
+await queue.unscheduleCron('daily-job')
+```
+
+## Best Practices
+
+1. **Be specific**: Avoid using `* * * * *` (every minute) in production as it can overload your system.
+2. **Use jobId**: Always provide a jobId for cron jobs so you can easily unschedule them later.
+3. **Test timezone logic**: If using timezones, test to ensure jobs run at the expected time.
+4. **Set limits**: Consider using the `limit` option to ensure jobs don't run indefinitely.
+5. **Handle edge cases**: Be aware of edge cases like months with varying numbers of days.
+
+## Additional Resources
+
+- [Crontab Guru](https://crontab.guru/): Interactive cron expression editor
+- [List of TZ database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones): Complete list of valid timezone identifiers

examples/cron-jobs.ts

@@ -0,0 +1,132 @@
+import { Queue } from '../src'
+
+interface NotificationData {
+  title: string
+  message: string
+  recipients: string[]
+  type: 'email' | 'push' | 'sms'
+}
+
+async function main() {
+  console.log('🕒 Cron Jobs Example')
+
+  // Create a queue for notifications
+  const notificationQueue = new Queue<NotificationData>('notifications', {
+    verbose: true,
+    logLevel: 'info',
+  })
+
+  console.log('✅ Queue created')
+
+  // Process notifications
+  notificationQueue.process(5, async (job) => {
+    const { title, message, recipients, type } = job.data
+    console.log(`📨 Processing ${type} notification "${title}" to ${recipients.length} recipients`)
+
+    // Simulate notification sending
+    await new Promise(resolve => setTimeout(resolve, 200))
+
+    return { success: true, sentAt: new Date(), recipientCount: recipients.length }
+  })
+
+  console.log('\n📅 Scheduling cron jobs with different expressions:')
+
+  // Example 1: Run every minute - useful for testing
+  const everyMinuteId = await notificationQueue.scheduleCron({
+    cronExpression: '* * * * *', // Every minute
+    data: {
+      title: 'Server Status',
+      message: 'All systems operational',
+      recipients: ['admin@example.com'],
+      type: 'email'
+    },
+    jobId: 'status-check-minute',
+    // Will stop after 5 executions
+    limit: 5
+  })
+  console.log(`  - Every minute status check scheduled (ID: ${everyMinuteId})`)
+
+  // Example 2: Hourly job with timezone
+  const hourlyJobId = await notificationQueue.scheduleCron({
+    cronExpression: '0 * * * *', // At minute 0 of every hour
+    timezone: 'America/New_York', // Eastern Time
+    data: {
+      title: 'Hourly Update',
+      message: 'This is your hourly system update',
+      recipients: ['team@example.com'],
+      type: 'push'
+    },
+    jobId: 'hourly-update'
+  })
+  console.log(`  - Hourly update scheduled in Eastern Time (ID: ${hourlyJobId})`)
+
+  // Example 3: Daily job at specific time
+  const dailyJobId = await notificationQueue.scheduleCron({
+    cronExpression: '30 9 * * *', // Every day at 9:30am
+    timezone: 'Europe/London', // London time
+    data: {
+      title: 'Daily Report',
+      message: 'Here is your daily activity report',
+      recipients: ['manager@example.com'],
+      type: 'email'
+    },
+    jobId: 'daily-report'
+  })
+  console.log(`  - Daily report scheduled for 9:30am London time (ID: ${dailyJobId})`)
+
+  // Example 4: Weekday job (Monday through Friday)
+  const weekdayJobId = await notificationQueue.scheduleCron({
+    cronExpression: '0 8 * * 1-5', // At 8:00am, Monday through Friday
+    data: {
+      title: 'Morning Briefing',
+      message: 'Your tasks for today',
+      recipients: ['staff@example.com'],
+      type: 'sms'
+    },
+    jobId: 'weekday-briefing'
+  })
+  console.log(`  - Weekday briefing scheduled for 8:00am Mon-Fri (ID: ${weekdayJobId})`)
+
+  // Example 5: Complex schedule (first Monday of the month)
+  const monthlyJobId = await notificationQueue.scheduleCron({
+    cronExpression: '0 12 1-7 * 1', // At 12:00pm on Monday in the first week of the month
+    data: {
+      title: 'Monthly Review',
+      message: 'Time for our monthly performance review',
+      recipients: ['executives@example.com'],
+      type: 'email'
+    },
+    jobId: 'monthly-review'
+  })
+  console.log(`  - Monthly review scheduled for first Monday of each month (ID: ${monthlyJobId})`)
+
+  // Show when the next few minutes of jobs will run
+  console.log('\n⏰ Demonstrating minute-by-minute execution for a short period:')
+  console.log('   (The every-minute job will run several times)')
+
+  // Wait for several minutes to see some executions
+  await new Promise(resolve => setTimeout(resolve, 180000)) // 3 minutes
+
+  // Unschedule one of the jobs to demonstrate cancellation
+  console.log('\n❌ Unscheduling the every-minute job')
+  const unscheduled = await notificationQueue.unscheduleCron(everyMinuteId)
+  console.log(`   Job ${everyMinuteId} ${unscheduled ? 'successfully unscheduled' : 'failed to unschedule'}`)
+
+  // Show the remaining scheduled jobs
+  console.log('\n📝 The following jobs remain scheduled:')
+  console.log(`  - Hourly update (ID: ${hourlyJobId})`)
+  console.log(`  - Daily report (ID: ${dailyJobId})`)
+  console.log(`  - Weekday briefing (ID: ${weekdayJobId})`)
+  console.log(`  - Monthly review (ID: ${monthlyJobId})`)
+
+  console.log('\n👋 Example completed. In a real application, these would continue running.')
+  console.log('   Closing the queue for the example.')
+
+  // In a real application, you might keep the queue running forever
+  await notificationQueue.close()
+}
+
+main().catch(error => {
+  console.error('Error in example:', error)
+  process.exit(1)
+})

package.json

@@ -67,7 +67,8 @@
     "example:advanced-features": "bun examples/advanced-features.ts",
     "example:priority-queue": "bun examples/priority-queue.ts",
     "example:key-rate-limiting": "bun examples/key-rate-limiting.ts",
-    "example:distributed-locks": "bun examples/distributed-locks.ts"
+    "example:distributed-locks": "bun examples/distributed-locks.ts",
+    "example:cron-jobs": "bun examples/cron-jobs.ts"
   },
   "devDependencies": {
     "@stacksjs/docs": "^0.70.23",