calendaryjs 0.2.0

package/dist/index.js

@@ -0,0 +1,1341 @@
+// src/cache/event-cache.ts
+var EventCache = class {
+  cache = /* @__PURE__ */ new Map();
+  /**
+   * Get cached events or compute and cache them
+   */
+  getOrCompute(key, computeFn) {
+    if (!this.cache.has(key)) {
+      this.cache.set(key, computeFn());
+    }
+    return this.cache.get(key);
+  }
+  /**
+   * Set cached events
+   */
+  set(key, events) {
+    this.cache.set(key, events);
+  }
+  /**
+   * Get cached events if available
+   */
+  get(key) {
+    return this.cache.get(key);
+  }
+  /**
+   * Check if key exists in cache
+   */
+  has(key) {
+    return this.cache.has(key);
+  }
+  /**
+   * Invalidate cache entry or entire cache
+   */
+  invalidate(key) {
+    if (key) {
+      this.cache.delete(key);
+    } else {
+      this.cache.clear();
+    }
+  }
+  /**
+   * Get all cached keys
+   */
+  keys() {
+    return Array.from(this.cache.keys());
+  }
+  /**
+   * Get cache size
+   */
+  get size() {
+    return this.cache.size;
+  }
+};
+
+// src/utils/date.ts
+function formatDate(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+function parseDate(dateStr) {
+  const [year, month, day] = dateStr.split("-").map(Number);
+  return new Date(year, month - 1, day);
+}
+function getYear(date) {
+  if (typeof date === "string") {
+    return parseInt(date.split("-")[0], 10);
+  }
+  return date.getFullYear();
+}
+function isDateInRange(date, from, to) {
+  return date >= from && date <= to;
+}
+function getYearsInRange(from, to) {
+  const fromYear = getYear(from);
+  const toYear = getYear(to);
+  const years = [];
+  for (let year = fromYear; year <= toYear; year++) {
+    years.push(year);
+  }
+  return years;
+}
+function createDate(year, month, day) {
+  return new Date(year, month - 1, day);
+}
+function addDays(date, days) {
+  const result = new Date(date);
+  result.setDate(result.getDate() + days);
+  return result;
+}
+function today() {
+  return formatDate(/* @__PURE__ */ new Date());
+}
+function daysFromToday(days) {
+  return formatDate(addDays(/* @__PURE__ */ new Date(), days));
+}
+function daysBetween(date1, date2) {
+  const oneDay = 24 * 60 * 60 * 1e3;
+  return Math.round((date2.getTime() - date1.getTime()) / oneDay);
+}
+function normalizeDateInput(input) {
+  if (typeof input === "string") {
+    return input;
+  }
+  const month = String(input.month).padStart(2, "0");
+  const day = String(input.day).padStart(2, "0");
+  return `${input.year}-${month}-${day}`;
+}
+function normalizeDateToDate(input) {
+  if (typeof input === "string") {
+    return parseDate(input);
+  }
+  return new Date(input.year, input.month - 1, input.day);
+}
+function isValidDateString(date) {
+  const match = /^\d{4}-\d{2}-\d{2}$/.exec(date);
+  if (!match) return false;
+  const d = new Date(date);
+  return !isNaN(d.getTime()) && d.toISOString().startsWith(date);
+}
+
+// src/generators/const.ts
+var constEventHandler = {
+  validate(event) {
+    if (typeof event !== "object" || event === null) return false;
+    const e = event;
+    return e.type === "const" && typeof e.month === "number" && e.month >= 1 && e.month <= 12 && typeof e.day === "number" && e.day >= 1 && e.day <= 31 && typeof e.title === "string" && typeof e.id === "string";
+  },
+  generate(event, year) {
+    if (event.startYear !== void 0 && year < event.startYear) {
+      return [];
+    }
+    if (event.endYear !== void 0 && year > event.endYear) {
+      return [];
+    }
+    if (event.excludeYears?.includes(year)) {
+      return [];
+    }
+    return [createDate(year, event.month, event.day)];
+  }
+};
+
+// src/generators/fixed.ts
+var fixedEventHandler = {
+  validate(event) {
+    if (typeof event !== "object" || event === null) return false;
+    const e = event;
+    return e.type === "fixed" && typeof e.year === "number" && typeof e.month === "number" && e.month >= 1 && e.month <= 12 && typeof e.day === "number" && e.day >= 1 && e.day <= 31 && typeof e.title === "string" && typeof e.id === "string";
+  },
+  generate(event, year) {
+    if (event.year !== year) {
+      return [];
+    }
+    return [createDate(event.year, event.month, event.day)];
+  }
+};
+
+// src/generators/monthly.ts
+function getDaysInMonth(year, month) {
+  return new Date(year, month, 0).getDate();
+}
+var monthlyEventHandler = {
+  validate(event) {
+    if (typeof event !== "object" || event === null) return false;
+    const e = event;
+    return e.type === "monthly" && typeof e.day === "number" && e.day >= 1 && e.day <= 31 && typeof e.title === "string" && typeof e.id === "string";
+  },
+  generate(event, year) {
+    const dates = [];
+    const interval = event.interval ?? 1;
+    const startMonth = event.startMonth ?? 1;
+    for (let month = 1; month <= 12; month++) {
+      if (interval > 1) {
+        const monthOffset = month - startMonth;
+        const normalizedOffset = (monthOffset % 12 + 12) % 12;
+        if (normalizedOffset % interval !== 0) {
+          continue;
+        }
+      }
+      if (event.excludeMonths?.includes(month)) {
+        continue;
+      }
+      const daysInMonth = getDaysInMonth(year, month);
+      if (event.day > daysInMonth) {
+        continue;
+      }
+      const date = createDate(year, month, event.day);
+      const dateStr = formatDate(date);
+      if (event.excludeDates?.includes(dateStr)) {
+        continue;
+      }
+      dates.push(date);
+    }
+    return dates;
+  }
+};
+
+// src/generators/weekly.ts
+function getFirstDayOfWeekInYear(year, dayOfWeek) {
+  const jan1 = createDate(year, 1, 1);
+  const jan1DayOfWeek = jan1.getDay();
+  const daysUntilTarget = (dayOfWeek - jan1DayOfWeek + 7) % 7;
+  return addDays(jan1, daysUntilTarget);
+}
+function weekStart(date) {
+  return addDays(date, -date.getDay());
+}
+function weekdays(dayOfWeek) {
+  const list = Array.isArray(dayOfWeek) ? dayOfWeek : [dayOfWeek];
+  return [...new Set(list)].sort((a, b) => a - b);
+}
+function isWeekdayIndex(d) {
+  return typeof d === "number" && d >= 0 && d <= 6;
+}
+var weeklyEventHandler = {
+  validate(event) {
+    if (typeof event !== "object" || event === null) return false;
+    const e = event;
+    const dow = e.dayOfWeek;
+    const validDays = Array.isArray(dow) ? dow.length > 0 && dow.every(isWeekdayIndex) : isWeekdayIndex(dow);
+    return e.type === "weekly" && validDays && typeof e.title === "string" && typeof e.id === "string";
+  },
+  generate(event, year) {
+    const days = weekdays(event.dayOfWeek);
+    if (days.length === 0) return [];
+    const interval = event.interval ?? 1;
+    const yearEnd = createDate(year, 12, 31);
+    const startDateLimit = event.startDate ? parseDate(event.startDate) : null;
+    const endDateLimit = event.endDate ? parseDate(event.endDate) : null;
+    const referenceWeek = weekStart(startDateLimit ?? getFirstDayOfWeekInYear(year, days[0]));
+    const seen = /* @__PURE__ */ new Set();
+    const dates = [];
+    for (const day of days) {
+      let currentDate = getFirstDayOfWeekInYear(year, day);
+      while (currentDate <= yearEnd) {
+        const dateStr = formatDate(currentDate);
+        if (startDateLimit && currentDate < startDateLimit) {
+          currentDate = addDays(currentDate, 7);
+          continue;
+        }
+        if (endDateLimit && currentDate > endDateLimit) {
+          break;
+        }
+        if (interval > 1) {
+          const weeksFromReference = Math.round(
+            daysBetween(referenceWeek, weekStart(currentDate)) / 7
+          );
+          if (weeksFromReference < 0 || weeksFromReference % interval !== 0) {
+            currentDate = addDays(currentDate, 7);
+            continue;
+          }
+        }
+        if (!event.excludeDates?.includes(dateStr) && !seen.has(dateStr)) {
+          seen.add(dateStr);
+          dates.push(new Date(currentDate));
+        }
+        currentDate = addDays(currentDate, 7);
+      }
+    }
+    dates.sort((a, b) => a.getTime() - b.getTime());
+    return dates;
+  }
+};
+
+// src/generators/nth-weekday.ts
+function nthWeekdayInMonth(year, month, dayOfWeek, nth) {
+  if (nth === -1) {
+    const lastDay = new Date(year, month, 0).getDate();
+    for (let d = lastDay; d >= 1; d--) {
+      const date = createDate(year, month, d);
+      if (date.getDay() === dayOfWeek) return date;
+    }
+    return null;
+  }
+  let count = 0;
+  const daysInMonth = new Date(year, month, 0).getDate();
+  for (let d = 1; d <= daysInMonth; d++) {
+    const date = createDate(year, month, d);
+    if (date.getDay() === dayOfWeek) {
+      count++;
+      if (count === nth) return date;
+    }
+  }
+  return null;
+}
+function firstWeekdayOnOrAfter(year, anchor, dayOfWeek) {
+  for (let offset = 0; offset <= 6; offset++) {
+    const date = createDate(year, anchor.month, anchor.day + offset);
+    if (date.getDay() === dayOfWeek) return date;
+  }
+  return null;
+}
+function anchorToDate(year, anchor) {
+  return createDate(year, anchor.month, anchor.day);
+}
+var nthWeekdayEventHandler = {
+  validate(event) {
+    if (typeof event !== "object" || event === null) return false;
+    const e = event;
+    if (e.type !== "nth-weekday") return false;
+    if (typeof e.id !== "string" || typeof e.title !== "string") return false;
+    if (typeof e.dayOfWeek !== "number" || e.dayOfWeek < 0 || e.dayOfWeek > 6) return false;
+    const hasSimple = e.nth !== void 0 || e.month !== void 0;
+    const hasAnchored = e.after !== void 0;
+    if (hasSimple && !hasAnchored) {
+      if (typeof e.nth !== "number" || ![1, 2, 3, 4, -1].includes(e.nth)) return false;
+      if (typeof e.month !== "number" || e.month < 1 || e.month > 12)
+        return false;
+    } else if (!hasAnchored) {
+      return false;
+    }
+    return true;
+  },
+  generate(event, year) {
+    if (event.startYear !== void 0 && year < event.startYear) return [];
+    if (event.endYear !== void 0 && year > event.endYear) return [];
+    if (event.excludeYears?.includes(year)) return [];
+    if (event.after !== void 0) {
+      const candidate = firstWeekdayOnOrAfter(year, event.after, event.dayOfWeek);
+      if (event.before !== void 0) {
+        const beforeDate = anchorToDate(year, event.before);
+        if (candidate === null || candidate >= beforeDate) {
+          if (event.fallback !== void 0) {
+            return [anchorToDate(year, event.fallback)];
+          }
+          return [];
+        }
+      }
+      return candidate ? [candidate] : [];
+    }
+    if (event.nth !== void 0 && event.month !== void 0) {
+      const date = nthWeekdayInMonth(year, event.month, event.dayOfWeek, event.nth);
+      return date ? [date] : [];
+    }
+    return [];
+  }
+};
+
+// src/generators/formula.ts
+function createFormulaEventHandler(getFormula) {
+  return {
+    validate(event) {
+      if (typeof event !== "object" || event === null) return false;
+      const e = event;
+      return e.type === "formula" && typeof e.formula === "string" && typeof e.title === "string" && typeof e.id === "string";
+    },
+    generate(event, year) {
+      const formula = getFormula(event.formula);
+      if (!formula) {
+        throw new Error(
+          `Formula "${event.formula}" is not registered. Register it before generating events.`
+        );
+      }
+      return [formula(year, event.params)];
+    }
+  };
+}
+
+// src/generators/relative.ts
+function createRelativeEventHandler(getAnchor) {
+  return {
+    validate(event) {
+      if (typeof event !== "object" || event === null) return false;
+      const e = event;
+      return e.type === "relative" && typeof e.anchor === "string" && typeof e.id === "string" && typeof e.title === "string";
+    },
+    generate(event, year) {
+      const resolve = getAnchor(event.anchor);
+      if (!resolve) {
+        throw new Error(
+          `Anchor "${event.anchor}" is not registered. Register it (e.g. cal.registerFormula) before generating events.`
+        );
+      }
+      const base = resolve(year);
+      const days = (event.offset.days ?? 0) + (event.offset.weeks ?? 0) * 7;
+      return [addDays(base, days)];
+    }
+  };
+}
+
+// src/query/event-index.ts
+var EventIndex = class {
+  byDate = /* @__PURE__ */ new Map();
+  byGroup = /* @__PURE__ */ new Map();
+  allEvents = [];
+  constructor(events = []) {
+    this.index(events);
+  }
+  /**
+   * Index events for fast lookups
+   */
+  index(events) {
+    this.allEvents = events;
+    this.byDate.clear();
+    this.byGroup.clear();
+    for (const event of events) {
+      const dateEvents = this.byDate.get(event.date) || [];
+      dateEvents.push(event);
+      this.byDate.set(event.date, dateEvents);
+      const groupEvents = this.byGroup.get(event.groupId) || [];
+      groupEvents.push(event);
+      this.byGroup.set(event.groupId, groupEvents);
+    }
+  }
+  /**
+   * Query events by date
+   */
+  queryByDate(date) {
+    return this.byDate.get(date) || [];
+  }
+  /**
+   * Query events by group
+   */
+  queryByGroup(groupId) {
+    return this.byGroup.get(groupId) || [];
+  }
+  /**
+   * Query events in date range
+   */
+  queryByDateRange(from, to) {
+    return this.allEvents.filter((event) => event.date >= from && event.date <= to);
+  }
+  /**
+   * Get all indexed events
+   */
+  getAll() {
+    return this.allEvents;
+  }
+  /**
+   * Get count of indexed events
+   */
+  get size() {
+    return this.allEvents.length;
+  }
+};
+
+// src/query/search-builder.ts
+var SPECIAL_CHAR_MAP = {
+  \u0111: "d",
+  \u0110: "D",
+  \u0142: "l",
+  \u0141: "L",
+  \u00F8: "o",
+  \u00D8: "O",
+  \u00DF: "ss",
+  \u00E6: "ae",
+  \u00C6: "AE",
+  \u0153: "oe",
+  \u0152: "OE"
+};
+function normalizeText(text) {
+  let result = text;
+  for (const [char, replacement] of Object.entries(SPECIAL_CHAR_MAP)) {
+    result = result.replaceAll(char, replacement);
+  }
+  return result.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase();
+}
+function normalizeTextCompact(text) {
+  return normalizeText(text).replace(/\s+/g, "");
+}
+function parseDatePattern(search) {
+  const match = search.match(/^(\d{1,2})[/\-.](\d{1,2})$/);
+  if (!match) return null;
+  const num1 = parseInt(match[1], 10);
+  const num2 = parseInt(match[2], 10);
+  if (num1 >= 1 && num1 <= 31 && num2 >= 1 && num2 <= 12) {
+    return { day: num1, month: num2 };
+  }
+  if (num1 >= 1 && num1 <= 12 && num2 >= 1 && num2 <= 31) {
+    return { day: num2, month: num1 };
+  }
+  return null;
+}
+function matchesDatePattern(event, datePattern) {
+  const [, month, day] = event.date.split("-").map(Number);
+  return day === datePattern.day && month === datePattern.month;
+}
+function containsTextFuzzy(text, search) {
+  if (!text) return false;
+  const textLower = text.toLowerCase();
+  const searchLower = search.toLowerCase();
+  if (textLower.includes(searchLower)) {
+    return true;
+  }
+  const textNormalized = normalizeText(text);
+  const searchNormalized = normalizeText(search);
+  if (textNormalized.includes(searchNormalized)) {
+    return true;
+  }
+  const textCompact = normalizeTextCompact(text);
+  const searchCompact = normalizeTextCompact(search);
+  return textCompact.includes(searchCompact);
+}
+function matchesMetadata(metadata, query) {
+  if (!metadata) return false;
+  for (const [key, queryValue] of Object.entries(query)) {
+    const metadataValue = metadata[key];
+    if (queryValue !== null && typeof queryValue === "object" && !Array.isArray(queryValue)) {
+      if (typeof metadataValue !== "object" || metadataValue === null || Array.isArray(metadataValue)) {
+        return false;
+      }
+      if (!matchesMetadata(metadataValue, queryValue)) {
+        return false;
+      }
+    } else if (Array.isArray(queryValue)) {
+      if (!queryValue.includes(metadataValue)) {
+        return false;
+      }
+    } else if (typeof queryValue === "string" && typeof metadataValue === "string") {
+      if (!metadataValue.toLowerCase().includes(queryValue.toLowerCase())) {
+        return false;
+      }
+    } else {
+      if (metadataValue !== queryValue) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+function compareEvents(a, b, sortBy, sortOrder) {
+  let comparison = 0;
+  switch (sortBy) {
+    case "date":
+      comparison = a.date.localeCompare(b.date);
+      break;
+    case "priority":
+      comparison = (a.priority ?? 0) - (b.priority ?? 0);
+      break;
+    case "id":
+      comparison = a.id.localeCompare(b.id);
+      break;
+  }
+  return sortOrder === "desc" ? -comparison : comparison;
+}
+var SearchBuilder = class {
+  options = {};
+  executor;
+  constructor(executor) {
+    this.executor = executor;
+  }
+  /**
+   * Search text in title and description (case-insensitive)
+   */
+  text(search) {
+    this.options.search = search;
+    return this;
+  }
+  /**
+   * Search text in title only (case-insensitive)
+   */
+  title(search) {
+    this.options.titleContains = search;
+    return this;
+  }
+  /**
+   * Search text in id only (case-insensitive)
+   */
+  id(search) {
+    this.options.idContains = search;
+    return this;
+  }
+  /**
+   * Search text in description only (case-insensitive)
+   */
+  description(search) {
+    this.options.descriptionContains = search;
+    return this;
+  }
+  /**
+   * Search by keywords (match any)
+   */
+  keywords(keywords) {
+    this.options.keywordsContain = keywords;
+    return this;
+  }
+  /**
+   * Search by single keyword
+   */
+  keyword(keyword) {
+    this.options.keywordsContain = [keyword];
+    return this;
+  }
+  /**
+   * Filter by date range (inclusive on both ends)
+   */
+  range(from, to) {
+    this.options.from = from;
+    this.options.to = to;
+    return this;
+  }
+  /**
+   * Filter events from this date onwards (inclusive, uses >=)
+   * @param date - Start date in YYYY-MM-DD format
+   */
+  dateFrom(date) {
+    this.options.from = date;
+    return this;
+  }
+  /**
+   * Filter events up to this date (inclusive, uses <=)
+   * @param date - End date in YYYY-MM-DD format
+   */
+  dateTo(date) {
+    this.options.to = date;
+    return this;
+  }
+  /**
+   * Filter by specific date
+   */
+  date(date) {
+    this.options.date = date;
+    return this;
+  }
+  /**
+   * Filter by groups
+   */
+  groups(groupIds) {
+    this.options.groups = groupIds;
+    return this;
+  }
+  /**
+   * Filter by single group
+   */
+  group(groupId) {
+    this.options.groups = [groupId];
+    return this;
+  }
+  /**
+   * Filter by categories (match any)
+   */
+  categories(categories) {
+    this.options.categories = categories;
+    return this;
+  }
+  /**
+   * Filter by category (single)
+   */
+  category(category) {
+    this.options.categories = [category];
+    return this;
+  }
+  /**
+   * Filter by categories (must have all)
+   */
+  hasAllCategories(categories) {
+    this.options.hasAllCategories = categories;
+    return this;
+  }
+  /**
+   * Search by metadata key-value pairs.
+   * Supports nested objects and case-insensitive string matching.
+   *
+   * @example
+   * ```typescript
+   * // Simple key-value
+   * .metadata({ season: 'advent' })
+   *
+   * // Nested object
+   * .metadata({ location: { country: 'fr' } })
+   *
+   * // Multiple conditions (AND)
+   * .metadata({ rank: 'solemnity', vestmentColor: 'white' })
+   * ```
+   */
+  metadata(query) {
+    this.options.metadata = { ...this.options.metadata, ...query };
+    return this;
+  }
+  /**
+   * Filter by minimum priority (higher = more important; default 0)
+   */
+  minPriority(priority) {
+    this.options.minPriority = priority;
+    return this;
+  }
+  /**
+   * Filter by maximum priority (higher = more important; default 0)
+   */
+  maxPriority(priority) {
+    this.options.maxPriority = priority;
+    return this;
+  }
+  /**
+   * Sort results by field and order
+   */
+  sortBy(field, order = "asc") {
+    this.options.sortBy = field;
+    this.options.sortOrder = order;
+    return this;
+  }
+  /**
+   * Limit number of results
+   */
+  limit(count) {
+    this.options.limit = count;
+    return this;
+  }
+  /**
+   * Offset results (for pagination)
+   */
+  offset(count) {
+    this.options.offset = count;
+    return this;
+  }
+  /**
+   * Get the first matching event or undefined
+   */
+  first() {
+    this.options.limit = 1;
+    const results = this.getEvents();
+    return results[0];
+  }
+  /**
+   * Check if any events match the search criteria
+   */
+  exists() {
+    this.options.limit = 1;
+    return this.getEvents().length > 0;
+  }
+  /**
+   * Count matching events
+   */
+  count() {
+    const savedLimit = this.options.limit;
+    const savedOffset = this.options.offset;
+    this.options.limit = void 0;
+    this.options.offset = void 0;
+    const count = this.getEvents().length;
+    this.options.limit = savedLimit;
+    this.options.offset = savedOffset;
+    return count;
+  }
+  /**
+   * Get matching events with typed result.
+   * Returns only the events that match the search criteria.
+   *
+   * @returns Array of matching events
+   *
+   * @example
+   * ```typescript
+   * // 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!
+   * ```
+   */
+  getEvents() {
+    return this.executor(this.options);
+  }
+  /**
+   * Get calendar days containing matching events.
+   * Returns days with their events sorted by keyword match score (highest first),
+   * then by priority.
+   *
+   * @returns Array of calendar days containing matching events
+   *
+   * @example
+   * ```typescript
+   * // 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!
+   * ```
+   */
+  getDays() {
+    const events = this.executor(this.options);
+    const searchKeywords = this.options.keywordsContain ?? [];
+    const searchText = this.options.search?.trim().toLowerCase();
+    const eventsByDate = /* @__PURE__ */ new Map();
+    for (const event of events) {
+      const existing = eventsByDate.get(event.date);
+      if (existing) {
+        existing.push(event);
+      } else {
+        eventsByDate.set(event.date, [event]);
+      }
+    }
+    const days = [];
+    for (const [date, dayEvents] of eventsByDate) {
+      const [year, month, day] = date.split("-").map(Number);
+      const dateObj = new Date(year, month - 1, day);
+      const dayOfWeek = dateObj.getDay();
+      const sortedEvents = dayEvents.sort((a, b) => {
+        const scoreA = calculateKeywordMatchScore(a, searchKeywords, searchText);
+        const scoreB = calculateKeywordMatchScore(b, searchKeywords, searchText);
+        if (scoreB !== scoreA) {
+          return scoreB - scoreA;
+        }
+        return (b.priority ?? 0) - (a.priority ?? 0);
+      });
+      days.push({
+        date,
+        year,
+        month,
+        day,
+        dayOfWeek,
+        isSunday: dayOfWeek === 0,
+        isWeekday: dayOfWeek >= 1 && dayOfWeek <= 6,
+        events: sortedEvents
+      });
+    }
+    days.sort((a, b) => a.date.localeCompare(b.date));
+    return days;
+  }
+};
+function calculateKeywordMatchScore(event, searchKeywords, searchText) {
+  let score = 0;
+  const eventKeywords = event.keywords ?? [];
+  for (const searchKw of searchKeywords) {
+    const searchNormalized = normalizeText(searchKw);
+    for (const eventKw of eventKeywords) {
+      const eventNormalized = normalizeText(eventKw);
+      if (eventNormalized === searchNormalized) {
+        score += 3;
+      } else if (eventNormalized.includes(searchNormalized)) {
+        score += 1;
+      }
+    }
+  }
+  if (searchText) {
+    const searchNormalized = normalizeText(searchText);
+    for (const eventKw of eventKeywords) {
+      const eventNormalized = normalizeText(eventKw);
+      if (eventNormalized === searchNormalized) {
+        score += 3;
+      } else if (eventNormalized.includes(searchNormalized)) {
+        score += 1;
+      }
+    }
+    const titleNormalized = normalizeText(event.title);
+    if (titleNormalized.includes(searchNormalized)) {
+      score += 2;
+    }
+  }
+  return score;
+}
+function executeSearch(events, options) {
+  let results = [...events];
+  if (options.date) {
+    results = results.filter((e) => e.date === options.date);
+  } else {
+    if (options.from) {
+      results = results.filter((e) => e.date >= options.from);
+    }
+    if (options.to) {
+      results = results.filter((e) => e.date <= options.to);
+    }
+  }
+  if (options.groups && options.groups.length > 0) {
+    results = results.filter((e) => options.groups.includes(e.groupId));
+  }
+  if (options.search) {
+    const search = options.search.trim();
+    const datePattern = parseDatePattern(search);
+    if (datePattern) {
+      results = results.filter((e) => matchesDatePattern(e, datePattern));
+    } else {
+      results = results.filter(
+        (e) => containsTextFuzzy(e.title, search) || containsTextFuzzy(e.id, search) || containsTextFuzzy(e.description, search) || e.keywords && e.keywords.some((k) => containsTextFuzzy(k, search))
+      );
+    }
+  }
+  if (options.titleContains) {
+    results = results.filter((e) => containsTextFuzzy(e.title, options.titleContains));
+  }
+  if (options.idContains) {
+    results = results.filter((e) => containsTextFuzzy(e.id, options.idContains));
+  }
+  if (options.descriptionContains) {
+    results = results.filter((e) => containsTextFuzzy(e.description, options.descriptionContains));
+  }
+  if (options.keywordsContain && options.keywordsContain.length > 0) {
+    results = results.filter((e) => {
+      if (!e.keywords) return false;
+      return options.keywordsContain.some((kw) => e.keywords.some((k) => containsTextFuzzy(k, kw)));
+    });
+  }
+  if (options.categories && options.categories.length > 0) {
+    results = results.filter((e) => {
+      if (!e.categories) return false;
+      return options.categories.some((cat) => e.categories.includes(cat));
+    });
+  }
+  if (options.hasAllCategories && options.hasAllCategories.length > 0) {
+    results = results.filter((e) => {
+      if (!e.categories) return false;
+      return options.hasAllCategories.every((cat) => e.categories.includes(cat));
+    });
+  }
+  if (options.metadata) {
+    results = results.filter((e) => matchesMetadata(e.metadata, options.metadata));
+  }
+  if (options.minPriority !== void 0) {
+    results = results.filter((e) => (e.priority ?? 0) >= options.minPriority);
+  }
+  if (options.maxPriority !== void 0) {
+    results = results.filter((e) => (e.priority ?? 0) <= options.maxPriority);
+  }
+  if (options.sortBy) {
+    const sortOrder = options.sortOrder ?? "asc";
+    results.sort((a, b) => compareEvents(a, b, options.sortBy, sortOrder));
+  }
+  if (options.offset && options.offset > 0) {
+    results = results.slice(options.offset);
+  }
+  if (options.limit && options.limit > 0) {
+    results = results.slice(0, options.limit);
+  }
+  return results;
+}
+
+// src/utils/conflict.ts
+var DEFAULT_ACTION = { action: "keep" };
+function resolveConflict(resolver, date) {
+  if (!resolver) {
+    return DEFAULT_ACTION;
+  }
+  if (typeof resolver === "function") {
+    return resolver(date);
+  }
+  return resolver[date] ?? DEFAULT_ACTION;
+}
+
+// src/utils/id.ts
+function generateEventId(sourceEventId, date) {
+  return `${sourceEventId}:${date}`;
+}
+
+// src/utils/template.ts
+function interpolateDateTokens(template, date) {
+  const [y, m, d] = date.split("-");
+  const tokens = {
+    YYYY: y,
+    MM: m,
+    DD: d,
+    M: String(Number(m)),
+    D: String(Number(d))
+  };
+  return template.replace(/\{(YYYY|MM|DD|M|D)\}/g, (_match, token) => tokens[token]);
+}
+
+// src/core.ts
+var IS_CALENDARY = "$isCalendary";
+var PASSTHROUGH_KEYS = [
+  "keywords",
+  "allDay",
+  "startTime",
+  "endTime",
+  "duration",
+  "description",
+  "location",
+  "url",
+  "source",
+  "categories",
+  "priority",
+  "status",
+  "icon",
+  "metadata",
+  "reminders"
+];
+var isCalendary = (d) => d instanceof CalendaryInstance || !!(d && d[IS_CALENDARY]);
+var isBuildable = (e) => typeof e.build === "function";
+var CalendaryInstance = class _CalendaryInstance {
+  [IS_CALENDARY] = true;
+  plugins = /* @__PURE__ */ new Map();
+  eventTypeHandlers = /* @__PURE__ */ new Map();
+  formulas = /* @__PURE__ */ new Map();
+  groups = /* @__PURE__ */ new Map();
+  cache = new EventCache();
+  index = new EventIndex();
+  dirty = true;
+  extensionData = {};
+  dayEnrichers = [];
+  constructor(cfg = {}) {
+    this.extensionData = cfg.x || {};
+    this.registerCoreHandlers();
+  }
+  registerCoreHandlers() {
+    this.eventTypeHandlers.set("const", constEventHandler);
+    this.eventTypeHandlers.set("fixed", fixedEventHandler);
+    this.eventTypeHandlers.set("monthly", monthlyEventHandler);
+    this.eventTypeHandlers.set("weekly", weeklyEventHandler);
+    this.eventTypeHandlers.set("nth-weekday", nthWeekdayEventHandler);
+    this.eventTypeHandlers.set(
+      "formula",
+      createFormulaEventHandler((name) => this.formulas.get(name))
+    );
+    this.eventTypeHandlers.set(
+      "relative",
+      createRelativeEventHandler((name) => this.formulas.get(name))
+    );
+  }
+  /**
+   * Clone this instance
+   */
+  clone() {
+    const cloned = new _CalendaryInstance({
+      x: { ...this.extensionData }
+    });
+    cloned.plugins = new Map(this.plugins);
+    cloned.eventTypeHandlers = new Map(this.eventTypeHandlers);
+    cloned.formulas = new Map(this.formulas);
+    cloned.groups = new Map(this.groups);
+    cloned.dayEnrichers = [...this.dayEnrichers];
+    return cloned;
+  }
+  /**
+   * Register a plugin (Day.js style: use/extend)
+   */
+  use(plugin) {
+    for (const dep of plugin.dependencies || []) {
+      if (!this.plugins.has(dep)) {
+        throw new Error(`Plugin "${plugin.name}" requires "${dep}"`);
+      }
+    }
+    if (plugin.eventTypes) {
+      for (const [type, handler] of Object.entries(plugin.eventTypes)) {
+        this.eventTypeHandlers.set(type, handler);
+      }
+    }
+    if (plugin.formulas) {
+      for (const [name, fn] of Object.entries(plugin.formulas)) {
+        this.formulas.set(name, fn);
+      }
+    }
+    const context = {};
+    plugin.install(this, context);
+    this.plugins.set(plugin.name, plugin);
+    this.dirty = true;
+    return this;
+  }
+  hasPlugin(name) {
+    return this.plugins.has(name);
+  }
+  registerFormula(name, fn) {
+    this.formulas.set(name, fn);
+    this.dirty = true;
+    return this;
+  }
+  addGroup(config) {
+    const events = config.events.map((e) => isBuildable(e) ? e.build() : e);
+    const group = {
+      ...config,
+      events,
+      enabled: config.enabled ?? true
+    };
+    for (const event of group.events) {
+      if (!this.eventTypeHandlers.has(event.type)) {
+        throw new Error(
+          `Event type "${event.type}" is not supported. Did you forget to register a plugin?`
+        );
+      }
+    }
+    this.groups.set(group.id, group);
+    this.dirty = true;
+    return this;
+  }
+  /**
+   * Load a {@link 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.
+   */
+  load(collection) {
+    const c = typeof collection === "string" ? JSON.parse(collection) : collection;
+    const missing = (c.plugins ?? []).filter((name) => !this.hasPlugin(name));
+    if (missing.length > 0) {
+      const which = c.collection ? `"${c.collection}" ` : "";
+      throw new Error(
+        `Collection ${which}requires plugin(s) not registered: ${missing.join(", ")}. Install them and call cal.use(...) before loading.`
+      );
+    }
+    return this.addGroup({
+      id: c.id ?? c.collection ?? "collection",
+      name: c.name,
+      events: c.events
+    });
+  }
+  removeGroup(groupId) {
+    this.groups.delete(groupId);
+    this.dirty = true;
+    return this;
+  }
+  getGroup(groupId) {
+    return this.groups.get(groupId);
+  }
+  getGroups() {
+    return Array.from(this.groups.values());
+  }
+  setGroupEnabled(groupId, enabled) {
+    const group = this.groups.get(groupId);
+    if (group) {
+      group.enabled = enabled;
+      this.dirty = true;
+    }
+    return this;
+  }
+  generateEvents(from, to) {
+    const cacheKey = `${from}:${to}`;
+    if (!this.dirty && this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey);
+    }
+    const events = [];
+    const years = getYearsInRange(from, to);
+    for (const group of this.groups.values()) {
+      if (!group.enabled) continue;
+      for (const eventConfig of group.events) {
+        const handler = this.eventTypeHandlers.get(eventConfig.type);
+        if (!handler) continue;
+        const directives = eventConfig;
+        for (const year of years) {
+          const dates = handler.generate(eventConfig, year);
+          for (const date of dates) {
+            let dateStr = formatDate(date);
+            if (directives.startDate && dateStr < directives.startDate) continue;
+            if (directives.endDate && dateStr > directives.endDate) continue;
+            const exception = directives.exceptions?.[dateStr];
+            if (exception && "skip" in exception) {
+              continue;
+            }
+            const override = exception && "override" in exception ? exception.override : void 0;
+            const rescheduled = directives.overrideDates?.[dateStr];
+            if (rescheduled) {
+              dateStr = rescheduled;
+            }
+            if (directives.onConflict) {
+              const conflictAction = resolveConflict(directives.onConflict, dateStr);
+              if (conflictAction.action === "drop") {
+                continue;
+              }
+              if (conflictAction.action === "reschedule" && conflictAction.to) {
+                dateStr = conflictAction.to;
+              }
+            }
+            if (!isDateInRange(dateStr, from, to)) continue;
+            const calendarEvent = this.createCalendarEvent(
+              eventConfig,
+              group,
+              dateStr,
+              override
+            );
+            events.push(calendarEvent);
+          }
+        }
+      }
+    }
+    events.sort((a, b) => {
+      const dateCompare = a.date.localeCompare(b.date);
+      if (dateCompare !== 0) return dateCompare;
+      return (b.priority ?? 0) - (a.priority ?? 0);
+    });
+    this.cache.set(cacheKey, events);
+    this.index.index(events);
+    this.dirty = false;
+    return events;
+  }
+  createCalendarEvent(config, group, dateStr, override) {
+    const base = config;
+    const event = {
+      id: generateEventId(base.id, dateStr),
+      sourceEventId: base.id,
+      title: base.title,
+      date: dateStr,
+      groupId: group.id
+    };
+    const target = event;
+    for (const key of PASSTHROUGH_KEYS) {
+      const value = base[key];
+      if (value !== void 0) target[key] = value;
+    }
+    if (group.name) event.groupName = group.name;
+    const color = base.color ?? group.color;
+    if (color) event.color = color;
+    if (base.templates) {
+      for (const [key, tpl] of Object.entries(base.templates)) {
+        target[key] = interpolateDateTokens(tpl, dateStr);
+      }
+    }
+    if (override) Object.assign(event, override);
+    return event;
+  }
+  getEvents(date) {
+    return this.search().date(date).getEvents();
+  }
+  getEventsInRange(from, to) {
+    return this.search().range(from, to).getEvents();
+  }
+  getEventsByGroup(groupId, from, to) {
+    const builder = this.search().group(groupId);
+    if (from && to) {
+      builder.range(from, to);
+    }
+    return builder.getEvents();
+  }
+  getUpcomingEvents(days) {
+    return this.search().range(today(), daysFromToday(days)).getEvents();
+  }
+  /**
+   * Register a day enricher to add custom data to CalendarDay objects
+   */
+  registerDayEnricher(enricher) {
+    this.dayEnrichers.push(enricher);
+    this.dayEnrichers.sort((a, b) => a.priority - b.priority);
+    return this;
+  }
+  /**
+   * Check if a day enricher is registered
+   */
+  hasDayEnricher(name) {
+    return this.dayEnrichers.some((e) => e.name === name);
+  }
+  /**
+   * Get calendar days for a date range
+   */
+  getDays(options) {
+    const { groups } = options;
+    const fromStr = normalizeDateInput(options.from);
+    const toStr = normalizeDateInput(options.to);
+    let events = this.generateEvents(fromStr, toStr);
+    if (groups && groups.length > 0) {
+      events = events.filter((e) => groups.includes(e.groupId));
+    }
+    const eventsByDate = /* @__PURE__ */ new Map();
+    for (const event of events) {
+      const existing = eventsByDate.get(event.date) || [];
+      existing.push(event);
+      eventsByDate.set(event.date, existing);
+    }
+    const days = [];
+    const startDate = normalizeDateToDate(options.from);
+    const endDate = normalizeDateToDate(options.to);
+    const current = new Date(startDate);
+    while (current <= endDate) {
+      const dateStr = formatDate(current);
+      const dayOfWeek = current.getDay();
+      const dayEvents = eventsByDate.get(dateStr) || [];
+      dayEvents.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+      let day = {
+        date: dateStr,
+        year: current.getFullYear(),
+        month: current.getMonth() + 1,
+        day: current.getDate(),
+        dayOfWeek,
+        events: dayEvents,
+        isSunday: dayOfWeek === 0,
+        isWeekday: dayOfWeek !== 0
+      };
+      for (const enricher of this.dayEnrichers) {
+        day = enricher.enrich(day);
+      }
+      days.push(day);
+      current.setDate(current.getDate() + 1);
+    }
+    return days;
+  }
+  /**
+   * Get a single calendar day
+   */
+  getDay(date) {
+    const days = this.getDays({ from: date, to: date });
+    return days[0];
+  }
+  /**
+   * Create a search builder for advanced event queries.
+   * Supports text search, metadata search, categories, and more.
+   *
+   * @example
+   * ```typescript
+   * // 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();
+   * ```
+   */
+  search() {
+    return new SearchBuilder(
+      (options) => this.executeSearch(options)
+    );
+  }
+  executeSearch(options) {
+    const from = options.date ?? options.from ?? "1970-01-01";
+    const to = options.date ?? options.to ?? "2100-12-31";
+    const events = this.generateEvents(from, to);
+    return executeSearch(events, options);
+  }
+  invalidateCache() {
+    this.cache.invalidate();
+    this.dirty = true;
+    return this;
+  }
+};
+var calendary = function(cfg) {
+  return new CalendaryInstance(cfg);
+};
+calendary.isCalendary = isCalendary;
+
+// src/utils/merge.ts
+function shouldSkipValue(value) {
+  if (value === void 0) return true;
+  if (value === "") return true;
+  if (Array.isArray(value) && value.length === 0) return true;
+  return false;
+}
+function mergeEventConfig(base, custom, options = {}) {
+  if (!custom) return base;
+  const { skipFields = [] } = options;
+  const result = { ...base };
+  const { metadata: customMetadata, ...customFields } = custom;
+  for (const [key, value] of Object.entries(customFields)) {
+    if (skipFields.includes(key)) continue;
+    if (shouldSkipValue(value)) continue;
+    result[key] = value;
+  }
+  if (customMetadata && typeof customMetadata === "object" && Object.keys(customMetadata).length > 0) {
+    const baseMetadata = base.metadata;
+    result.metadata = {
+      ...baseMetadata,
+      ...customMetadata
+    };
+  }
+  return result;
+}
+
+export { CalendaryInstance as Calendary, CalendaryInstance, SearchBuilder, addDays, calendary, daysBetween, formatDate, getYear, interpolateDateTokens, isCalendary, isValidDateString, mergeEventConfig, parseDate, resolveConflict };