jorroll / rschedule

A javascript library, written in typescript, for working with recurring dates. This is a mirror of the canonical repo located on Gitlab.

rSchedule

View docs

The canonical version of this repo is hosted on Gitlab, but there is also a Github mirror. Issues and merge requests should be created in the Gitlab repo.

A javascript library, written in typescript, for working with recurring dates. The library is "date agnostic" and usable with Date, Moment, luxon, dayjs, or js-joda objects. If your chosen date library supports time zones, rSchedule supports time zones. All objects in rSchedule are immutable. rSchedule supports creating schedules with durations. rSchedule is modular, tree-shakable, and extensible. It supports JSON and ICAL serialization as well as custom recurrence rules.

# To install both the main package and the `StandardDateAdapter` for standard javascript dates */

yarn add @rschedule/core @rschedule/standard-date-adapter

# or

npm install @rschedule/core @rschedule/standard-date-adapter

# Current DateAdapter packages

@rschedule/standard-date-adapter
@rschedule/moment-date-adapter
@rschedule/moment-tz-date-adapter
@rschedule/luxon-date-adapter
@rschedule/dayjs-date-adapter
@rschedule/joda-date-adapter

See the docs for setup instructions

Usage (online demo)

You can play around with a demo of rSchedule on codesandbox here.

Iterate using standard javascript syntax

// showing usage with the StandardDateAdapter

const rule = new Rule({
  frequency: 'YEARLY',
  byMonthOfYear: [2, 6],
  byDayOfWeek: ['SU', ['MO', 3]],
  start: new Date(2010, 1, 7),
});

for (const { date } of rule.occurrences({ take: 10 })) {
  date.toISOString();

  // do stuff...
}

Get the first 5 occurrences after a starting date

rule
  .occurrences({
    start: new Date(2010, 5, 7),
    take: 5,
  })
  .toArray()
  .map(date => date.toISOString());

Add another rule, subtract specific dates, filter to only return unique dates, and query to see if the result occurs on a Monday before 2013/11/15.

const secondRule = new Rule({
  start: new Date(2011, 1, 7),
  frequency: 'DAILY',
  byDayOfWeek: ['MO'],
});

const dates = new Dates({
  dates: [new Date(2010, 10, 15), new Date(2010, 11, 3)],
});

rule
  .pipe(add(secondRule), subtract(dates), unique())
  .occursOn({ weekday: 'MO', before: new Date(2013, 10, 15) }); // true

Docs

• Version 1.x docs (current)
• Version 0.12 docs
• Version 0.11 docs
• Version 0.10 docs
• Version 0.9 docs

Master branch docs (unreleased)

Known Limitations

• @rschedule/ical-tools
  • No BYWEEKNO, BYYEARDAY, or BYSETPOS rule support.
  • VEVENT supports RRULE, EXRULE, RDATE, EXDATE, DTSTART, DTEND and DURATION properties. Other properties are not supported.
  • No VCALENDAR iCal support.

Roadmap

• Explore rearranging library exports and build to better support tree shaking and reduce minimum bundle size.
• Natural language package for converting rSchedule objects into human readable strings
  • Internationalization of human readable strings
• Create subtractDuration operator

Typescript Version

rSchedule version	Typescript version
1.1.3	3.5
1.2.0	3.9

About

See the contributors list for an up-to-date record of contributions to this repo. The initial version of rSchedule was created by John Carroll. Most of the RRULE tests were taken from the excellent rrule.js library (which were, themselves, taken from a python library, I believe).

This library was built using the typescript starter repo. The implementation strategy drew inspiration from the Angular Material2 Date Picker component (which makes use of date adapters to support different javascript date libraries), as well as rrulejs and ice_cube.

This project is not affiliated with any of these projects.

Similar libraries

• rrulejs
  • Supports time zones via luxon and supports iCal. rrulejs is older and more mature than rSchedule and I used it before making rSchedule.
  • For most projects, rrulejs will probably do everything you need and you may feel more comfortable using something older and with a larger install base. Another reason you might want to choose rrule would be for it's NLP, internationalization support, or support for BYWEEKNO, BYYEARDAY, and BYSETPOS ICal rules. By comparison, rSchedule has better timezone support, support for different date libraries, duration support, custom rule support, a smaller minimum bundle size, and complex calendar support. See the docs of both projects to learn more.
• laterjs (currently unmaintained)
  • Simpler API. Not ICAL compatible. Has support for chron jobs.
• dayspan
  • Appears to be a pretty full featured recurring dates library (like rSchedule or rrulejs), but I don't know much about it. Interestingly, while rrulejs and rSchedule have somewhat similar APIs (borrowing heavily from the ICAL spec), dayspan's API seems to be very different and somewhat unique in places.