NthWeekdayEvent

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:

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

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

Extends

• BaseEventProperties<TMetadata, TCategory>

Type Parameters

TMetadata

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

Custom metadata type extending Record<string, unknown>

TCategory

TCategory extends string = string

Properties

after?

optional after?: DateAnchor

Find the first matching dayOfWeek on or after this date. When provided, nth and month are ignored.

---

allDay?

optional allDay?: boolean

Inherited from

BaseEventProperties.allDay

---

before?

optional before?: 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).

---

categories?

optional categories?: TCategory[]

Inherited from

BaseEventProperties.categories

---

color?

optional color?: string

Inherited from

BaseEventProperties.color

---

dayOfWeek

dayOfWeek: 0 | 1 | 2 | 3 | 4 | 5 | 6

Day of the week (0=Sunday, 1=Monday, …, 6=Saturday)

Example

0 // Sunday

---

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

---

endYear?

optional endYear?: number

Last year the event applies (inclusive).

---

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

---

excludeYears?

optional excludeYears?: number[]

Years to skip entirely.

---

fallback?

optional fallback?: DateAnchor

Fallback date used when no dayOfWeek is found between after and before (inclusive). Only meaningful when before is also set.

---

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

---

month?

optional month?: number

Month (1-12). In simple mode, omit to repeat every month (e.g. the first Monday of every month); set it to pin one month (e.g. the 4th Thursday of November). Ignored in anchored mode.

---

nth?

optional nth?: 1 | 2 | 3 | 4 | -1

Which occurrence within the month:

• 1–4: 1st through 4th occurrence
• -1: last occurrence

Required in simple mode. Omit for anchored mode.

---

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

---

startYear?

optional startYear?: number

First year the event applies (inclusive).

---

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: "nth-weekday"

---

url?

optional url?: string

Inherited from

BaseEventProperties.url