@remit/calendar-service 0.0.1

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@remit/calendar-service",
+  "version": "0.0.1",
+  "description": "iCalendar (RFC 5545) parsing, projection and recurrence expansion over the calendar store",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "test:typecheck": "tsgo --noEmit",
+    "test:run": "node $NODE_TEST_FLAGS --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-lines=90 --test 'src/**/*.test.ts'"
+  },
+  "dependencies": {
+    "@remit/data-ports": "*",
+    "@remit/domain-enums": "*",
+    "ical.js": "^2.2.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/remit-mail/reader.git",
+    "directory": "packages/calendar-service"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Why a VCALENDAR was refused. Every value names something the writer can act
+ * on — a caller maps these to a 4xx and repeats the message.
+ */
+export type CalendarValidationCode =
+	/** The bytes are not parseable iCalendar at all. */
+	| "MalformedIcalendar"
+	/** The document's root is not a VCALENDAR. */
+	| "NotACalendar"
+	/** A component this collection does not store, e.g. VTODO or VJOURNAL. */
+	| "UnsupportedComponent"
+	/** A VCALENDAR with no VEVENT in it. */
+	| "NoEvent"
+	/** No VEVENT without a RECURRENCE-ID: overrides with nothing to override. */
+	| "NoMasterEvent"
+	/** More than one VEVENT without a RECURRENCE-ID. */
+	| "MultipleMasterEvents"
+	/** A VEVENT with no UID, or an empty one. */
+	| "MissingUid"
+	/** VEVENTs in one resource declaring different UIDs. */
+	| "MismatchedUid"
+	/** A VEVENT with no DTSTART. */
+	| "MissingDtStart"
+	/** A VEVENT whose end precedes its start. */
+	| "BackwardsEnd";
+
+export interface CalendarValidationError {
+	code: CalendarValidationCode;
+	message: string;
+}
+
+/**
+ * The outcome of reading a VCALENDAR. A refusal is a value, not a throw:
+ * malformed input from a client is an expected outcome of this boundary, and
+ * every caller has to render it rather than crash on it.
+ */
+export type CalendarResult<T> =
+	| { ok: true; value: T }
+	| { ok: false; error: CalendarValidationError };
+
+export const calendarFailure = <T>(
+	code: CalendarValidationCode,
+	message: string,
+): CalendarResult<T> => ({ ok: false, error: { code, message } });

package/src/etag.test.ts

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { computeEtag } from "./etag.js";
+import { singleEvent } from "./fixtures.js";
+import { parseCalendar, serializeCalendar } from "./parse.js";
+
+const RESOURCE = singleEvent(
+	"DTSTART:20260826T090000Z",
+	"DTEND:20260826T100000Z",
+	"SUMMARY:Quarterly review",
+	"X-MICROSOFT-CDO-BUSYSTATUS:BUSY",
+);
+
+const reserialize = async (icalData: string): Promise<string> => {
+	const parsed = await parseCalendar(icalData);
+	assert.ok(parsed.ok);
+	return serializeCalendar(parsed.value.component);
+};
+
+describe("computeEtag", () => {
+	it("is a bare sha256 hex digest, unquoted", () => {
+		assert.match(computeEtag(RESOURCE), /^[0-9a-f]{64}$/);
+	});
+
+	it("is stable across a parse and serialize", async () => {
+		const once = await reserialize(RESOURCE);
+
+		assert.equal(computeEtag(await reserialize(once)), computeEtag(once));
+	});
+
+	it("moves when the event changes", () => {
+		assert.notEqual(
+			computeEtag(RESOURCE),
+			computeEtag(
+				singleEvent(
+					"DTSTART:20260826T090000Z",
+					"DTEND:20260826T110000Z",
+					"SUMMARY:Quarterly review",
+					"X-MICROSOFT-CDO-BUSYSTATUS:BUSY",
+				),
+			),
+		);
+	});
+
+	it("hashes the stored bytes, so line endings are never normalized away", () => {
+		// Two resources that differ only in line endings are two different
+		// resources: the store keeps what it was given, and a tag computed over a
+		// normalized copy would report them as the same bytes.
+		assert.notEqual(
+			computeEtag(RESOURCE),
+			computeEtag(RESOURCE.replace(/\r\n/g, "\n")),
+		);
+	});
+});

package/src/etag.ts

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Strong entity tag over the resource's stored bytes.
+ *
+ * Computed over the bytes exactly as they are stored — CRLF and all — rather
+ * than over a reparse of them, so the tag of an untouched resource never moves.
+ * Unquoted: HTTP's quoting is the transport's business, and a stored tag that
+ * carried the quotes would have to be stripped by everything that compares it.
+ */
+export const computeEtag = (icalData: string): string =>
+	createHash("sha256").update(icalData, "utf8").digest("hex");

package/src/expand.test.ts

@@ -0,0 +1,333 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	CALENDAR_EXPANSION_HORIZON_DAYS,
+	CALENDAR_EXPANSION_MAX_OCCURRENCES,
+	expandCalendar,
+} from "./expand.js";
+import { AMSTERDAM_VTIMEZONE, ical, singleEvent } from "./fixtures.js";
+import { parseCalendar } from "./parse.js";
+
+const expand = async (icalData: string, timezone = "") => {
+	const parsed = await parseCalendar(icalData);
+	assert.ok(parsed.ok, `expected a parse, got ${JSON.stringify(parsed)}`);
+	return expandCalendar(parsed.value, timezone);
+};
+
+const amsterdamSeries = (...eventLines: string[]): string =>
+	ical(
+		"BEGIN:VCALENDAR",
+		"VERSION:2.0",
+		...AMSTERDAM_VTIMEZONE,
+		"BEGIN:VEVENT",
+		"UID:weekly@example.com",
+		"DTSTART;TZID=Europe/Amsterdam:20261015T090000",
+		"DTEND;TZID=Europe/Amsterdam:20261015T100000",
+		...eventLines,
+		"END:VEVENT",
+		"END:VCALENDAR",
+	);
+
+describe("expandCalendar", () => {
+	it("writes a single occurrence under an empty recurrenceId", async () => {
+		const expansion = await expand(
+			singleEvent("DTSTART:20260826T090000Z", "DTEND:20260826T100000Z"),
+		);
+
+		assert.deepEqual(expansion.occurrences, [
+			{
+				recurrenceId: "",
+				startAt: "2026-08-26T09:00:00Z",
+				endAt: "2026-08-26T10:00:00Z",
+				allDay: false,
+			},
+		]);
+		assert.equal(expansion.expandedThrough, "");
+	});
+
+	it("keeps a weekly series at its local hour across the end of DST", async () => {
+		// 09:00 in Amsterdam is 07:00Z until the clocks go back on 2026-10-25 and
+		// 08:00Z after. An expansion that iterated instants instead of local times
+		// would move the meeting an hour for half the year.
+		const expansion = await expand(
+			amsterdamSeries("RRULE:FREQ=WEEKLY;COUNT=4"),
+		);
+
+		assert.deepEqual(
+			expansion.occurrences.map((occurrence) => occurrence.startAt),
+			[
+				"2026-10-15T07:00:00Z",
+				"2026-10-22T07:00:00Z",
+				"2026-10-29T08:00:00Z",
+				"2026-11-05T08:00:00Z",
+			],
+		);
+		assert.equal(expansion.expandedThrough, "");
+	});
+
+	it("keeps the same hour when the zone is named but not defined in the resource", async () => {
+		const expansion = await expand(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VEVENT",
+				"UID:weekly@example.com",
+				"DTSTART;TZID=Europe/Berlin:20261015T090000",
+				"DTEND;TZID=Europe/Berlin:20261015T100000",
+				"RRULE:FREQ=WEEKLY;COUNT=4",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		assert.deepEqual(
+			expansion.occurrences.map((occurrence) => occurrence.startAt),
+			[
+				"2026-10-15T07:00:00Z",
+				"2026-10-22T07:00:00Z",
+				"2026-10-29T08:00:00Z",
+				"2026-11-05T08:00:00Z",
+			],
+		);
+	});
+
+	it("carries each occurrence's own end", async () => {
+		const expansion = await expand(
+			amsterdamSeries("RRULE:FREQ=WEEKLY;COUNT=4"),
+		);
+
+		assert.deepEqual(
+			expansion.occurrences.map((occurrence) => occurrence.endAt),
+			[
+				"2026-10-15T08:00:00Z",
+				"2026-10-22T08:00:00Z",
+				"2026-10-29T09:00:00Z",
+				"2026-11-05T09:00:00Z",
+			],
+		);
+	});
+
+	it("drops an EXDATEd occurrence and keeps the rest at their slots", async () => {
+		const expansion = await expand(
+			amsterdamSeries(
+				"RRULE:FREQ=WEEKLY;COUNT=4",
+				"EXDATE;TZID=Europe/Amsterdam:20261022T090000",
+			),
+		);
+
+		assert.deepEqual(
+			expansion.occurrences.map((occurrence) => occurrence.recurrenceId),
+			["2026-10-15T07:00:00Z", "2026-10-29T08:00:00Z", "2026-11-05T08:00:00Z"],
+		);
+	});
+
+	it("moves an overridden occurrence but keeps the slot it replaces", async () => {
+		const expansion = await expand(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				...AMSTERDAM_VTIMEZONE,
+				"BEGIN:VEVENT",
+				"UID:weekly@example.com",
+				"DTSTART;TZID=Europe/Amsterdam:20261015T090000",
+				"DTEND;TZID=Europe/Amsterdam:20261015T100000",
+				"RRULE:FREQ=WEEKLY;COUNT=3",
+				"END:VEVENT",
+				"BEGIN:VEVENT",
+				"UID:weekly@example.com",
+				"RECURRENCE-ID;TZID=Europe/Amsterdam:20261022T090000",
+				"DTSTART;TZID=Europe/Amsterdam:20261022T140000",
+				"DTEND;TZID=Europe/Amsterdam:20261022T150000",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		const moved = expansion.occurrences.find(
+			(occurrence) => occurrence.recurrenceId === "2026-10-22T07:00:00Z",
+		);
+		assert.equal(moved?.startAt, "2026-10-22T12:00:00Z");
+		assert.equal(moved?.endAt, "2026-10-22T13:00:00Z");
+	});
+
+	it("indexes an override whose slot the rule never produces", async () => {
+		// What a client writes after moving one instance and then editing the
+		// series: the override's RECURRENCE-ID names a slot the new rule does not
+		// generate. The iterator walks only the rule's slots, so nothing but an
+		// explicit pass over the VEVENTs reaches this event.
+		const expansion = await expand(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				...AMSTERDAM_VTIMEZONE,
+				"BEGIN:VEVENT",
+				"UID:weekly@example.com",
+				"DTSTART;TZID=Europe/Amsterdam:20261015T090000",
+				"DTEND;TZID=Europe/Amsterdam:20261015T100000",
+				"RRULE:FREQ=WEEKLY;COUNT=2",
+				"END:VEVENT",
+				"BEGIN:VEVENT",
+				"UID:weekly@example.com",
+				"RECURRENCE-ID;TZID=Europe/Amsterdam:20261112T090000",
+				"DTSTART;TZID=Europe/Amsterdam:20261112T140000",
+				"DTEND;TZID=Europe/Amsterdam:20261112T153000",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		assert.deepEqual(
+			expansion.occurrences.map((occurrence) => occurrence.recurrenceId),
+			["2026-10-15T07:00:00Z", "2026-10-22T07:00:00Z", "2026-11-12T08:00:00Z"],
+		);
+		const stranded = expansion.occurrences.at(-1);
+		assert.equal(stranded?.startAt, "2026-11-12T13:00:00Z");
+		assert.equal(stranded?.endAt, "2026-11-12T14:30:00Z");
+	});
+
+	it("indexes every instance of a resource that has overrides but no rule", async () => {
+		const expansion = await expand(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VEVENT",
+				"UID:edited@example.com",
+				"DTSTART:20260826T090000Z",
+				"DTEND:20260826T100000Z",
+				"END:VEVENT",
+				"BEGIN:VEVENT",
+				"UID:edited@example.com",
+				"RECURRENCE-ID:20260902T090000Z",
+				"DTSTART:20260902T110000Z",
+				"DTEND:20260902T120000Z",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		assert.deepEqual(
+			expansion.occurrences.map((occurrence) => occurrence.startAt),
+			["2026-08-26T09:00:00Z", "2026-09-02T11:00:00Z"],
+		);
+	});
+
+	it("reads an override's end in the override's own zone", async () => {
+		// The moved instance was rewritten in a different zone from the series,
+		// and its DTEND names a third. Resolving either with the master's TZID
+		// puts this instance an hour out and changes how long it lasts.
+		const expansion = await expand(
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"BEGIN:VEVENT",
+				"UID:crosszone@example.com",
+				"DTSTART;TZID=Europe/Berlin:20260826T090000",
+				"DTEND;TZID=Europe/Berlin:20260826T100000",
+				"RRULE:FREQ=WEEKLY;COUNT=2",
+				"END:VEVENT",
+				"BEGIN:VEVENT",
+				"UID:crosszone@example.com",
+				"RECURRENCE-ID;TZID=Europe/Berlin:20260902T090000",
+				"DTSTART;TZID=Europe/London:20260902T090000",
+				"DTEND;TZID=Europe/Lisbon:20260902T103000",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			),
+		);
+
+		assert.deepEqual(
+			expansion.occurrences.map((occurrence) => [
+				occurrence.recurrenceId,
+				occurrence.startAt,
+				occurrence.endAt,
+			]),
+			[
+				[
+					"2026-08-26T07:00:00Z",
+					"2026-08-26T07:00:00Z",
+					"2026-08-26T08:00:00Z",
+				],
+				[
+					"2026-09-02T07:00:00Z",
+					"2026-09-02T08:00:00Z",
+					"2026-09-02T09:30:00Z",
+				],
+			],
+		);
+	});
+
+	it("expands an all-day series as whole days", async () => {
+		const expansion = await expand(
+			singleEvent(
+				"DTSTART;VALUE=DATE:20260826",
+				"DTEND;VALUE=DATE:20260827",
+				"RRULE:FREQ=DAILY;COUNT=2",
+			),
+			"Europe/Berlin",
+		);
+
+		assert.deepEqual(expansion.occurrences, [
+			{
+				recurrenceId: "2026-08-25T22:00:00Z",
+				startAt: "2026-08-25T22:00:00Z",
+				endAt: "2026-08-26T22:00:00Z",
+				allDay: true,
+			},
+			{
+				recurrenceId: "2026-08-26T22:00:00Z",
+				startAt: "2026-08-26T22:00:00Z",
+				endAt: "2026-08-27T22:00:00Z",
+				allDay: true,
+			},
+		]);
+	});
+
+	it("stops an open-ended series at the horizon and says how far it got", async () => {
+		const expansion = await expand(
+			singleEvent(
+				"DTSTART:20260101T090000Z",
+				"DTEND:20260101T100000Z",
+				"RRULE:FREQ=DAILY",
+			),
+		);
+
+		assert.notEqual(expansion.expandedThrough, "");
+		const last = expansion.occurrences[expansion.occurrences.length - 1];
+		assert.equal(expansion.expandedThrough, last?.startAt);
+		assert.ok(
+			Date.parse(expansion.expandedThrough) -
+				Date.parse("2026-01-01T09:00:00Z") <=
+				CALENDAR_EXPANSION_HORIZON_DAYS * 24 * 60 * 60 * 1000,
+			"the last written occurrence is inside the horizon",
+		);
+	});
+
+	it("stops a dense series at the occurrence ceiling", async () => {
+		const expansion = await expand(
+			singleEvent(
+				"DTSTART:20260101T090000Z",
+				"DTEND:20260101T090100Z",
+				"RRULE:FREQ=MINUTELY",
+			),
+		);
+
+		assert.equal(
+			expansion.occurrences.length,
+			CALENDAR_EXPANSION_MAX_OCCURRENCES,
+		);
+		assert.notEqual(expansion.expandedThrough, "");
+	});
+
+	it("says nothing about a horizon for a series that ends inside it", async () => {
+		const expansion = await expand(
+			singleEvent(
+				"DTSTART:20260101T090000Z",
+				"DTEND:20260101T100000Z",
+				"RRULE:FREQ=WEEKLY;UNTIL=20260301T090000Z",
+			),
+		);
+
+		assert.equal(expansion.expandedThrough, "");
+		assert.equal(expansion.occurrences.length, 9);
+	});
+});

package/src/expand.ts

@@ -0,0 +1,186 @@
+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";
+
+/**
+ * How far past a series' own start its occurrences are written out.
+ *
+ * A recurring event may have no end at all, so something has to bound the
+ * write. Two years covers every view a client asks for today and keeps the
+ * index one bounded write rather than an unbounded one; a resource whose series
+ * runs past it is marked with `expandedThrough` and stays the business of the
+ * live expansion that reads it.
+ */
+export const CALENDAR_EXPANSION_HORIZON_DAYS = 730;
+
+/**
+ * Ceiling on occurrences written for one resource, independent of the horizon.
+ * A per-minute RRULE fits three quarters of a million instances inside two
+ * years; the ceiling turns that into a marked, truncated index instead of a
+ * write that takes the process down.
+ */
+export const CALENDAR_EXPANSION_MAX_OCCURRENCES = 1000;
+
+const HORIZON_MS = CALENDAR_EXPANSION_HORIZON_DAYS * 24 * 60 * 60 * 1000;
+
+export interface CalendarExpansion {
+	occurrences: CalendarOccurrenceInput[];
+	/**
+	 * The instant through which `occurrences` is complete, or `""` when it holds
+	 * the whole series.
+	 */
+	expandedThrough: string;
+}
+
+/**
+ * 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.
+ *
+ * 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
+ * slots, so an override whose RECURRENCE-ID names a slot the rule never
+ * produces — the shape a client writes after moving one instance and then
+ * 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 = (
+	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,
+		};
+	};
+
+	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 occurrences: CalendarOccurrenceInput[] = [];
+	const claimed = new Set<string>();
+	const iterator = event.iterator();
+	let truncated = false;
+
+	let next = iterator.next();
+	while (next) {
+		const slot = resolve(next, startTzidOf(calendar.master));
+		if (
+			slot.instantMs > horizonMs ||
+			occurrences.length >= CALENDAR_EXPANSION_MAX_OCCURRENCES
+		) {
+			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);
+		claimed.add(slot.isoUtc);
+		occurrences.push(
+			occurrenceOf(
+				slot.isoUtc,
+				details.startDate,
+				details.endDate,
+				startTzidOf(source ?? calendar.master),
+				source ? endTzidOf(source) : startTzidOf(calendar.master),
+			),
+		);
+		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.
+	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),
+			),
+		);
+	}
+
+	occurrences.sort((left, right) => left.startAt.localeCompare(right.startAt));
+
+	return { occurrences, expandedThrough };
+};