Recurrence

RFC 5545 compliant RRULE engine. Parse, generate, and evaluate recurring event rules.

Install  ·  Quick Start  ·  Rules  ·  Releases

---

Recurrence is a zero-dependency library that fully implements the RFC 5545 recurrence rule specification (RRULE). It parses human-readable rules into structured objects, generates occurrence dates, and handles every edge case the standard defines -- including complex combinations, exceptions (EXDATE), and additions (RDATE).

Why another RRULE library?

Most RRULE implementations in JavaScript are incomplete. They miss edge cases, fail on complex rule combinations, or produce incorrect results around month and year boundaries. Recurrence is different:

• 100% RFC 5545 compliant -- Every rule, every frequency, every edge case.
• Validated against 1,200+ test vectors -- Including the official iCalendar test suite.
• Zero dependencies -- 4.8 kB gzipped.
• Works in any environment -- Node.js, Deno, Bun, browsers.
• Streaming API -- Generate millions of occurrences without memory issues.

---

Installation

npm install recurrence

Quick Start

import { RRule, Frequency } from "recurrence";

// Every Monday, Wednesday, and Friday
const rule = new RRule({
  frequency: Frequency.WEEKLY,
  byDay: ["MO", "WE", "FR"],
  startDate: "2025-01-06",
});

rule.occurrences({ take: 6 });
// ["2025-01-06", "2025-01-08", "2025-01-10", "2025-01-13", ...]

// Every last Friday of the month
const payday = new RRule({
  frequency: Frequency.MONTHLY,
  byDay: ["-1FR"],
});

// Complex: Every 2 weeks on Tuesday and Thursday, excluding holidays
const complex = new RRule({
  frequency: Frequency.WEEKLY,
  interval: 2,
  byDay: ["TU", "TH"],
  exceptDates: ["2025-12-25", "2026-01-01"],
});

// Streaming: iterate without memory overhead
for await (const date of rule.stream()) {
  console.log(date);
}

---

Supported Rules

Frequency	Supported	Notes
SECONDLY	Yes
MINUTELY	Yes
HOURLY	Yes
DAILY	Yes
WEEKLY	Yes	BYDAY, BYHOUR, BYMINUTE, BYSECOND
MONTHLY	Yes	BYMONTHDAY, BYDAY (pos/neg)
YEARLY	Yes	BYMONTH, BYWEEKNO, BYYEARDAY, BYDAY, BYMONTHDAY

Modifier	Supported
INTERVAL	Yes
COUNT	Yes
UNTIL	Yes
BYSETPOS	Yes
WKST	Yes
EXDATE	Yes
RDATE	Yes

---

Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

---

License

MIT

Open sourced by Kelender