cron_schedule #

⚡ Why cron_schedule? #

When building reminders, background tasks, or scheduling local notifications with flutter_local_notifications, developers face common friction points:

1. Predicting Future Timestamps: In-memory cron timers don't calculate upcoming execution timestamps. cron_schedule calculates the next $N$ future occurrences with microsecond accuracy.
2. Natural Language Explanation: Explaining "0 9 * * 1-5" in the UI requires messy custom code. schedule.toHumanReadable() outputs clean English summaries like "At 09:00, Monday through Friday".
3. Type-Safe Builder: Construct complex schedules programmatically without error-prone cron string concatenation.
4. Zero Dependencies & All 6 Platforms: Pure Dart implementation that runs natively on iOS, Android, Web, macOS, Windows, and Linux.

📦 Installation #

Add cron_schedule to your pubspec.yaml:

dependencies:
  cron_schedule: ^1.1.1

Or run:

flutter pub add cron_schedule

🚀 Quick Start #

1. Parse & Predict Next Occurrences #

import 'package:cron_schedule/cron_schedule.dart';

// Parse standard 5-part cron, 6-part seconds, or macros (@daily, @weekly)
final schedule = CronSchedule.parse('0 9 * * 1-5');

// Get the immediate next execution time:
final DateTime? nextRun = schedule.next();
print('Next run: $nextRun');

// Get the next 5 upcoming occurrence timestamps:
final List<DateTime> nextFive = schedule.nextOccurrences(count: 5);
for (final dt in nextFive) {
  print('Upcoming: $dt');
}

// Translate to natural human-readable English:
print(schedule.toHumanReadable()); // "At 09:00, Monday through Friday"

2. Schedule Local Notifications (flutter_local_notifications) #

final schedule = CronSchedule.parse('0 8 * * 1,3,5'); // Mon, Wed, Fri at 8 AM
final upcomingDates = schedule.nextOccurrences(count: 4);

for (final date in upcomingDates) {
  // Pass exact future DateTime instances to your notification plugin
  await flutterLocalNotificationsPlugin.zonedSchedule(
    id,
    'Workout Reminder',
    'Time for your morning stretch!',
    tz.TZDateTime.from(date, tz.local),
    notificationDetails,
    uiLocalNotificationDateInterpretation: UILocalNotificationDateInterpretation.absoluteTime,
  );
}

3. Type-Safe Schedule Builder #

// Daily at 08:30
final daily = CronSchedule.builder()
    .daily(hour: 8, minute: 30)
    .build();

// Weekdays (Mon-Fri) at 09:00
final weekdays = CronSchedule.builder()
    .weekdays(hour: 9, minute: 0)
    .build();

// Every 15 minutes
final periodic = CronSchedule.builder()
    .everyMinutes(15)
    .build();

🛠️ API Reference #

CronSchedule Methods #

💖 Support the Project #

If you find this project useful, consider supporting its active maintenance and future development:

📄 License #

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Maintained with ❤️ by Govind Tank.