Temporal-first recurrence API for rules, composed schedules, and RFC 5545 parsing.
rrule.net • Temporal API • @rrulenet ecosystem
@rrulenet/rrule ·
@rrulenet/recurrence ·
@rrulenet/core ·
@rrulenet/cli
@rrulenet/rrule: classic API · @rrulenet/recurrence: Temporal-first API · @rrulenet/core: engine · @rrulenet/cli: workflows
@rrulenet/recurrence models rules, explicit dates and composed schedules with
one public type: Recurrence. It accepts Date and Temporal inputs, returns
Temporal occurrences, and supports RFC 5545 parsing and native JSON persistence.
Use it to embed recurrence logic in an application. For the classic
rrule.js-style API, see @rrulenet/rrule.
npm install @rrulenet/recurrenceRequires Node.js 20 or later when used with Node. The library uses native
Temporal where available and the included polyfill otherwise. Inputs can use
native Temporal, temporal-polyfill, or @js-temporal/polyfill values.
import { Recurrence } from '@rrulenet/recurrence';
const recurrence = Recurrence.rule({
freq: 'WEEKLY',
byDay: ['MO', 'WE', 'FR'],
byHour: [9],
start: new Date('2026-01-05T08:00:00Z'),
tzid: 'Europe/Paris',
});
console.log(recurrence.take(3).map((value) => value.toString()));
// [
// '2026-01-05T09:00:00+01:00[Europe/Paris]',
// '2026-01-07T09:00:00+01:00[Europe/Paris]',
// '2026-01-09T09:00:00+01:00[Europe/Paris]'
// ]To parse an RFC-style string:
const parsed = Recurrence.parse({
rruleString: 'DTSTART:20260105T080000Z\nRRULE:FREQ=DAILY;COUNT=3',
});| Constructor | Meaning |
|---|---|
Recurrence.rule() / Recurrence.parse() |
Follow calendar dates and local clock values |
Recurrence.elapsed() |
Repeat a fixed duration from an exact anchor |
Recurrence.dates() |
Preserve explicit instants |
For example, an hourly elapsed cadence crosses both passages of an autumn overlap:
const cadence = Recurrence.elapsed({
start: new Date('2026-10-24T23:30:00Z'),
every: 'PT1H',
tzid: 'Europe/Paris',
count: 4,
});Elapsed steps must be positive whole-second ISO time durations, such as PT30M
or PT1H; calendar units such as P1D are rejected. The timezone controls
presentation without moving the elapsed grid.
Calendar rules use the first passage of an ambiguous autumn time and the pre-transition offset for a spring gap. Later periods keep their nominal clock time. COUNT and UNTIL are mutually exclusive; COUNT applies before explicit dates and exclusions. Explicit dates retain their exact instants.
Combine recurrences with union(), intersection() and difference(), or add
exceptions with includingDates() and excludingDates():
const schedule = recurrence.excludingDates([
new Date('2026-01-07T08:00:00Z'),
]);
console.log(schedule.take(3).map((value) => value.toString()));
// 5, 9 and 12 January at 09:00 in Europe/ParisThe same constructors can be used in a canonical include/exclude object.
See the API reference
for constructor shapes and composition examples.
| Method | Result |
|---|---|
take(count) / takeAfter(date, count) |
A requested number of occurrences |
between(after, before, inc?) |
Occurrences within a bounded range |
after(date, inc?) / before(date, inc?) |
One occurrence, or null |
first() |
The first occurrence, or null |
occursAt(date) / hasAnyBetween(...) |
Membership or presence checks |
all(callback?) |
Values up to completion, a preview limit, or callback stop |
Occurrence queries return Temporal.ZonedDateTime values. Bounds are exclusive
unless inc is true. For an open-ended recurrence, all() without a callback
returns a finite preview of up to 513 values; count() without a limit counts
that preview. Prefer explicit bounds for application queries.
A query that exhausts its search budget throws an error with code
RECURRENCE_SEARCH_LIMIT; it does not establish that the schedule is empty.
const saved = schedule.toJSON();
const restored = Recurrence.fromJSON(saved);Native JSON preserves calendar, elapsed and exact-date expressions, including
algebraic compositions. It carries temporalVersion: 2; leave this field intact.
Use isJSON() or validateJSON() to check received definitions before loading.
Legacy unversioned rule JSON requires an explicit adoption choice, described in
the JSON reference.
toString() exports RFC-compatible lines when the expression can be represented
without losing meaning. Otherwise it throws TEMPORAL_UNSERIALIZABLE_EXPRESSION.
Use toText() for a natural-language description.
Invalid date/time selectors throw a RangeError. API input errors expose a
stable code through TemporalApiError. Search-limit errors must be handled
separately from validation failures and empty results. The
API reference
lists the public error codes and validation methods.