A JavaScript / TypeScript library for working with recurrence rules for calendar dates, as defined in the iCalendar RFC (RFC 5545). A partial port of the rrule module from python-dateutil, with parsing and serialization to and from natural language on top.
- RFC 5545 recurrence rules — parse, serialize, and iterate
RRULEstrings and option objects RRuleSet— combine multipleRRULE,RDATE,EXRULE, andEXDATEentries into a single recurrence set- Occurrence retrieval —
.all(),.between(),.before(),.after(), with optional iterator-based early termination - Natural-language text —
toText()/fromText()for human-friendly rule descriptions - Timezone support —
TZIDparameter handling via the Intl API - Validation —
validate()returns a structured result without throwing - Result caching — enabled by default; configurable via
noCache - Bundled TypeScript types — works out of the box in TS projects
- Requirements
- Installation
- Quick Start
- Important: Use UTC dates
- Timezone Support
- API
- Differences From iCalendar RFC
- Demo App
- Authors
- Contributing
- Security
- License
- Node 20.19+
bun i @offload-project/rrule
# or
npm install @offload-project/rruleTypeScript types are bundled — no separate @types install needed.
import { datetime, RRule, RRuleSet, rrulestr, validate } from '@offload-project/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 December 31, 2012, starting February 1, 2012"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 an exclusion rrule to rruleSet
rruleSet.exrule(
new RRule({
freq: RRule.MONTHLY,
count: 2,
dtstart: datetime(2012, 3, 1, 10, 30),
})
)
// Add an 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\nRRULE:FREQ=MONTHLY;COUNT=5\nRDATE:20120701T023000Z,20120702T023000Z\nEXRULE:FREQ=MONTHLY;COUNT=2\nEXDATE:20120601T023000Z"// 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'
)import { validate } from '@offload-project/rrule'
// Check if a string is a valid rule or ruleset
validate('RRULE:FREQ=WEEKLY;COUNT=3')
// { valid: true }
validate('RRULE:FREQ=BOGUS')
// { valid: false, error: { message: 'Invalid frequency: ...', cause: Error } }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 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() // --> 18If 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 shiftFor more examples see python-dateutil documentation.
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']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:
|
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.
IMPORTANT: See the discussion under timezone support
|
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.
|
tzid |
If given, this must be a IANA string recognized by the Intl API. See discussion under Timezone support. |
bysetpos |
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 bysetpos of -1 if combined with a RRule.MONTHLY
frequency, and a byweekday of (RRule.MO, RRule.TU, RRule.WE,
RRule.TH, RRule.FR), will result in the last work day of every month.
|
bymonth |
If given, it must be either an integer, or an array of integers, meaning the months to apply the recurrence to. |
bymonthday |
If given, it must be either an integer, or an array of integers, meaning the month days to apply the recurrence to. |
byyearday |
If given, it must be either an integer, or an array of integers, meaning the year days to apply the recurrence to. |
byweekno |
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. |
byweekday |
If given, it must be either an integer (0 == RRule.MO), an array of integers, one of the
weekday constants (RRule.MO, RRule.TU, 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 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 an array of integers, meaning the hours to apply the recurrence to. |
byminute |
If given, it must be either an integer, or an array of integers, meaning the minutes to apply the recurrence to. |
bysecond |
If given, it must be either an integer, or an array of integers, meaning the seconds to apply the recurrence to. |
byeaster |
This is an extension to the RFC specification which the Python implementation provides. The value is a
number of days relative to Easter Sunday. For example, byeaster: 0 is Easter itself,
byeaster: 1 is the day after Easter, and byeaster: -2 is Good Friday.
|
noCache: Set to true to disable caching of results. If you use the same rrule instance multiple times, enabling
caching will improve the performance considerably. Enabled by default.
See also python-dateutil documentation.
rule.options-
Processed options applied to the rule. Includes default options (such as
wkst). Currently,rule.options.byweekdayisn't equal torule.origOptions.byweekday(which is an inconsistency). rule.origOptions-
The original
optionsargument passed to the constructor.
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()
[
'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((date, i) => i < 2)
['2012-02-01T10:30:00.000Z', '2012-05-01T10:30:00.000Z']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(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 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.
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.
Returns a string representation of the rule as per the iCalendar RFC.
Only properties explicitly specified in options are included:
rule.toString()
// "DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;INTERVAL=5;UNTIL=20130130T230000Z;BYDAY=MO,FR"
rule.toString() == RRule.optionsToString(rule.origOptions)
// trueConverts options to iCalendar RFC RRULE string:
// Get a full 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 an RRule instance from a complete rfcString:
const rule = RRule.fromString('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY;')
// This is equivalent
const rule = new RRule(
RRule.parseString('DTSTART:20120201T093000Z\nRRULE:FREQ=WEEKLY')
)Only parse RFC string and return options.
const options = RRule.parseString('FREQ=DAILY;INTERVAL=6')
options.dtstart = datetime(2000, 2, 1)
const rule = new RRule(options)These methods provide an incomplete support for text-to-RRule and RRule-to-text conversion. You should test them
with your input to see whether the result is acceptable.
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
ENGLISH). The optional dateFormatter callback controls how dates (for until and starting clauses) are formatted.
If dtstart is explicitly set in the rule options, it will be included as a ", starting [date]" suffix in the output.
const rule = new RRule({
freq: RRule.WEEKLY,
count: 23,
})
rule.toText()
// "every week for 23 times"
const rule2 = new RRule({
freq: RRule.MONTHLY,
bymonthday: 15,
interval: 2,
dtstart: datetime(2026, 2, 18),
})
rule2.toText()
// "every 2 months on the 15th, starting February 18, 2026"Provides a hint on whether all the options the rule has can be converted to text.
Constructs an RRule instance from text.
const rule = RRule.fromText('every day for 3 times')Parse text into options:
const options = RRule.parseText('every day for 3 times')
// {freq: 3, count: "3"}
options.dtstart = datetime(2000, 2, 1)
const rule = new RRule(options)new RRuleSet([(noCache = false)])The RRuleSet instance allows more complex recurrence setups, mixing multiple rules, dates, exclusion rules, and
exclusion dates.
Default noCache argument is false, caching of results will be enabled, improving performance of multiple queries
considerably.
Include the given rrule instance in the recurrence set generation.
Include the given datetime instance dt in the recurrence set generation.
Include the given rrule instance in the recurrence set exclusion list. Dates which are part of the given recurrence
rules will not be generated, even if some inclusive rrule or rdate matches them.
NOTE: EXRULE has been deprecated in RFC 5545
and does not support a DTSTART property.
Include the given datetime instance dt in the recurrence set exclusion list. Dates included that way will not be
generated, even if some inclusive rrule or rdate matches them.
Sets or gets the start date for the recurrence set.
Sets or gets the timezone identifier. Useful if there are no rrules in this RRuleSet and thus no DTSTART.
Same as RRule.prototype.all.
Same as RRule.prototype.between.
Same as RRule.prototype.before.
Same as RRule.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])The rrulestr function is a parser for RFC-like syntaxes. The string passed as parameter may be a multiple line string,
a single line string, or just the RRULE property value.
Additionally, it accepts the following keyword arguments:
cache-
If
true, therrulesetorrrulecreated instance will cache its results. Default is not to cache. dtstart-
If given, it must be a datetime instance that will be used when no
DTSTARTproperty 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 to
true, lines will be unfolded following the RFC specification. It defaults tofalse, meaning that spaces before every line will be stripped. forceset-
If set to
true, anrrulesetinstance will be returned, even if only a single rule is found. The default is to return anrruleif possible, and anrrulesetif necessary. compatible-
If set to
true, the parser will operate in RFC-compatible mode. Right now it means that unfold will be turned on, and if aDTSTARTis 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 no
TZIDproperty is found in the parsed string. If it is not given, and the property is not found,'UTC'will be used by default.
validate(rruleStr[, options])Validates an RRULE or RRuleSet string without throwing. Accepts the same string formats and options as rrulestr.
Returns a ValidationResult:
import { validate } from '@offload-project/rrule'
// Valid single rule
validate('RRULE:FREQ=WEEKLY;COUNT=3')
// { valid: true }
// Valid ruleset string
validate(
'DTSTART:19970902T090000Z\n' +
'RRULE:FREQ=YEARLY;COUNT=6;BYDAY=TU,TH\n' +
'EXDATE:19970911T090000Z'
)
// { valid: true }
// Invalid input
validate('RRULE:FREQ=BOGUS')
// { valid: false, error: { message: 'Invalid frequency: ...', cause: Error } }
// With options (same as rrulestr options)
validate('RRULE:FREQ=DAILY', { dtstart: new Date('1997-09-02T09:00:00Z') })
// { valid: true }The result type is a discriminated union:
interface ValidationSuccess {
valid: true
}
interface ValidationError {
valid: false
error: {
message: string // Human-readable error description
cause?: Error // Original error object with stack trace
}
}
type ValidationResult = ValidationSuccess | ValidationErrorRRulehas nobydaykeyword. The equivalent keyword has been replaced by thebyweekdaykeyword, to remove the ambiguity present in the original keyword.- Unlike documented in the RFC, the starting datetime,
dtstart, is not the first recurrence instance, unless it does fit in the specified rules. This is in part due to this project being a port of python-dateutil, which has the same non-compliant functionality. Note that you can get the original behavior by using aRRuleSetand adding thedtstartas anrdate.
const rruleSet = new RRuleSet()
const start = datetime(2012, 2, 1, 10, 30)
// Add a rrule to rruleSet
rruleSet.rrule(
new RRule({
freq: RRule.MONTHLY,
count: 5,
dtstart: start,
})
)
// Add a date to rruleSet
rruleSet.rdate(start)- Unlike documented in the RFC, every keyword is valid on every frequency. (The RFC documents that
byweeknois only valid on yearly frequencies, for example.)
- Shavonn Brown
- Jakub Roztocil (@jkbrzt)
- Lars Schöning (@lyschoening)
- David Golightly (@davigoli)
Python dateutil is written by Gustavo Niemeyer.
Contributions are welcome! Please see the documents below before getting started.
- Contributing Guide — setup, workflow, commit conventions, and PR process
- Code of Conduct — expectations for participation in this project
- Security Policy — how to report a vulnerability privately
BSD-3-Clause. Please see License File for more information.