cron_schedule

A lightweight, high-performance, pure-Dart cron expression parser, next-occurrence timestamp predictor, human-readable natural language translator, and fluent schedule builder for Dart and Flutter.

---

⚡ 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.0.0

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

Method	Return Type	Description
CronSchedule.parse(String)	CronSchedule	Parses standard 5/6 field expression or macro (@daily, @weekly).
CronSchedule.tryParse(String)	CronSchedule?	Safe parser returning null on syntax error.
next({DateTime? after})	DateTime?	Calculates the single next execution timestamp.
nextOccurrences({int count, DateTime? after})	List<DateTime>	Generates a list of upcoming execution timestamps.
isDue(DateTime)	bool	Checks if the schedule triggers at the exact given timestamp.
toHumanReadable()	String	Formats the cron expression into clear English.

---

👨💻 Author & Maintainer

Developed and maintained by Govind Tank.

Issues, feature requests, and pull requests are welcomed on GitHub!

---

📄 License

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