calendaryjs 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,1289 @@
+/**
+ * Date string in YYYY-MM-DD format.
+ * Template literal type provides compile-time format validation.
+ *
+ * @example
+ * ```typescript
+ * const date: DateString = "2025-12-25"; // ✓ Valid
+ * const bad: DateString = "25-12-2025";  // ✗ Error: wrong format
+ * ```
+ */
+type DateString = `${number}-${number}-${number}`;
+/**
+ * Map of dates to override (force reschedule).
+ * Unlike onConflict which handles conflicts, this unconditionally moves events.
+ *
+ * @example
+ * ```typescript
+ * const overrideDates: OverrideDatesMap = {
+ *   "2026-02-18": "2026-02-20",  // Move from Feb 18 to Feb 20
+ *   "2027-02-10": "2027-02-12",  // Move from Feb 10 to Feb 12
+ * };
+ * ```
+ */
+type OverrideDatesMap = Record<DateString, DateString>;
+/**
+ * Base properties shared by all event types (ICS-compatible)
+ *
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ * @template TCategory - Category type (default: string, can be enum for type safety)
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * type Event = BaseEventProperties;
+ *
+ * // With typed categories
+ * type LiturgicalCategory = "solemnity" | "feast" | "memorial";
+ * type LiturgicalEvent = BaseEventProperties<LiturgicalMetadata, LiturgicalCategory>;
+ * ```
+ */
+interface BaseEventProperties<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> {
+    id: string;
+    title: string;
+    keywords?: string[];
+    allDay?: boolean;
+    startTime?: string;
+    endTime?: string;
+    duration?: number;
+    description?: string;
+    location?: string;
+    url?: string;
+    /**
+     * Origin of the event — the plugin, feed, or ICS subscription that produced it.
+     * Lets a consumer customize/filter in bulk by source (like toggling a calendar
+     * in Google/Apple Calendar) and namespaces the ICS export `UID`.
+     * Distinct from `groupId` (a user-defined group) and `sourceEventId` (the
+     * originating config id).
+     */
+    source?: string;
+    categories?: TCategory[];
+    /**
+     * Display precedence when several events land on the same day, like CSS
+     * `z-index`: **higher = on top**, default `0`. The core only sorts by this
+     * number (highest first); it assigns no meaning to the values — the consumer
+     * does. Ties keep generation order (stable).
+     */
+    priority?: number;
+    status?: "confirmed" | "tentative" | "cancelled";
+    color?: string;
+    icon?: string;
+    metadata?: TMetadata;
+    reminders?: Reminder[];
+    /**
+     * Conflict resolver for handling events on the same day.
+     * Called during event generation to determine action when this event
+     * would occur on a specific date.
+     *
+     * Default behavior (when not specified): keep all events
+     */
+    onConflict?: ConflictResolver;
+    /**
+     * Force reschedule dates unconditionally.
+     * Unlike onConflict which handles conflicts, this always moves events.
+     * Key is the original computed date (YYYY-MM-DD), value is the new date.
+     *
+     * @example
+     * ```typescript
+     * overrideDates: {
+     *   "2026-02-18": "2026-02-20",  // Move from Feb 18 to Feb 20
+     * }
+     * ```
+     */
+    overrideDates?: OverrideDatesMap;
+    /**
+     * Per-occurrence exceptions keyed by the event's ORIGINAL computed date
+     * (YYYY-MM-DD) — maps ICS `EXDATE` / `RECURRENCE-ID`. `{ skip: true }` drops
+     * that occurrence; `{ override }` replaces properties for that one instance.
+     */
+    exceptions?: EventExceptions;
+    /**
+     * Recurrence validity window (`YYYY-MM-DD`, **both bounds inclusive**).
+     * Occurrences before `startDate` or after `endDate` are dropped — applied
+     * centrally during generation, so it works for ANY event type (const, monthly,
+     * weekly, nth-weekday, plugin types…), not just the few that ship their own
+     * range fields.
+     *
+     * Maps iCalendar semantics: `startDate` ↔ `DTSTART` lower bound, `endDate` ↔
+     * `RRULE;UNTIL` (which RFC 5545 defines as **inclusive**). Both are DATE values
+     * (all-day); recurrences are date-based, so no time component is involved.
+     *
+     * @example
+     * // Weekly stand-up, but only for July 2026
+     * { type: "weekly", id: "standup", dayOfWeek: 1,
+     *   startDate: "2026-07-01", endDate: "2026-07-31" }
+     */
+    startDate?: string;
+    endDate?: string;
+    /**
+     * Per-occurrence **dynamic** fields, derived from each occurrence's date. A map
+     * of `fieldName → template`, where the template may contain date tokens
+     * (`{YYYY}` `{MM}` `{DD}` zero-padded · `{M}` `{D}` no padding). Each occurrence
+     * gets the field set to the interpolated value.
+     *
+     * Applied during generation, **after** the base value and **before** a
+     * per-date `exceptions[date].override` (which always wins). Typically used for a
+     * date-specific `url`, but any string field works (`title`, `description`,
+     * `location`, …).
+     *
+     * @example
+     * // Every Sunday's link points at a date page
+     * { type: "weekly", id: "mass", dayOfWeek: 0, title: "Mass",
+     *   templates: { url: "https://x.com/mass/{D}-{M}" } }
+     * // 2026-07-07 → .../mass/7-7   ·   2026-07-14 → .../mass/14-7
+     */
+    templates?: Record<string, string>;
+}
+interface Reminder {
+    type: "notification" | "email";
+    trigger: number;
+    message?: string;
+}
+/**
+ * A single per-occurrence exception (see `BaseEventProperties.exceptions`).
+ * - `{ skip: true }` — drop this occurrence (ICS `EXDATE`).
+ * - `{ override }` — replace properties for this one instance (ICS
+ *   `RECURRENCE-ID`). Changes display properties only; to move an occurrence to
+ *   another date use `overrideDates`.
+ */
+type EventException = {
+    skip: true;
+} | {
+    override: Partial<Omit<BaseEventProperties, "id" | "exceptions">>;
+};
+/**
+ * Map of an event's ORIGINAL computed dates (YYYY-MM-DD) to per-occurrence
+ * exceptions.
+ */
+type EventExceptions = Record<DateString, EventException>;
+/**
+ * Conflict action when multiple events occur on the same day.
+ *
+ * - `keep` - Keep this event (default behavior, allows multiple events on same day)
+ * - `drop` - Remove this event when conflict exists
+ * - `reschedule` - Move this event to a different date
+ */
+type ConflictAction = {
+    action: "keep";
+} | {
+    action: "drop";
+} | {
+    action: "reschedule";
+    to: DateString;
+};
+/**
+ * Map of dates to conflict actions.
+ * Dates not in the map default to "keep".
+ */
+type ConflictMap = Partial<Record<DateString, ConflictAction>>;
+/**
+ * Function to determine conflict action for a specific date.
+ */
+type ConflictResolverFn = (date: DateString) => ConflictAction;
+/**
+ * Resolver to determine conflict action for events.
+ * Can be either a function for dynamic logic or a map for static date lists.
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Function for complex logic
+ * const onConflict: ConflictResolver = (date) => {
+ *   if (date === "2026-02-18") {
+ *     return { action: "reschedule", to: "2026-02-17" };
+ *   }
+ *   return { action: "keep" };
+ * };
+ *
+ * // Option 2: Map for static date lists (cleaner for many dates)
+ * const onConflict: ConflictResolver = {
+ *   "2026-02-18": { action: "reschedule", to: "2026-02-17" },
+ *   "2027-11-24": { action: "drop" },
+ *   "2028-02-18": { action: "reschedule", to: "2028-02-19" },
+ *   // Dates not in map default to "keep"
+ * };
+ * ```
+ */
+type ConflictResolver = ConflictResolverFn | ConflictMap;
+/**
+ * CONST - Fixed annual events (e.g., Christmas on Dec 25)
+ * Supports year exclusions and date range constraints.
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ * @example
+ * // Basic annual event
+ * { type: "const", id: "christmas", month: 12, day: 25 }
+ *
+ * // Annual event with exclusions
+ * { type: "const", id: "liberation-day",
+ *   month: 4, day: 30, excludeYears: [2025, 2040, 2043] }
+ *
+ * // Annual event with date range
+ * { type: "const", id: "company-anniversary",
+ *   month: 3, day: 15, startYear: 2020, endYear: 2030 }
+ */
+interface ConstEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    type: "const";
+    /**
+     * Month of the event (1-12)
+     * @example 12 // December
+     */
+    month: number;
+    /**
+     * Day of the month (1-31)
+     * @example 25 // 25th day
+     */
+    day: number;
+    /**
+     * Years to exclude from recurrence
+     * @example [2025, 2040, 2043] // Skip these years
+     */
+    excludeYears?: number[];
+    /**
+     * First year the event occurs (inclusive)
+     * @example 2020 // Start from 2020
+     */
+    startYear?: number;
+    /**
+     * Last year the event occurs (inclusive)
+     * @example 2030 // End at 2030
+     */
+    endYear?: number;
+}
+/**
+ * FIXED - One-time events on a specific date
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ * @example
+ * { type: "fixed", id: "wedding",
+ *   year: 2025, month: 6, day: 15 }
+ */
+interface FixedEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    type: "fixed";
+    /**
+     * Year of the event
+     * @example 2025
+     */
+    year: number;
+    /**
+     * Month of the event (1-12)
+     * @example 6 // June
+     */
+    month: number;
+    /**
+     * Day of the month (1-31)
+     * @example 15
+     */
+    day: number;
+}
+/**
+ * MONTHLY - Recurring events on the same day every month
+ * Supports intervals, month exclusions, and date exclusions.
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ * @example
+ * // Every 15th of the month
+ * { type: "monthly", id: "payday", day: 15 }
+ *
+ * // Quarterly (every 3 months starting January)
+ * { type: "monthly", id: "quarterly-review",
+ *   day: 1, interval: 3, startMonth: 1 }
+ *
+ * // Monthly except December
+ * { type: "monthly", id: "team-lunch",
+ *   day: 10, excludeMonths: [12] }
+ */
+interface MonthlyEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    type: "monthly";
+    /**
+     * Day of the month (1-31)
+     * Note: If day exceeds month's days (e.g., 31 in February), event is skipped for that month
+     * @example 15 // 15th of each month
+     */
+    day: number;
+    /**
+     * Recurrence interval in months (default: 1)
+     * @example 3 // Every 3 months (quarterly)
+     */
+    interval?: number;
+    /**
+     * Starting month for interval calculation (1-12, default: 1)
+     * Used with interval to determine which months the event occurs
+     * @example 1 // Start counting from January
+     */
+    startMonth?: number;
+    /**
+     * Months to exclude (1-12)
+     * @example [7, 8] // Skip July and August
+     */
+    excludeMonths?: number[];
+    /**
+     * Specific dates to exclude (ISO format: YYYY-MM-DD)
+     * @example ["2025-12-15"] // Skip this specific date
+     */
+    excludeDates?: string[];
+}
+/** A weekday index: 0 = Sunday, 1 = Monday, … 6 = Saturday. */
+type WeekdayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * WEEKLY - Recurring events on one or more days every week
+ * Supports multiple weekdays, intervals, date range, and date exclusions.
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ * @example
+ * // Every Monday
+ * { type: "weekly", id: "standup", dayOfWeek: 1 }
+ *
+ * // Every Monday, Wednesday & Friday (like an alarm's "Repeat")
+ * { type: "weekly", id: "logwork", dayOfWeek: [1, 3, 5] }
+ *
+ * // Every other Wednesday
+ * { type: "weekly", id: "biweekly-sync",
+ *   dayOfWeek: 3, interval: 2 }
+ *
+ * // Every Friday with date range
+ * { type: "weekly", id: "sprint-review",
+ *   dayOfWeek: 5, startDate: "2025-01-01", endDate: "2025-12-31" }
+ */
+interface WeeklyEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    type: "weekly";
+    /**
+     * Day of the week, or several. `0=Sunday, 1=Monday, ..., 6=Saturday`.
+     * A list fires on each selected day every week (ICS `BYDAY` semantics); with
+     * `interval`, all selected days share one reference week.
+     * @example 1 // Monday
+     * @example [1, 3, 5] // Monday, Wednesday, Friday
+     */
+    dayOfWeek: WeekdayIndex | WeekdayIndex[];
+    /**
+     * Recurrence interval in weeks (default: 1)
+     * @example 2 // Every 2 weeks (bi-weekly)
+     */
+    interval?: number;
+    /**
+     * Start date for the recurrence (ISO format: YYYY-MM-DD)
+     * Used as reference point for interval calculation
+     * @example "2025-01-06" // First Monday of 2025
+     */
+    startDate?: string;
+    /**
+     * End date for the recurrence (ISO format: YYYY-MM-DD)
+     * @example "2025-12-31"
+     */
+    endDate?: string;
+    /**
+     * Specific dates to exclude (ISO format: YYYY-MM-DD)
+     * @example ["2025-12-25"] // Skip Christmas
+     */
+    excludeDates?: string[];
+}
+/**
+ * FORMULA - Custom formula-based events
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ */
+interface FormulaEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    type: "formula";
+    formula: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * Anchor point for nth-weekday events relative to a fixed date.
+ */
+interface DateAnchor {
+    /** Month (1-12) */
+    month: number;
+    /** Day of month (1-31) */
+    day: number;
+}
+/**
+ * NTH-WEEKDAY - Recurring events on the Nth weekday of a month, or the first
+ * matching weekday relative to a fixed-date anchor.
+ *
+ * Supports two modes:
+ *
+ * **Simple mode** — nth occurrence of a weekday within a calendar month:
+ * ```typescript
+ * // Mother's Day: 2nd Sunday of May
+ * { type: "nth-weekday", nth: 2, dayOfWeek: 0, month: 5 }
+ *
+ * // Thanksgiving (US): 4th Thursday of November
+ * { type: "nth-weekday", nth: 4, dayOfWeek: 4, month: 11 }
+ *
+ * // Last Monday of August
+ * { type: "nth-weekday", nth: -1, dayOfWeek: 1, month: 8 }
+ * ```
+ *
+ * **Anchored mode** — first matching weekday on or after a fixed date,
+ * optionally bounded and with a fallback:
+ * ```typescript
+ * // Holy Family: first Sunday after Dec 25, fallback Dec 30
+ * { type: "nth-weekday", dayOfWeek: 0,
+ *   after: { month: 12, day: 26 }, before: { month: 12, day: 31 },
+ *   fallback: { month: 12, day: 30 } }
+ *
+ * // Baptism of the Lord: first Sunday on/after Jan 7
+ * { type: "nth-weekday", dayOfWeek: 0, after: { month: 1, day: 7 } }
+ * ```
+ *
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ */
+interface NthWeekdayEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    type: "nth-weekday";
+    /**
+     * Day of the week (0=Sunday, 1=Monday, ..., 6=Saturday)
+     * @example 0 // Sunday
+     */
+    dayOfWeek: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Which occurrence within the month:
+     * - `1`–`4`: 1st through 4th occurrence
+     * - `-1`: last occurrence
+     *
+     * Required in simple mode (paired with `month`). Omit for anchored mode.
+     */
+    nth?: 1 | 2 | 3 | 4 | -1;
+    /**
+     * Month (1-12). Required in simple mode. Omit for anchored mode.
+     */
+    month?: number;
+    /**
+     * Find the first matching `dayOfWeek` on or after this date.
+     * When provided, `nth` and `month` are ignored.
+     */
+    after?: DateAnchor;
+    /**
+     * Upper-bound anchor. If the first match found via `after` falls on or
+     * after this date, the `fallback` date is used instead (if supplied).
+     */
+    before?: DateAnchor;
+    /**
+     * Fallback date used when no `dayOfWeek` is found between `after` and
+     * `before` (inclusive). Only meaningful when `before` is also set.
+     */
+    fallback?: DateAnchor;
+    /** Years to skip entirely. */
+    excludeYears?: number[];
+    /** First year the event applies (inclusive). */
+    startYear?: number;
+    /** Last year the event applies (inclusive). */
+    endYear?: number;
+}
+/**
+ * Core event types (without plugins)
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ */
+/**
+ * RELATIVE - A date computed as an offset from a named anchor.
+ * The anchor is a resolver (year → Date) registered by the consumer or a plugin;
+ * the offset shifts from it. The core knows no specific anchors — it only
+ * resolves whatever name was registered. Compile target of the builder's
+ * `from(anchor).plus(...)`.
+ *
+ * @example
+ * // 49 days after whatever the "anchor" resolver returns for that year
+ * { type: "relative", id: "x", anchor: "anchor", offset: { days: 49 } }
+ */
+interface RelativeEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    type: "relative";
+    /** Name of a registered anchor resolver (year → Date). */
+    anchor: string;
+    /** Offset from the anchor date. */
+    offset: {
+        days?: number;
+        weeks?: number;
+    };
+}
+type CoreEventConfig<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> = ConstEvent<TMetadata, TCategory> | FixedEvent<TMetadata, TCategory> | MonthlyEvent<TMetadata, TCategory> | WeeklyEvent<TMetadata, TCategory> | NthWeekdayEvent<TMetadata, TCategory> | FormulaEvent<TMetadata, TCategory> | RelativeEvent<TMetadata, TCategory>;
+/**
+ * Generic event config - extended by plugins.
+ * Use the generic parameter to enforce metadata types.
+ *
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (any metadata)
+ * const event: EventConfig = { type: "const", id: "x", ... };
+ *
+ * // With typed metadata
+ * interface MyMetadata { rank: string; color: string; }
+ * const event: EventConfig<MyMetadata> = { ... metadata: { rank: "high", color: "red" } };
+ * ```
+ */
+type EventConfig<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> = CoreEventConfig<TMetadata, TCategory> | {
+    type: string;
+    metadata?: TMetadata;
+    [key: string]: unknown;
+};
+/**
+ * Event type identifiers
+ */
+type CoreEventType = "const" | "fixed" | "monthly" | "weekly" | "nth-weekday" | "formula" | "relative";
+/**
+ * Custom event configuration for overriding event properties.
+ * Used by generator packages to allow customization of generated events.
+ *
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ * @template TExclude - Fields to exclude from customization (default: never)
+ *
+ * @example
+ * ```typescript
+ * // Allow all fields except id
+ * const customConfig: CustomEventConfig<{ localName: string }> = {
+ *   title: "Easter Sunday",
+ *   keywords: ["easter", "resurrection"],
+ *   metadata: { localName: "Pâques" },
+ *   url: "https://example.com/easter",
+ * };
+ *
+ * // Force reschedule to different dates
+ * const customConfig: CustomEventConfig = {
+ *   overrideDates: {
+ *     "2026-02-18": "2026-02-20",  // Move Ash Wednesday
+ *   },
+ * };
+ *
+ * // Restrict certain fields from customization
+ * type RestrictedConfig = CustomEventConfig<MyMetadata, "status" | "reminders">;
+ * // Now status and reminders cannot be customized
+ * ```
+ */
+type CustomEventConfig<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string, TExclude extends keyof BaseEventProperties<TMetadata, TCategory> = never> = Partial<Omit<BaseEventProperties<TMetadata, TCategory>, "id" | "metadata" | TExclude>> & {
+    /**
+     * Partial metadata to merge with the base event's metadata.
+     * Only specify the fields you want to add or override.
+     * The base metadata fields will be preserved.
+     *
+     * @example
+     * ```typescript
+     * // Only add extra fields - base metadata (rank, season, etc.) is preserved
+     * metadata: { wikiFileUrl: "christmas.md" }
+     * ```
+     */
+    metadata?: Partial<TMetadata>;
+    /**
+     * Force reschedule dates unconditionally.
+     * Unlike onConflict which handles conflicts, this always moves events.
+     * Key is the original computed date, value is the new date.
+     */
+    overrideDates?: OverrideDatesMap;
+};
+/**
+ * Resolver function that provides custom configuration for each event key.
+ * Returns partial event properties that will be merged with the generated event.
+ *
+ * @template TKey - Event key type (e.g., MassKey, LunarKey)
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ * @template TExclude - Fields to exclude from customization (default: never)
+ *
+ * @example
+ * ```typescript
+ * // Liturgical events - allow all customization
+ * const resolver: CustomEventResolver<MassKey, LiturgicalMetadata> = (key) => ({
+ *   title: localTexts[key]?.title,
+ *   metadata: { localName: localTexts[key]?.name },
+ * });
+ *
+ * // Lunar events - restrict status and reminders
+ * const resolver: CustomEventResolver<LunarKey, LunarMetadata, "status" | "reminders"> = (key) => ({
+ *   title: lunarTexts[key]?.title,
+ * });
+ * ```
+ */
+type CustomEventResolver<TKey extends string, TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string, TExclude extends keyof BaseEventProperties = never> = (key: TKey) => CustomEventConfig<TMetadata, TCategory, TExclude> | undefined;
+
+/**
+ * Group configuration
+ */
+interface GroupConfig {
+    id: string;
+    name?: string;
+    description?: string;
+    color?: string;
+    enabled?: boolean;
+    events: EventConfig[];
+}
+/**
+ * Anything that compiles to a plain event config — e.g. the fluent builder.
+ * The core duck-types on `build()`, so it never depends on the builder.
+ */
+interface Buildable {
+    build(): EventConfig;
+}
+/**
+ * `addGroup` input: events may be plain configs or builders (compiled on the way
+ * in). Storage is always plain configs ({@link Group}).
+ */
+interface GroupInput extends Omit<GroupConfig, "events"> {
+    events: (EventConfig | Buildable)[];
+}
+/**
+ * A shareable, portable bundle of events (a `.cdy` document is its JSON form).
+ * Inert data: a manifest of the plugins its events need + the events themselves.
+ * Load it with `cal.load()` after registering the declared plugins.
+ */
+interface Collection {
+    /** Collection name; used as the group id when `id` is omitted. */
+    collection?: string;
+    /** Collection version (semver-ish, informational). */
+    version?: string;
+    /** Plugin package names the events need — validated on load. */
+    plugins?: string[];
+    /** Group id (defaults to `collection`, else `"collection"`). */
+    id?: string;
+    /** Group display name. */
+    name?: string;
+    /** The events — plain configs (as in a `.cdy` file) or builders. */
+    events: (EventConfig | Buildable)[];
+}
+/**
+ * Internal group representation
+ */
+interface Group extends GroupConfig {
+    enabled: boolean;
+}
+
+/**
+ * Calendar event - the output after processing event configs.
+ * Extends BaseEventProperties with computed fields.
+ *
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ * @template TCategory - Category type (default: string, can be enum for type safety)
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * const event: CalendarEvent = { ... };
+ *
+ * // With typed metadata and categories
+ * interface LiturgicalMetadata { rank: string; vestmentColor: string; }
+ * type LiturgicalCategory = "solemnity" | "feast" | "memorial";
+ * const event: CalendarEvent<LiturgicalMetadata, LiturgicalCategory> = { ... };
+ * ```
+ */
+interface CalendarEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    /** Original event ID from the event config */
+    sourceEventId: string;
+    /** Date in YYYY-MM-DD format */
+    date: DateString;
+    /** Group ID this event belongs to */
+    groupId: string;
+    /** Group name (optional, for convenience) */
+    groupName?: string;
+}
+
+/**
+ * Date components - structured date representation
+ * Use this instead of string dates to prevent format errors
+ */
+interface DateComponents {
+    /** Calendar year */
+    year: number;
+    /** Month (1-12) */
+    month: number;
+    /** Day of month (1-31) */
+    day: number;
+}
+/**
+ * Base calendar day - the fundamental unit returned by getDays()
+ *
+ * This is the core day structure that plugins can extend via DayEnricher.
+ * Contains only universal calendar properties.
+ * Clients should handle formatting themselves.
+ *
+ * @template TMetadata - Custom metadata type for events
+ * @template TCategory - Category type for events
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * const day: CalendarDay = cal.getDay("2025-12-25");
+ *
+ * // With typed metadata
+ * interface LiturgicalMetadata { rank: string; }
+ * const day: CalendarDay<LiturgicalMetadata> = cal.getDay("2025-12-25");
+ * day.events[0].metadata?.rank; // TypeScript knows this exists
+ * ```
+ */
+interface CalendarDay<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends DateComponents {
+    /** Date in YYYY-MM-DD format (derived from year/month/day, for convenience) */
+    date: string;
+    /** Day of week (0=Sunday, 1=Monday, ..., 6=Saturday) */
+    dayOfWeek: number;
+    /** Events on this day, sorted by priority (highest first; can be empty) */
+    events: CalendarEvent<TMetadata, TCategory>[];
+    /** Whether this is a Sunday */
+    isSunday: boolean;
+    /** Whether this is a weekday (Monday-Saturday) */
+    isWeekday: boolean;
+}
+/**
+ * Day enricher interface - plugins implement this to add data to days
+ *
+ * @example
+ * ```typescript
+ * // Lunar plugin enricher
+ * const lunarEnricher: DayEnricher = {
+ *   name: 'lunar',
+ *   priority: 10,
+ *   enrich: (day) => ({
+ *     ...day,
+ *     lunarDate: solarToLunar(day.year, day.month, day.day)
+ *   })
+ * };
+ * ```
+ */
+interface DayEnricher {
+    /** Unique name for this enricher */
+    name: string;
+    /** Priority order (lower runs first, default: 100) */
+    priority: number;
+    /** Enrich a day with additional data */
+    enrich: (day: CalendarDay<any, any>) => CalendarDay<any, any>;
+}
+/**
+ * Options for getDays() method
+ */
+interface GetDaysOptions {
+    /** Start date (inclusive) - DateComponents or YYYY-MM-DD string */
+    from: DateComponents | string;
+    /** End date (inclusive) - DateComponents or YYYY-MM-DD string */
+    to: DateComponents | string;
+    /** Filter by group IDs (optional) */
+    groups?: string[];
+    /** Filter by event types (optional) */
+    types?: string[];
+}
+
+/**
+ * Context passed to plugins during installation
+ * (Currently empty - reserved for future use)
+ */
+interface PluginContext {
+}
+/**
+ * Event type handler - processes a specific event type
+ */
+interface EventTypeHandler {
+    validate(event: unknown): boolean;
+    generate(event: EventConfig, year: number): Date[];
+}
+/**
+ * Formula function type
+ */
+type FormulaFn = (year: number, params?: Record<string, unknown>) => Date;
+/**
+ * Calendary interface for plugins.
+ * Defines the methods plugins can use during installation.
+ * This avoids circular dependency with the actual implementation.
+ */
+interface CalendaryForPlugin {
+    use(plugin: CalendaryPlugin): this;
+    hasPlugin(name: string): boolean;
+    registerFormula(name: string, fn: FormulaFn): this;
+    registerDayEnricher(enricher: DayEnricher): this;
+    hasDayEnricher(name: string): boolean;
+    addGroup(config: GroupConfig): this;
+    removeGroup(groupId: string): this;
+}
+/**
+ * Plugin interface
+ *
+ * Plugins work with any Calendary instance regardless of its generic parameters.
+ * The install function receives a Calendary with unknown metadata/category types.
+ */
+interface CalendaryPlugin {
+    name: string;
+    version: string;
+    dependencies?: string[];
+    install(calendary: CalendaryForPlugin, context?: PluginContext): void;
+    eventTypes?: Record<string, EventTypeHandler>;
+    formulas?: Record<string, FormulaFn>;
+}
+/**
+ * Plugin factory function type
+ */
+type PluginFactory = (options?: Record<string, unknown>) => CalendaryPlugin;
+
+/**
+ * Base localizable text for any event type.
+ * Plugins extend this pattern with their own key types.
+ *
+ * @example
+ * ```typescript
+ * // Plugin defines its texts type
+ * type LiturgicalTexts = Record<MassKey, EventText>;
+ *
+ * // User provides translations
+ * const viTexts: LiturgicalTexts = {
+ *   EASTER_SUNDAY: { title: "Easter Sunday", keywords: ["easter"] },
+ *   // ...
+ * };
+ * ```
+ */
+interface EventText {
+    /** Event title (required) */
+    title: string;
+    /** Search keywords for filtering/search (optional) */
+    keywords?: string[];
+}
+
+/**
+ * Metadata query type for searching nested metadata objects.
+ * Supports deep object matching and value comparisons.
+ *
+ * @template TMetadata - Custom metadata type for type-safe queries
+ */
+type MetadataQuery<TMetadata extends Record<string, unknown> = Record<string, unknown>> = Partial<TMetadata> & {
+    [key: string]: unknown;
+};
+/**
+ * Sort field options for search results
+ */
+type SortField = "date" | "priority" | "id";
+/**
+ * Sort order options
+ */
+type SortOrder = "asc" | "desc";
+/**
+ * Enhanced search options extending basic query options
+ */
+interface SearchOptions {
+    from?: string;
+    to?: string;
+    date?: string;
+    groups?: string[];
+    search?: string;
+    titleContains?: string;
+    idContains?: string;
+    descriptionContains?: string;
+    keywordsContain?: string[];
+    categories?: string[];
+    hasAllCategories?: string[];
+    metadata?: MetadataQuery;
+    minPriority?: number;
+    maxPriority?: number;
+    sortBy?: SortField;
+    sortOrder?: SortOrder;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Fluent search builder for advanced event queries.
+ * Provides case-insensitive text search, metadata search, and more.
+ *
+ * @template TMetadata - Custom metadata type for events
+ * @template TCategory - Category type for events
+ *
+ * @example
+ * ```typescript
+ * // Get events
+ * const events = cal.search()
+ *   .text('christmas')
+ *   .categories(['holiday'])
+ *   .metadata({ season: 'advent' })
+ *   .dateFrom('2025-01-01')
+ *   .dateTo('2025-12-31')
+ *   .sortBy('date', 'asc')
+ *   .getEvents();
+ *
+ * // Get days containing matching events
+ * const days = cal.search()
+ *   .text('easter')
+ *   .getDays();
+ * ```
+ */
+declare class SearchBuilder<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> {
+    private options;
+    private executor;
+    constructor(executor: (options: SearchOptions) => CalendarEvent<TMetadata, TCategory>[]);
+    /**
+     * Search text in title and description (case-insensitive)
+     */
+    text(search: string): this;
+    /**
+     * Search text in title only (case-insensitive)
+     */
+    title(search: string): this;
+    /**
+     * Search text in id only (case-insensitive)
+     */
+    id(search: string): this;
+    /**
+     * Search text in description only (case-insensitive)
+     */
+    description(search: string): this;
+    /**
+     * Search by keywords (match any)
+     */
+    keywords(keywords: string[]): this;
+    /**
+     * Search by single keyword
+     */
+    keyword(keyword: string): this;
+    /**
+     * Filter by date range (inclusive on both ends)
+     */
+    range(from: string, to: string): this;
+    /**
+     * Filter events from this date onwards (inclusive, uses >=)
+     * @param date - Start date in YYYY-MM-DD format
+     */
+    dateFrom(date: string): this;
+    /**
+     * Filter events up to this date (inclusive, uses <=)
+     * @param date - End date in YYYY-MM-DD format
+     */
+    dateTo(date: string): this;
+    /**
+     * Filter by specific date
+     */
+    date(date: string): this;
+    /**
+     * Filter by groups
+     */
+    groups(groupIds: string[]): this;
+    /**
+     * Filter by single group
+     */
+    group(groupId: string): this;
+    /**
+     * Filter by categories (match any)
+     */
+    categories(categories: string[]): this;
+    /**
+     * Filter by category (single)
+     */
+    category(category: string): this;
+    /**
+     * Filter by categories (must have all)
+     */
+    hasAllCategories(categories: string[]): this;
+    /**
+     * Search by metadata key-value pairs.
+     * Supports nested objects and case-insensitive string matching.
+     *
+     * @example
+     * ```typescript
+     * // Simple key-value
+     * .metadata({ season: 'advent' })
+     *
+     * // Nested object
+     * .metadata({ location: { country: 'fr' } })
+     *
+     * // Multiple conditions (AND)
+     * .metadata({ rank: 'solemnity', vestmentColor: 'white' })
+     * ```
+     */
+    metadata(query: MetadataQuery<TMetadata>): this;
+    /**
+     * Filter by minimum priority (higher = more important; default 0)
+     */
+    minPriority(priority: number): this;
+    /**
+     * Filter by maximum priority (higher = more important; default 0)
+     */
+    maxPriority(priority: number): this;
+    /**
+     * Sort results by field and order
+     */
+    sortBy(field: SortField, order?: SortOrder): this;
+    /**
+     * Limit number of results
+     */
+    limit(count: number): this;
+    /**
+     * Offset results (for pagination)
+     */
+    offset(count: number): this;
+    /**
+     * Get the first matching event or undefined
+     */
+    first(): CalendarEvent<TMetadata, TCategory> | undefined;
+    /**
+     * Check if any events match the search criteria
+     */
+    exists(): boolean;
+    /**
+     * Count matching events
+     */
+    count(): number;
+    /**
+     * Get matching events with typed result.
+     * Returns only the events that match the search criteria.
+     *
+     * @returns Array of matching events
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const events = cal.search().text('christmas').getEvents();
+     *
+     * // With typed calendar (generics flow automatically)
+     * const cal = calendary<LiturgicalMetadata>();
+     * const events = cal.search().metadata({ rank: 'solemnity' }).getEvents();
+     * // events[0].metadata?.rank is typed!
+     * ```
+     */
+    getEvents(): CalendarEvent<TMetadata, TCategory>[];
+    /**
+     * Get calendar days containing matching events.
+     * Returns days with their events sorted by keyword match score (highest first),
+     * then by priority.
+     *
+     * @returns Array of calendar days containing matching events
+     *
+     * @example
+     * ```typescript
+     * // Basic usage - get days with matching events
+     * const days = cal.search().text('christmas').getDays();
+     *
+     * // With typed calendar (generics flow automatically)
+     * const cal = calendary<LiturgicalMetadata>();
+     * const days = cal.search().category('holiday').getDays();
+     * // days[0].events[0].metadata?.rank is typed!
+     * ```
+     */
+    getDays(): CalendarDay<TMetadata, TCategory>[];
+}
+
+declare const IS_CALENDARY = "$isCalendary";
+/**
+ * Check if value is a Calendary instance
+ */
+declare const isCalendary: <TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string>(d: unknown) => d is CalendaryInstance<TMetadata, TCategory>;
+/**
+ * CalendaryInstance class - the main instance
+ *
+ * @template TMetadata - Custom metadata type for events
+ * @template TCategory - Category type for events
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * const cal = calendary();
+ *
+ * // With typed metadata
+ * interface LiturgicalMetadata { rank: string; vestmentColor: string; }
+ * const cal = calendary<LiturgicalMetadata>();
+ * const day = cal.getDay("2025-12-25");
+ * day.events[0].metadata?.rank; // TypeScript knows this exists
+ * ```
+ */
+declare class CalendaryInstance<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> {
+    [IS_CALENDARY]: boolean;
+    private plugins;
+    private eventTypeHandlers;
+    private formulas;
+    private groups;
+    private cache;
+    private index;
+    private dirty;
+    private extensionData;
+    private dayEnrichers;
+    constructor(cfg?: {
+        x?: Record<string, unknown>;
+    });
+    private registerCoreHandlers;
+    /**
+     * Clone this instance
+     */
+    clone(): CalendaryInstance<TMetadata, TCategory>;
+    /**
+     * Register a plugin (Day.js style: use/extend)
+     */
+    use(plugin: CalendaryPlugin): this;
+    hasPlugin(name: string): boolean;
+    registerFormula(name: string, fn: FormulaFn): this;
+    addGroup(config: GroupInput): this;
+    /**
+     * Load a {@link Collection} — a portable bundle of events (a `.cdy` document
+     * is its JSON form). Pass an object or a JSON string. The declared plugins must
+     * already be registered (`cal.use(...)`); a clear error lists any that aren't.
+     * Nothing is fetched or executed behind your back.
+     */
+    load(collection: Collection | string): this;
+    removeGroup(groupId: string): this;
+    getGroup(groupId: string): Group | undefined;
+    getGroups(): Group[];
+    setGroupEnabled(groupId: string, enabled: boolean): this;
+    private generateEvents;
+    private createCalendarEvent;
+    getEvents(date: string): CalendarEvent<TMetadata, TCategory>[];
+    getEventsInRange(from: string, to: string): CalendarEvent<TMetadata, TCategory>[];
+    getEventsByGroup(groupId: string, from?: string, to?: string): CalendarEvent<TMetadata, TCategory>[];
+    getUpcomingEvents(days: number): CalendarEvent<TMetadata, TCategory>[];
+    /**
+     * Register a day enricher to add custom data to CalendarDay objects
+     */
+    registerDayEnricher(enricher: DayEnricher): this;
+    /**
+     * Check if a day enricher is registered
+     */
+    hasDayEnricher(name: string): boolean;
+    /**
+     * Get calendar days for a date range
+     */
+    getDays(options: GetDaysOptions): CalendarDay<TMetadata, TCategory>[];
+    /**
+     * Get a single calendar day
+     */
+    getDay(date: GetDaysOptions["from"]): CalendarDay<TMetadata, TCategory>;
+    /**
+     * Create a search builder for advanced event queries.
+     * Supports text search, metadata search, categories, and more.
+     *
+     * @example
+     * ```typescript
+     * // Search by text (case-insensitive)
+     * cal.search().text('christmas').getEvents();
+     *
+     * // Search by metadata
+     * cal.search().metadata({ season: 'advent' }).getEvents();
+     *
+     * // Combined search
+     * cal.search()
+     *   .text('easter')
+     *   .categories(['liturgical'])
+     *   .range('2025-01-01', '2025-12-31')
+     *   .sortBy('date', 'asc')
+     *   .getEvents();
+     * ```
+     */
+    search(): SearchBuilder<TMetadata, TCategory>;
+    private executeSearch;
+    invalidateCache(): this;
+}
+/**
+ * Factory function interface with generics support
+ *
+ * @template TMetadata - Custom metadata type for events
+ * @template TCategory - Category type for events
+ */
+interface CalendaryFn {
+    <TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string>(cfg?: {
+        x?: Record<string, unknown>;
+    }): CalendaryInstance<TMetadata, TCategory>;
+    isCalendary: typeof isCalendary;
+}
+/**
+ * Factory function (Day.js style) with generics support
+ *
+ * @template TMetadata - Custom metadata type for events
+ * @template TCategory - Category type for events
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * const cal = calendary();
+ *
+ * // With typed metadata
+ * interface LiturgicalMetadata { rank: string; vestmentColor: string; }
+ * const cal = calendary<LiturgicalMetadata>();
+ * const day = cal.getDay("2025-12-25");
+ * day.events[0].metadata?.rank; // TypeScript knows this exists
+ *
+ * // With typed metadata and categories
+ * type LiturgicalCategory = "solemnity" | "feast" | "memorial";
+ * const cal = calendary<LiturgicalMetadata, LiturgicalCategory>();
+ * ```
+ */
+declare const calendary: CalendaryFn;
+
+/**
+ * Format a Date object to ISO date string (YYYY-MM-DD)
+ */
+declare function formatDate(date: Date): string;
+/**
+ * Parse an ISO date string to Date object
+ */
+declare function parseDate(dateStr: string): Date;
+/**
+ * Get the year from a date string or Date object
+ */
+declare function getYear(date: string | Date): number;
+/**
+ * Add days to a date
+ */
+declare function addDays(date: Date, days: number): Date;
+/**
+ * Get the number of days between two dates
+ */
+declare function daysBetween(date1: Date, date2: Date): number;
+/**
+ * Validate if a string is a valid date in YYYY-MM-DD format.
+ * Checks both format and actual date validity.
+ *
+ * @example
+ * ```typescript
+ * isValidDateString("2025-12-25"); // true
+ * isValidDateString("2025-02-30"); // false (invalid date)
+ * isValidDateString("25-12-2025"); // false (wrong format)
+ * ```
+ */
+declare function isValidDateString(date: string): boolean;
+
+/**
+ * Replace date tokens in a template string with parts of a `YYYY-MM-DD` date.
+ * Powers per-occurrence dynamic fields (see `BaseEventProperties.templates`) —
+ * e.g. a `url` that differs per occurrence.
+ *
+ * Tokens (literal, no locale): `{YYYY}` `{MM}` `{DD}` (zero-padded) · `{M}` `{D}`
+ * (no padding). Anything else is left untouched.
+ *
+ * @example
+ * interpolateDateTokens("https://x.com/mass/{D}-{M}", "2026-07-07"); // .../mass/7-7
+ * interpolateDateTokens("https://x.com/mass/{DD}-{MM}", "2026-07-07"); // .../mass/07-07
+ */
+declare function interpolateDateTokens(template: string, date: DateString): string;
+
+/**
+ * Resolve conflict action from a ConflictResolver (function or map).
+ * Returns "keep" if resolver is undefined or date not in map.
+ *
+ * @param resolver - ConflictResolver (function or map) or undefined
+ * @param date - Date string in YYYY-MM-DD format
+ * @returns ConflictAction for the given date
+ *
+ * @example
+ * ```typescript
+ * // With function resolver
+ * const fn: ConflictResolver = (date) => ({ action: "keep" });
+ * resolveConflict(fn, "2025-01-01"); // { action: "keep" }
+ *
+ * // With map resolver
+ * const map: ConflictResolver = { "2025-01-01": { action: "drop" } };
+ * resolveConflict(map, "2025-01-01"); // { action: "drop" }
+ * resolveConflict(map, "2025-01-02"); // { action: "keep" } (default)
+ *
+ * // With undefined
+ * resolveConflict(undefined, "2025-01-01"); // { action: "keep" }
+ * ```
+ */
+declare function resolveConflict(resolver: ConflictResolver | undefined, date: DateString): ConflictAction;
+
+/**
+ * Options for merging event configurations
+ */
+interface MergeEventConfigOptions {
+    /**
+     * Fields to skip during merge (in addition to metadata which is handled separately)
+     */
+    skipFields?: string[];
+}
+/**
+ * Merge custom event configuration into base configuration.
+ * - Skips undefined, empty strings, and empty arrays
+ * - Deep merges metadata (original + custom)
+ *
+ * @param base - Base event configuration
+ * @param custom - Custom configuration to merge (can be undefined)
+ * @param options - Merge options
+ * @returns Merged configuration
+ *
+ * @example
+ * ```typescript
+ * const base = { id: "event-1", title: "Event", metadata: { a: 1, b: 2 } };
+ * const custom = { title: "Custom Event", metadata: { b: 3, c: 4 } };
+ * const result = mergeEventConfig(base, custom);
+ * // Result: { id: "event-1", title: "Custom Event", metadata: { a: 1, b: 3, c: 4 } }
+ * ```
+ */
+declare function mergeEventConfig<T extends Record<string, unknown>>(base: T, custom: Partial<T> | undefined, options?: MergeEventConfigOptions): T;
+
+export { type BaseEventProperties, type Buildable, type CalendarDay, type CalendarEvent, CalendaryInstance as Calendary, type CalendaryForPlugin, CalendaryInstance, type CalendaryPlugin, type Collection, type ConflictAction, type ConflictMap, type ConflictResolver, type ConflictResolverFn, type ConstEvent, type CoreEventConfig, type CoreEventType, type CustomEventConfig, type CustomEventResolver, type DateAnchor, type DateComponents, type DateString, type DayEnricher, type EventConfig, type EventText, type EventTypeHandler, type FixedEvent, type FormulaEvent, type FormulaFn, type GetDaysOptions, type Group, type GroupConfig, type GroupInput, type MergeEventConfigOptions, type MetadataQuery, type MonthlyEvent, type NthWeekdayEvent, type OverrideDatesMap, type PluginContext, type PluginFactory, type RelativeEvent, type Reminder, SearchBuilder, type SearchOptions, type SortField, type SortOrder, type WeekdayIndex, type WeeklyEvent, addDays, calendary, daysBetween, formatDate, getYear, interpolateDateTokens, isCalendary, isValidDateString, mergeEventConfig, parseDate, resolveConflict };