@remit/calendar-service 0.0.18 → 0.0.19

package/dist/time.js

@@ -0,0 +1,164 @@
+import { ZoneCertainty } from "@remit/domain-enums";
+import ICAL from "ical.js";
+const pad = (value, width = 2) => String(Math.abs(value)).padStart(width, "0");
+const civilOf = (time) => ({
+    year: time.year,
+    month: time.month,
+    day: time.day,
+    hour: time.isDate ? 0 : time.hour,
+    minute: time.isDate ? 0 : time.minute,
+    second: time.isDate ? 0 : time.second,
+});
+/**
+ * The offset an IANA zone was at on a given instant, in minutes.
+ *
+ * Read from the platform's own zone database through `Intl` rather than from a
+ * bundled copy: ical.js ships no zone data, and a resource whose TZID names a
+ * zone it carries no VTIMEZONE for is otherwise unresolvable — which is how a
+ * DST-crossing series silently drifts by an hour.
+ */
+const zoneOffsetMinutes = (timeZone, instantMs) => {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    }).formatToParts(new Date(instantMs));
+    const field = (type) => Number(parts.find((part) => part.type === type)?.value ?? "0");
+    const asUtc = Date.UTC(field("year"), field("month") - 1, field("day"), field("hour"), field("minute"), field("second"));
+    return (asUtc - instantMs) / 60_000;
+};
+/**
+ * The zones this platform can be asked about.
+ *
+ * Read once from the runtime rather than probed per value: an unusable TZID —
+ * a Windows zone name, a typo — makes `Intl` throw, and a resource written by a
+ * client with a zone we cannot name is a resource to read in the next fallback,
+ * never a crashed write. The list is the canonical IANA set, so a deprecated
+ * alias falls through to the collection's own zone.
+ */
+const KNOWN_ZONES = new Set(Intl.supportedValuesOf("timeZone"));
+const isKnownZone = (timeZone) => KNOWN_ZONES.has(timeZone);
+/**
+ * The offset a civil wall time carries in a zone. Applied twice because the
+ * first lookup asks the zone about the wrong instant — the wall time read as if
+ * it were UTC — which lands in the wrong side of a DST transition for wall
+ * times within an hour or so of the cutover.
+ */
+const offsetForCivil = (timeZone, civil) => {
+    const asUtc = Date.UTC(civil.year, civil.month - 1, civil.day, civil.hour, civil.minute, civil.second);
+    const firstPass = zoneOffsetMinutes(timeZone, asUtc);
+    return zoneOffsetMinutes(timeZone, asUtc - firstPass * 60_000);
+};
+const formatOffset = (offsetMinutes) => {
+    const sign = offsetMinutes < 0 ? "-" : "+";
+    return `${sign}${pad(Math.trunc(offsetMinutes / 60))}:${pad(offsetMinutes % 60)}`;
+};
+const formatCivil = (civil, offsetMinutes) => `${pad(civil.year, 4)}-${pad(civil.month)}-${pad(civil.day)}T${pad(civil.hour)}:${pad(civil.minute)}:${pad(civil.second)}${formatOffset(offsetMinutes)}`;
+export const toUtcIso = (instantMs) => `${new Date(instantMs).toISOString().slice(0, 19)}Z`;
+/** Whether this platform can be asked about a zone by name. */
+export const isResolvableZone = (timeZone) => 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, timeZone) => {
+    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, timeZone) => {
+    const civil = civilInZone(instantMs, timeZone);
+    return formatCivil(civil, civil.offsetMinutes);
+};
+/**
+ * Resolves one iCalendar time to an instant and to its own wall-clock form.
+ *
+ * The zone is taken from the value itself when ical.js could bind one — a
+ * VTIMEZONE defined in this very resource, or UTC. A floating value, and a
+ * value whose TZID has no VTIMEZONE, falls back to `tzidHint` (the property's
+ * own TZID parameter) and then to the collection's timezone, so a resource
+ * written by a client that assumes the server knows the zone database still
+ * lands on the right instant.
+ *
+ * Which of those happened is reported, never swallowed: a named zone that no
+ * fallback could resolve comes back `Ambiguous`, so a caller can say the event
+ * may be hours out instead of drawing it in the wrong place in silence.
+ */
+export const resolveTime = (time, tzidHint, collectionTimezone) => {
+    const civil = civilOf(time);
+    let offsetMinutes;
+    let certainty;
+    if (time.zone === ICAL.Timezone.utcTimezone) {
+        offsetMinutes = 0;
+        certainty = ZoneCertainty.Explicit;
+    }
+    else if (time.zone !== ICAL.Timezone.localTimezone) {
+        offsetMinutes = time.utcOffset() / 60;
+        certainty = ZoneCertainty.Explicit;
+    }
+    else {
+        const fallback = [tzidHint, collectionTimezone].find(isKnownZone) ?? "UTC";
+        offsetMinutes = offsetForCivil(fallback, civil);
+        if (tzidHint === "") {
+            // No zone was ever named. RFC 5545 floating time, read where the
+            // collection lives.
+            certainty = ZoneCertainty.Local;
+        }
+        else {
+            certainty = isKnownZone(tzidHint)
+                ? ZoneCertainty.Explicit
+                : ZoneCertainty.Ambiguous;
+        }
+    }
+    const instantMs = Date.UTC(civil.year, civil.month - 1, civil.day, civil.hour, civil.minute, civil.second) -
+        offsetMinutes * 60_000;
+    return {
+        instantMs,
+        isoUtc: toUtcIso(instantMs),
+        isoOffset: formatCivil(civil, offsetMinutes),
+        isDate: time.isDate,
+        certainty,
+    };
+};
+/** The TZID a property was written with, or `""` when it names none. */
+export const tzidOf = (property) => {
+    const tzid = property?.getParameter("tzid");
+    return typeof tzid === "string" ? tzid : "";
+};
+/** The zone a component's DTSTART was written in. */
+export const dtStartTzid = (component) => 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) => component.hasProperty("dtend")
+    ? tzidOf(component.getFirstProperty("dtend"))
+    : dtStartTzid(component);

package/dist/window.d.ts

@@ -0,0 +1,85 @@
+import type { CalendarCollectionItem, CalendarObjectItem, ICalendarEventIndexRepository, ICalendarObjectRepository } from "@remit/data-ports";
+/**
+ * How far before the window occurrences are read, so one that started earlier
+ * and runs into it is still returned.
+ *
+ * The occurrence index is keyed by start, which is the only key a range read
+ * can use, so an event that began before the window is invisible to it. A
+ * bounded lookback buys back the events people actually have — a meeting that
+ * started last night, a week away, a fortnight of leave — without turning a
+ * day's read into a read of the whole calendar. An all-day block longer than
+ * this that began before the window is the one thing it misses.
+ */
+export declare const CALENDAR_WINDOW_LOOKBACK_DAYS = 31;
+/** One occurrence, in the form a client renders. */
+export interface CalendarInstance {
+    calendarId: string;
+    calendarObjectId: string;
+    recurrenceId: string;
+    icalUid: string;
+    summary: string;
+    /** ISO 8601 with the collection's own offset — what a client draws. */
+    start: string;
+    end: string;
+    /** ISO 8601 UTC instant — what sorts and compares. */
+    startAt: string;
+    endAt: string;
+    allDay: boolean;
+    status: CalendarObjectItem["status"];
+    transparency: CalendarObjectItem["transparency"];
+    zoneCertainty: CalendarObjectItem["zoneCertainty"];
+    etag: string;
+    hasRecurrence: boolean;
+}
+export interface CalendarWindowRepositories {
+    calendarObject: Pick<ICalendarObjectRepository, "find" | "listIncompleteExpansions">;
+    calendarEventIndex: Pick<ICalendarEventIndexRepository, "listByStartRange">;
+}
+export interface CalendarWindow {
+    /** ISO 8601 UTC instant, inclusive. */
+    from: string;
+    /** ISO 8601 UTC instant, exclusive. */
+    to: string;
+}
+/**
+ * Every occurrence in a window, across the collections given.
+ *
+ * Served from the stored occurrence index, except for the series the index
+ * does not reach: those are expanded live for this window and nothing is
+ * written to serve the read. A series is served from one source or the other,
+ * never merged from both, so an occurrence cannot appear twice.
+ */
+export declare const listCalendarInstances: (repositories: CalendarWindowRepositories, collections: CalendarCollectionItem[], window: CalendarWindow) => Promise<CalendarInstance[]>;
+/**
+ * The occurrences of one resource in a window, read from that resource alone:
+ * its own index rows where the index reaches the window, and a live expansion
+ * of it where it does not.
+ */
+export declare const listObjectInstances: (repositories: {
+    calendarEventIndex: Pick<ICalendarEventIndexRepository, "listForObject">;
+}, collection: CalendarCollectionItem, object: CalendarObjectItem, window: CalendarWindow) => Promise<CalendarInstance[]>;
+/** A stretch of time somebody is busy in, as instants. */
+export interface BusySpan {
+    startMs: number;
+    endMs: number;
+}
+/**
+ * Whether an occurrence consumes free/busy time. A cancelled event is not
+ * something to work around, and one marked TRANSP:TRANSPARENT was written
+ * precisely to say so.
+ */
+export declare const isBusy: (instance: CalendarInstance) => boolean;
+/**
+ * Collapses overlapping and touching spans into the stretches they cover.
+ *
+ * Touching counts: two meetings back to back are one stretch of being busy, and
+ * reporting them separately invites a caller to offer the zero-length gap
+ * between them as free.
+ */
+export declare const mergeBusySpans: (spans: BusySpan[]) => BusySpan[];
+/**
+ * The busy stretches in a window, merged across every collection given, and
+ * clipped to the window so a span never claims time outside what was asked
+ * for.
+ */
+export declare const listBusySpans: (repositories: CalendarWindowRepositories, collections: CalendarCollectionItem[], window: CalendarWindow) => Promise<BusySpan[]>;

package/dist/window.js

@@ -0,0 +1,161 @@
+import { CalendarEventStatus, CalendarTransparency } from "@remit/domain-enums";
+import { expandCalendarWindow } from "./expand.js";
+import { parseCalendar } from "./parse.js";
+import { toOffsetIso, toUtcIso } from "./time.js";
+/**
+ * How far before the window occurrences are read, so one that started earlier
+ * and runs into it is still returned.
+ *
+ * The occurrence index is keyed by start, which is the only key a range read
+ * can use, so an event that began before the window is invisible to it. A
+ * bounded lookback buys back the events people actually have — a meeting that
+ * started last night, a week away, a fortnight of leave — without turning a
+ * day's read into a read of the whole calendar. An all-day block longer than
+ * this that began before the window is the one thing it misses.
+ */
+export const CALENDAR_WINDOW_LOOKBACK_DAYS = 31;
+const LOOKBACK_MS = CALENDAR_WINDOW_LOOKBACK_DAYS * 24 * 60 * 60 * 1000;
+const instanceOf = (collection, object, occurrence) => ({
+    calendarId: collection.calendarId,
+    calendarObjectId: object.calendarObjectId,
+    recurrenceId: occurrence.recurrenceId,
+    icalUid: object.icalUid,
+    summary: occurrence.summary,
+    start: toOffsetIso(Date.parse(occurrence.startAt), collection.timezone),
+    end: toOffsetIso(Date.parse(occurrence.endAt), collection.timezone),
+    startAt: occurrence.startAt,
+    endAt: occurrence.endAt,
+    allDay: occurrence.allDay,
+    status: occurrence.status,
+    transparency: occurrence.transparency,
+    zoneCertainty: object.zoneCertainty,
+    etag: object.etag,
+    hasRecurrence: object.hasRecurrence,
+});
+/**
+ * Every occurrence in a window, across the collections given.
+ *
+ * Served from the stored occurrence index, except for the series the index
+ * does not reach: those are expanded live for this window and nothing is
+ * written to serve the read. A series is served from one source or the other,
+ * never merged from both, so an occurrence cannot appear twice.
+ */
+export const listCalendarInstances = async (repositories, collections, window) => {
+    const fromMs = Date.parse(window.from);
+    const toMs = Date.parse(window.to);
+    const lookbackFrom = toUtcIso(fromMs - LOOKBACK_MS);
+    const instances = [];
+    for (const collection of collections) {
+        // Both reads are bounded by the window: the occurrence rows that start in
+        // it, and the handful of series whose index stops short of it. Neither
+        // grows with the size of the calendar.
+        const live = await repositories.calendarObject.listIncompleteExpansions(collection.calendarId, window.to);
+        const liveIds = new Set(live.map((object) => object.calendarObjectId));
+        const rows = await repositories.calendarEventIndex.listByStartRange(collection.calendarId, lookbackFrom, window.to);
+        // One read per resource that actually appears in the window, cached across
+        // its own occurrences.
+        const byId = new Map();
+        for (const row of rows) {
+            if (liveIds.has(row.calendarObjectId))
+                continue;
+            if (!byId.has(row.calendarObjectId)) {
+                byId.set(row.calendarObjectId, await repositories.calendarObject.find(collection.calendarId, row.calendarObjectId));
+            }
+            const object = byId.get(row.calendarObjectId);
+            if (!object)
+                continue;
+            instances.push(instanceOf(collection, object, row));
+        }
+        for (const object of live) {
+            const parsed = await parseCalendar(object.icalData);
+            if (!parsed.ok) {
+                throw new Error(`stored calendar object ${object.calendarObjectId} no longer parses: ${parsed.error.message}`);
+            }
+            const occurrences = expandCalendarWindow(parsed.value, collection.timezone, { fromMs: fromMs - LOOKBACK_MS, toMs });
+            for (const occurrence of occurrences) {
+                instances.push(instanceOf(collection, object, occurrence));
+            }
+        }
+    }
+    return instances
+        .filter((instance) => overlapsWindow(instance, fromMs, toMs))
+        .sort((left, right) => left.startAt.localeCompare(right.startAt));
+};
+/**
+ * The occurrences of one resource in a window, read from that resource alone:
+ * its own index rows where the index reaches the window, and a live expansion
+ * of it where it does not.
+ */
+export const listObjectInstances = async (repositories, collection, object, window) => {
+    const fromMs = Date.parse(window.from);
+    const toMs = Date.parse(window.to);
+    const indexReaches = object.expandedThrough === "" || object.expandedThrough >= window.to;
+    const occurrences = indexReaches
+        ? await repositories.calendarEventIndex.listForObject(collection.calendarId, object.calendarObjectId)
+        : await expandObject(object, collection.timezone, fromMs, toMs);
+    return occurrences
+        .map((occurrence) => instanceOf(collection, object, occurrence))
+        .filter((instance) => overlapsWindow(instance, fromMs, toMs))
+        .sort((left, right) => left.startAt.localeCompare(right.startAt));
+};
+const expandObject = async (object, timezone, fromMs, toMs) => {
+    const parsed = await parseCalendar(object.icalData);
+    if (!parsed.ok) {
+        throw new Error(`stored calendar object ${object.calendarObjectId} no longer parses: ${parsed.error.message}`);
+    }
+    return expandCalendarWindow(parsed.value, timezone, {
+        fromMs: fromMs - LOOKBACK_MS,
+        toMs,
+    });
+};
+const overlapsWindow = (instance, fromMs, toMs) => {
+    const startMs = Date.parse(instance.startAt);
+    if (startMs >= toMs)
+        return false;
+    if (startMs >= fromMs)
+        return true;
+    return Date.parse(instance.endAt) > fromMs;
+};
+/**
+ * Whether an occurrence consumes free/busy time. A cancelled event is not
+ * something to work around, and one marked TRANSP:TRANSPARENT was written
+ * precisely to say so.
+ */
+export const isBusy = (instance) => instance.transparency === CalendarTransparency.Opaque &&
+    instance.status !== CalendarEventStatus.Cancelled;
+/**
+ * Collapses overlapping and touching spans into the stretches they cover.
+ *
+ * Touching counts: two meetings back to back are one stretch of being busy, and
+ * reporting them separately invites a caller to offer the zero-length gap
+ * between them as free.
+ */
+export const mergeBusySpans = (spans) => {
+    const sorted = [...spans].sort((left, right) => left.startMs - right.startMs);
+    const merged = [];
+    for (const span of sorted) {
+        if (span.endMs <= span.startMs)
+            continue;
+        const last = merged[merged.length - 1];
+        if (last && span.startMs <= last.endMs) {
+            last.endMs = Math.max(last.endMs, span.endMs);
+            continue;
+        }
+        merged.push({ ...span });
+    }
+    return merged;
+};
+/**
+ * The busy stretches in a window, merged across every collection given, and
+ * clipped to the window so a span never claims time outside what was asked
+ * for.
+ */
+export const listBusySpans = async (repositories, collections, window) => {
+    const fromMs = Date.parse(window.from);
+    const toMs = Date.parse(window.to);
+    const instances = await listCalendarInstances(repositories, collections, window);
+    return mergeBusySpans(instances.filter(isBusy).map((instance) => ({
+        startMs: Math.max(Date.parse(instance.startAt), fromMs),
+        endMs: Math.min(Date.parse(instance.endAt), toMs),
+    })));
+};

package/package.json

@@ -1,37 +1,42 @@
 {
-  "name": "@remit/calendar-service",
-  "version": "0.0.18",
-  "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"
-    },
-    "./memory-store": {
-      "types": "./src/memory-store.ts",
-      "default": "./src/memory-store.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-exclude='src/memory-store.ts' --test-coverage-lines=90 --test 'src/**/*.test.ts'"
-  },
-  "dependencies": {
-    "@remit/api-openapi-types": "*",
-    "@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"
-  }
+	"name": "@remit/calendar-service",
+	"version": "0.0.19",
+	"description": "iCalendar (RFC 5545) parsing, projection and recurrence expansion over the calendar store",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./memory-store": {
+			"types": "./dist/memory-store.d.ts",
+			"default": "./dist/memory-store.js"
+		}
+	},
+	"scripts": {
+		"prepack": "node ../../npm-scripts/pack-dist.mjs prepack",
+		"postpack": "node ../../npm-scripts/pack-dist.mjs postpack",
+		"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-exclude='src/memory-store.ts' --test-coverage-lines=90 --test 'src/**/*.test.ts'"
+	},
+	"dependencies": {
+		"@remit/api-openapi-types": "*",
+		"@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"
+	},
+	"files": [
+		"dist"
+	]
 }