calendaryjs-plugin-liturgicalv0.2.1

The General Roman Calendar for calendaryjs: Easter computus, movable feasts declared as offsets from Easter, ready-made presets for the major celebrations, a full-calendar generator (solemnities, feasts, memorials with ranks and vestment colors), and day enrichment (season, week, color for any date).

Install

npm i calendaryjs calendaryjs-plugin-liturgical

Quick start

Register the plugin, then declare easter and offset events — an offset is placed relative to Easter (negative = before, positive = after):

import { calendary } from "calendaryjs";
import { liturgical } from "calendaryjs-plugin-liturgical";

const cal = calendary().use(liturgical());

cal.addGroup({
  id: "movable",
  events: [
    { type: "easter", id: "easter", title: "Easter Sunday" },
    { type: "offset", id: "ash-wednesday", baseEvent: "easter", offsetDays: -46, title: "Ash Wednesday" },
    { type: "offset", id: "pentecost", baseEvent: "easter", offsetDays: 49, title: "Pentecost" },
  ],
});

cal.getEventsInRange("2025-01-01", "2025-12-31");
// → Ash Wednesday 2025-03-05 · Easter 2025-04-20 · Pentecost 2025-06-08

An unknown baseEvent throws rather than silently producing nothing.

Presets — skip the offsets

The major celebrations ship pre-declared (correct offsets, titles, metadata):

import { EASTER, ASH_WEDNESDAY, PALM_SUNDAY, GOOD_FRIDAY, PENTECOST } from "calendaryjs-plugin-liturgical";

cal.addGroup({ id: "church", events: [EASTER, ASH_WEDNESDAY, PALM_SUNDAY, GOOD_FRIDAY, PENTECOST] });

Available: EASTER · ASH_WEDNESDAY · PALM_SUNDAY · HOLY_THURSDAY · GOOD_FRIDAY · HOLY_SATURDAY · ASCENSION · PENTECOST · TRINITY_SUNDAY · CORPUS_CHRISTI — or all at once as LITURGICAL_EVENTS.

The full calendar — generateLiturgicalEvents

For a complete liturgical calendar (easter cycle + solemnities + feasts + memorials, each carrying rank, season, and vestmentColor metadata), use the generator instead of hand-picking events:

import { generateLiturgicalEvents } from "calendaryjs-plugin-liturgical";

const { id, events } = generateLiturgicalEvents({
  range: { from: "2025-01-01", to: "2025-12-31" },
});
cal.addGroup({ id, events }); // ~170 events with full liturgical metadata

Options:

Option	Default	Meaning
range	required	{ from, to } window the events are generated for
includeCategories	["easter-cycle", "solemnities", "feasts", "memorials", "computed"]	Which event categories to include
epiphanyOnSunday	false	Epiphany on the Sunday of Jan 2–8 instead of fixed Jan 6
ascensionOnSunday	false	Ascension moved to the 7th Sunday of Easter (Easter + 42)
corpusChristiOnSunday	true	Corpus Christi on Sunday (Easter + 63) instead of Thursday
groupId	"liturgical-calendar"	The group id returned for addGroup
customResolver	—	Per-key overrides — localization, custom titles (see below)

Localization / customization — customResolver receives each event’s MassKey and returns partial overrides merged into the generated event:

const { id, events } = generateLiturgicalEvents({
  range: { from: "2025-01-01", to: "2025-12-31" },
  customResolver: key =>
    key === "EASTER" ? { title: "Chúa Nhật Phục Sinh", metadata: { localName: "Phục Sinh" } } : undefined,
});

createLiturgicalGenerator({ defaults }) returns a generator with preset options, for reuse across years.

Day enrichment — season, week, color

Enrichment is on by default (enrichDays: true): every day from getDay() / getDays() carries a liturgical object:

const day = cal.getDay("2025-12-25");
day.liturgical;
// → { season: "christmas", week: 1, rank: "solemnity", vestmentColor: "white" }

• season — advent · christmas · ordinary-time-1 · lent · easter · ordinary-time-2
• week — week number within the season
• rank — solemnity · feast · memorial · ordinary
• vestmentColor — white · green · red · violet · rose

Compute directly (no engine)

import {
  computeEaster,
  computeOrthodoxEaster,
  easterRelativeDate,
  getSeason,
  getLiturgicalDay,
  getLiturgicalYearChart,
} from "calendaryjs-plugin-liturgical";

computeEaster(2025); // → Date — Easter Sunday (2025-04-20)
computeOrthodoxEaster(2025); // → Date — Julian-computus Easter
easterRelativeDate(2025, 49); // → Date — Pentecost (Easter + 49)
getSeason("2025-12-25");
// → { season: "christmas", vestmentColor: "white", week: 1, liturgicalYear: 2026 }
getLiturgicalDay("2025-12-25"); // → full liturgical day (season, week, celebrations)
getLiturgicalYearChart(2025); // → the year's season segments (for a wheel/timeline UI)

Sunday-anchored formulas are exported too: getAdvent1–getAdvent4, getHolyFamily, getBaptismOfLord, getChristTheKing.

Reference

Plugin options — enrichDays?: boolean (default true) · epiphanyOnSunday?: boolean (default false).

Event types

Type	Fields	Meaning
easter	—	Easter Sunday of each year (Gregorian computus)
offset	baseEvent: "easter" · offsetDays: number	A date relative to Easter (negative = before)

Both accept every standard event property; generated events carry LiturgicalMetadata (season, rank, vestmentColor).

Key exports — liturgical() · presets (EASTER, PENTECOST, …, LITURGICAL_EVENTS) · generateLiturgicalEvents / createLiturgicalGenerator · computus (computeEaster, computeOrthodoxEaster, easterRelativeDate) · daily utils (getLiturgicalDay, getLiturgicalDaysInRange, getSeason, getLiturgicalYearChart, …) · event definitions (ALL_LITURGICAL_EVENTS, getEventsByCategory) and their MassKey types.