perf: cache fetched events within a refresh cycle

FeedEngine calls fetchContext then fetchItems with the same
context. Cache events by context.time reference to avoid
duplicate CalDAV round-trips.

Co-authored-by: Ona <no-reply@ona.com>

packages/aris-source-apple-calendar/src/calendar-source.test.ts

@@ -48,12 +48,13 @@ class MockCredentialProvider implements CalendarCredentialProvider {
 
 class MockDAVClient implements CalendarDAVClient {
 	credentials: Record<string, unknown> = {}
+	fetchCalendarsCallCount = 0
 	private calendars: CalendarDAVCalendar[]
-	private objectsByCalendarUrl: Map<string, CalendarDAVObject[]>
+	private objectsByCalendarUrl: Record<string, CalendarDAVObject[]>
 
 	constructor(
 		calendars: CalendarDAVCalendar[],
-		objectsByCalendarUrl: Map<string, CalendarDAVObject[]>,
+		objectsByCalendarUrl: Record<string, CalendarDAVObject[]>,
 	) {
 		this.calendars = calendars
 		this.objectsByCalendarUrl = objectsByCalendarUrl
@@ -62,6 +63,7 @@ class MockDAVClient implements CalendarDAVClient {
 	async login(): Promise<void> {}
 
 	async fetchCalendars(): Promise<CalendarDAVCalendar[]> {
+		this.fetchCalendarsCallCount++
 		return this.calendars
 	}
 
@@ -69,7 +71,7 @@ class MockDAVClient implements CalendarDAVClient {
 		calendar: CalendarDAVCalendar
 		timeRange: { start: string; end: string }
 	}): Promise<CalendarDAVObject[]> {
-		return this.objectsByCalendarUrl.get(params.calendar.url) ?? []
+		return this.objectsByCalendarUrl[params.calendar.url] ?? []
 	}
 }
 
@@ -86,7 +88,7 @@ describe("CalendarSource", () => {
 	})
 
 	test("returns empty array when no calendars exist", async () => {
-		const client = new MockDAVClient([], new Map())
+		const client = new MockDAVClient([], {})
 		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
 			davClient: client,
 		})
@@ -95,9 +97,9 @@ describe("CalendarSource", () => {
 	})
 
 	test("returns feed items from a single calendar", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			["/cal/work", [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }]],
-		])
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
 		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
 		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
 			davClient: client,
@@ -116,13 +118,12 @@ describe("CalendarSource", () => {
 	})
 
 	test("returns feed items from multiple calendars", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			["/cal/work", [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }]],
-			[
-				"/cal/personal",
-				[{ url: "/cal/personal/event2.ics", data: loadFixture("all-day-event.ics") }],
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+			"/cal/personal": [
+				{ url: "/cal/personal/event2.ics", data: loadFixture("all-day-event.ics") },
 			],
-		])
+		}
 		const client = new MockDAVClient(
 			[
 				{ url: "/cal/work", displayName: "Work" },
@@ -150,16 +151,13 @@ describe("CalendarSource", () => {
 	})
 
 	test("skips objects with non-string data", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			[
-				"/cal/work",
-				[
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
 				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
 				{ url: "/cal/work/bad.ics", data: 12345 },
 				{ url: "/cal/work/empty.ics" },
 			],
-			],
-		])
+		}
 		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
 		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
 			davClient: client,
@@ -171,9 +169,9 @@ describe("CalendarSource", () => {
 	})
 
 	test("uses context time as feed item timestamp", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			["/cal/work", [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }]],
-		])
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
 		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
 		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
 			davClient: client,
@@ -185,15 +183,12 @@ describe("CalendarSource", () => {
 	})
 
 	test("assigns priority based on event proximity", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			[
-				"/cal/work",
-				[
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
 				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
 				{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") },
 			],
-			],
-		])
+		}
 		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
 		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
 			davClient: client,
@@ -210,9 +205,9 @@ describe("CalendarSource", () => {
 	})
 
 	test("handles calendar with non-string displayName", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			["/cal/weird", [{ url: "/cal/weird/event1.ics", data: loadFixture("minimal-event.ics") }]],
-		])
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/weird": [{ url: "/cal/weird/event1.ics", data: loadFixture("minimal-event.ics") }],
+		}
 		const client = new MockDAVClient(
 			[{ url: "/cal/weird", displayName: { _cdata: "Weird Calendar" } }],
 			objects,
@@ -226,9 +221,9 @@ describe("CalendarSource", () => {
 	})
 
 	test("handles recurring events with exceptions", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			["/cal/work", [{ url: "/cal/work/recurring.ics", data: loadFixture("recurring-event.ics") }]],
-		])
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/recurring.ics", data: loadFixture("recurring-event.ics") }],
+		}
 		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
 		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
 			davClient: client,
@@ -248,6 +243,40 @@ describe("CalendarSource", () => {
 		expect(exception!.data.recurrenceId).not.toBeNull()
 		expect(exception!.id).toContain("-")
 	})
+
+	test("caches events within the same refresh cycle", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const context = createContext(new Date("2026-01-15T12:00:00Z"))
+
+		await source.fetchContext(context)
+		await source.fetchItems(context)
+
+		// Same context.time reference — fetchEvents should only hit the client once
+		expect(client.fetchCalendarsCallCount).toBe(1)
+	})
+
+	test("refetches events for a different context time", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		await source.fetchItems(createContext(new Date("2026-01-15T13:00:00Z")))
+
+		// Different context.time references — should fetch twice
+		expect(client.fetchCalendarsCallCount).toBe(2)
+	})
 })
 
 describe("CalendarSource.fetchContext", () => {
@@ -264,9 +293,9 @@ describe("CalendarSource.fetchContext", () => {
 	})
 
 	test("identifies in-progress events", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			["/cal/work", [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }]],
-		])
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
 		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
 		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
 			davClient: client,
@@ -281,9 +310,9 @@ describe("CalendarSource.fetchContext", () => {
 	})
 
 	test("identifies next upcoming event", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			["/cal/work", [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }]],
-		])
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
 		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
 		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
 			davClient: client,
@@ -299,9 +328,9 @@ describe("CalendarSource.fetchContext", () => {
 	})
 
 	test("excludes all-day events from inProgress and nextEvent", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			["/cal/work", [{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") }]],
-		])
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") }],
+		}
 		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
 		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
 			davClient: client,
@@ -317,15 +346,12 @@ describe("CalendarSource.fetchContext", () => {
 	})
 
 	test("counts all events including all-day in todayEventCount", async () => {
-		const objects = new Map<string, CalendarDAVObject[]>([
-			[
-				"/cal/work",
-				[
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
 				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
 				{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") },
 			],
-			],
-		])
+		}
 		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
 		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
 			davClient: client,

packages/aris-source-apple-calendar/src/calendar-source.ts

@@ -8,9 +8,15 @@ import type {
 	CalendarDAVClient,
 	CalendarEventData,
 	CalendarFeedItem,
-	CalendarSourceOptions,
 } from "./types.ts"
 
+export interface CalendarSourceOptions {
+	/** Number of additional days beyond today to fetch. Default: 0 (today only). */
+	lookAheadDays?: number
+	/** Optional DAVClient instance for testing. Uses tsdav DAVClient by default. */
+	davClient?: CalendarDAVClient
+}
+
 import { CalendarKey, type CalendarContext } from "./calendar-context.ts"
 import { parseICalEvents } from "./ical-parser.ts"
 
@@ -39,6 +45,7 @@ export class CalendarSource implements FeedSource<CalendarFeedItem> {
 	private readonly injectedClient: CalendarDAVClient | null
 	private davClient: CalendarDAVClient | null = null
 	private lastAccessToken: string | null = null
+	private cachedEvents: { time: Date; events: CalendarEventData[] } | null = null
 
 	constructor(
 		credentialProvider: CalendarCredentialProvider,
@@ -88,6 +95,10 @@ export class CalendarSource implements FeedSource<CalendarFeedItem> {
 	}
 
 	private async fetchEvents(context: Context): Promise<CalendarEventData[]> {
+		if (this.cachedEvents && this.cachedEvents.time === context.time) {
+			return this.cachedEvents.events
+		}
+
 		const credentials = await this.credentialProvider.fetchCredentials(this.userId)
 		if (!credentials) {
 			return []
@@ -128,6 +139,7 @@ export class CalendarSource implements FeedSource<CalendarFeedItem> {
 			}
 		}
 
+		this.cachedEvents = { time: context.time, events: allEvents }
 		return allEvents
 	}
 

packages/aris-source-apple-calendar/src/ical-parser.ts

@@ -52,11 +52,16 @@ function parseVEvent(
 
 function parseStatus(raw: string | null): CalendarEventStatus | null {
 	if (!raw) return null
-	const lower = raw.toLowerCase()
-	if (lower === "confirmed") return CalendarEventStatus.Confirmed
-	if (lower === "tentative") return CalendarEventStatus.Tentative
-	if (lower === "cancelled") return CalendarEventStatus.Cancelled
+	switch (raw.toLowerCase()) {
+		case "confirmed":
+			return CalendarEventStatus.Confirmed
+		case "tentative":
+			return CalendarEventStatus.Tentative
+		case "cancelled":
+			return CalendarEventStatus.Cancelled
+		default:
 			return null
+	}
 }
 
 function parseOrganizer(
@@ -97,21 +102,32 @@ function parseAttendees(properties: unknown[]): CalendarAttendee[] {
 
 function parseAttendeeRole(raw: string | null): AttendeeRole | null {
 	if (!raw) return null
-	const upper = raw.toUpperCase()
-	if (upper === "CHAIR") return AttendeeRole.Chair
-	if (upper === "REQ-PARTICIPANT") return AttendeeRole.Required
-	if (upper === "OPT-PARTICIPANT") return AttendeeRole.Optional
+	switch (raw.toUpperCase()) {
+		case "CHAIR":
+			return AttendeeRole.Chair
+		case "REQ-PARTICIPANT":
+			return AttendeeRole.Required
+		case "OPT-PARTICIPANT":
+			return AttendeeRole.Optional
+		default:
 			return null
+	}
 }
 
 function parseAttendeeStatus(raw: string | null): AttendeeStatus | null {
 	if (!raw) return null
-	const upper = raw.toUpperCase()
-	if (upper === "ACCEPTED") return AttendeeStatus.Accepted
-	if (upper === "DECLINED") return AttendeeStatus.Declined
-	if (upper === "TENTATIVE") return AttendeeStatus.Tentative
-	if (upper === "NEEDS-ACTION") return AttendeeStatus.NeedsAction
+	switch (raw.toUpperCase()) {
+		case "ACCEPTED":
+			return AttendeeStatus.Accepted
+		case "DECLINED":
+			return AttendeeStatus.Declined
+		case "TENTATIVE":
+			return AttendeeStatus.Tentative
+		case "NEEDS-ACTION":
+			return AttendeeStatus.NeedsAction
+		default:
 			return null
+	}
 }
 
 function parseAlarms(vevent: InstanceType<typeof ICAL.Component>): CalendarAlarm[] {

packages/aris-source-apple-calendar/src/index.ts

@@ -1,5 +1,5 @@
 export { CalendarKey, type CalendarContext } from "./calendar-context.ts"
-export { CalendarSource } from "./calendar-source.ts"
+export { CalendarSource, type CalendarSourceOptions } from "./calendar-source.ts"
 export {
 	CalendarEventStatus,
 	AttendeeRole,
@@ -13,5 +13,4 @@ export {
 	type CalendarAlarm,
 	type CalendarEventData,
 	type CalendarFeedItem,
-	type CalendarSourceOptions,
 } from "./types.ts"

packages/aris-source-apple-calendar/src/types.ts

@@ -99,12 +99,3 @@ export interface CalendarDAVClient {
 	}): Promise<CalendarDAVObject[]>
 	credentials: Record<string, unknown>
 }
-
-// -- Source options --
-
-export interface CalendarSourceOptions {
-	/** Number of additional days beyond today to fetch. Default: 0 (today only). */
-	lookAheadDays?: number
-	/** Optional DAVClient instance for testing. Uses tsdav DAVClient by default. */
-	davClient?: CalendarDAVClient
-}