SearchBuilder

Fluent search builder for advanced event queries. Provides case-insensitive text search, metadata search, and more.

Example

// Get events
const events = cal.search()
  .text('christmas')
  .categories(['holiday'])
  .metadata({ season: 'advent' })
  .dateFrom('2025-01-01')
  .dateTo('2025-12-31')
  .sortBy('date', 'asc')
  .getEvents();

// Get days containing matching events
const days = cal.search()
  .text('easter')
  .getDays();

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 SearchBuilder<TMetadata, TCategory>(executor): SearchBuilder<TMetadata, TCategory>

Parameters

executor

(options) => CalendarEvent<TMetadata, TCategory>[]

Returns

SearchBuilder<TMetadata, TCategory>

Methods

categories()

categories(categories): this

Filter by categories (match any)

Parameters

Returns

this

category()

category(category): this

Filter by category (single)

Parameters

Returns

this

count()

count(): number

Count matching events

Returns

number

date()

date(date): this

Filter by specific date

Parameters

date

string

Returns

this

dateFrom()

dateFrom(date): this

Filter events from this date onwards (inclusive, uses >=)

Parameters

date

string

Start date in YYYY-MM-DD format

Returns

this

dateTo()

dateTo(date): this

Filter events up to this date (inclusive, uses <=)

Parameters

date

string

End date in YYYY-MM-DD format

Returns

this

description()

description(search): this

Search text in description only (case-insensitive)

Parameters

search

string

Returns

this

exists()

exists(): boolean

Check if any events match the search criteria

Returns

boolean

first()

first(): CalendarEvent<TMetadata, TCategory> | undefined

Get the first matching event or undefined

Returns

CalendarEvent<TMetadata, TCategory> | undefined

getDays()

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

Get calendar days containing matching events. Returns days with their events sorted by keyword match score (highest first), then by priority.

Returns

CalendarDay<TMetadata, TCategory>[]

Array of calendar days containing matching events

Example

// Basic usage - get days with matching events
const days = cal.search().text('christmas').getDays();

// With typed calendar (generics flow automatically)
const cal = calendary<LiturgicalMetadata>();
const days = cal.search().category('holiday').getDays();
// days[0].events[0].metadata?.rank is typed!

getEvents()

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

Get matching events with typed result. Returns only the events that match the search criteria.

Returns

CalendarEvent<TMetadata, TCategory>[]

Array of matching events

Example

// Basic usage
const events = cal.search().text('christmas').getEvents();

// With typed calendar (generics flow automatically)
const cal = calendary<LiturgicalMetadata>();
const events = cal.search().metadata({ rank: 'solemnity' }).getEvents();
// events[0].metadata?.rank is typed!

group()

group(groupId): this

Filter by single group

Parameters

groupId

string

Returns

this

groups()

groups(groupIds): this

Filter by groups

Parameters

groupIds

string[]

Returns

this

hasAllCategories()

hasAllCategories(categories): this

Filter by categories (must have all)

Parameters

Returns

this

id()

id(search): this

Search text in id only (case-insensitive)

Parameters

search

string

Returns

this

keyword()

keyword(keyword): this

Search by single keyword

Parameters

keyword

string

Returns

this

keywords()

keywords(keywords): this

Search by keywords (match any)

Parameters

keywords

string[]

Returns

this

limit()

limit(count): this

Limit number of results

Parameters

count

number

Returns

this

maxPriority()

maxPriority(priority): this

Filter by maximum priority (higher = more important; default 0)

Parameters

priority

number

Returns

this

metadata()

metadata(query): this

Search by metadata key-value pairs. Supports nested objects and case-insensitive string matching.

Parameters

query

MetadataQuery<TMetadata>

Returns

this

Example

// Simple key-value
.metadata({ season: 'advent' })

// Nested object
.metadata({ location: { country: 'fr' } })

// Multiple conditions (AND)
.metadata({ rank: 'solemnity', vestmentColor: 'white' })

minPriority()

minPriority(priority): this

Filter by minimum priority (higher = more important; default 0)

Parameters

priority

number

Returns

this

offset()

offset(count): this

Offset results (for pagination)

Parameters

count

number

Returns

this

range()

range(from, to): this

Filter by date range (inclusive on both ends)

Parameters

from

string

to

string

Returns

this

sortBy()

sortBy(field, order?): this

Sort results by field and order

Parameters

field

SortField

order?

SortOrder = "asc"

Returns

this

source()

source(…source): this

Filter by source — match any (the plugin / feed / subscription that produced it).

Parameters

source

…string[]

Returns

this

status()

status(…status): this

Filter by status — match any (e.g. hide cancelled by listing the ones you want).

Parameters

status

…("confirmed" | "tentative" | "cancelled")[]

Returns

this

text()

text(search): this

Search text in title and description (case-insensitive)

Parameters

search

string

Returns

this

title()

title(search): this

Search text in title only (case-insensitive)

Parameters

search

string

Returns

this

type()

type(…types): this

Filter by event type(s) — match any (e.g. "weekly", "daily", a plugin type).

Parameters

types

…string[]

Returns

this