calendaryjs-plugin-liturgical 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1064 @@
+import { BaseEventProperties, CustomEventResolver, CustomEventConfig, EventConfig, CalendarDay, CalendaryPlugin, EventTypeHandler, EventText, DateString } from 'calendaryjs';
+
+/**
+ * MassKey - Unique identifier for each liturgical event
+ *
+ * These keys are used to:
+ * 1. Identify events uniquely across the system
+ * 2. Map to custom titles via Record<MassKey, string>
+ * 3. Reference events in queries and searches
+ *
+ * @example
+ * ```typescript
+ * const titles: Record<MassKey, string> = {
+ *   EASTER_SUNDAY: 'Easter Sunday',
+ *   CHRISTMAS: 'Christmas',
+ *   // ...
+ * };
+ * ```
+ */
+/**
+ * Easter Cycle events - dates calculated relative to Easter Sunday
+ */
+type EasterCycleKey = "EASTER_SUNDAY" | "ASH_WEDNESDAY" | "PALM_SUNDAY" | "HOLY_THURSDAY" | "GOOD_FRIDAY" | "HOLY_SATURDAY" | "DIVINE_MERCY_SUNDAY" | "ASCENSION" | "PENTECOST" | "TRINITY_SUNDAY" | "CORPUS_CHRISTI" | "SACRED_HEART" | "IMMACULATE_HEART";
+/**
+ * Fixed date solemnities - same date every year
+ */
+type FixedSolemnityKey = "MARY_MOTHER_OF_GOD" | "EPIPHANY" | "PRESENTATION" | "SAINT_JOSEPH" | "ANNUNCIATION" | "NATIVITY_OF_JOHN_BAPTIST" | "PETER_AND_PAUL" | "TRANSFIGURATION" | "ASSUMPTION" | "EXALTATION_OF_CROSS" | "ALL_SAINTS" | "ALL_SOULS" | "IMMACULATE_CONCEPTION" | "CHRISTMAS" | "HOLY_INNOCENTS" | "HOLY_FAMILY";
+/**
+ * Computed dates - calculated based on formulas (e.g., Advent Sundays)
+ */
+type ComputedKey = "ADVENT_1" | "ADVENT_2" | "ADVENT_3" | "ADVENT_4" | "BAPTISM_OF_LORD" | "CHRIST_THE_KING";
+/**
+ * Memorial saints - fixed date memorials and feasts of saints
+ */
+type MemorialSaintKey = "BASIL_GREGORY" | "ANTHONY_ABBOT" | "AGNES" | "FRANCIS_DE_SALES" | "TIMOTHY_TITUS" | "THOMAS_AQUINAS" | "JOHN_BOSCO" | "AGATHA" | "PAUL_MIKI" | "SCHOLASTICA" | "OUR_LADY_OF_LOURDES" | "CYRIL_METHODIUS" | "POLYCARP" | "PERPETUA_FELICITY" | "PATRICK" | "CYRIL_OF_JERUSALEM" | "MARTIN_I" | "ANSELM" | "GEORGE" | "ADALBERT" | "FIDELIS" | "LOUIS_GRIGNION" | "PETER_CHANEL" | "CATHERINE_OF_SIENA" | "PIUS_V" | "JOSEPH_WORKER" | "ATHANASIUS" | "NEREUS_ACHILLEUS" | "PANCRAS" | "OUR_LADY_OF_FATIMA" | "JOHN_I" | "BERNARDINE" | "PHILIP_NERI" | "AUGUSTINE_OF_CANTERBURY" | "JUSTIN" | "MARCELLINUS_PETER" | "CHARLES_LWANGA" | "BONIFACE" | "NORBERT" | "EPHREM" | "BARNABAS" | "ROMUALD" | "JOHN_FISHER_THOMAS_MORE" | "FIRST_MARTYRS_OF_ROME" | "THOMAS_APOSTLE" | "ELIZABETH_OF_PORTUGAL" | "MARIA_GORETTI" | "AUGUSTINE_ZHAO" | "BENEDICT" | "HENRY" | "CAMILLUS" | "BONAVENTURE" | "OUR_LADY_OF_MOUNT_CARMEL" | "APOLLINARIS" | "LAWRENCE_OF_BRINDISI" | "MARY_MAGDALENE" | "BRIDGET" | "SHARBEL" | "JAMES_APOSTLE" | "MARTHA" | "PETER_CHRYSOLOGUS" | "IGNATIUS_OF_LOYOLA" | "ALPHONSUS" | "JOHN_VIANNEY" | "DEDICATION_MARY_MAJOR" | "SIXTUS_II" | "CAJETAN" | "DOMINIC" | "LAWRENCE" | "CLARE" | "JANE_FRANCES" | "PONTIAN_HIPPOLYTUS" | "MAXIMILIAN_KOLBE" | "JOHN_EUDES" | "BERNARD" | "PIUS_X" | "QUEENSHIP_OF_MARY" | "BARTHOLOMEW" | "LOUIS_IX" | "JOSEPH_CALASANZ" | "MONICA" | "AUGUSTINE" | "PASSION_OF_JOHN_BAPTIST" | "GREGORY_THE_GREAT" | "BIRTH_OF_MARY" | "PETER_CLAVER" | "MOST_HOLY_NAME_OF_MARY" | "OUR_LADY_OF_SORROWS" | "CORNELIUS_CYPRIAN" | "ROBERT_BELLARMINE" | "JANUARIUS" | "MATTHEW" | "PADRE_PIO" | "COSMAS_DAMIAN" | "WENCESLAUS" | "LAWRENCE_RUIZ" | "ARCHANGELS" | "JEROME" | "THERESE_OF_LISIEUX" | "GUARDIAN_ANGELS" | "FRANCIS_OF_ASSISI" | "FAUSTINA" | "BRUNO" | "OUR_LADY_OF_ROSARY" | "DENIS" | "CALLISTUS_I" | "TERESA_OF_AVILA" | "HEDWIG" | "MARGARET_MARY" | "IGNATIUS_OF_ANTIOCH" | "LUKE" | "ISAAC_JOGUES" | "PAUL_OF_CROSS" | "JOHN_PAUL_II" | "JOHN_OF_CAPISTRANO" | "ANTHONY_MARY_CLARET" | "SIMON_JUDE" | "DEDICATION_LATERAN" | "LEO_THE_GREAT" | "MARTIN_OF_TOURS" | "JOSAPHAT" | "MARGARET_OF_SCOTLAND" | "GERTRUDE" | "ELIZABETH_OF_HUNGARY" | "DEDICATION_PETER_PAUL" | "PRESENTATION_OF_MARY" | "CLEMENT_I" | "COLUMBAN" | "CATHERINE_OF_ALEXANDRIA" | "ANDREW_APOSTLE" | "FRANCIS_XAVIER" | "LUCY" | "STEPHEN_FIRST_MARTYR" | "JOHN_APOSTLE";
+/**
+ * All liturgical event keys combined
+ */
+type MassKey = EasterCycleKey | FixedSolemnityKey | ComputedKey | MemorialSaintKey;
+/**
+ * Array of all Easter cycle keys for iteration
+ */
+declare const EASTER_CYCLE_KEYS: EasterCycleKey[];
+/**
+ * Array of all fixed solemnity keys for iteration
+ */
+declare const FIXED_SOLEMNITY_KEYS: FixedSolemnityKey[];
+/**
+ * Array of all computed keys for iteration
+ */
+declare const COMPUTED_KEYS: ComputedKey[];
+/**
+ * Array of all memorial saint keys for iteration
+ */
+declare const MEMORIAL_SAINT_KEYS: MemorialSaintKey[];
+/**
+ * Array of all mass keys for iteration
+ */
+declare const ALL_MASS_KEYS: MassKey[];
+/**
+ * MassKeys constant object for enum-like usage.
+ * Use this to reference keys in title formatters and translations.
+ *
+ * @example
+ * ```typescript
+ * import { MassKeys } from "calendaryjs-plugin-liturgical";
+ *
+ * const titles = {
+ *   [MassKeys.CHRISTMAS]: "Christmas",
+ *   [MassKeys.EASTER_SUNDAY]: "Easter Sunday",
+ * };
+ *
+ * // With titleFormatter
+ * generateLiturgicalEvents({
+ *   range: { from: "2025-01-01", to: "2025-12-31" },
+ *   titleFormatter: ({ key }) => titles[key] ?? key,
+ * });
+ * ```
+ */
+declare const MassKeys: {
+    readonly EASTER_SUNDAY: "EASTER_SUNDAY";
+    readonly ASH_WEDNESDAY: "ASH_WEDNESDAY";
+    readonly PALM_SUNDAY: "PALM_SUNDAY";
+    readonly HOLY_THURSDAY: "HOLY_THURSDAY";
+    readonly GOOD_FRIDAY: "GOOD_FRIDAY";
+    readonly HOLY_SATURDAY: "HOLY_SATURDAY";
+    readonly DIVINE_MERCY_SUNDAY: "DIVINE_MERCY_SUNDAY";
+    readonly ASCENSION: "ASCENSION";
+    readonly PENTECOST: "PENTECOST";
+    readonly TRINITY_SUNDAY: "TRINITY_SUNDAY";
+    readonly CORPUS_CHRISTI: "CORPUS_CHRISTI";
+    readonly SACRED_HEART: "SACRED_HEART";
+    readonly IMMACULATE_HEART: "IMMACULATE_HEART";
+    readonly MARY_MOTHER_OF_GOD: "MARY_MOTHER_OF_GOD";
+    readonly EPIPHANY: "EPIPHANY";
+    readonly PRESENTATION: "PRESENTATION";
+    readonly SAINT_JOSEPH: "SAINT_JOSEPH";
+    readonly ANNUNCIATION: "ANNUNCIATION";
+    readonly NATIVITY_OF_JOHN_BAPTIST: "NATIVITY_OF_JOHN_BAPTIST";
+    readonly PETER_AND_PAUL: "PETER_AND_PAUL";
+    readonly TRANSFIGURATION: "TRANSFIGURATION";
+    readonly ASSUMPTION: "ASSUMPTION";
+    readonly EXALTATION_OF_CROSS: "EXALTATION_OF_CROSS";
+    readonly ALL_SAINTS: "ALL_SAINTS";
+    readonly ALL_SOULS: "ALL_SOULS";
+    readonly IMMACULATE_CONCEPTION: "IMMACULATE_CONCEPTION";
+    readonly CHRISTMAS: "CHRISTMAS";
+    readonly HOLY_INNOCENTS: "HOLY_INNOCENTS";
+    readonly HOLY_FAMILY: "HOLY_FAMILY";
+    readonly ADVENT_1: "ADVENT_1";
+    readonly ADVENT_2: "ADVENT_2";
+    readonly ADVENT_3: "ADVENT_3";
+    readonly ADVENT_4: "ADVENT_4";
+    readonly BAPTISM_OF_LORD: "BAPTISM_OF_LORD";
+    readonly CHRIST_THE_KING: "CHRIST_THE_KING";
+    readonly BASIL_GREGORY: "BASIL_GREGORY";
+    readonly ANTHONY_ABBOT: "ANTHONY_ABBOT";
+    readonly AGNES: "AGNES";
+    readonly FRANCIS_DE_SALES: "FRANCIS_DE_SALES";
+    readonly TIMOTHY_TITUS: "TIMOTHY_TITUS";
+    readonly THOMAS_AQUINAS: "THOMAS_AQUINAS";
+    readonly JOHN_BOSCO: "JOHN_BOSCO";
+    readonly AGATHA: "AGATHA";
+    readonly PAUL_MIKI: "PAUL_MIKI";
+    readonly SCHOLASTICA: "SCHOLASTICA";
+    readonly OUR_LADY_OF_LOURDES: "OUR_LADY_OF_LOURDES";
+    readonly CYRIL_METHODIUS: "CYRIL_METHODIUS";
+    readonly POLYCARP: "POLYCARP";
+    readonly PERPETUA_FELICITY: "PERPETUA_FELICITY";
+    readonly PATRICK: "PATRICK";
+    readonly CYRIL_OF_JERUSALEM: "CYRIL_OF_JERUSALEM";
+    readonly MARTIN_I: "MARTIN_I";
+    readonly ANSELM: "ANSELM";
+    readonly GEORGE: "GEORGE";
+    readonly ADALBERT: "ADALBERT";
+    readonly FIDELIS: "FIDELIS";
+    readonly LOUIS_GRIGNION: "LOUIS_GRIGNION";
+    readonly PETER_CHANEL: "PETER_CHANEL";
+    readonly CATHERINE_OF_SIENA: "CATHERINE_OF_SIENA";
+    readonly PIUS_V: "PIUS_V";
+    readonly JOSEPH_WORKER: "JOSEPH_WORKER";
+    readonly ATHANASIUS: "ATHANASIUS";
+    readonly NEREUS_ACHILLEUS: "NEREUS_ACHILLEUS";
+    readonly PANCRAS: "PANCRAS";
+    readonly OUR_LADY_OF_FATIMA: "OUR_LADY_OF_FATIMA";
+    readonly JOHN_I: "JOHN_I";
+    readonly BERNARDINE: "BERNARDINE";
+    readonly PHILIP_NERI: "PHILIP_NERI";
+    readonly AUGUSTINE_OF_CANTERBURY: "AUGUSTINE_OF_CANTERBURY";
+    readonly JUSTIN: "JUSTIN";
+    readonly MARCELLINUS_PETER: "MARCELLINUS_PETER";
+    readonly CHARLES_LWANGA: "CHARLES_LWANGA";
+    readonly BONIFACE: "BONIFACE";
+    readonly NORBERT: "NORBERT";
+    readonly EPHREM: "EPHREM";
+    readonly BARNABAS: "BARNABAS";
+    readonly ROMUALD: "ROMUALD";
+    readonly JOHN_FISHER_THOMAS_MORE: "JOHN_FISHER_THOMAS_MORE";
+    readonly FIRST_MARTYRS_OF_ROME: "FIRST_MARTYRS_OF_ROME";
+    readonly THOMAS_APOSTLE: "THOMAS_APOSTLE";
+    readonly ELIZABETH_OF_PORTUGAL: "ELIZABETH_OF_PORTUGAL";
+    readonly MARIA_GORETTI: "MARIA_GORETTI";
+    readonly AUGUSTINE_ZHAO: "AUGUSTINE_ZHAO";
+    readonly BENEDICT: "BENEDICT";
+    readonly HENRY: "HENRY";
+    readonly CAMILLUS: "CAMILLUS";
+    readonly BONAVENTURE: "BONAVENTURE";
+    readonly OUR_LADY_OF_MOUNT_CARMEL: "OUR_LADY_OF_MOUNT_CARMEL";
+    readonly APOLLINARIS: "APOLLINARIS";
+    readonly LAWRENCE_OF_BRINDISI: "LAWRENCE_OF_BRINDISI";
+    readonly MARY_MAGDALENE: "MARY_MAGDALENE";
+    readonly BRIDGET: "BRIDGET";
+    readonly SHARBEL: "SHARBEL";
+    readonly JAMES_APOSTLE: "JAMES_APOSTLE";
+    readonly MARTHA: "MARTHA";
+    readonly PETER_CHRYSOLOGUS: "PETER_CHRYSOLOGUS";
+    readonly IGNATIUS_OF_LOYOLA: "IGNATIUS_OF_LOYOLA";
+    readonly ALPHONSUS: "ALPHONSUS";
+    readonly JOHN_VIANNEY: "JOHN_VIANNEY";
+    readonly DEDICATION_MARY_MAJOR: "DEDICATION_MARY_MAJOR";
+    readonly SIXTUS_II: "SIXTUS_II";
+    readonly CAJETAN: "CAJETAN";
+    readonly DOMINIC: "DOMINIC";
+    readonly LAWRENCE: "LAWRENCE";
+    readonly CLARE: "CLARE";
+    readonly JANE_FRANCES: "JANE_FRANCES";
+    readonly PONTIAN_HIPPOLYTUS: "PONTIAN_HIPPOLYTUS";
+    readonly MAXIMILIAN_KOLBE: "MAXIMILIAN_KOLBE";
+    readonly JOHN_EUDES: "JOHN_EUDES";
+    readonly BERNARD: "BERNARD";
+    readonly PIUS_X: "PIUS_X";
+    readonly QUEENSHIP_OF_MARY: "QUEENSHIP_OF_MARY";
+    readonly BARTHOLOMEW: "BARTHOLOMEW";
+    readonly LOUIS_IX: "LOUIS_IX";
+    readonly JOSEPH_CALASANZ: "JOSEPH_CALASANZ";
+    readonly MONICA: "MONICA";
+    readonly AUGUSTINE: "AUGUSTINE";
+    readonly PASSION_OF_JOHN_BAPTIST: "PASSION_OF_JOHN_BAPTIST";
+    readonly GREGORY_THE_GREAT: "GREGORY_THE_GREAT";
+    readonly BIRTH_OF_MARY: "BIRTH_OF_MARY";
+    readonly PETER_CLAVER: "PETER_CLAVER";
+    readonly MOST_HOLY_NAME_OF_MARY: "MOST_HOLY_NAME_OF_MARY";
+    readonly OUR_LADY_OF_SORROWS: "OUR_LADY_OF_SORROWS";
+    readonly CORNELIUS_CYPRIAN: "CORNELIUS_CYPRIAN";
+    readonly ROBERT_BELLARMINE: "ROBERT_BELLARMINE";
+    readonly JANUARIUS: "JANUARIUS";
+    readonly MATTHEW: "MATTHEW";
+    readonly PADRE_PIO: "PADRE_PIO";
+    readonly COSMAS_DAMIAN: "COSMAS_DAMIAN";
+    readonly WENCESLAUS: "WENCESLAUS";
+    readonly LAWRENCE_RUIZ: "LAWRENCE_RUIZ";
+    readonly ARCHANGELS: "ARCHANGELS";
+    readonly JEROME: "JEROME";
+    readonly THERESE_OF_LISIEUX: "THERESE_OF_LISIEUX";
+    readonly GUARDIAN_ANGELS: "GUARDIAN_ANGELS";
+    readonly FRANCIS_OF_ASSISI: "FRANCIS_OF_ASSISI";
+    readonly FAUSTINA: "FAUSTINA";
+    readonly BRUNO: "BRUNO";
+    readonly OUR_LADY_OF_ROSARY: "OUR_LADY_OF_ROSARY";
+    readonly DENIS: "DENIS";
+    readonly CALLISTUS_I: "CALLISTUS_I";
+    readonly TERESA_OF_AVILA: "TERESA_OF_AVILA";
+    readonly HEDWIG: "HEDWIG";
+    readonly MARGARET_MARY: "MARGARET_MARY";
+    readonly IGNATIUS_OF_ANTIOCH: "IGNATIUS_OF_ANTIOCH";
+    readonly LUKE: "LUKE";
+    readonly ISAAC_JOGUES: "ISAAC_JOGUES";
+    readonly PAUL_OF_CROSS: "PAUL_OF_CROSS";
+    readonly JOHN_PAUL_II: "JOHN_PAUL_II";
+    readonly JOHN_OF_CAPISTRANO: "JOHN_OF_CAPISTRANO";
+    readonly ANTHONY_MARY_CLARET: "ANTHONY_MARY_CLARET";
+    readonly SIMON_JUDE: "SIMON_JUDE";
+    readonly DEDICATION_LATERAN: "DEDICATION_LATERAN";
+    readonly LEO_THE_GREAT: "LEO_THE_GREAT";
+    readonly MARTIN_OF_TOURS: "MARTIN_OF_TOURS";
+    readonly JOSAPHAT: "JOSAPHAT";
+    readonly MARGARET_OF_SCOTLAND: "MARGARET_OF_SCOTLAND";
+    readonly GERTRUDE: "GERTRUDE";
+    readonly ELIZABETH_OF_HUNGARY: "ELIZABETH_OF_HUNGARY";
+    readonly DEDICATION_PETER_PAUL: "DEDICATION_PETER_PAUL";
+    readonly PRESENTATION_OF_MARY: "PRESENTATION_OF_MARY";
+    readonly CLEMENT_I: "CLEMENT_I";
+    readonly COLUMBAN: "COLUMBAN";
+    readonly CATHERINE_OF_ALEXANDRIA: "CATHERINE_OF_ALEXANDRIA";
+    readonly ANDREW_APOSTLE: "ANDREW_APOSTLE";
+    readonly FRANCIS_XAVIER: "FRANCIS_XAVIER";
+    readonly LUCY: "LUCY";
+    readonly STEPHEN_FIRST_MARTYR: "STEPHEN_FIRST_MARTYR";
+    readonly JOHN_APOSTLE: "JOHN_APOSTLE";
+};
+
+/**
+ * Module augmentation for CalendarDay.
+ * When this plugin is imported, TypeScript will recognize the optional `liturgical` property
+ * on CalendarDay objects returned by getDays() and getDay().
+ */
+declare module "calendaryjs" {
+    interface CalendarDay {
+        /**
+         * Liturgical information (available when liturgical plugin is used with enrichDays: true)
+         */
+        liturgical?: LiturgicalInfo;
+    }
+}
+/**
+ * Event category for filtering
+ */
+type EventCategory = "easter-cycle" | "solemnities" | "feasts" | "memorials" | "computed" | "daily";
+/**
+ * Liturgical season in the Roman Catholic Church (Roman Rite).
+ *
+ * The liturgical year consists of five seasons.
+ * Ordinary Time is a single season, divided here into two periods
+ * for calculation and representation purposes.
+ *
+ * - `advent`: From the First Sunday of Advent until before the Christmas Vigil
+ * - `christmas`: From the Christmas Vigil through the Baptism of the Lord
+ * - `ordinary-time-1`: From after the Baptism of the Lord until before Ash Wednesday
+ * - `lent`: From Ash Wednesday until before the Mass of the Lord's Supper
+ * - `easter`: From the Easter Vigil through Pentecost
+ * - `ordinary-time-2`: From after Pentecost until before the First Sunday of Advent
+ */
+type LiturgicalSeason = "advent" | "christmas" | "ordinary-time-1" | "lent" | "easter" | "ordinary-time-2";
+/**
+ * Liturgical rank indicating the importance of a celebration.
+ *
+ * Ranks in descending order of importance:
+ * - `solemnity`: Highest rank (e.g., Easter, Christmas, major feasts)
+ * - `feast`: Significant celebrations of saints or mysteries
+ * - `memorial`: Remembrance of saints (can be obligatory or optional)
+ * - `ordinary`: Regular weekday celebrations with no special observance
+ */
+type LiturgicalRank = "solemnity" | "feast" | "memorial" | "ordinary";
+/**
+ * Liturgical vestment color used during Mass and other celebrations.
+ *
+ * Each color has specific symbolic meanings:
+ * - `white`: Joy, purity, glory (Christmas, Easter, celebrations of Christ, Mary, saints who were not martyrs)
+ * - `green`: Hope, growth (Ordinary Time)
+ * - `red`: Fire of the Holy Spirit, blood of martyrs (Pentecost, Palm Sunday, Good Friday, martyrs' feasts)
+ * - `violet`: Penance, preparation (Advent, Lent)
+ * - `rose`: Joyful anticipation (optional for Gaudete Sunday in Advent and Laetare Sunday in Lent)
+ */
+type VestmentColor = "white" | "green" | "red" | "violet" | "rose";
+/**
+ * Metadata specific to liturgical events.
+ */
+type LiturgicalMetadata<TExtra extends Record<string, unknown> = Record<string, unknown>> = TExtra & {
+    season: LiturgicalSeason;
+    rank: LiturgicalRank;
+    vestmentColor: VestmentColor;
+};
+/**
+ * Base properties for liturgical events with typed metadata.
+ *
+ * This ensures that all liturgical events always have `LiturgicalMetadata`
+ * plus any additional, custom metadata provided by the caller.
+ *
+ * @template TExtra - Additional metadata fields to merge with LiturgicalMetadata
+ *
+ * @example
+ * type LocalizedMetadata = {
+ *   localName: string;
+ *   localDescription?: string;
+ * };
+ *
+ * type LocalizedLiturgicalEvent = LiturgicalEventProperties<LocalizedMetadata>;
+ * // metadata: LiturgicalMetadata & LocalizedMetadata (and is required)
+ */
+interface LiturgicalEventProperties<TExtra extends Record<string, unknown> = Record<string, unknown>> extends Omit<BaseEventProperties<LiturgicalMetadata<TExtra>, EventCategory>, "metadata"> {
+    metadata: LiturgicalMetadata<TExtra>;
+}
+/**
+ * Easter event configuration.
+ *
+ * Uses the same metadata merging rules as LiturgicalEventProperties:
+ * metadata is required and is `LiturgicalMetadata & TExtra`.
+ */
+interface EasterEvent<TExtra extends Record<string, unknown> = Record<string, unknown>> extends LiturgicalEventProperties<TExtra> {
+    type: "easter";
+}
+/**
+ * Offset event configuration (relative to another event).
+ *
+ * Uses the same metadata merging rules as LiturgicalEventProperties:
+ * metadata is required and is `LiturgicalMetadata & TExtra`.
+ */
+interface OffsetEvent<TExtra extends Record<string, unknown> = Record<string, unknown>> extends LiturgicalEventProperties<TExtra> {
+    type: "offset";
+    baseEvent: string;
+    offsetDays: number;
+}
+/**
+ * Liturgical event config - any event type with required LiturgicalMetadata.
+ * Use this for type-safe liturgical event definitions.
+ *
+ * @template TExtra - Additional metadata fields to merge with LiturgicalMetadata
+ *
+ * @example
+ * ```typescript
+ * // Basic liturgical event
+ * const event: LiturgicalEventConfig = {
+ *   type: "const",
+ *   id: "christmas",
+ *   month: 12,
+ *   day: 25,
+ *   title: "Christmas",
+ *   metadata: { season: "christmas", rank: "solemnity", vestmentColor: "white" },
+ * };
+ * ```
+ */
+type LiturgicalEventConfig<TExtra extends Record<string, unknown> = Record<string, unknown>> = EventConfig<LiturgicalMetadata<TExtra>, EventCategory>;
+/**
+ * Custom event configuration for liturgical events.
+ * Re-exported from core with TExtra for additional metadata fields.
+ *
+ * @template TExtra - Additional metadata fields to merge with LiturgicalMetadata
+ */
+type CustomLiturgicalEventConfig<TExtra extends Record<string, unknown> = Record<string, unknown>> = CustomEventConfig<LiturgicalMetadata<TExtra>, EventCategory>;
+/**
+ * Resolver function for liturgical events.
+ * Specialized version of core CustomEventResolver with MassKey.
+ *
+ * @template TExtra - Additional metadata fields to merge with LiturgicalMetadata
+ */
+type CustomLiturgicalEventResolver<TExtra extends Record<string, unknown> = Record<string, unknown>, TExclude extends keyof LiturgicalEventProperties<TExtra> = never> = CustomEventResolver<MassKey, LiturgicalMetadata<TExtra>, EventCategory, TExclude>;
+
+/**
+ * Options for the liturgical plugin
+ */
+interface LiturgicalPluginOptions {
+    /**
+     * Whether Epiphany is celebrated on Sunday (between January 2-8) or fixed January 6
+     * @default false (January 6)
+     */
+    epiphanyOnSunday?: boolean;
+    /**
+     * Whether to enrich days with liturgical information (season, vestmentColor, etc.)
+     * When true, getDays() will return LiturgicalDay objects instead of CalendarDay
+     * @default true
+     */
+    enrichDays?: boolean;
+}
+/**
+ * Liturgical info added by liturgical plugin
+ */
+interface LiturgicalInfo {
+    season: LiturgicalSeason;
+    week: number;
+    rank: LiturgicalRank;
+    vestmentColor: VestmentColor;
+}
+/**
+ * CalendarDay with liturgical enrichment
+ */
+interface CalendarDayWithLiturgical extends CalendarDay {
+    liturgical: LiturgicalInfo;
+}
+/**
+ * Liturgical calendar plugin for Calendary.
+ *
+ * This is a minimal plugin that provides:
+ * - Event types: `easter`, `offset`
+ * - Formulas: `advent-1`, `advent-2`, `advent-3`, `advent-4`, `baptism-of-lord`, `christ-the-king`
+ *
+ * For event generation utilities, use `generateLiturgicalEvents` (exported from this package).
+ *
+ * @param options - Plugin configuration options
+ * @returns CalendaryPlugin instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - register event types and formulas
+ * const cal = calendary();
+ * cal.use(liturgical());
+ *
+ * // Now you can use easter and offset event types
+ * cal.addGroup({
+ *   id: 'my-liturgical',
+ *   name: 'My Liturgical Events',
+ *   events: [
+ *     { type: 'easter', id: 'easter', title: 'Easter Sunday', metadata: {...} },
+ *     { type: 'offset', id: 'pentecost', title: 'Pentecost', baseEvent: 'easter', offsetDays: 49, metadata: {...} },
+ *   ],
+ * });
+ *
+ * // For auto-generation (same package):
+ * // import { generateLiturgicalEvents } from 'calendaryjs-plugin-liturgical';
+ * // const { id, name, events } = generateLiturgicalEvents({ range: { from: '2025-01-01', to: '2025-12-31' } });
+ * // cal.addGroup({ id, name, events });
+ * ```
+ */
+declare function liturgical(options?: LiturgicalPluginOptions): CalendaryPlugin;
+
+/**
+ * Calculate Easter Sunday using the Anonymous Gregorian algorithm (Computus)
+ * This is the algorithm used by Western Christianity
+ *
+ * @param year - The year to calculate Easter for
+ * @returns Date object for Easter Sunday
+ */
+declare function computeEaster(year: number): Date;
+/**
+ * Calculate Orthodox Easter using the Julian calendar algorithm
+ * Then convert to Gregorian calendar
+ *
+ * @param year - The year to calculate Orthodox Easter for
+ * @returns Date object for Orthodox Easter Sunday
+ */
+declare function computeOrthodoxEaster(year: number): Date;
+/**
+ * Get Easter date as ISO string
+ */
+declare function getEasterDateString(year: number): string;
+/**
+ * Solar date `offsetDays` from Easter Sunday in `year`.
+ *
+ * Convenience resolver for movable Easter-cycle feasts: offset 0 = Easter,
+ * negative = Lent / Holy Week (e.g. -46 = Ash Wednesday), positive = Eastertide
+ * (e.g. +49 = Pentecost). Consumers declare only the offset; the Easter computus
+ * stays here in the plugin.
+ *
+ * @param year - Gregorian year
+ * @param offsetDays - days relative to Easter Sunday
+ * @returns Date object for the resolved day
+ */
+declare function easterRelativeDate(year: number, offsetDays: number): Date;
+
+/**
+ * Generator for EASTER events
+ */
+declare const easterEventHandler: EventTypeHandler;
+
+/**
+ * Generator for OFFSET events (relative to a base event)
+ */
+declare const offsetEventHandler: EventTypeHandler;
+
+/**
+ * Advent and Christmas season date calculations
+ */
+/**
+ * Get the date of the First Sunday of Advent
+ * Advent begins on the fourth Sunday before Christmas
+ *
+ * @param year - The year to calculate for
+ * @returns Date of the First Sunday of Advent
+ */
+declare function getAdvent1(year: number): Date;
+/**
+ * Get the date of the Second Sunday of Advent
+ */
+declare function getAdvent2(year: number): Date;
+/**
+ * Get the date of the Third Sunday of Advent (Gaudete Sunday)
+ */
+declare function getAdvent3(year: number): Date;
+/**
+ * Get the date of the Fourth Sunday of Advent
+ */
+declare function getAdvent4(year: number): Date;
+/**
+ * Get the date of the Baptism of the Lord
+ * Usually the Sunday after Epiphany (January 6)
+ * If Epiphany falls on Sunday January 7 or 8, Baptism is the following Monday
+ *
+ * @param year - The year to calculate for
+ * @param epiphanyOnSunday - Whether Epiphany is celebrated on Sunday
+ * @returns Date of the Baptism of the Lord
+ */
+declare function getBaptismOfLord(year: number, epiphanyOnSunday?: boolean): Date;
+/**
+ * Get the date of Christ the King
+ * Last Sunday of the liturgical year (Sunday before Advent 1)
+ *
+ * @param year - The year to calculate for
+ * @returns Date of Christ the King
+ */
+declare function getChristTheKing(year: number): Date;
+/**
+ * Get the date of Holy Family
+ * Sunday after Christmas, or December 30 if no Sunday between Dec 25-31
+ *
+ * @param year - The year to calculate for
+ * @returns Date of Holy Family
+ */
+declare function getHolyFamily(year: number): Date;
+
+/**
+ * Internal definition for a liturgical event
+ */
+interface LiturgicalEventDef {
+    /** Unique key for the event */
+    key: MassKey;
+    /** Event type for generation */
+    type: "easter" | "offset" | "const" | "nth-weekday" | "formula";
+    /** Category for filtering */
+    category: EventCategory;
+    /** Offset days from Easter (for offset type) */
+    offsetDays?: number;
+    /** Month (1-12) for const type */
+    month?: number;
+    /** Day (1-31) for const type */
+    day?: number;
+    /** Formula name for formula type */
+    formula?: string;
+    /** Day of week (0=Sun … 6=Sat) for nth-weekday type */
+    dayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /** Nth occurrence (1-4 or -1 for last) for simple mode */
+    nth?: 1 | 2 | 3 | 4 | -1;
+    /** Simple-mode month (1-12) */
+    nthMonth?: number;
+    /** Anchored mode: first matching dayOfWeek on/after this fixed date */
+    after?: {
+        month: number;
+        day: number;
+    };
+    /** Anchored mode: upper bound (use fallback if match falls on/after this) */
+    before?: {
+        month: number;
+        day: number;
+    };
+    /** Anchored mode: fallback date when no match found before upper bound */
+    fallback?: {
+        month: number;
+        day: number;
+    };
+    /** Liturgical metadata */
+    metadata: LiturgicalMetadata;
+}
+/**
+ * Easter cycle events - dates relative to Easter Sunday
+ */
+declare const EASTER_CYCLE_EVENTS: LiturgicalEventDef[];
+/**
+ * Fixed date solemnities - same date every year
+ */
+declare const FIXED_SOLEMNITY_EVENTS: LiturgicalEventDef[];
+/**
+ * Computed date events - calculated based on formulas
+ */
+declare const COMPUTED_EVENTS: LiturgicalEventDef[];
+/**
+ * Memorial saints - fixed date memorials and feasts of saints
+ * Organized by month for easy maintenance
+ */
+declare const MEMORIAL_SAINT_EVENTS: LiturgicalEventDef[];
+/**
+ * All liturgical event definitions
+ */
+declare const ALL_LITURGICAL_EVENTS: LiturgicalEventDef[];
+/**
+ * Get events by category
+ */
+declare function getEventsByCategory(categories: EventCategory[]): LiturgicalEventDef[];
+
+/**
+ * Complete liturgical event texts mapping.
+ * All MassKey entries are required.
+ * Used for typing DEFAULT_LITURGICAL_TEXTS.
+ *
+ * @example
+ * ```typescript
+ * const enTexts: LiturgicalTexts = {
+ *   EASTER_SUNDAY: { title: "Easter Sunday", keywords: ["easter"] },
+ *   CHRISTMAS: { title: "Christmas", keywords: ["christmas", "nativity"] },
+ *   // ... all keys required - TypeScript enforces completeness
+ * };
+ * ```
+ */
+type LiturgicalTexts = Record<MassKey, EventText>;
+
+/**
+ * Pre-defined liturgical events
+ */
+declare const EASTER: EasterEvent;
+declare const ASH_WEDNESDAY: OffsetEvent;
+declare const PALM_SUNDAY: OffsetEvent;
+declare const HOLY_THURSDAY: OffsetEvent;
+declare const GOOD_FRIDAY: OffsetEvent;
+declare const HOLY_SATURDAY: OffsetEvent;
+declare const ASCENSION: OffsetEvent;
+declare const PENTECOST: OffsetEvent;
+declare const TRINITY_SUNDAY: OffsetEvent;
+declare const CORPUS_CHRISTI: OffsetEvent;
+/**
+ * All pre-defined liturgical events
+ */
+declare const LITURGICAL_EVENTS: (EasterEvent<Record<string, unknown>> | OffsetEvent<Record<string, unknown>>)[];
+
+/**
+ * Season information for a specific date
+ */
+interface SeasonInfo {
+    /** Liturgical season */
+    season: LiturgicalSeason;
+    /** Primary vestment color for the season */
+    vestmentColor: VestmentColor;
+    /** Week number within the season (1-based) */
+    week: number;
+    /** Liturgical year this date belongs to */
+    liturgicalYear: number;
+}
+/**
+ * Season segment for chart visualization
+ */
+interface SeasonSegment {
+    /** Liturgical season identifier */
+    season: LiturgicalSeason;
+    /** Vestment color */
+    vestmentColor: VestmentColor;
+    /** Start date (inclusive) in YYYY-MM-DD format */
+    startDate: string;
+    /** End date (inclusive) in YYYY-MM-DD format */
+    endDate: string;
+    /** Number of days in this segment */
+    days: number;
+    /** Start angle in degrees (0 = top, clockwise) for pie/donut charts */
+    startAngle: number;
+    /** End angle in degrees for pie/donut charts */
+    endAngle: number;
+    /** Percentage of the year this segment occupies */
+    percentage: number;
+}
+/**
+ * Complete liturgical year data for chart visualization
+ */
+interface LiturgicalYearChart {
+    /** Liturgical year number */
+    liturgicalYear: number;
+    /** Calendar year the liturgical year starts in */
+    calendarYearStart: number;
+    /** Calendar year the liturgical year ends in */
+    calendarYearEnd: number;
+    /** Start date of the liturgical year (Advent 1) */
+    startDate: string;
+    /** End date of the liturgical year (Saturday before next Advent 1) */
+    endDate: string;
+    /** Total days in the liturgical year */
+    totalDays: number;
+    /** Season segments in chronological order */
+    segments: SeasonSegment[];
+}
+/**
+ * Options for getSeason function
+ */
+interface GetSeasonOptions {
+    /** Whether Epiphany is celebrated on Sunday */
+    epiphanyOnSunday?: boolean;
+}
+/**
+ * Get the liturgical season for a specific date.
+ *
+ * @param date - Date to check (Date object or YYYY-MM-DD string)
+ * @param options - Configuration options
+ * @returns Season information
+ *
+ * @example
+ * ```typescript
+ * const season = getSeason("2024-12-25");
+ * // { season: "christmas", vestmentColor: "white", week: 1, liturgicalYear: 2025 }
+ *
+ * const today = getSeason(new Date());
+ * console.log(`Current season: ${today.season}`);
+ * ```
+ */
+declare function getSeason(date: Date | string, options?: GetSeasonOptions): SeasonInfo;
+/**
+ * Get the current liturgical season (today).
+ *
+ * @param options - Configuration options
+ * @returns Season information for today
+ *
+ * @example
+ * ```typescript
+ * const current = getCurrentSeason();
+ * console.log(`We are in ${current.season}, week ${current.week}`);
+ * ```
+ */
+declare function getCurrentSeason(options?: GetSeasonOptions): SeasonInfo;
+/**
+ * Options for getLiturgicalYearChart function
+ */
+interface GetLiturgicalYearChartOptions {
+    /** Whether Epiphany is celebrated on Sunday */
+    epiphanyOnSunday?: boolean;
+}
+/**
+ * Get liturgical year data optimized for chart visualization.
+ *
+ * Returns season segments with:
+ * - Start/end dates
+ * - Number of days
+ * - Angles for pie/donut charts (0° = top, clockwise)
+ * - Percentages
+ * - Colors (both vestment and hex for visualization)
+ *
+ * @param liturgicalYear - The liturgical year (e.g., 2025)
+ * @param options - Configuration options
+ * @returns Chart data with season segments
+ *
+ * @example
+ * ```typescript
+ * const chart = getLiturgicalYearChart(2025);
+ *
+ * // Use with a charting library
+ * const pieData = chart.segments.map(s => ({
+ *   label: s.season,
+ *   value: s.percentage,
+ *   color: s.vestmentColor,
+ * }));
+ *
+ * // Or for SVG arc rendering
+ * chart.segments.forEach(s => {
+ *   drawArc(s.startAngle, s.endAngle, s.vestmentColor);
+ * });
+ * ```
+ */
+declare function getLiturgicalYearChart(liturgicalYear: number, options?: GetLiturgicalYearChartOptions): LiturgicalYearChart;
+/**
+ * Get all season segments for a calendar year (may span two liturgical years).
+ *
+ * Useful when you want to visualize a calendar year (Jan-Dec) instead of
+ * a liturgical year (Advent to Christ the King).
+ *
+ * @param calendarYear - The calendar year (e.g., 2024)
+ * @param options - Configuration options
+ * @returns Array of season segments covering the calendar year
+ *
+ * @example
+ * ```typescript
+ * const segments = getCalendarYearSeasons(2024);
+ * // Returns segments from Jan 1, 2024 to Dec 31, 2024
+ * // May include parts of two liturgical years
+ * ```
+ */
+declare function getCalendarYearSeasons(calendarYear: number, options?: GetLiturgicalYearChartOptions): SeasonSegment[];
+
+/**
+ * Liturgical day information for any date (used by getLiturgicalDay)
+ */
+interface LiturgicalDay {
+    /** Date in YYYY-MM-DD format */
+    date: string;
+    /** Liturgical season */
+    season: LiturgicalSeason;
+    /** Week number within the season (1-based) */
+    week: number;
+    /** Day of week (0=Sunday, 1=Monday, etc.) */
+    dayOfWeek: number;
+    /** Liturgical rank */
+    rank: LiturgicalRank;
+    /** Vestment color */
+    vestmentColor: VestmentColor;
+    /** Whether this is a Sunday */
+    isSunday: boolean;
+    /** Whether this is a weekday (Monday-Saturday) */
+    isWeekday: boolean;
+    /** Full metadata */
+    metadata: LiturgicalMetadata;
+}
+/**
+ * Liturgical year boundaries
+ */
+interface LiturgicalYearBoundaries {
+    /** First Sunday of Advent (start of liturgical year) */
+    advent1: Date;
+    /** Christmas Day */
+    christmas: Date;
+    /** Baptism of the Lord (end of Christmas season) */
+    baptismOfLord: Date;
+    /** Ash Wednesday (start of Lent) */
+    ashWednesday: Date;
+    /** Easter Sunday */
+    easter: Date;
+    /** Pentecost Sunday (end of Easter season) */
+    pentecost: Date;
+    /** Christ the King (last Sunday of liturgical year) */
+    christTheKing: Date;
+}
+
+/**
+ * Options for getLiturgicalDay
+ */
+interface GetLiturgicalDayOptions {
+    /** Whether Epiphany is celebrated on Sunday */
+    epiphanyOnSunday?: boolean;
+}
+/**
+ * Get the liturgical day information for a specific date.
+ *
+ * @param date - Date to get liturgical info for (Date object or YYYY-MM-DD string)
+ * @param options - Configuration options
+ * @returns Liturgical day information
+ */
+declare function getLiturgicalDay(date: Date | string, options?: GetLiturgicalDayOptions): LiturgicalDay;
+/**
+ * Generate liturgical days for a date range.
+ *
+ * @param startDate - Start date (inclusive)
+ * @param endDate - End date (inclusive)
+ * @param options - Configuration options
+ * @returns Array of liturgical days
+ */
+declare function getLiturgicalDaysInRange(startDate: Date | string, endDate: Date | string, options?: GetLiturgicalDayOptions): LiturgicalDay[];
+/**
+ * Generate all liturgical days for a given month.
+ *
+ * @param year - Calendar year
+ * @param month - Month (1-12)
+ * @param options - Configuration options
+ * @returns Array of liturgical days for the month
+ */
+declare function getLiturgicalDaysForMonth(year: number, month: number, options?: GetLiturgicalDayOptions): LiturgicalDay[];
+/**
+ * Generate all liturgical days for a given year.
+ *
+ * @param year - Calendar year
+ * @param options - Configuration options
+ * @returns Array of liturgical days for the year
+ */
+declare function getLiturgicalDaysForYear(year: number, options?: GetLiturgicalDayOptions): LiturgicalDay[];
+
+/**
+ * Get the liturgical year for a given date.
+ * The liturgical year starts on the First Sunday of Advent.
+ *
+ * @param date - Date to check
+ * @returns The liturgical year number
+ */
+declare function getLiturgicalYear(date: Date): number;
+/**
+ * Calculate all liturgical year boundaries for a given liturgical year.
+ *
+ * @param liturgicalYear - The liturgical year (e.g., 2025 means Advent 2024 to Christ the King 2025)
+ * @param epiphanyOnSunday - Whether Epiphany is celebrated on Sunday
+ * @returns All key dates for the liturgical year
+ */
+declare function getLiturgicalYearBoundaries(liturgicalYear: number, epiphanyOnSunday?: boolean): LiturgicalYearBoundaries;
+
+/**
+ * Date range for event generation
+ */
+interface DateRange {
+    from: DateString;
+    to: DateString;
+}
+/**
+ * Options for generating liturgical events
+ *
+ * Note: Major events (solemnities, feasts, memorials) are always generated.
+ * Days without events will have empty events[] - no filler "daily" events are created.
+ * Use getDays() to get full day information including season context.
+ */
+interface GenerateLiturgicalEventsOptions<TExtra extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Date range for event generation.
+     * Format: { from: 'YYYY-MM-DD', to: 'YYYY-MM-DD' }
+     */
+    range: DateRange;
+    /**
+     * Whether Epiphany is celebrated on Sunday (between January 2-8) or fixed January 6
+     * @default false (January 6)
+     */
+    epiphanyOnSunday?: boolean;
+    /**
+     * Whether Ascension is on Sunday or Thursday (+39 days from Easter)
+     * @default false (Thursday)
+     */
+    ascensionOnSunday?: boolean;
+    /**
+     * Whether Corpus Christi is on Sunday or Thursday (+60 days from Easter)
+     * @default true (Sunday - most countries)
+     */
+    corpusChristiOnSunday?: boolean;
+    /**
+     * Filter which event categories to include for major events.
+     * @default ['easter-cycle', 'solemnities', 'feasts', 'memorials', 'computed']
+     */
+    includeCategories?: Array<"easter-cycle" | "solemnities" | "feasts" | "memorials" | "computed">;
+    /**
+     * Group ID for the generated events
+     * @default 'liturgical-calendar'
+     */
+    groupId?: string;
+    /**
+     * Custom event resolver - provides custom configuration for each event.
+     * Allows overriding any BaseEventProperties field (title, keywords, url, metadata, overrideDates, onConflict, etc.).
+     * Metadata from customization will be merged with the original event metadata.
+     *
+     * - Use `overrideDates` to force reschedule events to different dates unconditionally.
+     * - Use `onConflict` to handle date conflicts dynamically (drop, reschedule, or keep).
+     *
+     * @template TExtra - Additional metadata fields to merge with LiturgicalMetadata
+     *
+     * @example
+     * ```typescript
+     * // With custom metadata and date overrides
+     * interface LocalizedMetadata {
+     *   localName: string;
+     * }
+     *
+     * generateLiturgicalEvents<LocalizedMetadata>({
+     *   range: { from: "2025-01-01", to: "2026-12-31" },
+     *   customResolver: (key) => ({
+     *     title: localTexts[key]?.title,
+     *     keywords: localTexts[key]?.keywords,
+     *     metadata: { localName: localTexts[key]?.name },
+     *
+     *     // Option 1: Force reschedule unconditionally
+     *     overrideDates: key === "ASH_WEDNESDAY" ? {
+     *       "2026-02-18": "2026-02-20",
+     *     } : undefined,
+     *
+     *     // Option 2: Handle conflicts dynamically
+     *     onConflict: key === "SAINT_JOSEPH" ? (date) => {
+     *       if (date === "2026-03-19") {
+     *         return { action: "reschedule", to: "2026-03-20" };
+     *       }
+     *       return { action: "keep" };
+     *     } : undefined,
+     *   }),
+     * });
+     * ```
+     */
+    customResolver?: CustomLiturgicalEventResolver<TExtra>;
+}
+/**
+ * Result of generateLiturgicalEvents
+ *
+ * @template TExtra - Additional metadata fields merged with LiturgicalMetadata
+ */
+interface GeneratedLiturgicalEvents<TExtra extends Record<string, unknown> = Record<string, unknown>> {
+    /** Group ID */
+    id: string;
+    /** Generated events with LiturgicalMetadata & TExtra */
+    events: LiturgicalEventConfig<TExtra>[];
+}
+/**
+ * Options for creating a liturgical events generator
+ *
+ * @template TExtra - Additional metadata fields merged with LiturgicalMetadata
+ */
+interface CreateGeneratorOptions<TExtra extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Default options for all generations
+     */
+    defaults?: Partial<GenerateLiturgicalEventsOptions<TExtra>>;
+}
+
+/**
+ * Generate liturgical events for a date range.
+ *
+ * Always generates major liturgical events (solemnities, feasts, memorials).
+ * Days without events will have empty events[] - use getDays() for full day info.
+ *
+ * @param options - Generation options
+ * @returns Generated events ready to be added to a Calendary group
+ *
+ * @example
+ * ```typescript
+ * const cal = calendary();
+ * cal.use(liturgical());
+ *
+ * const { id, events } = generateLiturgicalEvents({
+ *   range: { from: "2025-01-01", to: "2025-12-31" },
+ * });
+ *
+ * cal.addGroup({ id, events });
+ *
+ * // Get days with full context (season, lunar date, etc.)
+ * const days = cal.getDays({ from: "2025-12-01", to: "2025-12-31" });
+ * ```
+ */
+declare function generateLiturgicalEvents<TExtra extends Record<string, unknown> = Record<string, unknown>>(options: GenerateLiturgicalEventsOptions<TExtra>): GeneratedLiturgicalEvents<TExtra>;
+/**
+ * Create a liturgical events generator with preset options.
+ * Useful when you want to reuse the same configuration.
+ *
+ * @param generatorOptions - Options for the generator
+ * @returns A function that generates events with the preset options
+ *
+ * @example
+ * ```typescript
+ * const generate = createLiturgicalGenerator({
+ *   defaults: {
+ *     epiphanyOnSunday: true,
+ *     ascensionOnSunday: true,
+ *   },
+ * });
+ *
+ * const events2025 = generate({ range: { from: "2025-01-01", to: "2025-12-31" } });
+ * const events2026 = generate({ range: { from: "2026-01-01", to: "2026-12-31" } });
+ * ```
+ */
+declare function createLiturgicalGenerator<TExtra extends Record<string, unknown> = Record<string, unknown>>(generatorOptions?: CreateGeneratorOptions<TExtra>): (options: GenerateLiturgicalEventsOptions<TExtra>) => GeneratedLiturgicalEvents<TExtra>;
+
+/**
+ * Default English liturgical event texts.
+ * Use as fallback or reference for creating custom translations.
+ */
+declare const DEFAULT_LITURGICAL_TEXTS: LiturgicalTexts;
+
+export { ALL_LITURGICAL_EVENTS, ALL_MASS_KEYS, ASCENSION, ASH_WEDNESDAY, COMPUTED_EVENTS, COMPUTED_KEYS, CORPUS_CHRISTI, type CalendarDayWithLiturgical, type ComputedKey, type CreateGeneratorOptions, type CustomLiturgicalEventConfig, type CustomLiturgicalEventResolver, DEFAULT_LITURGICAL_TEXTS, EASTER, EASTER_CYCLE_EVENTS, EASTER_CYCLE_KEYS, type EasterCycleKey, type EasterEvent, type EventCategory, FIXED_SOLEMNITY_EVENTS, FIXED_SOLEMNITY_KEYS, type FixedSolemnityKey, GOOD_FRIDAY, type GenerateLiturgicalEventsOptions, type GeneratedLiturgicalEvents, type GetLiturgicalDayOptions, type GetLiturgicalYearChartOptions, type GetSeasonOptions, HOLY_SATURDAY, HOLY_THURSDAY, LITURGICAL_EVENTS, type LiturgicalDay, type LiturgicalEventConfig, type LiturgicalEventDef, type LiturgicalEventProperties, type LiturgicalInfo, type LiturgicalMetadata, type LiturgicalPluginOptions, type LiturgicalRank, type LiturgicalSeason, type LiturgicalTexts, type LiturgicalYearBoundaries, type LiturgicalYearChart, MEMORIAL_SAINT_EVENTS, MEMORIAL_SAINT_KEYS, type MassKey, MassKeys, type MemorialSaintKey, type OffsetEvent, PALM_SUNDAY, PENTECOST, type SeasonInfo, type SeasonSegment, TRINITY_SUNDAY, type VestmentColor, computeEaster, computeOrthodoxEaster, createLiturgicalGenerator, easterEventHandler, easterRelativeDate, generateLiturgicalEvents, getAdvent1, getAdvent2, getAdvent3, getAdvent4, getBaptismOfLord, getCalendarYearSeasons, getChristTheKing, getCurrentSeason, getEasterDateString, getEventsByCategory, getHolyFamily, getLiturgicalDay, getLiturgicalDaysForMonth, getLiturgicalDaysForYear, getLiturgicalDaysInRange, getLiturgicalYear, getLiturgicalYearBoundaries, getLiturgicalYearChart, getSeason, liturgical, offsetEventHandler };