rrule

You can install rrule for both client-side and server-side environments using yarn or npm. The package includes optional TypeScript types.

# Client Side
$ yarn add rrule

# Server Side
$ yarn add rrule
# or
$ npm install rrule

To avoid unexpected timezone offsets, it is highly recommended to use UTC timestamps (e.g., new Date(Date.UTC(...))) or the provided datetime() helper.

RRule returns dates with zero offset (as if they were UTC), but they are intended to be interpreted as local times. If you need true UTC conversion, consider using a library like Luxon to convert the returned JS Date objects.

// RECOMMENDED: Use datetime() helper to avoid offset issues
new RRule({
  freq: RRule.MONTHLY,
  dtstart: datetime(2018, 2, 1, 10, 30),
  until: datetime(2018, 3, 31),
}).all()

// WRONG: Using standard Date constructor may add unwanted offsets
new RRule({
  freq: RRule.MONTHLY,
  dtstart: new Date(2018, 1, 1, 10, 30),
  until: new Date(2018, 2, 31),
})

You can specify a timezone using the tzid option in the RRule constructor. This requires an IANA string recognized by the Intl API.

new RRule({
  dtstart: datetime(2018, 2, 1, 10, 30),
  count: 1,
  tzid: 'Asia/Tokyo',
}).all()

Convert an RRule instance into different string formats:

• toString(): Returns an iCalendar RFC compliant string (e.g., DTSTART:...\nRRULE:...).
• toText([gettext, [language]]): Returns a human-friendly natural language string (e.g., "every 5 weeks on Monday, Friday").

Use the RRule constructor to define a recurrence rule based on iCalendar RFC 5545. You must provide a freq (frequency). Other common options include interval, byweekday, dtstart, and until.

import { datetime, RRule } from 'rrule'

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)
})

Once an RRule instance is created, you can retrieve occurrences using several methods:

• all([iterator]): Returns all matching dates. The optional iterator is a function (date, i) => boolean used to limit results.
• between(after, before, inc=false [, iterator]): Returns occurrences within a specific range. inc determines if the boundary dates are included.
• before(dt, inc=false): Returns the last occurrence before the given date.
• after(dt, inc=false): Returns the first occurrence after the given date.

The rrulestr(rruleStr, options) function accepts several configuration keys:

• cache: Boolean. If true, the resulting instance will cache results. Default is false.
• dtstart: A datetime instance to use if no DTSTART is found in the string. Defaults to datetime.now().
• unfold: Boolean. If true, lines will be unfolded following RFC spec. Default is false.
• forceset: Boolean. If true, always returns an RRuleSet instance. Default is to return RRule if possible.
• compatible: Boolean. If true, operates in RFC-compatible mode (enables unfold and treats DTSTART as the first instance).
• tzid: A string for the timezone identifier to use if no TZID is found. Defaults to 'UTC'.

Use ToText.isFullyConvertible(rrule) or the instance method toText.isFullyConvertible() to determine if an RRule can be converted to a complete natural language string without approximation.

An RRule is considered fully convertible if its frequency is supported and it does not contain a combination of until and count options, or other unsupported configuration keys.

The ToText class allows you to convert an RRule instance into a human-readable string (e.g., "every 2 weeks on Monday").

Note that not all RRule options are supported for conversion. If an RRule contains unsupported options, the resulting string will be appended with (~ approximate).

Constructor Parameters

• rrule: The RRule instance to convert.
• gettext (optional): A function (id: string | number | Weekday) => string used for translating identifiers.
• language (optional): A Language object (defaults to ENGLISH).
• dateFormatter (optional): A function (year: number, month: string, day: number) => string to format dates.