simple-rrule.js

Simple recurrence rules to get scheduler events for calendar dates.

simple-rrule.js expands recurrence dates from a rrule string.

rules as defined in the iCalendar RFC (with partial implementation)

---

---

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

Includes optional TypeScript types

$ yarn add simple-rrule
# or
$ npm install simple-rrule

Example 1

import { expandRRuleFromString } from 'simple-rrule'

const rRule =
    'DTSTART:20221215T100000Z\nRRULE:FREQ=YEARLY;BYDAY=MO;BYMONTH=1;BYSETPOS=2;COUNT=5;WKST=SU'
const rRule = `DTSTART:DTSTART:20221215T100000Z\nRRULE:FREQ=DAILY;INTERVAL=1;COUNT=3;WKST=SU`

const r = expandRRuleFromString(rRule, today, addDays(today, 3))

Example 2

import { parseRecurrenceFromString, expandRRule, WeekDay } from 'simple-rrule'
const rRule =
    'DTSTART:20221216T100000Z\nRRULE:FREQ=MONTHLY;INTERVAL=1;BYSETPOS=2;BYDAY=WE;UNTIL=20230411T100000Z;WKST=SU'

const rRule = await parseRecurrenceFromString(rRule, Weekday.Sunday)
console.log(rRule)

const r = expandRRule(
    rRule,
    new Date('2023-02-02T10:00:00.000Z'),
    new Date('2023-12-31T10:00:00.000Z')
)

Example 3

import { expandRRuleFromString } from 'simple-rrule'

const rRule =
    'DTSTART:20221215T100000Z\nRRULE:FREQ=YEARLY;BYDAY=MO;BYMONTH=1;BYSETPOS=2;COUNT=5;WKST=SU'

const r = expandRRuleFromString(
    rRule,
    new Date('2023-01-28T10:00:00.000Z'),
    new Date('2025-05-31T10:00:00.000Z')
)

Example 4

import { expandRRuleFromString } from 'simple-rrule'

const rRule =
    'DTSTART:20221215T100000Z\nRRULE:FREQ=YEARLY;BYDAY=MO;BYMONTH=1;BYSETPOS=2;COUNT=5;WKST=SU'

const r = expandRRuleFromString(
    rRule,
    new Date('2023-01-28T10:00:00.000Z'),
    new Date('2025-05-31T10:00:00.000Z')
)

Good examples in 'test' folder.

rrule string fields

Field	Type	Required	Default	Description
dtStart	Date	Y		The recurrence start.
dtEnd	Date	Y		Used for duration (dtStart-dtEnd)
frequency	Frequency as String	Y		Frequency.YEARLY Frequency.MONTHLY Frequency.WEEKLY Frequency.DAILY Frequency.HOURLY Frequency.MINUTELY Frequency.SECONDLY
interval	Positive Integer	Y	1	The interval between each freq iteration
wkst	Weekday as String	Y	'SU'	The week start day.
count	Positive Integer	N		How many occurrences will be generated.
until	Date	N		End limit of recurrence dates generated.
byday	WeekDay[] as String	N		Weekday or WeekDays ex: 'SU' or 'SU,MO,FR'
bysetpos	Integer	N		Used only in byMonth and byYear
bymonth	Integer	N		Month
bymonthday	Integer	N		Month day

---