@remit/calendar-service 0.0.1 → 0.0.2

package/src/expand.ts

@@ -1,8 +1,14 @@
 import type { CalendarOccurrenceInput } from "@remit/data-ports";
 import ICAL from "ical.js";
 import type { ParsedCalendar } from "./parse.js";
-import { hasRecurrence } from "./project.js";
-import { resolveTime, toUtcIso, tzidOf } from "./time.js";
+import { hasRecurrence, projectEventDisplay } from "./project.js";
+import {
+	dtEndTzid,
+	dtStartTzid,
+	resolveTime,
+	toUtcIso,
+	tzidOf,
+} from "./time.js";
 
 /**
  * How far past a series' own start its occurrences are written out.
@@ -23,6 +29,17 @@ export const CALENDAR_EXPANSION_HORIZON_DAYS = 730;
  */
 export const CALENDAR_EXPANSION_MAX_OCCURRENCES = 1000;
 
+/**
+ * Ceiling on iterator steps a live window expansion may take.
+ *
+ * A window expansion walks the series from its own start, because a rule is
+ * only meaningful from where it was anchored. A daily event written in 2005 is
+ * a few thousand steps away from today, which is cheap; a per-minute one is
+ * millions, which is a read that never returns. The cap turns the second case
+ * into a short answer rather than a hung request.
+ */
+export const CALENDAR_WINDOW_MAX_STEPS = 50_000;
+
 const HORIZON_MS = CALENDAR_EXPANSION_HORIZON_DAYS * 24 * 60 * 60 * 1000;
 
 export interface CalendarExpansion {
@@ -34,14 +51,68 @@ export interface CalendarExpansion {
 	expandedThrough: string;
 }
 
+const occurrenceOf = (
+	collectionTimezone: string,
+	recurrenceId: string,
+	source: ICAL.Component,
+	startDate: ICAL.Time,
+	endDate: ICAL.Time,
+	startTzid: string,
+	endTzid: string,
+): CalendarOccurrenceInput => {
+	const start = resolveTime(startDate, startTzid, collectionTimezone);
+	const end = resolveTime(endDate, endTzid, collectionTimezone);
+	return {
+		recurrenceId,
+		startAt: start.isoUtc,
+		endAt: end.isoUtc,
+		allDay: start.isDate,
+		...projectEventDisplay(source),
+	};
+};
+
 /**
- * Flattens a resource into the occurrence rows a date-range read returns.
- *
- * A non-recurring resource is one row under an empty `recurrenceId`. A
- * recurring one is a row per occurrence, each keyed by its RECURRENCE-ID slot
- * as a UTC instant — the same canonical form an override's own RECURRENCE-ID
- * resolves to, so an override lands on the occurrence it replaces instead of
- * beside it.
+ * The slot each override claims, canonicalized the way the iterator's slots
+ * are, so the two can be compared at all.
+ */
+export const overridesBySlot = (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+): Map<string, ICAL.Component> => {
+	const bySlot = new Map<string, ICAL.Component>();
+	for (const override of calendar.overrides) {
+		const recurrenceId = override.getFirstPropertyValue("recurrence-id");
+		if (!(recurrenceId instanceof ICAL.Time)) continue;
+		const slot = resolveTime(
+			recurrenceId,
+			tzidOf(override.getFirstProperty("recurrence-id")),
+			collectionTimezone,
+		).isoUtc;
+		bySlot.set(slot, override);
+	}
+	return bySlot;
+};
+
+/** The window a walk collects occurrences in, and what bounds the walk. */
+interface WalkBounds {
+	/** Occurrences starting before this are stepped past, not collected. */
+	fromMs: number;
+	/** The walk stops once a slot starts after this. */
+	throughMs: number;
+	maxOccurrences: number;
+	maxSteps: number;
+}
+
+interface Walk {
+	occurrences: CalendarOccurrenceInput[];
+	/** Whether the walk stopped on a bound rather than on the series ending. */
+	truncated: boolean;
+	/** Start of the last slot the iterator itself produced, or `""` for none. */
+	lastIteratedStart: string;
+}
+
+/**
+ * Walks a recurring resource's occurrences between the bounds it is given.
  *
  * EXDATEs are ical.js's business — `ICAL.Event` skips them. Overrides are not
  * left entirely to it: the iterator yields the master's own RRULE and RDATE
@@ -50,137 +121,176 @@ export interface CalendarExpansion {
  * editing the rule — would never be reached. Those are walked explicitly, so
  * every VEVENT in the resource is an occurrence somebody can find.
  */
-export const expandCalendar = (
+const walkOccurrences = (
 	calendar: ParsedCalendar,
 	collectionTimezone: string,
-): CalendarExpansion => {
-	const resolve = (time: ICAL.Time, tzid: string) =>
-		resolveTime(time, tzid, collectionTimezone);
-
-	const startTzidOf = (component: ICAL.Component): string =>
-		tzidOf(component.getFirstProperty("dtstart"));
-
-	// DTEND carries its own TZID and need not match DTSTART's, so an end read
-	// with the start's zone silently changes the event's length. Only a stated
-	// DTEND has a zone of its own: an end ical.js derived from a duration is
-	// already in the start's zone, and hinting it with anything else is wrong.
-	const endTzidOf = (component: ICAL.Component): string =>
-		component.hasProperty("dtend")
-			? tzidOf(component.getFirstProperty("dtend"))
-			: startTzidOf(component);
-
-	const occurrenceOf = (
-		recurrenceId: string,
-		startDate: ICAL.Time,
-		endDate: ICAL.Time,
-		startTzid: string,
-		endTzid: string,
-	): CalendarOccurrenceInput => {
-		const start = resolve(startDate, startTzid);
-		const end = resolve(endDate, endTzid);
-		return {
-			recurrenceId,
-			startAt: start.isoUtc,
-			endAt: end.isoUtc,
-			allDay: start.isDate,
-		};
-	};
-
+	bounds: WalkBounds,
+): Walk => {
 	const event = new ICAL.Event(calendar.master);
 	for (const override of calendar.overrides) {
 		event.relateException(override);
 	}
 
-	if (!hasRecurrence(calendar)) {
-		return {
-			occurrences: [
-				occurrenceOf(
-					"",
-					event.startDate,
-					event.endDate,
-					startTzidOf(calendar.master),
-					endTzidOf(calendar.master),
-				),
-			],
-			expandedThrough: "",
-		};
-	}
-
-	// The slot each override claims, canonicalized the same way the iterator's
-	// slots are, so the two can be compared at all.
-	const overrideBySlot = new Map<string, ICAL.Component>();
-	for (const override of calendar.overrides) {
-		const recurrenceId = override.getFirstPropertyValue("recurrence-id");
-		if (!(recurrenceId instanceof ICAL.Time)) continue;
-		overrideBySlot.set(
-			resolve(recurrenceId, tzidOf(override.getFirstProperty("recurrence-id")))
-				.isoUtc,
-			override,
-		);
-	}
-
-	const seriesStart = resolve(
-		event.startDate,
-		startTzidOf(calendar.master),
-	).instantMs;
-	const horizonMs = seriesStart + HORIZON_MS;
+	const overrideBySlot = overridesBySlot(calendar, collectionTimezone);
+	const masterStartTzid = dtStartTzid(calendar.master);
 	const occurrences: CalendarOccurrenceInput[] = [];
 	const claimed = new Set<string>();
 	const iterator = event.iterator();
 	let truncated = false;
+	let steps = 0;
+	let lastIteratedStart = "";
 
 	let next = iterator.next();
 	while (next) {
-		const slot = resolve(next, startTzidOf(calendar.master));
+		const slot = resolveTime(next, masterStartTzid, collectionTimezone);
 		if (
-			slot.instantMs > horizonMs ||
-			occurrences.length >= CALENDAR_EXPANSION_MAX_OCCURRENCES
+			slot.instantMs > bounds.throughMs ||
+			occurrences.length >= bounds.maxOccurrences ||
+			steps >= bounds.maxSteps
 		) {
 			truncated = true;
 			break;
 		}
-
-		// An overridden slot hands back the override's own DTSTART and DTEND, so
-		// the zones to read them in are the override's. A plain slot hands back
-		// the rule's start and an end derived from the master's duration, both in
-		// the master's start zone.
-		const source = overrideBySlot.get(slot.isoUtc);
-		const details = event.getOccurrenceDetails(next);
+		steps += 1;
 		claimed.add(slot.isoUtc);
-		occurrences.push(
-			occurrenceOf(
-				slot.isoUtc,
-				details.startDate,
-				details.endDate,
-				startTzidOf(source ?? calendar.master),
-				source ? endTzidOf(source) : startTzidOf(calendar.master),
-			),
-		);
+
+		if (slot.instantMs >= bounds.fromMs) {
+			// An overridden slot hands back the override's own DTSTART and DTEND, so
+			// the zones to read them in are the override's. A plain slot hands back
+			// the rule's start and an end derived from the master's duration, both in
+			// the master's start zone.
+			const source = overrideBySlot.get(slot.isoUtc);
+			const details = event.getOccurrenceDetails(next);
+			occurrences.push(
+				occurrenceOf(
+					collectionTimezone,
+					slot.isoUtc,
+					source ?? calendar.master,
+					details.startDate,
+					details.endDate,
+					dtStartTzid(source ?? calendar.master),
+					source ? dtEndTzid(source) : masterStartTzid,
+				),
+			);
+			lastIteratedStart = occurrences[occurrences.length - 1]?.startAt ?? "";
+		}
 		next = iterator.next();
 	}
 
-	const iterated = occurrences[occurrences.length - 1];
-	const expandedThrough =
-		truncated && iterated ? toUtcIso(Date.parse(iterated.startAt)) : "";
-
-	// Overrides the rule never reached. Written regardless of the horizon: they
-	// are a bounded, explicit list, and one moved instance is exactly the thing
-	// a user goes looking for.
+	// Overrides the rule never reached. Kept regardless of the horizon: they are
+	// a bounded, explicit list, and one moved instance is exactly the thing a
+	// user goes looking for.
 	for (const [slot, override] of overrideBySlot) {
 		if (claimed.has(slot)) continue;
 		const overrideEvent = new ICAL.Event(override);
-		occurrences.push(
-			occurrenceOf(
-				slot,
-				overrideEvent.startDate,
-				overrideEvent.endDate,
-				startTzidOf(override),
-				endTzidOf(override),
-			),
+		const occurrence = occurrenceOf(
+			collectionTimezone,
+			slot,
+			override,
+			overrideEvent.startDate,
+			overrideEvent.endDate,
+			dtStartTzid(override),
+			dtEndTzid(override),
 		);
+		const startMs = Date.parse(occurrence.startAt);
+		if (startMs < bounds.fromMs || startMs > bounds.throughMs) continue;
+		occurrences.push(occurrence);
 	}
 
 	occurrences.sort((left, right) => left.startAt.localeCompare(right.startAt));
 
-	return { occurrences, expandedThrough };
+	return { occurrences, truncated, lastIteratedStart };
+};
+
+/** The one occurrence a resource that does not recur produces. */
+const singleOccurrence = (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+): CalendarOccurrenceInput => {
+	const event = new ICAL.Event(calendar.master);
+	return occurrenceOf(
+		collectionTimezone,
+		"",
+		calendar.master,
+		event.startDate,
+		event.endDate,
+		dtStartTzid(calendar.master),
+		dtEndTzid(calendar.master),
+	);
+};
+
+/**
+ * Flattens a resource into the occurrence rows a date-range read returns.
+ *
+ * A non-recurring resource is one row under an empty `recurrenceId`. A
+ * recurring one is a row per occurrence, each keyed by its RECURRENCE-ID slot
+ * as a UTC instant — the same canonical form an override's own RECURRENCE-ID
+ * resolves to, so an override lands on the occurrence it replaces instead of
+ * beside it.
+ *
+ * The horizon is anchored at the series' own start, not at today: two years of
+ * a series is a bounded write whatever a caller's clock says. A series running
+ * past it comes back marked with `expandedThrough`, which is what tells a later
+ * read to expand that resource live instead of trusting the index.
+ */
+export const expandCalendar = (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+): CalendarExpansion => {
+	if (!hasRecurrence(calendar)) {
+		return {
+			occurrences: [singleOccurrence(calendar, collectionTimezone)],
+			expandedThrough: "",
+		};
+	}
+
+	const event = new ICAL.Event(calendar.master);
+	const seriesStart = resolveTime(
+		event.startDate,
+		dtStartTzid(calendar.master),
+		collectionTimezone,
+	).instantMs;
+
+	const walk = walkOccurrences(calendar, collectionTimezone, {
+		fromMs: Number.NEGATIVE_INFINITY,
+		throughMs: seriesStart + HORIZON_MS,
+		maxOccurrences: CALENDAR_EXPANSION_MAX_OCCURRENCES,
+		maxSteps: Number.POSITIVE_INFINITY,
+	});
+
+	return {
+		occurrences: walk.occurrences,
+		expandedThrough:
+			walk.truncated && walk.lastIteratedStart
+				? toUtcIso(Date.parse(walk.lastIteratedStart))
+				: "",
+	};
+};
+
+/**
+ * The occurrences of a resource that fall inside one window, computed rather
+ * than read.
+ *
+ * This is what serves a view of a series whose stored index stops before the
+ * window — an open-ended weekly meeting written years ago, whose horizon ran
+ * out long before today. The alternative is extending the index on read, which
+ * turns every view of an old series into an unbounded write; a bounded
+ * computation that persists nothing is the cheaper half of that trade, and the
+ * one that cannot leave anything behind to be wrong later.
+ */
+export const expandCalendarWindow = (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+	window: { fromMs: number; toMs: number },
+): CalendarOccurrenceInput[] => {
+	if (!hasRecurrence(calendar)) {
+		return [singleOccurrence(calendar, collectionTimezone)];
+	}
+
+	return walkOccurrences(calendar, collectionTimezone, {
+		fromMs: window.fromMs,
+		throughMs: window.toMs,
+		maxOccurrences: CALENDAR_EXPANSION_MAX_OCCURRENCES,
+		maxSteps: CALENDAR_WINDOW_MAX_STEPS,
+	}).occurrences;
 };

package/src/index.ts

@@ -1,3 +1,12 @@
+export {
+	applyEventFields,
+	buildEventCalendar,
+	CALENDAR_PRODID,
+	type CalendarEventFields,
+	eventTimeFields,
+	readEventTime,
+	readRecurrenceRule,
+} from "./build.js";
 export type {
 	CalendarResult,
 	CalendarValidationCode,
@@ -7,8 +16,10 @@ export { computeEtag } from "./etag.js";
 export {
 	CALENDAR_EXPANSION_HORIZON_DAYS,
 	CALENDAR_EXPANSION_MAX_OCCURRENCES,
+	CALENDAR_WINDOW_MAX_STEPS,
 	type CalendarExpansion,
 	expandCalendar,
+	expandCalendarWindow,
 } from "./expand.js";
 export {
 	type ParsedCalendar,
@@ -26,4 +37,30 @@ export {
 	provisionDefaultCalendar,
 	putCalendarObject,
 } from "./put.js";
-export { type ResolvedTime, resolveTime, toUtcIso } from "./time.js";
+export {
+	applyScopedDelete,
+	applyScopedUpdate,
+	findOccurrence,
+	type RecurrenceScopeValue,
+	type ScopedWrite,
+	type ScopedWriteInput,
+} from "./scope.js";
+export {
+	civilInZone,
+	isResolvableZone,
+	type ResolvedTime,
+	resolveTime,
+	toOffsetIso,
+	toUtcIso,
+} from "./time.js";
+export {
+	type BusySpan,
+	CALENDAR_WINDOW_LOOKBACK_DAYS,
+	type CalendarInstance,
+	type CalendarWindow,
+	type CalendarWindowRepositories,
+	isBusy,
+	listBusySpans,
+	listCalendarInstances,
+	mergeBusySpans,
+} from "./window.js";

package/src/project.ts

@@ -48,6 +48,31 @@ const readString = (component: ICAL.Component, name: string): string => {
  * but a master and its exceptions, and every one of those is still an
  * occurrence somebody has to see.
  */
+/**
+ * The fields that describe one VEVENT rather than the series it belongs to.
+ *
+ * Read per occurrence as well as per resource: an override VEVENT carries its
+ * own summary, status and transparency, and a range read that took them from
+ * the master would draw the old title over an edited instance and count a
+ * cancelled one as busy time.
+ */
+export type CalendarEventDisplay = Pick<
+	CalendarObjectItem,
+	"summary" | "status" | "transparency"
+>;
+
+export const projectEventDisplay = (
+	component: ICAL.Component,
+): CalendarEventDisplay => ({
+	summary: readString(component, "summary"),
+	status:
+		STATUS_BY_ICAL[readString(component, "status").toUpperCase()] ??
+		CalendarEventStatus.Confirmed,
+	transparency:
+		TRANSPARENCY_BY_ICAL[readString(component, "transp").toUpperCase()] ??
+		CalendarTransparency.Opaque,
+});
+
 export const hasRecurrence = (calendar: ParsedCalendar): boolean =>
 	calendar.master.hasProperty("rrule") ||
 	calendar.master.hasProperty("rdate") ||
@@ -85,18 +110,11 @@ export const projectCalendar = (
 		ok: true,
 		value: {
 			icalUid: calendar.uid,
-			summary: readString(calendar.master, "summary"),
 			dtStart: start.isoOffset,
 			dtEnd: end.isoOffset,
 			allDay: start.isDate,
 			zoneCertainty: start.certainty,
-			status:
-				STATUS_BY_ICAL[readString(calendar.master, "status").toUpperCase()] ??
-				CalendarEventStatus.Confirmed,
-			transparency:
-				TRANSPARENCY_BY_ICAL[
-					readString(calendar.master, "transp").toUpperCase()
-				] ?? CalendarTransparency.Opaque,
+			...projectEventDisplay(calendar.master),
 			hasRecurrence: hasRecurrence(calendar),
 			sequence: typeof sequence === "number" ? sequence : 0,
 		},

package/src/put.test.ts

@@ -88,6 +88,14 @@ class MemoryCalendarStore implements ICalendarUnitOfWork {
 			[...this.collections.values()].filter(
 				(collection) => collection.accountConfigId === accountConfigId,
 			),
+		createExclusive: async (input: CreateCalendarCollectionInput) => {
+			const calendarId = deriveCalendarId(
+				input.accountConfigId,
+				input.urlSegment,
+			);
+			if (this.collections.has(calendarId)) return null;
+			return this.collectionRepo.create(input);
+		},
 		findByUrlSegment: async (accountConfigId: string, urlSegment: string) =>
 			this.collections.get(deriveCalendarId(accountConfigId, urlSegment)) ??
 			null,
@@ -119,6 +127,15 @@ class MemoryCalendarStore implements ICalendarUnitOfWork {
 			this.objects.set(calendarObjectId, object);
 			return object;
 		},
+		listIncompleteExpansions: async (calendarId: string, instant: string) =>
+			[...this.objects.values()].filter(
+				(object) =>
+					object.calendarId === calendarId &&
+					object.expandedThrough !== "" &&
+					object.expandedThrough < instant,
+			),
+		find: async (_calendarId: string, calendarObjectId: string) =>
+			this.objects.get(calendarObjectId) ?? null,
 		get: async (_calendarId: string, calendarObjectId: string) => {
 			const object = this.objects.get(calendarObjectId);
 			if (!object) throw new MissingRow(calendarObjectId);