Events

Calendar events are time-bounded entries tied to calendar rows in a sheet.

Overview

Events appear within calendar, calendar-list, and timeline rows. Each event has a time range, title, and optional metadata from the connected calendar provider (Google Calendar, Apple Calendar, etc.).

Listing events

Events are accessed through the sheet's row tree. Calendar rows contain event data indexed by date:

const sheet = await client.open(sheetKey);
const tree = sheet.tree();

for (const node of tree.nodes) {
  const row = sheet.rows.get(node.id.toString());
  if (row?.is("calendar")) {
    console.log(`Calendar: ${row.label}`);
    console.log(`  lookup: ${row.lookupKey}`);
  }
}

Calendar row types

Type	Description
`calendar`	Main calendar row — timed events
`calendar-list`	List view of events
`timeline`	All-day events
`calendar-month`	Month grid view

Event time ranges

Events use DateTimeRange for timed events and DateRange for all-day events:

// Timed event range
{ start: DateTime<Utc>, end: DateTime<Utc> }

// All-day event range
{ start: NaiveDate, end: NaiveDate }

EventsStore

client.events is the reactive in-memory event index. It caches events fetched from the server and provides querying, subscriptions, and optimistic mutations.

Inserting events

await client.events.insert(events);

insert() accepts an array of Network.EventDb objects. Events are indexed by time range for fast lookup. Pass false as the second argument to suppress change notifications (useful during initialization).

Querying events

import { DateTime, NaiveDate, Utc } from "@tento-chrono";

// Partial-day events in a DateTime range
const events = client.events.findAllInRange(range);

// All-day events in a NaiveDate range
const allDay = client.events.findFullDayEventsInRange(
  new NaiveDate.Range(start, end),
);

// Find a specific event by ID
const event = client.events.find(eventId);

// Check existence
const exists = client.events.has(eventId);

Updating events

// Optimistic update — patches local state and syncs to server
await client.events.update(eventId, {
  title: "Updated Title",
  start: newStart,
});

The third argument controls debouncing (defaults to true). When debounced, rapid updates are batched into a single server call.

Deleting events

client.events.delete(eventId);

Subscribing to changes

const unsubscribe = client.events.subscribe({
  onInsert(partial, fullDay) {
    // New or updated events
  },
  onDelete(event) {
    // Partial-day event removed
  },
  onDeleteFullDay(event) {
    // All-day event removed
  },
});

// Later:
unsubscribe();

Pre-seeded store

For previews or tests that don't hit the API:

import { EventsStore } from "@tento-lona";

const store = EventsStore.seeded(mockEvents);

EventsClient

EventsClient provides the low-level HTTP CRUD layer for calendar events. It's used internally by EventsStore.Backend but can be constructed directly for advanced use cases.

import { EventsClient } from "@tento-lona";

Method	Returns	Description
`list(start?, end?)`	`Promise<EventDb[]>`	Fetch events in a time range
`create(authId, calendarId, event)`	`Promise<EventDb>`	Create an event
`update(authId, calendarId, eventId, update)`	`Promise<EventDb>`	Update an event
`delete(authId, calendarId, eventId)`	`Promise<void>`	Delete an event
`moveEvent(authId, calendarId, eventId, targetAuthId, targetCalendarId)`	`Promise<void>`	Move event between calendars
`copyTo(authId, calendarId, eventId, targetAuthId, targetCalendarId)`	`Promise<EventDb>`	Copy event to another calendar

Something went wrong