@remit/calendar-service 0.0.18 → 0.0.19

package/src/parse.test.ts

@@ -1,264 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { asLf, ical, singleEvent } from "./fixtures.js";
-import { parseCalendar, serializeCalendar } from "./parse.js";
-
-const parsed = async (icalData: string) => {
-	const result = await parseCalendar(icalData);
-	assert.ok(result.ok, `expected a parse, got ${JSON.stringify(result)}`);
-	return result.value;
-};
-
-const refusalCode = async (icalData: string) => {
-	const result = await parseCalendar(icalData);
-	assert.ok(!result.ok, "expected a refusal");
-	return result.error;
-};
-
-describe("parseCalendar", () => {
-	it("reads the master event and its UID", async () => {
-		const calendar = await parsed(
-			singleEvent("DTSTART:20260826T090000Z", "DTEND:20260826T100000Z"),
-		);
-
-		assert.equal(calendar.uid, "fixture@example.com");
-		assert.equal(calendar.master.name, "vevent");
-		assert.deepEqual(calendar.overrides, []);
-	});
-
-	it("separates the overrides from the master", async () => {
-		const calendar = await parsed(
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				"BEGIN:VEVENT",
-				"UID:series@example.com",
-				"DTSTART:20260826T090000Z",
-				"RRULE:FREQ=WEEKLY;COUNT=3",
-				"END:VEVENT",
-				"BEGIN:VEVENT",
-				"UID:series@example.com",
-				"RECURRENCE-ID:20260902T090000Z",
-				"DTSTART:20260902T110000Z",
-				"END:VEVENT",
-				"END:VCALENDAR",
-			),
-		);
-
-		assert.equal(calendar.overrides.length, 1);
-		assert.ok(!calendar.master.hasProperty("recurrence-id"));
-	});
-
-	it("refuses bytes that are not iCalendar", async () => {
-		assert.equal(
-			(await refusalCode("this is not a calendar")).code,
-			"MalformedIcalendar",
-		);
-	});
-
-	it("refuses empty bytes as a value, naming nothing rather than crashing", async () => {
-		// A suggestion read out of prose carries no iCalendar at all, and the
-		// accept path reaches this with `""`. ical.js reads empty bytes as a
-		// component with no name, so naming what arrived would throw here — a
-		// crash on ordinary input rather than the refusal every caller renders.
-		const refusal = await refusalCode("");
-
-		assert.equal(refusal.code, "NotACalendar");
-		assert.match(refusal.message, /found nothing/);
-	});
-
-	it("refuses a document whose root is not a VCALENDAR", async () => {
-		assert.equal(
-			(
-				await refusalCode(
-					ical("BEGIN:VCARD", "VERSION:4.0", "FN:Someone", "END:VCARD"),
-				)
-			).code,
-			"NotACalendar",
-		);
-	});
-
-	it("refuses a component this collection does not store, naming it", async () => {
-		const error = await refusalCode(
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				"BEGIN:VTODO",
-				"UID:todo@example.com",
-				"SUMMARY:Buy milk",
-				"END:VTODO",
-				"END:VCALENDAR",
-			),
-		);
-
-		assert.equal(error.code, "UnsupportedComponent");
-		assert.match(error.message, /VTODO/);
-	});
-
-	it("refuses a VCALENDAR with no VEVENT", async () => {
-		assert.equal(
-			(
-				await refusalCode(
-					ical("BEGIN:VCALENDAR", "VERSION:2.0", "END:VCALENDAR"),
-				)
-			).code,
-			"NoEvent",
-		);
-	});
-
-	it("refuses overrides with no event to override", async () => {
-		const error = await refusalCode(
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				"BEGIN:VEVENT",
-				"UID:orphan@example.com",
-				"RECURRENCE-ID:20260902T090000Z",
-				"DTSTART:20260902T110000Z",
-				"END:VEVENT",
-				"END:VCALENDAR",
-			),
-		);
-
-		assert.equal(error.code, "NoMasterEvent");
-	});
-
-	it("refuses two unrelated events in one resource", async () => {
-		const error = await refusalCode(
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				"BEGIN:VEVENT",
-				"UID:one@example.com",
-				"DTSTART:20260826T090000Z",
-				"END:VEVENT",
-				"BEGIN:VEVENT",
-				"UID:two@example.com",
-				"DTSTART:20260827T090000Z",
-				"END:VEVENT",
-				"END:VCALENDAR",
-			),
-		);
-
-		assert.equal(error.code, "MultipleMasterEvents");
-	});
-
-	it("refuses a VEVENT with no UID", async () => {
-		const error = await refusalCode(
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				"BEGIN:VEVENT",
-				"DTSTART:20260826T090000Z",
-				"END:VEVENT",
-				"END:VCALENDAR",
-			),
-		);
-
-		assert.equal(error.code, "MissingUid");
-	});
-
-	it("refuses an override that belongs to a different event", async () => {
-		const error = await refusalCode(
-			ical(
-				"BEGIN:VCALENDAR",
-				"VERSION:2.0",
-				"BEGIN:VEVENT",
-				"UID:series@example.com",
-				"DTSTART:20260826T090000Z",
-				"RRULE:FREQ=WEEKLY;COUNT=3",
-				"END:VEVENT",
-				"BEGIN:VEVENT",
-				"UID:stranger@example.com",
-				"RECURRENCE-ID:20260902T090000Z",
-				"DTSTART:20260902T110000Z",
-				"END:VEVENT",
-				"END:VCALENDAR",
-			),
-		);
-
-		assert.equal(error.code, "MismatchedUid");
-	});
-
-	it("refuses a VEVENT with no DTSTART", async () => {
-		assert.equal(
-			(await refusalCode(singleEvent("SUMMARY:Undated"))).code,
-			"MissingDtStart",
-		);
-	});
-});
-
-describe("serializeCalendar", () => {
-	it("keeps the line endings RFC 5545 requires", async () => {
-		const source = singleEvent(
-			"DTSTART:20260826T090000Z",
-			"DTEND:20260826T100000Z",
-		);
-
-		const serialized = serializeCalendar((await parsed(source)).component);
-
-		assert.ok(serialized.includes("\r\n"));
-		assert.doesNotMatch(
-			serialized,
-			/(?<!\r)\n/,
-			"every line break is a CRLF, with no bare LF left behind",
-		);
-	});
-
-	it("reads an LF-only resource and writes it back as CRLF", async () => {
-		// RFC 5545 says CRLF; real files arrive both ways, and a parser that only
-		// recognises CRLF reads an LF-only resource as one enormous line.
-		const source = asLf(
-			singleEvent("DTSTART:20260826T090000Z", "DTEND:20260826T100000Z"),
-		);
-		assert.ok(!source.includes("\r"), "the fixture is LF-only");
-
-		const calendar = await parsed(source);
-		const serialized = serializeCalendar(calendar.component);
-
-		assert.equal(calendar.uid, "fixture@example.com");
-		assert.ok(calendar.master.hasProperty("dtstart"));
-		assert.doesNotMatch(serialized, /(?<!\r)\n/);
-	});
-
-	it("round-trips a resource losslessly, unknown properties included", async () => {
-		const source = singleEvent(
-			"DTSTART:20260826T090000Z",
-			"DTEND:20260826T100000Z",
-			"SUMMARY:Quarterly review",
-			"X-APPLE-TRAVEL-ADVISORY-BEHAVIOR:AUTOMATIC",
-			"X-MICROSOFT-CDO-BUSYSTATUS:BUSY",
-			"ATTENDEE;CN=Someone;X-NUM-GUESTS=0:mailto:someone@example.com",
-		);
-
-		const once = serializeCalendar((await parsed(source)).component);
-		const twice = serializeCalendar((await parsed(once)).component);
-
-		assert.equal(twice, once);
-		for (const line of [
-			"X-APPLE-TRAVEL-ADVISORY-BEHAVIOR:AUTOMATIC",
-			"X-MICROSOFT-CDO-BUSYSTATUS:BUSY",
-			"X-NUM-GUESTS=0",
-			"SUMMARY:Quarterly review",
-		]) {
-			assert.ok(once.includes(line), `${line} did not survive the round trip`);
-		}
-	});
-
-	it("keeps a whole unknown subcomponent of the event", async () => {
-		const source = singleEvent(
-			"DTSTART:20260826T090000Z",
-			"DTEND:20260826T100000Z",
-			"BEGIN:VALARM",
-			"ACTION:DISPLAY",
-			"DESCRIPTION:Reminder",
-			"TRIGGER:-PT15M",
-			"END:VALARM",
-		);
-
-		const serialized = serializeCalendar((await parsed(source)).component);
-
-		assert.ok(serialized.includes("BEGIN:VALARM"));
-		assert.ok(serialized.includes("TRIGGER:-PT15M"));
-	});
-});

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");
-	});
-});