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

add()

add(…events): this

Add events without the group ceremony — they land in a shared "events" group. Repeated calls accumulate; pass builders or plain configs.

Parameters

events

…(Buildable | EventConfig)[]

Returns

this

Example

cal.add(
  weekly("monday").title("Gym"),
  yearly(12, 25).title("Christmas"),
);

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>[]

All occurrences in [from, to] (both inclusive), globally sorted: date ascending, then priority descending (higher = on top), across every year in the range — not just within a year. Ties keep generation order (stable). A consumer can render the list directly without re-sorting.

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[]

getSkipped()

getSkipped(range): SkippedOccurrence<TMetadata>[]

Occurrences that WOULD have fallen in the range but were removed by an exceptions skip (ICS EXDATE) — so a consumer can render them (e.g. a struck-through “ghost”) without re-reading the event store. Moved occurrences carry CalendarEvent.movedFrom on the normal output instead.

Parameters

range

from

string

to

string

Returns

SkippedOccurrence<TMetadata>[]

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(input, options?): this

Load a Collection — a portable bundle of events (a .cdy document is its JSON form) — or a CollectionBundle carrying several named collections, expanded into one group each (id/priority/color preserved). Pass an object or a JSON string. Declared plugins must already be registered (cal.use(...)); a clear error lists any that aren’t. Nothing is fetched or executed behind your back.

options.priority overrides the priority of a single collection; for a bundle each collection keeps its own (that’s the point of a bundle).

Parameters

input

string | Collection | CollectionBundle

options?

priority?

number

Returns

this

registerAnchor()

registerAnchor(name, fn): this

Register a named anchor — a year → Date resolver that relative events (the builder’s from(anchor).plus(...)) offset from. Anchors share the formula registry; this is the anchor-flavoured name for the same call.

Parameters

name

string

fn

FormulaFn

Returns

this

registerDayEnricher()

registerDayEnricher(enricher): this

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

requiredPlugins()

requiredPlugins(events?): string[]

The npm names of the registered plugins whose event types appear in events — the minimal manifest a consumer must install + use(). Defaults to every loaded event. This is the derivation toCollection uses, exposed so you don’t re-implement a “plugins for these events” helper.

Parameters

events?

EventConfig[]

events to inspect (default: all loaded events, across groups).

Returns

string[]

search()

search(): SearchBuilder<TMetadata, TCategory>

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

Every search needs a bounded window — recurrences are infinite, so “search everything” has no meaning. Set it with .range(from, to), .date(date), .year(y), or .month(y, m).

Returns

SearchBuilder<TMetadata, TCategory>

Example

// Search by text (case-insensitive), within a year
cal.search().text('christmas').year(2026).getEvents();

// Search by metadata
cal.search().metadata({ season: 'advent' }).year(2026).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

toBundle()

toBundle(options?): SerializedCollectionBundle

Export every group as a SerializedCollectionBundle — one collection per group, each keeping its id / name / priority / color and its own plugin manifest. The inverse of load() on a bundle; round-trips several named, independently-styled collections through a single .cdy file (unlike toCollection, which flattens every group’s events into one collection).

Parameters

options?

schema?

string

version?

string

Returns

SerializedCollectionBundle

toCollection()

toCollection(options?): SerializedCollection

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

SerializedCollection

use()

use(plugin): this

Parameters

plugin

CalendaryPlugin

Returns

this