@happyvertical/smrt-events

Infinite-nesting event hierarchy with series, participant tracking, and recurrence patterns. Events can model anything from conferences with sessions to sports games with periods and goals.

Installation

pnpm add @happyvertical/smrt-events

Usage

Hierarchical events with participants

import { EventCollection, EventSeriesCollection, EventParticipantCollection } from '@happyvertical/smrt-events';

const events = await EventCollection.create();

// Create a game with nested periods
const game = await events.create({
  name: 'Lakers vs Warriors',
  slug: 'lakers-warriors-2024-01-20',
  startDate: new Date('2024-01-20T19:30:00'),
  endDate: new Date('2024-01-20T22:00:00'),
  status: 'scheduled',
  placeId: 'arena-id', // plain string FK to smrt-places
});

const quarter = await events.create({
  name: '1st Quarter',
  parentId: game.id, // infinite nesting (via SmrtHierarchical)
  startDate: new Date('2024-01-20T19:30:00'),
});

// Hierarchy traversal
const hierarchy = await quarter.getHierarchy();
console.log(hierarchy.ancestors.map(e => e.name)); // ['Lakers vs Warriors']

// Add participants with roles and placement
const participants = await EventParticipantCollection.create();
await participants.create({
  eventId: game.id,
  profileId: 'lakers-id', // plain string FK to smrt-profiles
  role: 'home',
  placement: 0,
});

// Recurring series
const series = await EventSeriesCollection.create();
await series.create({
  name: 'Weekly Standup',
  slug: 'weekly-standup-2024',
  recurrence: { frequency: 'weekly', interval: 1, byDay: ['MO', 'WE', 'FR'] },
});

All-day events, time zones, and recurrence expansion

Event.allDay marks whole-day events (startDate is local midnight of the first day, endDate the exclusive midnight after the last day) and Event.timeZone is the IANA zone the event is scheduled in (empty inherits from the series, place, or site).

expandRecurrence(pattern, { start, rangeStart, rangeEnd, timeZone }) turns a RecurrencePattern (object or stored JSON) into occurrence start instants. It supports frequency daily/weekly/monthly/yearly, interval, byDay (weekly day lists; monthly ordinals like 2TU or -1FR), byMonthDay (negative counts from the month end), byMonth, bySetPos, inclusive until, and count (counted from start). The start's wall-clock time is kept in timeZone (default pattern.timeZone, then UTC), so a 19:00 meeting stays at 19:00 across daylight-saving changes. EventSeries.getOccurrences() wraps it with the series' startDate/endDate.

import { expandRecurrence } from '@happyvertical/smrt-events';

// Council meets the second Tuesday at 19:00 Edmonton time
const october = expandRecurrence(
  { frequency: 'monthly', byDay: ['2TU'] },
  {
    start: new Date('2026-01-14T02:00:00Z'), // Jan 13 19:00 MST
    rangeStart: new Date('2026-10-01T00:00:00Z'),
    rangeEnd: new Date('2026-11-01T00:00:00Z'),
    timeZone: 'America/Edmonton',
  },
);

Owned assets

import { AssetCollection } from '@happyvertical/smrt-assets';

const assets = await AssetCollection.create();
const hero = await assets.create({
  name: 'launch-poster.jpg',
  sourceUri: 'file:///tmp/launch-poster.jpg',
  mimeType: 'image/jpeg',
});

await game.addAsset(hero, 'hero');
await events.addAsset(game.id!, hero, 'gallery', 1);

const heroAssets = await game.getAssets('hero');
const galleryAssets = await events.getAssets(game.id!, 'gallery');

API

Models

| Export | Description | |--------|------------| | Event | Hierarchical event with status lifecycle, STI enabled. Links to series, type, place via string IDs; allDay and IANA timeZone fields | | EventSeries | Recurring event group with recurrence patterns (daily/weekly/monthly/yearly) | | EventType | Classification with JSON schema for custom fields per type | | EventParticipant | Junction linking profiles to events with role, placement, and groupId | | EventAsset | Dedicated owned-asset join stored in event_assets with relationship and sortOrder |

Collections

| Export | Description | |--------|------------| | EventCollection | CRUD + hierarchy traversal for events | | EventAssetCollection | Direct access to event_assets rows plus asset helper wrappers | | EventSeriesCollection | CRUD for event series | | EventTypeCollection | CRUD for event types | | EventParticipantCollection | CRUD for participants (conflictColumns: event_id, profile_id, role) |

Types

| Export | Description | |--------|------------| | EventOptions, EventSeriesOptions, EventTypeOptions, EventParticipantOptions | Creation option types for each model | | EventStatus | 'scheduled' \| 'in_progress' \| 'completed' \| 'cancelled' \| 'postponed' | | ParticipantRole | Role values (speaker, home, away, organizer, etc.) | | RecurrenceFrequency | 'daily' \| 'weekly' \| 'monthly' \| 'yearly' | | RecurrencePattern | Recurrence definition with count, until, byDay, byMonth filters | | EventSearchFilters, EventSeriesSearchFilters, ParticipantSearchFilters | Query filter types |

Utilities

| Export | Description | |--------|------------| | formatEventDateRange | Format start/end dates as human-readable string | | generateEventSlug | Create URL-friendly slug from name + date | | checkSchedulingConflict | Detect overlapping time ranges | | calculateDuration | Duration in milliseconds between two dates | | formatDuration | Human-readable duration (e.g., "2h 30m") | | isEventNow | Check if event is currently in progress | | getEventStatusFromDates | Auto-detect status from start/end dates | | sortEventsByDate | Sort events chronologically | | validateEventStatus | Validate status transition is allowed | | calculateNextOccurrence | Next date for a recurrence pattern (host-local arithmetic; prefer expandRecurrence) | | expandRecurrence | Time-zone-aware occurrence instants for a pattern within a window | | toZonedWallTime / fromZonedWallTime | Convert between an instant and wall-clock fields in an IANA zone | | isValidTimeZone | Check an IANA zone name against the runtime's Intl data | | parseRecurrencePattern | Parse recurrence from string or object |

UI Metadata

| Export | Description | |--------|------------| | EVENTS_MODULE_META | Module metadata for UI registration | | EVENTS_UI_SLOTS | UI slot definitions for the events module |

Instance Methods (Event)

getParent(), getChildren(), getAncestors(), getDescendants(), getRootEvent(), getHierarchy() -- hierarchy traversal on any Event instance.

Owned asset helpers are available on both Event and EventCollection via getAssets(), addAsset(), and removeAsset(). Common relationships include hero, gallery, attachment, and thumbnail.

Dependencies

| Package | Purpose | |---------|---------| | @happyvertical/smrt-core | SmrtObject/SmrtCollection base classes | | @happyvertical/smrt-tenancy | Optional tenant scoping | | @happyvertical/smrt-places | Place references (cross-package string FKs) | | @happyvertical/smrt-profiles | Participant profile references (cross-package string FKs) | | @happyvertical/smrt-types | Shared TypeScript types | | @happyvertical/sql | Database operations | | @happyvertical/ai | AI integration |

iCalendar source synchronization

parseICalendarEvents(source, ics, { floatingTimeZone?, limits? }) validates caller-supplied RFC 5545 text through the published @happyvertical/icalendar facade. expandICalendarEvents(source, ics, options) adds a required inclusive rangeStart/rangeEnd window. syncICalendarSource({ db, source, ics, tenantId?, parse?, expansion? }) persists those records and returns created, updated, unchanged, and retainedOnOmission: true. Recurring feeds require expansion. Parsing/expansion require no database or network; sync supports SQLite and PostgreSQL with migrated Event/EventSeries schemas. Other dialects are not currently supported (EventSeries FK gap #3469); runtime-schema adapters are rejected before mutation.

A tenant, source and UID identify a series. Its expanded occurrences use the original RECURRENCE-ID (UTC ISO instant for timed events, calendar date for all-day events), so a moved instance retains its ID. Non-recurring records use UID without an occurrence suffix. Recurring masters live in series/provenance; they are not duplicate Event rows alongside their first occurrence. RDATE is normalized using each RDATE property's own timezone and unioned with RRULE, duplicate instants collapse, and EXDATE slots persist as cancelled events. Detached records override their original slot, including a move beyond the requested window. Duplicate VEVENT identities reject the feed.

Daily, weekly, monthly and yearly RRULEs use the SDK's public recurrence engine. The supported bounded subset is daily without BY filters; weekly BYDAY without ordinals; monthly BYDAY or BYMONTHDAY (not both), with BYSETPOS supported only for BYDAY; and yearly BYMONTH/BYMONTHDAY. Other BY combinations reject rather than risking unbounded search inside the recurrence engine. COUNT, UNTIL and INTERVAL apply throughout. Expansion rejects rather than truncates when it exceeds limit (default 1,000; maximum 10,000) or maxIterations (default 10,000; maximum 100,000, including slots before the window). Unsupported frequency, unknown recurrence properties, multiple RRULEs, EXRULE, DURATION, RDATE PERIOD and RECURRENCE-ID RANGE reject. SDK parser resource limits remain in force. Expand a practical window near the series start; very old or dense feeds may need a deliberate higher scan budget.

IANA zones use the runtime's timezone database and the framework's wall-time conversion: DST gaps move forward and overlaps choose the first instant. UTC values stay UTC. Floating timed values require parse.floatingTimeZone (or the same option directly on parse/expand); no host zone is inferred. All-day DATEs use that policy or UTC, with exclusive DTEND and a default next-day end. A timed event without DTEND has zero duration. Timed recurrence keeps the exact elapsed duration of DTSTART to DTEND; all-day recurrence keeps calendar-day duration across DST. Date-only recurrence remains date-only.

A higher SEQUENCE or a newer DTSTAMP accepts an update; equal/older versions are unchanged. Missing SEQUENCE is zero and missing DTSTAMP is the oldest stamp. A producer changing payload without either version marker is deliberately ignored. Each series retains the authoritative master's SDK-serialized document and version, including when a requested window contains no occurrences. Later windows expand that retained document when the supplied master is stale or equal, so unseen slots cannot be created from older payloads or recurrence rules. The master document is written in the same transaction as occurrence updates. The expansion requirement also applies to the retained document: a stale minimal cancellation that resolves to a recurring master requires a window. Without one, sync rejects and rolls back all writes; retry with bounded expansion. A cancellation is an update, and a newer scheduled record restores it. A minimal master cancellation (UID/STATUS/version without DTSTART) cancels known series events and stores a series tombstone that blocks older resurrection. No feed omission deletes events: outside-window records remain; omitted detached exceptions stay authoritative until that detached identity reappears with a newer version. A newer master removing EXDATE restores that generated slot.

Every sync resolves its database configuration once and performs all writes on one transaction executor, including series creation. Failures propagate and roll back; callers may retry the same feed. An existing SQLite/PostgreSQL transaction is joined through an adapter savepoint, preserving caller rollback. The caller must authorize tenant/source access and serialize concurrent syncs for the same tenant/source; this API does not implement scheduling or locking. An active tenant context supplies an omitted tenantId and rejects a conflicting explicit tenantId, including a request for global rows. System contexts may explicitly import a tenant or global source.

Source fetching (including conditional requests, unavailable-feed detection and retry scheduling) remains caller-owned. Pass only a successfully fetched feed; partial feeds are safe under omission retention. Sync performs no drafting or publication. Event metadata records UID, occurrence ID, version markers, RRULE/EXDATE/RDATE and whether the record is detached.