Skip to content

sources

Sources the calendar fetches its events from, as the period shown changes.

Typereadonly EventSourceSpec[]
Defaultnot set
Live update (update())Yes
Declared inpackages/core/src/kernel.ts

Each source is a spec made by a helper:

  • jsonSource(id, { url }) (@dzcalendar/core): a GET with start, end and timeZone in the query (a POST: in its form body); the answer is the list of events, or map turns it into one. By default one month a request.
  • fnSource(id, fetch): your function, given { window, signal } — the stretch to fetch (window.startDate, window.endDate, exclusive) and an abort signal — returning the events, or a promise of them.
  • icalSource(id, { url }) (@dzcalendar/ical): an iCalendar feed.
  • sseSource(id, url, { map }) and liveSource(id, { connect }) (@dzcalendar/core/live): a feed that tells rather than being asked — Server-Sent Events, or any transport (a WebSocket…). map turns each message into { create }, { update, patch } (fields laid over, extendedProps merged), { remove } or { reset }; the browser reconnects a dropped stream with Last-Event-ID, and a stream the server closed for good is opened again (reopenAfterMs, the last id as ?lastEventId=). The connection opens when the source is added and closes when it is removed or the calendar destroyed.
import { sseSource } from '@dzcalendar/core/live';
const runs = sseSource('runs', '/api/runs/stream', {
map: (msg) => {
const m = msg as { kind: 'start' | 'end'; id: string; process: string; at: string; failed?: boolean };
return m.kind === 'start'
? { create: { id: m.id, title: 'Import', start: m.at, resourceId: m.process, ongoing: true } }
: { update: m.id, patch: { ongoing: false, end: m.at, tone: m.failed ? 'red' : 'green' } };
},
});

A source fetches the pieces of time it is asked for (chunk: a month at a time by default, prefetch more on each side), keeps them, and fetches again one gone stale (staleAfter) when it is shown again. The start and end a server receives are whole days around the piece, wider than the screen. A failed fetch is retried when retry asks, then told through onSource; what was shown stays. With save, the changes to its events (a person’s, a command’s, an undo) are written back: shown at once, put back if the promise rejects — or, when the events changed again meanwhile, fetched again. (icalSource takes url, text, headers, defaults, staleAfter, retry and save.)

update({ sources }) takes the whole list: sources gone are removed, new ones added, the others kept — compared by identity, so keep the same spec objects (a new object is a new source, fetched again). calendar.refetch(id) fetches one again. The id 'events' is the events option’s: a source with it is refused (duplicate-id).

import { jsonSource, fnSource } from '@dzcalendar/core';
import { createCalendar } from '@dzcalendar/dom';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
sources: [
// GET /api/rendez-vous?start=…&end=…&timeZone=Europe%2FParis
jsonSource('appointments', { url: '/api/rendez-vous' }),
fnSource('holidays', async ({ window }) => {
const res = await fetch(`/api/holidays?from=${window!.startDate}&to=${window!.endDate}`);
return res.json();
}),
],
});
// Later: fetch the appointments again.
calendar.refetch('appointments');

In the frameworks it is an input: Angular’s sources, React’s sources, Vue’s sources — keep the specs outside the render (a module constant, useMemo), or each render is a new source.