rrule.js

Library for working with recurrence rules for calendar dates.

[![NPM version][npm-image]][npm-url] [![Build Status][ci-image]][ci-url] [![js-standard-style][js-standard-image]][js-standard-url] [![Downloads][downloads-image]][downloads-url] [![Gitter][gitter-image]][gitter-url]

rrule.js supports recurrence rules as defined in the iCalendar RFC, with a few important differences. It is a partial port of the rrule module from the excellent python-dateutil library. On top of that, it supports parsing and serialization of recurrence rules from and to natural language.

---

Quick Start

• Demo app

• For contributors and maintainers: the code for the demo app is only on gh-pages branch

Client Side

$ yarn add rrule

Server Side

Includes optional TypeScript types

$ yarn add rrule
# or
$ npm install rrule

Usage

RRule:

import { datetime, RRule, RRuleSet, rrulestr } from 'rrule'

// Create a rule:
const rule = new RRule({
  freq: RRule.WEEKLY,
  interval: 5,
  byweekday: [RRule.MO, RRule.FR],
  dtstart: datetime(2012, 2, 1, 10, 30),
  until: datetime(2012, 12, 31)
})

// Get all occurrence dates (Date instances):
rule.all()
[ '2012-02-03T10:30:00.000Z',
  '2012-03-05T10:30:00.000Z',
  '2012-03-09T10:30:00.000Z',
  '2012-04-09T10:30:00.000Z',
  '2012-04-13T10:30:00.000Z',
  '2012-05-14T10:30:00.000Z',
  '2012-05-18T10:30:00.000Z',

 /* … */]

// Get a slice:
rule.between(datetime(2012, 8, 1), datetime(2012, 9, 1))
['2012-08-27T10:30:00.000Z',
 '2012-08-31T10:30:00.000Z']

// Get an iCalendar RRULE string representation:
// The output can be used with RRule.fromString().
rule.toString()
"DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;INTERVAL=5;UNTIL=20130130T230000Z;BYDAY=MO,FR"

// Get a human-friendly text representation:
// The output can be used with RRule.fromText().
rule.toText()
"every 5 weeks on Monday, Friday until January 31, 2013"

RRuleSet:

const rruleSet = new RRuleSet()

// Add a rrule to rruleSet
rruleSet.rrule(
  new RRule({
    freq: RRule.MONTHLY,
    count: 5,
    dtstart: datetime(2012, 2, 1, 10, 30),
  })
)

// Add a date to rruleSet
rruleSet.rdate(datetime(2012, 7, 1, 10, 30))

// Add another date to rruleSet
rruleSet.rdate(datetime(2012, 7, 2, 10, 30))

// Add a exclusion rrule to rruleSet
rruleSet.exrule(
  new RRule({
    freq: RRule.MONTHLY,
    count: 2,
    dtstart: datetime(2012, 3, 1, 10, 30),
  })
)

// Add a exclusion date to rruleSet
rruleSet.exdate(datetime(2012, 5, 1, 10, 30))

// Get all occurrence dates (Date instances):
rruleSet.all()[
  ('2012-02-01T10:30:00.000Z',
  '2012-05-01T10:30:00.000Z',
  '2012-07-01T10:30:00.000Z',
  '2012-07-02T10:30:00.000Z')
]

// Get a slice:
rruleSet.between(datetime(2012, 2, 1), datetime(2012, 6, 2))[
  ('2012-05-01T10:30:00.000Z', '2012-07-01T10:30:00.000Z')
]

// To string
rruleSet.valueOf()[
  ('DTSTART:20120201T023000Z',
  'RRULE:FREQ=MONTHLY;COUNT=5',
  'RDATE:20120701T023000Z,20120702T023000Z',
  'EXRULE:FREQ=MONTHLY;COUNT=2',
  'EXDATE:20120601T023000Z')
]

// To string
rruleSet.toString()
;('["DTSTART:20120201T023000Z","RRULE:FREQ=MONTHLY;COUNT=5","RDATE:20120701T023000Z,20120702T023000Z","EXRULE:FREQ=MONTHLY;COUNT=2","EXDATE:20120601T023000Z"]')

rrulestr:

// Parse a RRule string, return a RRule object
rrulestr('DTSTART:20120201T023000Z\nRRULE:FREQ=MONTHLY;COUNT=5')

// Parse a RRule string, return a RRuleSet object
rrulestr('DTSTART:20120201T023000Z\nRRULE:FREQ=MONTHLY;COUNT=5', {
  forceset: true,
})

// Parse a RRuleSet string, return a RRuleSet object
rrulestr(
  'DTSTART:20120201T023000Z\nRRULE:FREQ=MONTHLY;COUNT=5\nRDATE:20120701T023000Z,20120702T023000Z\nEXRULE:FREQ=MONTHLY;COUNT=2\nEXDATE:20120601T023000Z'
)

Important: Use UTC dates

Dates in JavaScript are tricky. RRule tries to support as much flexibility as possible without adding any large required 3rd party dependencies, but that means we also have some special rules.

By default, RRule deals in "floating" times or UTC timezones. If you want results in a specific timezone, RRule also provides timezone support. Either way, JavaScript's built-in "timezone" offset tends to just get in the way, so this library simply doesn't use it at all. All times are returned with zero offset, as though it didn't exist in JavaScript.

THE BOTTOM LINE: Returned "UTC" dates are always meant to be interpreted as dates in your local timezone. This may mean you have to do additional conversion to get the "correct" local time with offset applied.

For this reason, it is highly recommended to use timestamps in UTC eg. new Date(Date.UTC(...)). Returned dates will likewise be in UTC (except on Chrome, which always returns dates with a timezone offset). It's recommended to use the provided datetime() helper, which creates dates in the correct format using a 1-based month.

For example:

// local machine zone is America/Los_Angeles
const rule = RRule.fromString(
  "DTSTART;TZID=America/Denver:20181101T190000;\n"
  + "RRULE:FREQ=WEEKLY;BYDAY=MO,WE,TH;INTERVAL=1;COUNT=3"
)
rule.all()

[ 2018-11-01T18:00:00.000Z,
  2018-11-05T18:00:00.000Z,
  2018-11-07T18:00:00.000Z ]
// Even though the given offset is `Z` (UTC), these are local times, not UTC times.
// Each of these this is the correct local Pacific time of each recurrence in
// America/Los_Angeles when it is 19:00 in America/Denver, including the DST shift.

// You can get the local components by using the getUTC* methods eg:
date.getUTCDate() // --> 1
date.getUTCHours() // --> 18

If you want to get the same times in true UTC, you may do so (e.g., using Luxon):

rule.all().map(date =>
DateTime.fromJSDate(date)
  .toUTC()
  .setZone('local', { keepLocalTime: true })
  .toJSDate()
)

[ 2018-11-02T01:00:00.000Z,
  2018-11-06T02:00:00.000Z,
  2018-11-08T02:00:00.000Z ]
// These times are in true UTC; you can see the hours shift

For more examples see python-dateutil documentation.

---

Timezone Support

Rrule also supports use of the TZID parameter in the RFC using the Intl API. Support matrix for the Intl API applies. If you need to support additional environments, please consider using a polyfill.

Example with TZID:

new RRule({
  dtstart: datetime(2018, 2, 1, 10, 30),
  count: 1,
  tzid: 'Asia/Tokyo',
}).all()[
  // assuming the system timezone is set to America/Los_Angeles, you get:
  '2018-01-31T17:30:00.000Z'
]
// which is the time in Los Angeles when it's 2018-02-01T10:30:00 in Tokyo.

Whether or not you use the TZID param, make sure to only use JS Date objects that are represented in UTC to avoid unexpected timezone offsets being applied, for example:

// WRONG: Will produce dates with TZ offsets added
new RRule({
  freq: RRule.MONTHLY,
  dtstart: new Date(2018, 1, 1, 10, 30),
  until: new Date(2018, 2, 31),
}).all()[('2018-02-01T18:30:00.000Z', '2018-03-01T18:30:00.000Z')]

// RIGHT: Will produce dates with recurrences at the correct time
new RRule({
  freq: RRule.MONTHLY,
  dtstart: datetime(2018, 2, 1, 10, 30),
  until: datetime(2018, 3, 31),
}).all()[('2018-02-01T10:30:00.000Z', '2018-03-01T10:30:00.000Z')]

API

RRule Constructor

new RRule(options[, noCache=false])

The options argument mostly corresponds to the properties defined for RRULE in the iCalendar RFC. Only freq is required.

<table> <!-- why, markdown... --> <thead> <tr> <th>Option</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>freq</code></td> <td> <p>(required) One of the following constants:</p> <ul> <li><code>RRule.YEARLY</code></li> <li><code>RRule.MONTHLY</code></li> <li><code>RRule.WEEKLY</code></li> <li><code>RRule.DAILY</code></li> <li><code>RRule.HOURLY</code></li> <li><code>RRule.MINUTELY</code></li> <li><code>RRule.SECONDLY</code></li> </ul> </td> </tr> <tr> <td><code>dtstart</code></td> <td>The recurrence start. Besides being the base for the recurrence, missing parameters in the final recurrence instances will also be extracted from this date. If not given, <code>new Date</code> will be used instead. **IMPORTANT:** See the discussion under <a href="#timezone-support">timezone support</a> </td> </tr> <tr> <td><code>interval</code></td> <td>The interval between each freq iteration. For example, when using <code>RRule.YEARLY</code>, an interval of <code>2</code> means once every two years, but with <code>RRule.HOURLY</code>, it means once every two hours. The default interval is <code>1</code>. </td> </tr> <tr> <td><code>wkst</code></td> <td>The week start day. Must be one of the <code>RRule.MO</code>, <code>RRule.TU</code>, <code>RRule.WE</code> constants, or an integer, specifying the first day of the week. This will affect recurrences based on weekly periods. The default week start is <code>RRule.MO</code>. </td> </tr> <tr> <td><code>count</code></td> <td>How many occurrences will be generated.</td> </tr> <tr> <td><code>until</code></td> <td>If given, this must be a <code>Date</code> instance, that will specify the limit of the recurrence. If a recurrence instance happens to be the same as the <code>Date</code> instance given in the <code>until</code> argument, this will be the last occurrence. </td> </tr> <tr> <td><code>tzid</code></td> <td>If given, this must be a IANA string recognized by the Intl API. See discussion under <a href="#timezone-support">Timezone support</a>. </td> </tr> <tr> <td><code>bysetpos</code></td> <td>If given, it must be either an integer, or an array of integers, positive or negative. Each given integer will specify an occurrence number, corresponding to the nth occurrence of the rule inside the frequency period. For example, a <code>bysetpos</code> of <code>-1</code> if combined with a <code>RRule.MONTHLY</code> frequency, and a byweekday of (<code>RRule.MO</code>, <code>RRule.TU</code>, <code>RRule.WE</code>, <code>RRule.TH</code>, <code>RRule.FR</code>), will result in the last work day of every month. </td> </tr> <tr> <td><code>bymonth</code></td> <td>If given, it must be either an integer, or an array of integers, meaning the months to apply the recurrence to. </td> </tr> <tr> <td><code>bymonthday</code></td> <td>If given, it must be either an integer, or an array of integers, meaning the month days to apply the recurrence to. </td> </tr> <tr> <td><code>byyearday</code></td> <td>If given, it must be either an integer, or an array of integers, meaning the year days to apply the recurrence to. </td> </tr> <tr> <td><code>byweekno</code></td> <td>If given, it must be either an integer, or an array of integers, meaning the week numbers to apply the recurrence to. Week numbers have the meaning described in ISO8601, that is, the first week of the year is that containing at least four days of the new year. </td> </tr> <tr> <td><code>byweekday</code></td> <td>If given, it must be either an integer (<code>0 == RRule.MO</code>), an array of integers, one of the weekday constants (<code>RRule.MO</code>, <code>RRule.TU</code>, etc), or an array of these constants. When given, these variables will define the weekdays where the recurrence will be applied. It's also possible to use an argument n for the weekday instances, which will mean the nth occurrence of this weekday in the period. For example, with <code>RRule.MONTHLY</code>, or with