@remit/calendar-service 0.0.1 → 0.0.2

package/src/scope.ts

@@ -0,0 +1,490 @@
+import { RecurrenceScope } from "@remit/domain-enums";
+import ICAL from "ical.js";
+import { applyEventFields, type CalendarEventFields } from "./build.js";
+import { type CalendarResult, calendarFailure } from "./errors.js";
+import { CALENDAR_WINDOW_MAX_STEPS, overridesBySlot } from "./expand.js";
+import {
+	type ParsedCalendar,
+	parseCalendar,
+	serializeCalendar,
+} from "./parse.js";
+import { hasRecurrence } from "./project.js";
+import { dtStartTzid, resolveTime, toUtcIso } from "./time.js";
+
+export type RecurrenceScopeValue =
+	(typeof RecurrenceScope)[keyof typeof RecurrenceScope];
+
+/**
+ * What a scoped write turns into on the store.
+ *
+ * `Split` is the only one that is not a single resource: iCalendar has no way
+ * to say "the rest of this series is different", so a `Following` edit really
+ * is two resources — the truncated original and a new one under a UID of its
+ * own. Both go through the one write path rather than through a second.
+ */
+export type ScopedWrite =
+	| { kind: "Replace"; icalData: string }
+	| { kind: "Split"; icalData: string; following: string }
+	| { kind: "Delete" };
+
+export interface ScopedWriteInput {
+	scope: RecurrenceScopeValue;
+	/** ISO 8601 UTC instant naming the occurrence; `""` outside `This`/`Following`. */
+	recurrenceId: string;
+	/** UID the resource a `Following` split creates is written under. */
+	followingUid: string;
+}
+
+interface FoundOccurrence {
+	/** The rule slot, in whatever form the master's DTSTART is written in. */
+	slot: ICAL.Time;
+	slotUtc: string;
+	/** The occurrence as the series produces it; absent when only an override names the slot. */
+	details: ReturnType<ICAL.Event["getOccurrenceDetails"]> | null;
+	/** Position in the rule's own sequence, `-1` when the rule never reaches it. */
+	index: number;
+	override: ICAL.Component | null;
+}
+
+/** A deep copy of a resource, taken the one way that cannot share structure. */
+const cloneCalendar = (
+	calendar: ParsedCalendar,
+): Promise<CalendarResult<ParsedCalendar>> =>
+	parseCalendar(serializeCalendar(calendar.component));
+
+const timeProperty = (
+	name: string,
+	time: ICAL.Time,
+	tzid: string,
+): ICAL.Property => {
+	const property = new ICAL.Property(name);
+	property.setValue(time);
+	if (!time.isDate && tzid !== "") property.setParameter("tzid", tzid);
+	return property;
+};
+
+const setTimeValue = (
+	component: ICAL.Component,
+	name: string,
+	time: ICAL.Time,
+	tzid: string,
+): void => {
+	const existing = component.getFirstProperty(name);
+	if (existing) {
+		existing.setValue(time);
+		return;
+	}
+	component.addProperty(timeProperty(name, time, tzid));
+};
+
+/**
+ * The occurrence a scoped write is anchored at.
+ *
+ * Walks the series rather than trusting the caller's instant: a RECURRENCE-ID
+ * naming no occurrence is the shape of a stale client acting on a series
+ * somebody has since edited, and writing an override or an EXDATE for a slot
+ * the rule never produces leaves a resource nothing can reconcile afterwards.
+ */
+export const findOccurrence = (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+	recurrenceId: string,
+): CalendarResult<FoundOccurrence> => {
+	const targetMs = Date.parse(recurrenceId);
+	if (Number.isNaN(targetMs)) {
+		return calendarFailure(
+			"InvalidDateTime",
+			`"${recurrenceId}" is not a RECURRENCE-ID this server can read`,
+		);
+	}
+	const targetUtc = toUtcIso(targetMs);
+
+	const overrideBySlot = overridesBySlot(calendar, collectionTimezone);
+	const masterStartTzid = dtStartTzid(calendar.master);
+	const event = new ICAL.Event(calendar.master);
+	for (const override of calendar.overrides) {
+		event.relateException(override);
+	}
+
+	const iterator = event.iterator();
+	let next = iterator.next();
+	let index = 0;
+	while (next && index < CALENDAR_WINDOW_MAX_STEPS) {
+		const slot = resolveTime(next, masterStartTzid, collectionTimezone);
+		if (slot.isoUtc === targetUtc) {
+			return {
+				ok: true,
+				value: {
+					slot: next.clone(),
+					slotUtc: slot.isoUtc,
+					details: event.getOccurrenceDetails(next),
+					index,
+					override: overrideBySlot.get(slot.isoUtc) ?? null,
+				},
+			};
+		}
+		if (slot.instantMs > targetMs) break;
+		index += 1;
+		next = iterator.next();
+	}
+
+	// An override the rule never reaches is still an occurrence somebody can
+	// see, so it is still one they can edit or drop.
+	const stranded = overrideBySlot.get(targetUtc);
+	const strandedSlot = stranded?.getFirstPropertyValue("recurrence-id");
+	if (stranded && strandedSlot instanceof ICAL.Time) {
+		return {
+			ok: true,
+			value: {
+				slot: strandedSlot.clone(),
+				slotUtc: targetUtc,
+				details: null,
+				index: -1,
+				override: stranded,
+			},
+		};
+	}
+
+	return calendarFailure(
+		"UnknownOccurrence",
+		`this series has no occurrence at ${recurrenceId}`,
+	);
+};
+
+const slotUtcOf = (
+	override: ICAL.Component,
+	collectionTimezone: string,
+): string => {
+	const recurrenceId = override.getFirstPropertyValue("recurrence-id");
+	if (!(recurrenceId instanceof ICAL.Time)) return "";
+	return resolveTime(recurrenceId, dtStartTzid(override), collectionTimezone)
+		.isoUtc;
+};
+
+/** Drops the override VEVENTs on one side of a split point. */
+const keepOverrides = (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+	keep: (slotMs: number) => boolean,
+): void => {
+	const kept: ICAL.Component[] = [];
+	for (const override of calendar.overrides) {
+		const slot = slotUtcOf(override, collectionTimezone);
+		if (slot !== "" && keep(Date.parse(slot))) {
+			kept.push(override);
+			continue;
+		}
+		calendar.component.removeSubcomponent(override);
+	}
+	calendar.overrides = kept;
+};
+
+/** Drops the values of one repeating date property on a side of a split point. */
+const keepDateValues = (
+	master: ICAL.Component,
+	name: string,
+	collectionTimezone: string,
+	keep: (slotMs: number) => boolean,
+): void => {
+	for (const property of master.getAllProperties(name)) {
+		const kept = property.getValues().filter((value: unknown) => {
+			if (!(value instanceof ICAL.Time)) return true;
+			return keep(
+				resolveTime(value, dtStartTzid(master), collectionTimezone).instantMs,
+			);
+		});
+		if (kept.length === 0) {
+			master.removeProperty(property);
+			continue;
+		}
+		property.setValues(kept);
+	}
+};
+
+/**
+ * The last value the truncated series still covers, in the frame its own
+ * DTSTART is written in.
+ *
+ * UNTIL has to be comparable to the values the rule produces, and an expander
+ * compares them as they are written rather than as this server resolves them.
+ * A UTC instant against a floating or all-day series is therefore off by the
+ * collection's offset, and in a zone behind UTC that leaves the split
+ * occurrence in both halves of the split. So the value is derived from the slot
+ * itself: a date for a date series, the same wall clock for a floating one, and
+ * UTC where the slot really is an instant — which is also what RFC 5545 3.3.10
+ * asks for in each of those cases.
+ */
+const untilBefore = (slot: ICAL.Time): ICAL.Time => {
+	const until = slot.clone();
+	if (until.isDate) {
+		until.adjust(-1, 0, 0, 0);
+		return until;
+	}
+	until.adjust(0, 0, 0, -1);
+	return until.zone === ICAL.Timezone.localTimezone
+		? until
+		: until.convertToZone(ICAL.Timezone.utcTimezone);
+};
+
+/**
+ * Ends the master's rule just before an occurrence.
+ *
+ * A COUNT rule is truncated by count and an open or UNTIL rule by UNTIL,
+ * because rewriting one as the other changes what the series means: a rule
+ * counting ten meetings and a rule running to a date agree today and stop
+ * agreeing the moment anything is added to or dropped from the series.
+ */
+const truncateRule = (
+	master: ICAL.Component,
+	occurrence: FoundOccurrence,
+): void => {
+	const property = master.getFirstProperty("rrule");
+	if (!property) return;
+	const rule = property.getFirstValue();
+	if (!(rule instanceof ICAL.Recur)) return;
+
+	if (rule.count !== null && occurrence.index >= 0) {
+		rule.count = occurrence.index;
+		rule.until = null;
+	} else {
+		rule.until = untilBefore(occurrence.slot);
+		rule.count = null;
+	}
+	property.setValue(rule);
+};
+
+/** The rule the remainder of a split series carries. */
+const applyRemainderRule = (
+	master: ICAL.Component,
+	occurrence: FoundOccurrence,
+): void => {
+	const property = master.getFirstProperty("rrule");
+	if (!property) return;
+	const rule = property.getFirstValue();
+	if (!(rule instanceof ICAL.Recur)) return;
+	if (rule.count === null || occurrence.index < 0) return;
+	rule.count = Math.max(rule.count - occurrence.index, 1);
+	property.setValue(rule);
+};
+
+const replaceWith = (calendar: ParsedCalendar): ScopedWrite => ({
+	kind: "Replace",
+	icalData: serializeCalendar(calendar.component),
+});
+
+const applyToMaster = async (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+	patch: Partial<CalendarEventFields>,
+): Promise<CalendarResult<ScopedWrite>> => {
+	const applied = await applyEventFields(
+		calendar.master,
+		patch,
+		collectionTimezone,
+	);
+	if (!applied.ok) return applied;
+	return { ok: true, value: replaceWith(calendar) };
+};
+
+/**
+ * The occurrence a `This` or `Following` write names, or `null` when the scope
+ * collapses to the whole series — which is what "everything from the first
+ * occurrence on" means.
+ */
+const anchorOf = (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+	input: ScopedWriteInput,
+): CalendarResult<FoundOccurrence | null> => {
+	if (!hasRecurrence(calendar)) {
+		return calendarFailure(
+			"NotRecurring",
+			"this event happens once, so there is no occurrence to single out — use scope=All",
+		);
+	}
+	if (input.recurrenceId === "") {
+		return calendarFailure(
+			"MissingRecurrenceId",
+			`scope=${input.scope} needs the recurrenceId of the occurrence it applies to`,
+		);
+	}
+
+	const found = findOccurrence(
+		calendar,
+		collectionTimezone,
+		input.recurrenceId,
+	);
+	if (!found.ok) return found;
+	if (input.scope !== RecurrenceScope.Following) {
+		return { ok: true, value: found.value };
+	}
+	if (found.value.index === 0) return { ok: true, value: null };
+	if (found.value.index < 0) {
+		return calendarFailure(
+			"UnknownOccurrence",
+			`${input.recurrenceId} is a moved instance rather than a point in the rule, so there is nothing to split there`,
+		);
+	}
+	return { ok: true, value: found.value };
+};
+
+/**
+ * The override VEVENT for one occurrence, built from the master when the
+ * resource does not already carry one.
+ */
+const overrideFor = async (
+	calendar: ParsedCalendar,
+	occurrence: FoundOccurrence,
+): Promise<CalendarResult<ICAL.Component>> => {
+	if (occurrence.override) return { ok: true, value: occurrence.override };
+
+	const clone = await cloneCalendar(calendar);
+	if (!clone.ok) return clone;
+	const override = clone.value.master;
+	for (const name of ["rrule", "rdate", "exdate"]) {
+		override.removeAllProperties(name);
+	}
+
+	const tzid = dtStartTzid(calendar.master);
+	override.addProperty(timeProperty("recurrence-id", occurrence.slot, tzid));
+	if (occurrence.details) {
+		setTimeValue(override, "dtstart", occurrence.details.startDate, tzid);
+		if (override.hasProperty("dtend")) {
+			setTimeValue(override, "dtend", occurrence.details.endDate, tzid);
+		}
+	}
+
+	calendar.component.addSubcomponent(override);
+	calendar.overrides.push(override);
+	return { ok: true, value: override };
+};
+
+/**
+ * Turns an edit of one drawing of a series into the resource writes it means.
+ *
+ * `All` rewrites the master. `This` writes a RECURRENCE-ID override, which is
+ * the only thing iCalendar has for "this one is different". `Following` splits,
+ * because a rule cannot change halfway through.
+ */
+export const applyScopedUpdate = async (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+	input: ScopedWriteInput,
+	patch: Partial<CalendarEventFields>,
+): Promise<CalendarResult<ScopedWrite>> => {
+	if (input.scope === RecurrenceScope.All) {
+		return applyToMaster(calendar, collectionTimezone, patch);
+	}
+
+	const anchored = anchorOf(calendar, collectionTimezone, input);
+	if (!anchored.ok) return anchored;
+	if (anchored.value === null) {
+		return applyToMaster(calendar, collectionTimezone, patch);
+	}
+	const occurrence = anchored.value;
+
+	if (input.scope === RecurrenceScope.This) {
+		const override = await overrideFor(calendar, occurrence);
+		if (!override.ok) return override;
+		// A rule belongs to a series; an override is one occurrence of it and
+		// carries no rule of its own.
+		const { recurrenceRule: _seriesOnly, ...occurrencePatch } = patch;
+		const applied = await applyEventFields(
+			override.value,
+			occurrencePatch,
+			collectionTimezone,
+		);
+		if (!applied.ok) return applied;
+		return { ok: true, value: replaceWith(calendar) };
+	}
+
+	const splitMs = Date.parse(occurrence.slotUtc);
+	const tail = await cloneCalendar(calendar);
+	if (!tail.ok) return tail;
+
+	const before = (slotMs: number) => slotMs < splitMs;
+	const fromHere = (slotMs: number) => slotMs >= splitMs;
+
+	truncateRule(calendar.master, occurrence);
+	keepOverrides(calendar, collectionTimezone, before);
+	keepDateValues(calendar.master, "rdate", collectionTimezone, before);
+	keepDateValues(calendar.master, "exdate", collectionTimezone, before);
+
+	applyRemainderRule(tail.value.master, occurrence);
+	keepOverrides(tail.value, collectionTimezone, fromHere);
+	keepDateValues(tail.value.master, "rdate", collectionTimezone, fromHere);
+	keepDateValues(tail.value.master, "exdate", collectionTimezone, fromHere);
+
+	const tzid = dtStartTzid(tail.value.master);
+	const tailEnd = occurrence.slot.clone();
+	tailEnd.addDuration(new ICAL.Event(tail.value.master).duration);
+	setTimeValue(tail.value.master, "dtstart", occurrence.slot, tzid);
+	if (tail.value.master.hasProperty("dtend")) {
+		setTimeValue(tail.value.master, "dtend", tailEnd, tzid);
+	}
+	for (const component of [tail.value.master, ...tail.value.overrides]) {
+		component.removeAllProperties("uid");
+		component.addPropertyWithValue("uid", input.followingUid);
+	}
+
+	const applied = await applyEventFields(
+		tail.value.master,
+		patch,
+		collectionTimezone,
+	);
+	if (!applied.ok) return applied;
+
+	return {
+		ok: true,
+		value: {
+			kind: "Split",
+			icalData: serializeCalendar(calendar.component),
+			following: serializeCalendar(tail.value.component),
+		},
+	};
+};
+
+/**
+ * Turns a delete of one drawing of a series into the resource writes it means.
+ *
+ * `This` is an EXDATE and `Following` truncates the rule; neither removes the
+ * resource, because the rest of the series is still somebody's calendar. `All`
+ * removes it.
+ */
+export const applyScopedDelete = async (
+	calendar: ParsedCalendar,
+	collectionTimezone: string,
+	input: ScopedWriteInput,
+): Promise<CalendarResult<ScopedWrite>> => {
+	if (input.scope === RecurrenceScope.All) {
+		return { ok: true, value: { kind: "Delete" } };
+	}
+
+	const anchored = anchorOf(calendar, collectionTimezone, input);
+	if (!anchored.ok) return anchored;
+	if (anchored.value === null) {
+		return { ok: true, value: { kind: "Delete" } };
+	}
+	const occurrence = anchored.value;
+	const splitMs = Date.parse(occurrence.slotUtc);
+
+	if (input.scope === RecurrenceScope.Following) {
+		const before = (slotMs: number) => slotMs < splitMs;
+		truncateRule(calendar.master, occurrence);
+		keepOverrides(calendar, collectionTimezone, before);
+		keepDateValues(calendar.master, "rdate", collectionTimezone, before);
+		keepDateValues(calendar.master, "exdate", collectionTimezone, before);
+		return { ok: true, value: replaceWith(calendar) };
+	}
+
+	if (occurrence.override) {
+		calendar.component.removeSubcomponent(occurrence.override);
+		calendar.overrides = calendar.overrides.filter(
+			(override) => override !== occurrence.override,
+		);
+	}
+	calendar.master.addProperty(
+		timeProperty("exdate", occurrence.slot, dtStartTzid(calendar.master)),
+	);
+	return { ok: true, value: replaceWith(calendar) };
+};

package/src/time.ts

@@ -124,6 +124,57 @@ const formatCivil = (
 export const toUtcIso = (instantMs: number): string =>
 	`${new Date(instantMs).toISOString().slice(0, 19)}Z`;
 
+/** Whether this platform can be asked about a zone by name. */
+export const isResolvableZone = (timeZone: string): boolean =>
+	isKnownZone(timeZone);
+
+/**
+ * The wall-clock fields an instant reads as in a zone, with the offset that
+ * zone was at. The zone falls back to UTC when it is one this platform cannot
+ * name, which is the same fallback `resolveTime` takes.
+ */
+export const civilInZone = (
+	instantMs: number,
+	timeZone: string,
+): {
+	year: number;
+	month: number;
+	day: number;
+	hour: number;
+	minute: number;
+	second: number;
+	offsetMinutes: number;
+} => {
+	const zone = isKnownZone(timeZone) ? timeZone : "UTC";
+	const offsetMinutes = zoneOffsetMinutes(zone, instantMs);
+	const shifted = new Date(instantMs + offsetMinutes * 60_000);
+	return {
+		year: shifted.getUTCFullYear(),
+		month: shifted.getUTCMonth() + 1,
+		day: shifted.getUTCDate(),
+		hour: shifted.getUTCHours(),
+		minute: shifted.getUTCMinutes(),
+		second: shifted.getUTCSeconds(),
+		offsetMinutes,
+	};
+};
+
+/**
+ * An instant as the wall time it reads as in a zone, carrying that zone's
+ * offset — the form a client renders.
+ *
+ * The store keeps occurrences as UTC instants because only a fixed-width form
+ * sorts correctly, and a client that was handed those would have to re-derive
+ * the event's own zone to draw it anywhere. This is the other direction, done
+ * once on the server: an occurrence of a 09:00 Amsterdam meeting comes back as
+ * `09:00+02:00` in summer and `09:00+01:00` in winter rather than as two
+ * different times of day.
+ */
+export const toOffsetIso = (instantMs: number, timeZone: string): string => {
+	const civil = civilInZone(instantMs, timeZone);
+	return formatCivil(civil, civil.offsetMinutes);
+};
+
 /**
  * Resolves one iCalendar time to an instant and to its own wall-clock form.
  *
@@ -192,3 +243,18 @@ export const tzidOf = (property: ICAL.Property | null): string => {
 	const tzid = property?.getParameter("tzid");
 	return typeof tzid === "string" ? tzid : "";
 };
+
+/** The zone a component's DTSTART was written in. */
+export const dtStartTzid = (component: ICAL.Component): string =>
+	tzidOf(component.getFirstProperty("dtstart"));
+
+/**
+ * The zone a component's end was written in. 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
+ * derived from a duration is already in the start's zone.
+ */
+export const dtEndTzid = (component: ICAL.Component): string =>
+	component.hasProperty("dtend")
+		? tzidOf(component.getFirstProperty("dtend"))
+		: dtStartTzid(component);