date_tools 0.1.0

Tools for managing dates including a DateInterval implementation.

Date Tools

Tools for working with dates including implementations of [DateInterval], [DateSchedule] and additional extensions on [DateTime].

Date Intervals

The [DateInterval] API makes it easier to work with common date intervals like days, months and years. You can check the start/end of intervals, move to previous and next intervals, and generate sequences of intervals.

/// The interval defaults to the [DateTime.now()], but we'll provide a date to make it clear.
final now = DateTime(2023, 10, 26);

print(DateInterval.day(now).start()); // DateTime:<2023-10-26 00:00:00.000000>
print(DateInterval.day(now).end()); // DateTime:<2023-10-26 23:59:59.999999>

print(DateInterval.year(now).next().start); // DateTime:<2024-01-01 00:00:00.000000>

print(DateInterval.month(now).generate(4).toList());
// DateInterval(interval: month, start: 2023-10-01 00:00:00.000, end: 2023-10-31 23:59:59.999999)
// DateInterval(interval: month, start: 2023-11-01 00:00:00.000, end: 2023-11-30 23:59:59.999999)
// DateInterval(interval: month, start: 2023-12-01 00:00:00.000, end: 2023-12-31 23:59:59.999999)
// DateInterval(interval: month, start: 2024-01-01 00:00:00.000, end: 2023-01-31 23:59:59.999999)

print(DateInterval.day(now).range(now.add(2.days)).toList());
// DateInterval(interval: day, start: 2023-10-26 00:00:00.000, end: 2023-10-26 23:59:59.999999)
// DateInterval(interval: day, start: 2023-10-27 00:00:00.000, end: 2023-10-27 23:59:59.999999)
// DateInterval(interval: day, start: 2023-10-28 00:00:00.000, end: 2023-10-28 23:59:59.999999)

print(DateInterval.month(now).spans(now)); // true
print(DateInterval.month(now).subtract(1).spans(now)); // false

Date Schedules

The [DateSchedule] API supports the generation of dates in the past/future based on a given schedule.

final now = DateTime(2025, 1, 1); // Wednesday January 1st, 2025.

/// A schedule that repeats every week on Monday and Friday.
print(DateSchedule.weekly(weekdays: [1, 5]).start(now).take(3));
// DateTime:<2025-01-03 00:00:00.000000>
// DateTime:<2025-01-06 00:00:00.000000>
// DateTime:<2025-01-10 00:00:00.000000>

/// A schedule that repeats every month on the 15th and 30th of the month beginning [now].
print(DateSchedule.monthly(days: [15, 30]).start(now).take(3));
// DateTime:<2025-01-15 00:00:00.000000>
// DateTime:<2025-01-30 00:00:00.000000>
// DateTime:<2025-02-15 00:00:00.000000>

/// A schedule that repeats every *other* month on the 15th and 30th of the month beginning [now].
print(DateSchedule.monthly(days: [15, 30], interval: 2).start(now).take(3));
// DateTime:<2025-01-15 00:00:00.000000>
// DateTime:<2025-01-30 00:00:00.000000>
// DateTime:<2025-03-15 00:00:00.000000>

/// A schedule that repeats on Monday and Friday of every week beginning [now].
print(DateSchedule.monthly(weekdays: [1, 5]).start(now).take(3));
// DateTime:<2025-01-03 00:00:00.000000>
// DateTime:<2025-01-06 00:00:00.000000>
// DateTime:<2025-01-10 00:00:00.000000>

/// A schedule that repeats on the 1st and 3rd Friday of every week beginning [now].
print(DateSchedule.monthly(nthWeekdays: [1, 3], weekdays: [5]).start(now).take(3));
// DateTime:<2025-01-03 00:00:00.000000>
// DateTime:<2025-01-17 00:00:00.000000>
// DateTime:<2025-02-07 00:00:00.000000>

/// A schedule that repeats on the first and last day of every other month beginning [now].
print(DateSchedule.monthly(days: [1, -1], interval: 2).start(now).take(3));
// DateTime:<2025-01-01 00:00:00.000000>
// DateTime:<2025-01-31 00:00:00.000000>
// DateTime:<2025-03-01 00:00:00.000000>

/// A schedule that repeats on the last friday of the month beginning [now] and *going back in time*.
print(DateSchedule.monthly(nthWeekdays: [-1], weekdays: [5]).start(now, ascending: false).take(3));
// DateTime:<2024-12-27 00:00:00.000000>
// DateTime:<2024-11-29 00:00:00.000000>
// DateTime:<2024-10-25 00:00:00.000000>

/// A schedule can also be created with a fixed list of dates.
print(DateSchedule.fixed([DateTime(2025, 03, 25), DateTime(2025, 04, 27)]));
// DateTime:<2025-03-25 00:00:00.000000>
// DateTime:<2025-04-27 00:00:00.000000>

// Date schedules can be merged together to support more complex scheduling scenarios. By default,
// overlapping dates are deduped across merged schedules.
print(
   DateSchedule.merge([
    DateSchedule.yearly(months: [1], days: [10, 15]),
    DateSchedule.monthly(days: [2, 9, 10]),
    DateSchedule.fixed([DateTime(2025, 1, 15), DateTime(2025, 1, 16)]),
  ]).start(now).take(7)
);
// DateTime:<2025-01-02 00:00:00.000000>
// DateTime:<2025-01-09 00:00:00.000000>
// DateTime:<2025-01-10 00:00:00.000000>
// DateTime:<2025-01-15 00:00:00.000000>
// DateTime:<2025-01-16 00:00:00.000000>

More tools will be added in the future. Happy coding!