RelativeEvent

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 } }

Extends

• BaseEventProperties<TMetadata, TCategory>

Type Parameters

TMetadata

TMetadata extends Record<string, unknown> = Record<string, unknown>

TCategory

TCategory extends string = string

Properties

allDay?

optional allDay?: boolean

Inherited from

BaseEventProperties.allDay

---

anchor

anchor: string

Name of a registered anchor resolver (year → Date).

---

categories?

optional categories?: TCategory[]

Inherited from

BaseEventProperties.categories

---

color?

optional color?: string

Inherited from

BaseEventProperties.color

---

description?

optional description?: string

Inherited from

BaseEventProperties.description

---

duration?

optional duration?: number

Inherited from

BaseEventProperties.duration

---

endDate?

optional endDate?: string

Inherited from

BaseEventProperties.endDate

---

endTime?

optional endTime?: string

Inherited from

BaseEventProperties.endTime

---

exceptions?

optional exceptions?: 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

BaseEventProperties.exceptions

---

icon?

optional icon?: string

Inherited from

BaseEventProperties.icon

---

id

id: string

Inherited from

BaseEventProperties.id

---

keywords?

optional keywords?: string[]

Inherited from

BaseEventProperties.keywords

---

location?

optional location?: string

Inherited from

BaseEventProperties.location

---

metadata?

optional metadata?: TMetadata

Inherited from

BaseEventProperties.metadata

---

offset

offset: object

Offset from the anchor date.

days?

optional days?: number

weeks?

optional weeks?: number

---

onConflict?

optional onConflict?: 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

BaseEventProperties.onConflict

---

overrideDates?

optional overrideDates?: 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

overrideDates: {
  "2026-02-18": "2026-02-20",  // Move from Feb 18 to Feb 20
}

Inherited from

BaseEventProperties.overrideDates

---

priority?

optional priority?: 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

BaseEventProperties.priority

---

reminders?

optional reminders?: Reminder[]

Inherited from

BaseEventProperties.reminders

---

source?

optional source?: 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

BaseEventProperties.source

---

startDate?

optional startDate?: 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

// Weekly stand-up, but only for July 2026
{ type: "weekly", id: "standup", dayOfWeek: 1,
  startDate: "2026-07-01", endDate: "2026-07-31" }

Inherited from

BaseEventProperties.startDate

---

startTime?

optional startTime?: string

Inherited from

BaseEventProperties.startTime

---

status?

optional status?: "confirmed" | "tentative" | "cancelled"

Inherited from

BaseEventProperties.status

---

templates?

optional templates?: 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

// 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

Inherited from

BaseEventProperties.templates

---

title

title: string

Inherited from

BaseEventProperties.title

---

type

type: "relative"

---

url?

optional url?: string

Inherited from

BaseEventProperties.url