Skip to content

About

Temporal-first recurrence API for rules, composed schedules, and RFC 5545 parsing.

Topics

Resources

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

rrule.net

@rrulenet/recurrence

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

npm version JSR version Coverage MIT License

@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.

Install

npm install @rrulenet/recurrence

Requires 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.

Getting started

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',
});

Choose the temporal intention

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.

Compose schedules

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/Paris

The same constructors can be used in a canonical include/exclude object. See the API reference for constructor shapes and composition examples.

Query occurrences

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.

Persist and interchange

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.

Validation and errors

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.

About

Temporal-first recurrence API for rules, composed schedules, and RFC 5545 parsing.

Topics

Resources

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages