ConstEvent
CONST - Fixed annual events (e.g., Christmas on Dec 25) Supports year exclusions and date range constraints.
Example
Section titled “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 }Extends
Section titled “Extends”BaseEventProperties<TMetadata,TCategory>
Type Parameters
Section titled “Type Parameters”TMetadata
Section titled “TMetadata”TMetadata extends Record<string, unknown> = Record<string, unknown>
Custom metadata type extending Record<string, unknown>
TCategory
Section titled “TCategory”TCategory extends string = string
Properties
Section titled “Properties”allDay?
Section titled “allDay?”
optionalallDay?:boolean
Inherited from
Section titled “Inherited from”categories?
Section titled “categories?”
optionalcategories?:TCategory[]
Inherited from
Section titled “Inherited from”BaseEventProperties.categories
color?
Section titled “color?”
optionalcolor?:string
Inherited from
Section titled “Inherited from”count?
Section titled “count?”
optionalcount?:number
End the series after this many occurrences (ICS RRULE;COUNT, an
alternative to endDate/UNTIL). Applied centrally during generation, so
it works for ANY event type — core or plugin.
Counting starts at the series’ beginning, so the event must declare one:
a startDate or a startYear. Occurrences are counted on their natural
computed dates — the event’s own exclusions (excludeDates,
excludeYears, …) shrink the series before counting, while per-occurrence
exceptions and reschedules (overrideDates, onConflict) apply after and
don’t change how many occurrences exist.
Example
Section titled “Example”// A 10-session course, every Tuesday from Sep 1{ type: "weekly", id: "course", dayOfWeek: 2, startDate: "2026-09-01", count: 10 }Inherited from
Section titled “Inherited from”day:
number
Day of the month. 1–31, or negative to count from the end
(-1 = last day, -2 = second-to-last).
Examples
Section titled “Examples”25 // 25th day-1 // last day of the monthdescription?
Section titled “description?”
optionaldescription?:string
Inherited from
Section titled “Inherited from”BaseEventProperties.description
duration?
Section titled “duration?”
optionalduration?:number
Inherited from
Section titled “Inherited from”endDate?
Section titled “endDate?”
optionalendDate?:string
Inherited from
Section titled “Inherited from”endTime?
Section titled “endTime?”
optionalendTime?:string
Inherited from
Section titled “Inherited from”endYear?
Section titled “endYear?”
optionalendYear?:number
Last year the event occurs (inclusive)
Example
Section titled “Example”2030 // End at 2030exceptions?
Section titled “exceptions?”
optionalexceptions?:EventExceptions
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.
Inherited from
Section titled “Inherited from”BaseEventProperties.exceptions
excludeYears?
Section titled “excludeYears?”
optionalexcludeYears?:number[]
Years to exclude from recurrence
Example
Section titled “Example”[2025, 2040, 2043] // Skip these years
optionalicon?:string
Inherited from
Section titled “Inherited from”id:
string
Inherited from
Section titled “Inherited from”interval?
Section titled “interval?”
optionalinterval?:number
Recurrence interval in years (default: 1). With interval > 1 the event
needs a startYear to phase the cadence from (occurs when
(year - startYear) % interval === 0).
Example
Section titled “Example”2 // Every other yearkeepOrdinals?
Section titled “keepOrdinals?”
optionalkeepOrdinals?:number[]
Emit only the listed anniversary ordinals — occurrenceYear - (origin ?? startYear). e.g. [1, 5, 10] fires only the +1/+5/+10 years. Requires
origin or startYear; mutually exclusive with interval.
Example
Section titled “Example”[1, 5, 10, 15, 20, 25] // milestone anniversaries onlykeywords?
Section titled “keywords?”
optionalkeywords?:string[]
Inherited from
Section titled “Inherited from”location?
Section titled “location?”
optionallocation?:string
Inherited from
Section titled “Inherited from”metadata?
Section titled “metadata?”
optionalmetadata?:TMetadata
Arbitrary consumer data, carried through untouched onto every output CalendarEvent (and SkippedOccurrence) for round-tripping your own domain object. On output, present exactly when the source config set it.
Inherited from
Section titled “Inherited from”month:
number
Month of the event (1-12)
Example
Section titled “Example”12 // DecemberonConflict?
Section titled “onConflict?”
optionalonConflict?:ConflictResolver
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
Inherited from
Section titled “Inherited from”BaseEventProperties.onConflict
onMissingDay?
Section titled “onMissingDay?”
optionalonMissingDay?:"overflow"|"clamp"|"skip"
Policy when a positive day doesn’t exist that period (Feb 29, day 31 in a
30-day month). "overflow" spills into the next month (default, unchanged),
"clamp" uses the month’s last valid day, "skip" emits nothing that period.
Negative days already resolve to a last-relative day and are unaffected.
Default
Section titled “Default”"overflow"origin?
Section titled “origin?”
optionalorigin?:number
Anniversary anchor year. An occurrence’s ordinal (surfaced on the computed
event) and keepOrdinals are counted as occurrenceYear - origin. Defaults
to startYear when omitted.
Example
Section titled “Example”2010 // wedding year → 2015 is ordinal 5overrideDates?
Section titled “overrideDates?”
optionaloverrideDates?:OverrideDatesMap
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
Section titled “Example”overrideDates: { "2026-02-18": "2026-02-20", // Move from Feb 18 to Feb 20}Inherited from
Section titled “Inherited from”BaseEventProperties.overrideDates
priority?
Section titled “priority?”
optionalpriority?:number
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).
Inherited from
Section titled “Inherited from”reminders?
Section titled “reminders?”
optionalreminders?:Reminder[]
Inherited from
Section titled “Inherited from”source?
Section titled “source?”
optionalsource?: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).
Inherited from
Section titled “Inherited from”startDate?
Section titled “startDate?”
optionalstartDate?:string
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
Section titled “Example”// Weekly stand-up, but only for July 2026{ type: "weekly", id: "standup", dayOfWeek: 1, startDate: "2026-07-01", endDate: "2026-07-31" }Inherited from
Section titled “Inherited from”startTime?
Section titled “startTime?”
optionalstartTime?:string
Inherited from
Section titled “Inherited from”startYear?
Section titled “startYear?”
optionalstartYear?:number
First year the event occurs (inclusive)
Example
Section titled “Example”2020 // Start from 2020status?
Section titled “status?”
optionalstatus?:"confirmed"|"tentative"|"cancelled"
Inherited from
Section titled “Inherited from”templates?
Section titled “templates?”
optionaltemplates?:Record<string,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
Section titled “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-7Inherited from
Section titled “Inherited from”title:
string
Inherited from
Section titled “Inherited from”type:
"const"
optionalurl?:string