rrule

What is rrule?

The 'rrule' npm package is a powerful library for working with recurrence rules as defined in the iCalendar RFC. It allows you to generate and manipulate recurring dates with a high degree of flexibility and precision.

What are rrule's main functionalities?

Generating Recurrence Rules

This feature allows you to generate a set of recurring dates based on a specified rule. In this example, the rule generates dates that occur weekly on Mondays and Fridays, starting from January 1, 2023, and ending on June 1, 2023.

const { RRule } = require('rrule');

const rule = new RRule({
  freq: RRule.WEEKLY,
  interval: 1,
  byweekday: [RRule.MO, RRule.FR],
  dtstart: new Date(Date.UTC(2023, 0, 1, 10, 30)),
  until: new Date(Date.UTC(2023, 5, 1))
});

console.log(rule.all());

Parsing Recurrence Rules

This feature allows you to parse a recurrence rule from a string in the iCalendar format. The example demonstrates how to parse a rule string and generate the corresponding dates.

const { RRule } = require('rrule');

const ruleString = 'FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,FR;DTSTART=20230101T103000Z;UNTIL=20230601T000000Z';
const rule = RRule.fromString(ruleString);

console.log(rule.all());

Converting Recurrence Rules to String

This feature allows you to convert a recurrence rule to its string representation in the iCalendar format. The example shows how to create a rule and then convert it to a string.

const { RRule } = require('rrule');

const rule = new RRule({
  freq: RRule.WEEKLY,
  interval: 1,
  byweekday: [RRule.MO, RRule.FR],
  dtstart: new Date(Date.UTC(2023, 0, 1, 10, 30)),
  until: new Date(Date.UTC(2023, 5, 1))
});

console.log(rule.toString());

Handling Timezones

This feature allows you to handle timezones when working with recurrence rules. The example demonstrates how to create a rule and add it to a rule set, which can then be used to generate dates considering timezones.

const { RRule, RRuleSet, rrulestr } = require('rrule');

const rule = new RRule({
  freq: RRule.WEEKLY,
  interval: 1,
  byweekday: [RRule.MO, RRule.FR],
  dtstart: new Date(Date.UTC(2023, 0, 1, 10, 30)),
  until: new Date(Date.UTC(2023, 5, 1))
});

const ruleSet = new RRuleSet();
ruleSet.rrule(rule);

console.log(ruleSet.all());

Other packages similar to rrule

moment-recur

The 'moment-recur' package extends the Moment.js library to support recurring dates. It is less feature-rich compared to 'rrule' but integrates well with Moment.js for simpler use cases.

later

The 'later' package is a flexible library for defining recurring schedules and executing functions at specified times. It offers more complex scheduling options but is less focused on iCalendar standards compared to 'rrule'.

date-fns

The 'date-fns' package provides a wide range of date utility functions, including some support for recurring dates. It is more general-purpose and less specialized in recurrence rules compared to 'rrule'.

README

rrule.js

Library for working with recurrence rules for calendar dates.

rrule.js supports recurrence rules as defined in the iCalendar RFC. 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
• Test suite

Client Side

$ bower install rrule

Alternatively, download rrule.js manually. If you intend to use RRule.prototype.toText() or RRule.fromText(), you'll also need nlp.js.

<script src="rrule/lib/rrule.js"></script>

<!-- Optional -->
<script src="rrule/lib/nlp.js"></script>

Server Side

$ npm install rrule

var RRule = require('rrule').RRule;

Usage

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

// Get all occurrence dates (Date instances):
rule.all();
['Fri Feb 03 2012 10:30:00 GMT+0100 (CET)',
 'Mon Mar 05 2012 10:30:00 GMT+0100 (CET)',
 'Fri Mar 09 2012 10:30:00 GMT+0100 (CET)',
 'Mon Apr 09 2012 10:30:00 GMT+0200 (CEST)',
 /* … */]

// Get a slice:
rule.between(new Date(2012, 7, 1), new Date(2012, 8, 1))
['Mon Aug 27 2012 10:30:00 GMT+0200 (CEST)',
 'Fri Aug 31 2012 10:30:00 GMT+0200 (CEST)']

// Get an iCalendar RRULE string representation:
// The output can be used with RRule.fromString().
rule.toString();
"FREQ=WEEKLY;DTSTART=20120201T093000Z;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"

For more examples see tests/tests.js and python-dateutil documentation.

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.

Option	Description
freq	(required) One of the following constants: RRule.YEARLY RRule.MONTHLY RRule.WEEKLY RRule.DAILY RRule.HOURLY RRule.MINUTELY RRule.SECONDLY
dtstart	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, new Date will be used instead.
interval	The interval between each freq iteration. For example, when using RRule.YEARLY, an interval of 2 means once every two years, but with RRule.HOURLY, it means once every two hours. The default interval is 1.
wkst	The week start day. Must be one of the RRule.MO, RRule.TU, RRule.WE constants, or an integer, specifying the first day of the week. This will affect recurrences based on weekly periods. The default week start is RRule.MO.
count	How many occurrences will be generated.
until	If given, this must be a Date instance, that will specify the limit of the recurrence. If a recurrence instance happens to be the same as the Date instance given in the until argument, this will be the last occurrence.
bysetpos	If given, it must be either an integer, or a sequence 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 bysetpos of -1 if combined with a RRule.MONTHLY frequency, and a byweekday of (RRule.MO, RRule.TU, RRule.WE, RRule.TH, FR), will result in the last work day of every month.
bymonth	If given, it must be either an integer, or a sequence of integers, meaning the months to apply the recurrence to.
bymonthday	If given, it must be either an integer, or a sequence of integers, meaning the month days to apply the recurrence to.
byyearday	If given, it must be either an integer, or a sequence of integers, meaning the year days to apply the recurrence to.
byweekno	If given, it must be either an integer, or a sequence 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.
byweekday	If given, it must be either an integer (0 == RRule.MO), a sequence of integers, one of the weekday constants (RRule.MO, RRule.TU, etc), or a sequence 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 RRule.MONTHLY, or with RRule.YEARLY and BYMONTH, using RRule.FR.nth(+1) or RRule.FR.nth(-1) in byweekday will specify the first or last friday of the month where the recurrence happens. Notice that the RFC documentation, this is specified as BYDAY, but was renamed to avoid the ambiguity of that argument.
byhour	If given, it must be either an integer, or a sequence of integers, meaning the hours to apply the recurrence to.
byminute	If given, it must be either an integer, or a sequence of integers, meaning the minutes to apply the recurrence to.
bysecond	If given, it must be either an integer, or a sequence of integers, meaning the seconds to apply the recurrence to.
byeaster	This is an extension to the RFC specification which the Python implementation provides. Not implemented in the JavaScript version.

noCache: Set to true to disable caching of results. If you will use the same rrule instance multiple times, enabling caching will improve the performance considerably. Enabled by default.

See also python-dateutil documentation.

---

Instance properties

rule.options

Processed options applied to the rule. Includes default options (such us wkstart). Currently, rule.options.byweekday isn't equal to rule.origOptions.byweekday (which is an inconsistency).

<dt><code>rule.origOptions</code></dt>
<dd>The original <code>options</code> argument passed to
the constructor.</dd>

---

Occurrence Retrieval Methods

RRule.prototype.all([iterator])

Returns all dates matching the rule. It is a replacement for the iterator protocol this class implements in the Python version.

As rules without until or count represent infinite date series, you can optionally pass iterator, which is a function that is called for each date matched by the rule. It gets two parameters date (the Date instance being added), and i (zero-indexed position of date in the result). Dates are being added to the result as long as the iterator returns true. If a false-y value is returned, date isn't added to the result and the iteration is interrupted (possibly prematurely).

rule.all()
['Fri Feb 03 2012 10:30:00 GMT+0100 (CET)',
 'Mon Mar 05 2012 10:30:00 GMT+0100 (CET)',
 'Fri Mar 09 2012 10:30:00 GMT+0100 (CET)',
 'Mon Apr 09 2012 10:30:00 GMT+0200 (CEST)',
 /* … */]

rule.all(function (date, i){return i < 2});
['Fri Feb 03 2012 10:30:00 GMT+0100 (CET)',
 'Mon Mar 05 2012 10:30:00 GMT+0100 (CET)',]

RRule.prototype.between(after, before, inc=false [, iterator])

Returns all the occurrences of the rrule between after and before. The inc keyword defines what happens if after and/or before are themselves occurrences. With inc == true, they will be included in the list, if they are found in the recurrence set.

Optional iterator has the same function as it has with RRule.prototype.all().

rule.between(new Date(2012, 7, 1), new Date(2012, 8, 1))
['Mon Aug 27 2012 10:30:00 GMT+0200 (CEST)',
 'Fri Aug 31 2012 10:30:00 GMT+0200 (CEST)']

RRule.prototype.before(dt, inc=false)

Returns the last recurrence before the given Date instance. The inc argument defines what happens if dt is an occurrence. With inc == true, if dt itself is an occurrence, it will be returned.

RRule.prototype.after(dt, inc=false)

Returns the first recurrence after the given Date instance. The inc argument defines what happens if dt is an occurrence. With inc == true, if dt itself is an occurrence, it will be returned.

See also python-dateutil documentation.

---

iCalendar RFC String Methods

RRule.prototype.toString()

Returns a string representation of the rule as per the iCalendar RFC. Only properties explicitely specified in options are included:

rule.toString();
"FREQ=WEEKLY;DTSTART=20120201T093000Z;INTERVAL=5;UNTIL=20130130T230000Z;BYDAY=MO,FR"

rule.toString() == RRule.optionsToString(rule.origOptions)
true

RRule.optionsToString(options)

Converts options to iCalendar RFC RRULE string:

// Get full a string representation of all options,
// including the default and inferred ones.
RRule.optionsToString(rule.options)
"FREQ=WEEKLY;DTSTART=20120201T093000Z;INTERVAL=5;WKST=0;UNTIL=20130130T230000Z;BYDAY=MO,FR;BYHOUR=10;BYMINUTE=30;BYSECOND=0"

// Cherry-pick only some options from an rrule:
RRule.optionsToString({
    freq: rule.options.freq,
    dtstart: rule.options.dtstart,
})
"FREQ=WEEKLY;DTSTART=20120201T093000Z"

RRule.fromString(rfcString)

Constructs an RRule instance from a complete rfcString:

var rule = RRule.fromString("FREQ=WEEKLY;DTSTART=20120201T093000Z")

// This is equivalent
var rule = new RRule(RRule.parseString("FREQ=WEEKLY;DTSTART=20120201T093000Z"))

RRule.parseString(rfcString)

Only parse RFC string and return options.

var options = RRule.parseString('FREQ=DAILY;INTERVAL=6')
options.dtstart = new Date(2000, 1, 1)
var rule = new RRule(options)

---

Natural Language Text Methods

These methods provide an incomplete support for text–RRule and RRule–text conversion. You should test them with your input to see whether the result is acceptable.

To use these methods in the browser, you need to include the rrule/nlp.js file as well.

RRule.prototype.toText([gettext, [language]])

Returns a textual representation of rule. The gettext callback, if provided, will be called for each text token and its return value used instead. The optional language argument is a language definition to be used (defaults to rrule/nlp.js:ENGLISH).

var rule = new RRule({
  freq: RRule.WEEKLY,
  count: 23
})
rule.toText()
"every week for 23 times"

RRule.prototype.isFullyConvertibleToText()

Provides a hint on whether all the options the rule has are convertible to text.

RRule.fromText(text[, language])

Constructs an RRule instance from text.

rule = RRule.fromText('every day for 3 times')

RRule.parseText(text[, language])

Parse text into options:

options = RRule.parseText('every day for 3 times')
// {freq: 3, count: "3"}
options.dtstart = new Date(2000, 1, 1)
var rule = new RRule(options)

---

Changelog

• 2.1.0
  • Removed dependency on Underscore.js (thanks @gsf).
  • Various small bugfixes and improvements.
• 2.0.1
  • Added bower.json.
• 2.0.0 (2013-07-16)
  • Fixed a February 28-related issue.
  • More flexible, backwards-incompatible API:
    • freq is now options.freq.
    • options.cache is now noCache.
    • iterator has to return true
    • dtstart and options arguments removed from RRule.fromString (use RRule.parseString and modify options manually instead).
    • today argument removed from Rule.prototype.toText (never actually used).
    • rule.toString() now includes DTSTART (if explicitely specified in options).
    • Day constants .clone is now .nth, eg. RRule.FR.nth(-1) (last Friday).
  • Added RRule.parseString
  • Added RRule.parseText
  • Added RRule.optionsToString
• 1.1.0 (2013-05-21)
  • Added a demo app.
  • Handle dates in UNTIL in RRule.fromString.
  • Added support for RequireJS.
  • Added options argument to RRule.fromString.
• 1.0.1 (2013-02-26)
  • Fixed leap years (thanks @jessevogt)
• 1.0.0 (2013-01-24)
  • Fixed timezone offset issues related to DST (thanks @evro).
• 1.0.0-beta (2012-08-15)
  • Initial public release.

Authors

• Jakub Roztocil (@jakubroztocil)
• Lars Schöning (@lyschoening)

Python dateutil is written by Gustavo Niemeyer.

See LICENCE for more details.