CalendaryInstance

CalendaryInstance class - the main instance

Example

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

Type Parameters

TMetadata

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

Custom metadata type for events

TCategory

TCategory extends string = string

Category type for events

Constructors

Constructor

new CalendaryInstance<TMetadata, TCategory>(cfg?): CalendaryInstance<TMetadata, TCategory>

Parameters

cfg?

x?

Record<string, unknown>

Returns

CalendaryInstance<TMetadata, TCategory>

Properties

$isCalendary

$isCalendary: boolean = true

Methods

addGroup()

addGroup(config): this

Parameters

config

GroupInput

Returns

this

---

clone()

clone(): CalendaryInstance<TMetadata, TCategory>

Clone this instance

Returns

CalendaryInstance<TMetadata, TCategory>

---

getDay()

getDay(date): CalendarDay<TMetadata, TCategory>

Get a single calendar day

Parameters

date

string | DateComponents

Returns

CalendarDay<TMetadata, TCategory>

---

getDays()

getDays(options): CalendarDay<TMetadata, TCategory>[]

Get calendar days for a date range

Parameters

options

GetDaysOptions

Returns

CalendarDay<TMetadata, TCategory>[]

---

getEvents()

getEvents(date): CalendarEvent<TMetadata, TCategory>[]

Parameters

date

string

Returns

CalendarEvent<TMetadata, TCategory>[]

---

getEventsByGroup()

getEventsByGroup(groupId, from?, to?): CalendarEvent<TMetadata, TCategory>[]

Parameters

groupId

string

from?

string

to?

string

Returns

CalendarEvent<TMetadata, TCategory>[]

---

getEventsInRange()

getEventsInRange(from, to): CalendarEvent<TMetadata, TCategory>[]

Parameters

from

string

to

string

Returns

CalendarEvent<TMetadata, TCategory>[]

---

getGroup()

getGroup(groupId): Group | undefined

Parameters

groupId

string

Returns

Group | undefined

---

getGroups()

getGroups(): Group[]

Returns

Group[]

---

getUpcomingEvents()

getUpcomingEvents(days): CalendarEvent<TMetadata, TCategory>[]

Parameters

days

number

Returns

CalendarEvent<TMetadata, TCategory>[]

---

hasDayEnricher()

hasDayEnricher(name): boolean

Check if a day enricher is registered

Parameters

name

string

Returns

boolean

---

hasPlugin()

hasPlugin(name): boolean

Parameters

name

string

Returns

boolean

---

invalidateCache()

invalidateCache(): this

Returns

this

---

load()

load(collection): this

Load a 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.

Parameters

collection

string | Collection

Returns

this

---

registerDayEnricher()

registerDayEnricher(enricher): this

Register a day enricher to add custom data to CalendarDay objects

Parameters

enricher

DayEnricher

Returns

this

---

registerFormula()

registerFormula(name, fn): this

Parameters

name

string

fn

FormulaFn

Returns

this

---

removeGroup()

removeGroup(groupId): this

Parameters

groupId

string

Returns

this

---

search()

search(): SearchBuilder<TMetadata, TCategory>

Create a search builder for advanced event queries. Supports text search, metadata search, categories, and more.

Returns

SearchBuilder<TMetadata, TCategory>

Example

// 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();

---

setGroupEnabled()

setGroupEnabled(groupId, enabled): this

Parameters

groupId

string

enabled

boolean

Returns

this

---

toCollection()

toCollection(options?): Collection

Export events as a portable Collection — the inverse of load. Serializes the plain event configs plus a manifest of the plugins their event types need, so the result round-trips back through load(). Pass it to JSON.stringify for a .cdy document.

Parameters

options?

group?

string

export a single group; omit to export every group’s events.

name?

string

the collection name (also the default group id on re-load).

version?

string

an informational version stamp.

Returns

Collection

---

use()

use(plugin): this

Register a plugin (use/extend)

Parameters

plugin

CalendaryPlugin

Returns

this