@remit/calendar-service 0.0.17 → 0.0.19

package/src/parse.ts

@@ -1,138 +0,0 @@
-import ICAL from "ical.js";
-import { type CalendarResult, calendarFailure } from "./errors.js";
-
-/** Components a VEVENT-only collection accepts at the top level of a resource. */
-const ACCEPTED_COMPONENTS = new Set(["vevent", "vtimezone"]);
-
-export interface ParsedCalendar {
-	/** The VCALENDAR, with every property and component the input carried. */
-	component: ICAL.Component;
-	/** The VEVENT without a RECURRENCE-ID. */
-	master: ICAL.Component;
-	/** The VEVENTs carrying a RECURRENCE-ID, in document order. */
-	overrides: ICAL.Component[];
-	uid: string;
-}
-
-/**
- * Serializes a VCALENDAR back to iCalendar text.
- *
- * Lossless by construction: ical.js keeps every property it parsed, including
- * ones it has no design rule for, so an X- property or a whole unknown
- * component survives the round trip. The output is always CRLF (RFC 5545 3.1),
- * whatever the input used.
- *
- * The write path does not call this. A resource is stored as the bytes it
- * arrived in — LF-only ones included — because the etag is a digest of exactly
- * what the writer sent; running a stored resource through here would rewrite
- * its line endings, refold its long lines, and move the tag of a resource
- * nobody edited. This is for building a VCALENDAR, not for keeping one.
- */
-export const serializeCalendar = (component: ICAL.Component): string =>
-	component.toString();
-
-/**
- * ical.js's parser in a promise, so unreadable bytes arrive as a rejection to
- * branch on rather than a synchronous throw.
- */
-export const readCalendarComponent = (
-	icalData: string,
-): Promise<CalendarResult<ICAL.Component>> =>
-	new Promise<ICAL.Component>((resolve) => {
-		resolve(new ICAL.Component(ICAL.parse(icalData)));
-	}).then(
-		(component) => ({ ok: true, value: component }) as const,
-		(error: unknown) =>
-			calendarFailure<ICAL.Component>(
-				"MalformedIcalendar",
-				error instanceof Error ? error.message : "unreadable iCalendar data",
-			),
-	);
-
-/**
- * Reads and validates a VCALENDAR carrying exactly one event.
- *
- * Every refusal is a returned value. The input is client-supplied bytes, so a
- * malformed resource is an ordinary outcome of this function rather than a
- * fault.
- */
-export const parseCalendar = async (
-	icalData: string,
-): Promise<CalendarResult<ParsedCalendar>> => {
-	const read = await readCalendarComponent(icalData);
-	if (!read.ok) return read;
-	const component = read.value;
-
-	if (component.name !== "vcalendar") {
-		// A document with nothing in it names nothing: ical.js reads empty bytes
-		// as a component with no name at all, and a suggestion read out of prose
-		// carries exactly that. Naming what arrived is for a document that has a
-		// root to name.
-		return calendarFailure(
-			"NotACalendar",
-			component.name
-				? `expected a VCALENDAR, found ${component.name.toUpperCase()}`
-				: "expected a VCALENDAR, found nothing",
-		);
-	}
-
-	const unsupported = component
-		.getAllSubcomponents()
-		.map((child) => child.name)
-		.find((name) => !ACCEPTED_COMPONENTS.has(name));
-	if (unsupported) {
-		return calendarFailure(
-			"UnsupportedComponent",
-			`this calendar stores VEVENT only, and the resource carries a ${unsupported.toUpperCase()}`,
-		);
-	}
-
-	const events = component.getAllSubcomponents("vevent");
-	if (events.length === 0) {
-		return calendarFailure("NoEvent", "the resource carries no VEVENT");
-	}
-
-	const masters = events.filter((event) => !event.hasProperty("recurrence-id"));
-	if (masters.length === 0) {
-		return calendarFailure(
-			"NoMasterEvent",
-			"every VEVENT carries a RECURRENCE-ID, so there is no event for them to override",
-		);
-	}
-	if (masters.length > 1) {
-		return calendarFailure(
-			"MultipleMasterEvents",
-			`one resource holds one event, and this one holds ${masters.length}`,
-		);
-	}
-
-	const master = masters[0] as ICAL.Component;
-	const uid = master.getFirstPropertyValue("uid");
-	if (typeof uid !== "string" || uid === "") {
-		return calendarFailure("MissingUid", "the VEVENT declares no UID");
-	}
-
-	const mismatched = events.find(
-		(event) => event.getFirstPropertyValue("uid") !== uid,
-	);
-	if (mismatched) {
-		return calendarFailure(
-			"MismatchedUid",
-			"the VEVENTs in this resource declare different UIDs",
-		);
-	}
-
-	if (!master.hasProperty("dtstart")) {
-		return calendarFailure("MissingDtStart", "the VEVENT declares no DTSTART");
-	}
-
-	return {
-		ok: true,
-		value: {
-			component,
-			master,
-			overrides: events.filter((event) => event.hasProperty("recurrence-id")),
-			uid,
-		},
-	};
-};

package/src/project.test.ts

@@ -1,247 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { AMSTERDAM_VTIMEZONE, ical, singleEvent } from "./fixtures.js";
-import { parseCalendar } from "./parse.js";
-import { projectCalendar } from "./project.js";
-
-const project = async (icalData: string, timezone = "") => {
-	const parsed = await parseCalendar(icalData);
-	assert.ok(parsed.ok, `expected a parse, got ${JSON.stringify(parsed)}`);
-	return projectCalendar(parsed.value, timezone);
-};
-
-const projection = async (icalData: string, timezone = "") => {
-	const result = await project(icalData, timezone);
-	assert.ok(result.ok, `expected a projection, got ${JSON.stringify(result)}`);
-	return result.value;
-};
-
-describe("projectCalendar", () => {
-	it("projects the columns a UTC event carries", async () => {
-		const value = await projection(
-			singleEvent(
-				"DTSTART:20260826T090000Z",
-				"DTEND:20260826T100000Z",
-				"SUMMARY:Quarterly review",
-				"STATUS:TENTATIVE",
-				"TRANSP:TRANSPARENT",
-				"SEQUENCE:3",
-			),
-		);
-
-		assert.deepEqual(value, {
-			icalUid: "fixture@example.com",
-			summary: "Quarterly review",
-			dtStart: "2026-08-26T09:00:00+00:00",
-			dtEnd: "2026-08-26T10:00:00+00:00",
-			allDay: false,
-			zoneCertainty: "Explicit",
-			status: "Tentative",
-			transparency: "Transparent",
-			hasRecurrence: false,
-			sequence: 3,
-		});
-	});
-
-	it("gives an event that states neither the RFC's defaults", async () => {
-		const value = await projection(
-			singleEvent("DTSTART:20260826T090000Z", "DTEND:20260826T100000Z"),
-		);
-
-		assert.equal(value.status, "Confirmed");
-		assert.equal(value.transparency, "Opaque");
-		assert.equal(value.summary, "");
-		assert.equal(value.sequence, 0);
-	});
-
-	it("keeps the event's own offset, resolved from the VTIMEZONE it carries", async () => {
-		const value = await projection(
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				...AMSTERDAM_VTIMEZONE,
-				"BEGIN:VEVENT",
-				"UID:fixture@example.com",
-				"DTSTART;TZID=Europe/Amsterdam:20260826T090000",
-				"DTEND;TZID=Europe/Amsterdam:20260826T100000",
-				"END:VEVENT",
-				"END:VCALENDAR",
-			),
-		);
-
-		assert.equal(value.dtStart, "2026-08-26T09:00:00+02:00");
-		assert.equal(value.dtEnd, "2026-08-26T10:00:00+02:00");
-	});
-
-	it("resolves a TZID the resource carries no VTIMEZONE for", async () => {
-		const value = await projection(
-			singleEvent(
-				"DTSTART;TZID=Europe/Berlin:20260826T090000",
-				"DTEND;TZID=Europe/Berlin:20260826T100000",
-			),
-		);
-
-		assert.equal(value.dtStart, "2026-08-26T09:00:00+02:00");
-	});
-
-	it("reads a floating time in the collection's timezone", async () => {
-		const value = await projection(
-			singleEvent("DTSTART:20260826T090000", "DTEND:20260826T100000"),
-			"Europe/Berlin",
-		);
-
-		assert.equal(value.dtStart, "2026-08-26T09:00:00+02:00");
-	});
-
-	it("marks a zone nothing could resolve as ambiguous rather than reading it as UTC in silence", async () => {
-		// A Windows zone name with no VTIMEZONE. The event still gets an instant —
-		// there is nothing else to give it — but a two-hour error that presents as
-		// a fact is the failure this marker exists to prevent.
-		const value = await projection(
-			singleEvent(
-				"DTSTART;TZID=W. Europe Standard Time:20260826T090000",
-				"DTEND;TZID=W. Europe Standard Time:20260826T100000",
-			),
-		);
-
-		assert.equal(value.dtStart, "2026-08-26T09:00:00+00:00");
-		assert.equal(value.zoneCertainty, "Ambiguous");
-	});
-
-	it("marks a floating time as local to the collection", async () => {
-		const value = await projection(
-			singleEvent("DTSTART:20260826T090000", "DTEND:20260826T100000"),
-			"Europe/Berlin",
-		);
-
-		assert.equal(value.zoneCertainty, "Local");
-	});
-
-	it("marks a zone that resolved as explicit, however it resolved", async () => {
-		const fromVtimezone = await projection(
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				...AMSTERDAM_VTIMEZONE,
-				"BEGIN:VEVENT",
-				"UID:fixture@example.com",
-				"DTSTART;TZID=Europe/Amsterdam:20260826T090000",
-				"DTEND;TZID=Europe/Amsterdam:20260826T100000",
-				"END:VEVENT",
-				"END:VCALENDAR",
-			),
-		);
-		const fromPlatform = await projection(
-			singleEvent(
-				"DTSTART;TZID=Europe/Berlin:20260826T090000",
-				"DTEND;TZID=Europe/Berlin:20260826T100000",
-			),
-		);
-		const fromUtc = await projection(
-			singleEvent("DTSTART:20260826T090000Z", "DTEND:20260826T100000Z"),
-		);
-
-		assert.equal(fromVtimezone.zoneCertainty, "Explicit");
-		assert.equal(fromPlatform.zoneCertainty, "Explicit");
-		assert.equal(fromUtc.zoneCertainty, "Explicit");
-	});
-
-	it("projects an all-day event as midnight with an exclusive end", async () => {
-		const value = await projection(
-			singleEvent("DTSTART;VALUE=DATE:20260826", "DTEND;VALUE=DATE:20260828"),
-			"Europe/Berlin",
-		);
-
-		assert.equal(value.allDay, true);
-		assert.equal(value.dtStart, "2026-08-26T00:00:00+02:00");
-		assert.equal(value.dtEnd, "2026-08-28T00:00:00+02:00");
-	});
-
-	it("ends a one-day all-day event on the following day, per RFC 5545", async () => {
-		const value = await projection(
-			singleEvent("DTSTART;VALUE=DATE:20260826"),
-			"Europe/Berlin",
-		);
-
-		assert.equal(value.dtEnd, "2026-08-27T00:00:00+02:00");
-	});
-
-	it("resolves an end stated as a DURATION", async () => {
-		const value = await projection(
-			singleEvent("DTSTART:20260826T090000Z", "DURATION:PT90M"),
-		);
-
-		assert.equal(value.dtEnd, "2026-08-26T10:30:00+00:00");
-	});
-
-	it("marks an event that recurs", async () => {
-		const withRrule = await projection(
-			singleEvent("DTSTART:20260826T090000Z", "RRULE:FREQ=WEEKLY;COUNT=3"),
-		);
-		const withRdate = await projection(
-			singleEvent("DTSTART:20260826T090000Z", "RDATE:20260902T090000Z"),
-		);
-		const withOnlyOverrides = await projection(
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				"BEGIN:VEVENT",
-				"UID:fixture@example.com",
-				"DTSTART:20260826T090000Z",
-				"DTEND:20260826T100000Z",
-				"END:VEVENT",
-				"BEGIN:VEVENT",
-				"UID:fixture@example.com",
-				"RECURRENCE-ID:20260902T090000Z",
-				"DTSTART:20260902T110000Z",
-				"DTEND:20260902T120000Z",
-				"END:VEVENT",
-				"END:VCALENDAR",
-			),
-		);
-
-		assert.equal(withRrule.hasRecurrence, true);
-		assert.equal(withRdate.hasRecurrence, true);
-		assert.equal(withOnlyOverrides.hasRecurrence, true);
-	});
-
-	it("refuses an event that ends before it starts, naming both times", async () => {
-		const result = await project(
-			singleEvent("DTSTART:20260826T100000Z", "DTEND:20260826T090000Z"),
-		);
-
-		assert.ok(!result.ok);
-		assert.equal(result.error.code, "BackwardsEnd");
-		assert.match(result.error.message, /2026-08-26T09:00:00Z/);
-		assert.match(result.error.message, /2026-08-26T10:00:00Z/);
-	});
-
-	it("refuses an event whose end precedes its start only once zones are applied", async () => {
-		// 09:30 in Amsterdam is 07:30Z, half an hour before the 08:00Z start — a
-		// comparison of the wall-clock strings would have called this fine.
-		const result = await project(
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				...AMSTERDAM_VTIMEZONE,
-				"BEGIN:VEVENT",
-				"UID:fixture@example.com",
-				"DTSTART:20260826T080000Z",
-				"DTEND;TZID=Europe/Amsterdam:20260826T093000",
-				"END:VEVENT",
-				"END:VCALENDAR",
-			),
-		);
-
-		assert.ok(!result.ok);
-		assert.equal(result.error.code, "BackwardsEnd");
-	});
-
-	it("accepts a zero-length event", async () => {
-		const value = await projection(
-			singleEvent("DTSTART:20260826T090000Z", "DTEND:20260826T090000Z"),
-		);
-
-		assert.equal(value.dtEnd, "2026-08-26T09:00:00+00:00");
-	});
-});

package/src/project.ts

@@ -1,122 +0,0 @@
-import type { CalendarObjectItem } from "@remit/data-ports";
-import { CalendarEventStatus, CalendarTransparency } from "@remit/domain-enums";
-import ICAL from "ical.js";
-import { type CalendarResult, calendarFailure } from "./errors.js";
-import type { ParsedCalendar } from "./parse.js";
-import { resolveTime, tzidOf } from "./time.js";
-
-/**
- * The columns `CalendarObject` carries beside its bytes. Every one of them is
- * read out of the VEVENT here and nowhere else, so the row can only ever
- * describe the `icalData` it was written with.
- */
-export type CalendarObjectProjection = Pick<
-	CalendarObjectItem,
-	| "icalUid"
-	| "summary"
-	| "dtStart"
-	| "dtEnd"
-	| "allDay"
-	| "zoneCertainty"
-	| "status"
-	| "transparency"
-	| "hasRecurrence"
-	| "sequence"
->;
-
-const STATUS_BY_ICAL: Record<string, CalendarObjectItem["status"]> = {
-	CONFIRMED: CalendarEventStatus.Confirmed,
-	TENTATIVE: CalendarEventStatus.Tentative,
-	CANCELLED: CalendarEventStatus.Cancelled,
-};
-
-const TRANSPARENCY_BY_ICAL: Record<string, CalendarObjectItem["transparency"]> =
-	{
-		OPAQUE: CalendarTransparency.Opaque,
-		TRANSPARENT: CalendarTransparency.Transparent,
-	};
-
-export const readString = (component: ICAL.Component, name: string): string => {
-	const value = component.getFirstPropertyValue(name);
-	return typeof value === "string" ? value : "";
-};
-
-/**
- * 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,
-});
-
-/**
- * Whether the resource expands to more than its master instance — an RRULE, an
- * RDATE, or an override VEVENT. The overrides count: a client that edits one
- * instance of a series and then deletes the rule leaves a resource with nothing
- * but a master and its exceptions, and every one of those is still an
- * occurrence somebody has to see.
- */
-export const hasRecurrence = (calendar: ParsedCalendar): boolean =>
-	calendar.master.hasProperty("rrule") ||
-	calendar.master.hasProperty("rdate") ||
-	calendar.overrides.length > 0;
-
-export const projectCalendar = (
-	calendar: ParsedCalendar,
-	collectionTimezone: string,
-): CalendarResult<CalendarObjectProjection> => {
-	const event = new ICAL.Event(calendar.master);
-	const start = resolveTime(
-		event.startDate,
-		tzidOf(calendar.master.getFirstProperty("dtstart")),
-		collectionTimezone,
-	);
-	const end = resolveTime(
-		event.endDate,
-		tzidOf(
-			calendar.master.getFirstProperty("dtend") ??
-				calendar.master.getFirstProperty("dtstart"),
-		),
-		collectionTimezone,
-	);
-
-	if (end.instantMs < start.instantMs) {
-		return calendarFailure(
-			"BackwardsEnd",
-			`the event ends at ${end.isoUtc}, before it starts at ${start.isoUtc}`,
-		);
-	}
-
-	const sequence = calendar.master.getFirstPropertyValue("sequence");
-
-	return {
-		ok: true,
-		value: {
-			icalUid: calendar.uid,
-			dtStart: start.isoOffset,
-			dtEnd: end.isoOffset,
-			allDay: start.isDate,
-			zoneCertainty: start.certainty,
-			...projectEventDisplay(calendar.master),
-			hasRecurrence: hasRecurrence(calendar),
-			sequence: typeof sequence === "number" ? sequence : 0,
-		},
-	};
-};