calendaryjs 0.2.1 → 0.2.3

package/dist/events-Bm7R9XFB.d.cts

@@ -0,0 +1,590 @@
+/**
+ * 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;
+
+export type { BaseEventProperties as B, ConflictResolver as C, DateString as D, EventConfig as E, FixedEvent as F, MonthlyEvent as M, NthWeekdayEvent as N, OverrideDatesMap as O, RelativeEvent as R, WeekdayIndex as W, ConflictAction as a, ConflictMap as b, ConflictResolverFn as c, ConstEvent as d, CoreEventConfig as e, CoreEventType as f, CustomEventConfig as g, CustomEventResolver as h, DateAnchor as i, FormulaEvent as j, Reminder as k, WeeklyEvent as l };