Repository files navigation

Library for working with recurrence rules for calendar dates.

rrule.js supports recurrence rules as defined in theiCalendarRFC, with a few importantdifferences. It is a partial port of therrule module from the excellentpython-dateutil library. On top ofthat, it supports parsing and serialization of recurrence rules from andto natural language.

• Demo app

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

$ yarn add rrule

Includes optional TypeScript types

$ yarn add rrule# or$ npm install rrule

RRule:

import{datetime,RRule,RRuleSet,rrulestr}from'rrule'// Create a rule:construle=newRRule({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:

constrruleSet=newRRuleSet()// Add a rrule to rruleSetrruleSet.rrule(newRRule({freq:RRule.MONTHLY,count:5,dtstart:datetime(2012,2,1,10,30),}))// Add a date to rruleSetrruleSet.rdate(datetime(2012,7,1,10,30))// Add another date to rruleSetrruleSet.rdate(datetime(2012,7,2,10,30))// Add a exclusion rrule to rruleSetrruleSet.exrule(newRRule({freq:RRule.MONTHLY,count:2,dtstart:datetime(2012,3,1,10,30),}))// Add a exclusion date to rruleSetrruleSet.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 stringrruleSet.valueOf()[('DTSTART:20120201T023000Z','RRULE:FREQ=MONTHLY;COUNT=5','RDATE:20120701T023000Z,20120702T023000Z','EXRULE:FREQ=MONTHLY;COUNT=2','EXDATE:20120601T023000Z')]// To stringrruleSet.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 objectrrulestr('DTSTART:20120201T023000Z\nRRULE:FREQ=MONTHLY;COUNT=5')// Parse a RRule string, return a RRuleSet objectrrulestr('DTSTART:20120201T023000Z\nRRULE:FREQ=MONTHLY;COUNT=5',{forceset:true,})// Parse a RRuleSet string, return a RRuleSet objectrrulestr('DTSTART:20120201T023000Z\nRRULE:FREQ=MONTHLY;COUNT=5\nRDATE:20120701T023000Z,20120702T023000Z\nEXRULE:FREQ=MONTHLY;COUNT=2\nEXDATE:20120601T023000Z')

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 providestimezone 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 provideddatetime() helper, whichcreates dates in the correct format using a 1-based month.

For example:

// local machine zone is America/Los_Angelesconstrule=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()// --> 1date.getUTCHours()// --> 18

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

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 seepython-dateutil documentation.

Rrule also supports use of theTZID parameter in theRFC using theIntl API.Support matrix for the Intl API applies. If you need to support additional environments,please consider using apolyfill.

Example withTZID:

newRRule({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 theTZID param, make sure to only use JSDate objects that arerepresented in UTC to avoid unexpected timezone offsets being applied, for example:

// WRONG: Will produce dates with TZ offsets addednewRRule({freq:RRule.MONTHLY,dtstart:newDate(2018,1,1,10,30),until:newDate(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 timenewRRule({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')]

newRRule(options[,noCache=false])

Theoptions argument mostly corresponds to the properties defined forRRULE in theiCalendar RFC. Onlyfreq is required.

noCache: Set totrue to disable caching of results. If you will use thesame rrule instance multiple times, enabling caching will improve theperformance considerably. Enabled by default.

See alsopython-dateutildocumentation.

rule.options

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

rule.origOptions

The originaloptions argument passed to the constructor.

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

As rules withoutuntil orcount represent infinite date series, youcan optionally passiterator, which is a function that is called foreach date matched by the rule. It gets two parametersdate (theDateinstance being added), andi (zero-indexed position ofdate in theresult). Dates are being added to the result as long as the iteratorreturnstrue. If afalse-y value is returned,date isn't added tothe result and the iteration is interrupted (possibly prematurely).

rule.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')]rule.all(function(date,i){returni<2})[('2012-02-01T10:30:00.000Z','2012-05-01T10:30:00.000Z')]

Returns all the occurrences of the rrule betweenafter andbefore.Theinc keyword defines what happens ifafter and/orbefore arethemselves occurrences. Withinc == true, they will be included in thelist, if they are found in the recurrence set.

Optionaliterator has the same function as it has withRRule.prototype.all().

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

Returns the last recurrence before the givenDate instance. Theincargument defines what happens ifdt is an occurrence. Withinc == true, ifdt itself is an occurrence, it will be returned.

Returns the first recurrenceafter the givenDate instance. Theinc argument defines what happensifdt is an occurrence. Withinc == true, ifdt itself is anoccurrence, it will be returned.

See alsopython-dateutildocumentation.

Returns a string representation of the rule as per the iCalendar RFC.Only properties explicitly specified inoptions are included:

rule.toString();('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;INTERVAL=5;UNTIL=20130130T230000Z;BYDAY=MO,FR')rule.toString()==RRule.optionsToString(rule.origOptions)true

Convertsoptions to iCalendar RFCRRULE string:

// Get full a string representation of all options,// including the default and inferred ones.RRule.optionsToString(rule.options);('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;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,});('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;')

Constructs anRRule instance from a completerfcString:

varrule=RRule.fromString('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;')// This is equivalentvarrule=newRRule(RRule.parseString('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY'))

Only parse RFC string and returnoptions.

varoptions=RRule.parseString('FREQ=DAILY;INTERVAL=6')options.dtstart=datetime(2000,2,1)varrule=newRRule(options)

These methods provide an incomplete support for text→RRule andRRule→text conversion. You should test them with your input to seewhether the result is acceptable.

Returns a textual representation ofrule. Thegettext callback, ifprovided, will be called for each text token and its return value usedinstead. The optionallanguage argument is a language definition to beused (defaults torrule/nlp.js:ENGLISH).

varrule=newRRule({freq:RRule.WEEKLY,count:23,})rule.toText();('every week for 23 times')

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

Constructs anRRule instance fromtext.

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

Parsetext intooptions:

options=RRule.parseText('every day for 3 times')// {freq: 3, count: "3"}options.dtstart=datetime(2000,2,1)varrule=newRRule(options)

newRRuleSet([(noCache=false)])

TheRRuleSet instance allows more complex recurrence setups, mixing multiplerules, dates, exclusion rules, and exclusion dates.

DefaultnoCache argument isfalse, caching of results will be enabled,improving performance of multiple queries considerably.

Include the givenrrule instance in the recurrence set generation.

Include the given datetime instancedt in the recurrence set generation.

Include the givenrrule instance in the recurrence set exclusion list. Dateswhich are part of the given recurrence rules will not be generated, even ifsome inclusive rrule or rdate matches them.NOTE:EXRULE has been (deprecatedin RFC 5545)[https://icalendar.org/iCalendar-RFC-5545/a-3-deprecated-features.html]and does not support aDTSTART property.

Include the given datetime instancedt in the recurrence set exclusion list. Datesincluded that way will not be generated, even if some inclusiverrule orrdate matches them.

Sets or overrides the timezone identifier. Useful if there are no rrules in thisRRuleSet and thus noDTSTART.

Same asRRule.prototype.all.

Same asRRule.prototype.between.

Same asRRule.prototype.before.

Same asRRule.prototype.after.

Get list of included rrules in this recurrence set.

Get list of excluded rrules in this recurrence set.

Get list of included datetimes in this recurrence set.

Get list of excluded datetimes in this recurrence set.

rrulestr(rruleStr[,options])

Therrulestr function is a parser for RFC-like syntaxes. The string passedas parameter may be a multiple line string, a single line string, or just theRRULE property value.

Additionally, it accepts the following keyword arguments:

cache

Iftrue, therruleset orrrule created instance will cache its results.Default is not to cache.

dtstart

If given, it must be a datetime instance that will be used when noDTSTART property is found in the parsed string. If it is not given, and the property is not found,datetime.now() will be used instead.

unfold

If set totrue, lines will be unfolded following the RFC specification. It defaults tofalse, meaning that spaces before every line will be stripped.

forceset

If set totrue, anrruleset instance will be returned, even if only a single rule is found. The default is to return anrrule if possible, and anrruleset if necessary.

compatible

If set totrue, the parser will operate in RFC-compatible mode. Right now it means that unfold will be turned on, and if aDTSTART is found, it will be considered the first recurrence instance, as documented in the RFC.

tzid

If given, it must be a string that will be used when noTZID property is found in the parsed string. If it is not given, and the property is not found,'UTC' will be used by default.

• RRule has nobyday keyword. The equivalent keyword has been replaced bythebyweekday keyword, to remove the ambiguity present in the originalkeyword.
• Unlike documented in the RFC, the starting datetime,dtstart, isnot the first recurrence instance, unless it does fit in the specified rules.This is in part due to this project being a port ofpython-dateutil,which has the same non-compliant functionality. Note that you can get theoriginal behavior by using aRRuleSet and adding thedtstart as anrdate.

varrruleSet=newRRuleSet()varstart=datetime(2012,2,1,10,30)// Add a rrule to rruleSetrruleSet.rrule(newRRule({freq:RRule.MONTHLY,count:5,dtstart:start,}))// Add a date to rruleSetrruleSet.rdate(start)

• Unlike documented in the RFC, every keyword is valid on every frequency. (TheRFC documents thatbyweekno is only valid on yearly frequencies, for example.)

rrule.js is implemented in Typescript. It usesJavaScript Standard Style coding style.

To run the code, checkout this repository and run:

$ yarn

To run the tests, run:

$ yarn test

To build files for distribution, run:

$ yarn build

• Jakub Roztocil(@jkbrzt)
• Lars Schöning (@lyschoening)
• David Golightly (@davigoli)

Pythondateutil is written byGustavoNiemeyer.

SeeLICENCE formore details.

• https://rrules.com — RESTful API to get back occurrences of RRULEs that conform to RFC 5545.