@craftguild/jscalendar 0.2.0 → 0.3.0

package/README.md

@@ -72,6 +72,69 @@ const group = new JsCal.Group({
 });
 ```
 
+## Builder Helpers (Strict, Validated Inputs)
+
+JSCalendar objects require `@type` fields for nested objects like
+participants, locations, alerts, and recurrence rules. Requiring every
+caller to manually specify `@type` is noisy and error-prone. To avoid
+leaking RFC-specific details into app code, this library provides
+**builder helpers** that:
+
+- Fill in the correct `@type`
+- Validate the result against RFC 8984 immediately
+
+You can still pass strict plain JSCalendar objects directly (e.g., from
+your database), but builders offer a safer, clearer option for app code.
+
+### Using builders (recommended for app code)
+
+```ts
+const task = new JsCal.Task({
+  title: "Write report",
+  start: "2026-02-11T09:00:00",
+  participants: JsCal.participants([
+    JsCal.Participant({ name: "Alice", email: "a@example.com" }),
+    JsCal.Participant({ name: "Bob" }),
+  ]),
+  locations: JsCal.locations([
+    JsCal.Location({ name: "Room A" }),
+  ]),
+  alerts: JsCal.alerts([
+    JsCal.Alert({ trigger: { "@type": "OffsetTrigger", offset: "-PT15M" } }),
+  ]),
+});
+```
+
+### Using strict plain objects (for DB/imported data)
+
+```ts
+const task = new JsCal.Task({
+  title: "Imported task",
+  start: "2026-02-11T09:00:00",
+  participants: {
+    p1: { "@type": "Participant", name: "Alice", email: "a@example.com" },
+  },
+  locations: {
+    l1: { "@type": "Location", name: "Room A" },
+  },
+  alerts: {
+    a1: { "@type": "Alert", trigger: { "@type": "OffsetTrigger", offset: "-PT15M" } },
+  },
+});
+```
+
+### Validation behavior
+
+Builders validate on creation, and constructors validate on object
+creation. That means:
+
+- Builder inputs are validated immediately
+- `new JsCal.Event/Task/Group(...)` also validates the final object
+
+This double validation is intentional for safety: even if data originates
+from an untrusted or inconsistent source, you still get strict RFC 8984
+checks at the point of object creation.
+
 ## Ejecting to plain objects
 
 `JsCal.Event`/`JsCal.Task` are class instances with helper methods and a

package/dist/__tests__/builders.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/builders.test.js

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { JsCal } from "../jscal.js";
+import { buildAlert, buildIdMap, buildLink, buildLocation, buildNDay, buildRecurrenceRule, buildRelation, buildTimeZone, buildTimeZoneMap, buildTimeZoneRule, buildVirtualLocation, } from "../jscal/builders.js";
+describe("builders", () => {
+    it("builds strict objects with @type", () => {
+        const participant = JsCal.Participant({ name: "Alice", roles: { attendee: true } });
+        const location = buildLocation({ name: "Room A" });
+        const vloc = buildVirtualLocation({ name: "Zoom", uri: "https://example.com" });
+        const link = buildLink({ href: "https://example.com" });
+        const relation = buildRelation({ relation: { parent: true } });
+        const alert = buildAlert({ trigger: { "@type": "OffsetTrigger", offset: "-PT15M" } });
+        const nday = buildNDay({ day: "mo" });
+        const rule = buildRecurrenceRule({ frequency: "daily" });
+        const tzRule = buildTimeZoneRule({
+            start: "2026-01-01T00:00:00",
+            offsetFrom: "+09:00",
+            offsetTo: "+09:00",
+        });
+        const tz = buildTimeZone({
+            tzId: "Asia/Tokyo",
+            standard: [tzRule],
+        });
+        expect(participant["@type"]).toBe("Participant");
+        expect(location["@type"]).toBe("Location");
+        expect(vloc["@type"]).toBe("VirtualLocation");
+        expect(link["@type"]).toBe("Link");
+        expect(relation["@type"]).toBe("Relation");
+        expect(alert["@type"]).toBe("Alert");
+        expect(nday["@type"]).toBe("NDay");
+        expect(rule["@type"]).toBe("RecurrenceRule");
+        expect(tz["@type"]).toBe("TimeZone");
+    });
+    it("builds id maps with generated ids", () => {
+        const participants = JsCal.participants([
+            { name: "Alice", roles: { attendee: true } },
+            { name: "Bob", roles: { attendee: true } },
+        ]);
+        expect(Object.keys(participants).length).toBe(2);
+        const locations = JsCal.locations([{ name: "Room A" }]);
+        expect(Object.keys(locations).length).toBe(1);
+        const links = JsCal.links([{ href: "https://example.com" }]);
+        expect(Object.keys(links).length).toBe(1);
+        const related = JsCal.relatedTo([{ relation: { parent: true } }]);
+        expect(Object.keys(related).length).toBe(1);
+    });
+    it("builds a time zone map keyed by tzId", () => {
+        const map = buildTimeZoneMap([
+            { tzId: "Asia/Tokyo", standard: [{ "@type": "TimeZoneRule", start: "2026-01-01T00:00:00", offsetFrom: "+09:00", offsetTo: "+09:00" }] },
+        ]);
+        expect(map["Asia/Tokyo"]?.tzId).toBe("Asia/Tokyo");
+    });
+    it("buildIdMap uses a custom id function", () => {
+        const map = buildIdMap([{ name: "A" }], (item) => item, (_item, index) => `id-${index}`);
+        expect(Object.keys(map)).toEqual(["id-0"]);
+    });
+    it("throws when @type mismatches", () => {
+        // Intentionally bypass type safety to assert @type validation errors.
+        const bad = { "@type": "Location" };
+        expect(() => JsCal.Participant(bad)).toThrowError("participant: must have @type Participant");
+    });
+    it("throws for mismatched @type across builders", () => {
+        // Intentionally bypass type safety to assert @type validation errors.
+        expect(() => buildLocation({ "@type": "Participant" }))
+            .toThrowError("location: must have @type Location");
+        expect(() => buildVirtualLocation({ "@type": "Location" }))
+            .toThrowError("virtualLocation: must have @type VirtualLocation");
+        expect(() => buildAlert({ "@type": "Link" }))
+            .toThrowError("alert: must have @type Alert");
+        expect(() => buildRelation({ "@type": "Link" }))
+            .toThrowError("relation: must have @type Relation");
+        expect(() => buildLink({ "@type": "Relation" }))
+            .toThrowError("link: must have @type Link");
+        expect(() => buildTimeZone({ "@type": "Alert" }))
+            .toThrowError("timeZone: must have @type TimeZone");
+        expect(() => buildTimeZoneRule({ "@type": "TimeZone" }))
+            .toThrowError("timeZoneRule: must have @type TimeZoneRule");
+        expect(() => buildRecurrenceRule({ "@type": "NDay" }))
+            .toThrowError("recurrenceRule: must have @type RecurrenceRule");
+        expect(() => buildNDay({ "@type": "RecurrenceRule" }))
+            .toThrowError("nday: must have @type NDay");
+    });
+});

package/dist/__tests__/calendar-extra.test.js

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { JsCal, createId, isEvent, isGroup, isTask } from "../jscal.js";
+import { Base } from "../jscal/base.js";
 const fixedNow = () => "2026-02-01T00:00:00Z";
 function makeEvent() {
     return new JsCal.Event({
@@ -14,6 +15,16 @@ describe("JsCal helpers", () => {
         group.addEntry(event.data);
         expect(group.data.entries.length).toBe(1);
     });
+    it("accepts JsCal instances and ejected entries in groups", () => {
+        const event = makeEvent();
+        const task = new JsCal.Task({ title: "Task", start: "2026-02-02T10:00:00" }, { now: fixedNow });
+        const group = new JsCal.Group({
+            entries: [event, task.eject()],
+        }, { now: fixedNow });
+        expect(group.data.entries.length).toBe(2);
+        expect(group.data.entries[0]?.["@type"]).toBe("Event");
+        expect(group.data.entries[1]?.["@type"]).toBe("Task");
+    });
     it("does not expose addEntry on non-group", () => {
         const event = makeEvent();
         expect("addEntry" in event).toBe(false);
@@ -79,6 +90,31 @@ describe("JsCal helpers", () => {
         json.title = "Changed";
         expect(event.data.title).toBe("Kickoff");
     });
+    it("clones Base instances with deep-copied data", () => {
+        const base = new Base({ "@type": "Event", uid: "base", updated: "2026-02-01T00:00:00Z", start: "2026-02-01T10:00:00" });
+        const cloned = base.clone();
+        cloned.data.uid = "changed";
+        expect(base.data.uid).toBe("base");
+    });
+    it("builds participant inputs without @type", () => {
+        const participant = JsCal.Participant({ name: "Alice", roles: { attendee: true } });
+        const task = new JsCal.Task({
+            start: "2026-02-02T10:00:00",
+            participants: { p1: participant },
+        });
+        expect(task.data.participants?.p1?.["@type"]).toBe("Participant");
+    });
+    it("builds participant maps with stable ids", () => {
+        const participants = JsCal.participants([
+            { name: "Alice", roles: { attendee: true } },
+            { name: "Bob", roles: { attendee: true } },
+        ]);
+        const task = new JsCal.Task({
+            start: "2026-02-02T10:00:00",
+            participants,
+        });
+        expect(Object.keys(task.data.participants ?? {}).length).toBe(2);
+    });
     it("createId returns base64url without padding", () => {
         const id = createId();
         expect(id).toMatch(/^[A-Za-z0-9_-]+$/);

package/dist/__tests__/recurrence.test.js

@@ -449,6 +449,129 @@ describe("recurrence expansion", () => {
             "2026-02-02T09:00:00",
         ]);
     });
+    it("uses implicit byMonthDay for monthly rules", () => {
+        const event = new JsCal.Event({
+            title: "Monthly Default",
+            start: "2026-02-10T09:00:00",
+            recurrenceRules: [
+                { "@type": "RecurrenceRule", frequency: "monthly", count: 2 },
+            ],
+        });
+        const occ = collect(JsCal.expandRecurrence([event], {
+            from: new Date("2026-02-01"),
+            to: new Date("2026-03-31"),
+        }));
+        const starts = occ.map((o) => o.recurrenceId);
+        expect(starts).toEqual([
+            "2026-02-10T09:00:00",
+            "2026-03-10T09:00:00",
+        ]);
+    });
+    it("adds byMonth defaults for yearly rules with byMonthDay", () => {
+        const event = new JsCal.Event({
+            title: "Yearly ByMonthDay",
+            start: "2026-02-01T09:00:00",
+            recurrenceRules: [
+                { "@type": "RecurrenceRule", frequency: "yearly", byMonthDay: [1], count: 2 },
+            ],
+        });
+        const occ = collect(JsCal.expandRecurrence([event], {
+            from: new Date("2026-02-01"),
+            to: new Date("2027-02-02"),
+        }));
+        const starts = occ.map((o) => o.recurrenceId);
+        expect(starts).toEqual([
+            "2026-02-01T09:00:00",
+            "2027-02-01T09:00:00",
+        ]);
+    });
+    it("adds byDay defaults for yearly byWeekNo rules", () => {
+        const event = new JsCal.Event({
+            title: "Week 1 Default Day",
+            start: "2026-01-01T09:00:00",
+            recurrenceRules: [
+                { "@type": "RecurrenceRule", frequency: "yearly", byWeekNo: [1], count: 1 },
+            ],
+        });
+        const occ = collect(JsCal.expandRecurrence([event], {
+            from: new Date("2026-01-01"),
+            to: new Date("2026-01-10"),
+        }));
+        const starts = occ.map((o) => o.recurrenceId);
+        expect(starts).toEqual([
+            "2026-01-01T09:00:00",
+        ]);
+    });
+    it("supports negative bySetPosition values", () => {
+        const event = new JsCal.Event({
+            title: "Last Wednesday",
+            start: "2026-01-07T10:00:00",
+            recurrenceRules: [
+                {
+                    "@type": "RecurrenceRule",
+                    frequency: "monthly",
+                    byDay: [{ "@type": "NDay", day: "we" }],
+                    bySetPosition: [-1],
+                },
+            ],
+        });
+        const occ = collect(JsCal.expandRecurrence([event], {
+            from: new Date("2026-01-01"),
+            to: new Date("2026-03-31"),
+        }));
+        const starts = occ.map((o) => o.recurrenceId);
+        expect(starts).toEqual([
+            "2026-01-07T10:00:00",
+            "2026-01-28T10:00:00",
+            "2026-02-25T10:00:00",
+            "2026-03-25T10:00:00",
+        ]);
+    });
+    it("expands tasks that only have due dates", () => {
+        const task = new JsCal.Task({
+            title: "Due Only",
+            due: "2026-02-01T10:00:00",
+            recurrenceRules: [
+                { "@type": "RecurrenceRule", frequency: "daily", count: 2 },
+            ],
+            recurrenceOverrides: {
+                "2026-02-02T10:00:00": { "/due": "2026-02-05T10:00:00" },
+            },
+        });
+        const occ = Array.from(JsCal.expandRecurrence([task], {
+            from: new Date("2026-02-01"),
+            to: new Date("2026-02-03"),
+        }));
+        expect(occ.map((o) => o.recurrenceId)).toEqual([
+            "2026-02-01T10:00:00",
+            "2026-02-02T10:00:00",
+        ]);
+        // Intentional cast to Task for test-only access to due.
+        const second = occ[1];
+        expect(second?.due).toBe("2026-02-05T10:00:00");
+    });
+    it("skips tasks without start or due dates", () => {
+        const task = new JsCal.Task({ title: "No Dates" });
+        const occ = Array.from(JsCal.expandRecurrence([task], {
+            from: new Date("2026-02-01"),
+            to: new Date("2026-02-02"),
+        }));
+        expect(occ.length).toBe(0);
+    });
+    it("throws on unsupported rscale during expansion", () => {
+        const event = new JsCal.Event({
+            title: "Bad Rscale",
+            start: "2026-02-01T10:00:00",
+            recurrenceRules: [
+                { "@type": "RecurrenceRule", frequency: "daily", rscale: "hebrew" },
+            ],
+        }, { validate: false });
+        expect(() => {
+            for (const _ of JsCal.expandRecurrence([event], { from: new Date("2026-02-01"), to: new Date("2026-02-02") })) {
+                void 0;
+            }
+        }).toThrow("Unsupported rscale");
+    });
     it("pages recurrence expansion with cursor and limit", () => {
         const event = new JsCal.Event({
             title: "Weekly",

package/dist/__tests__/search.test.js

@@ -84,6 +84,33 @@ describe("search helpers", () => {
             throw new Error("Missing result");
         expect(first.uid).toBe("e1");
     });
+    it("handles Date range for UTC events without time zones", () => {
+        const utcEvent = {
+            "@type": "Event",
+            uid: "eUtc",
+            updated: "2026-02-01T00:00:00Z",
+            start: "2026-02-01T10:00:00Z",
+            duration: "PT1H",
+        };
+        const results = filterByDateRange([utcEvent], {
+            start: new Date("2026-02-01T09:30:00Z"),
+            end: new Date("2026-02-01T10:30:00Z"),
+        });
+        expect(results.map((item) => item.uid)).toEqual(["eUtc"]);
+    });
+    it("handles Date range for UTC tasks without time zones", () => {
+        const utcTask = {
+            "@type": "Task",
+            uid: "tUtc",
+            updated: "2026-02-01T00:00:00Z",
+            start: "2026-02-01T10:00:00Z",
+        };
+        const results = filterByDateRange([utcTask], {
+            start: new Date("2026-02-01T09:30:00Z"),
+            end: new Date("2026-02-01T10:30:00Z"),
+        });
+        expect(results.map((item) => item.uid)).toEqual(["tUtc"]);
+    });
     it("uses JsCal.groupByType wrapper", () => {
         const grouped = JsCal.groupByType([event, task]);
         expect(Object.keys(grouped)).toContain("Event");

package/dist/__tests__/utils.test.js

@@ -25,6 +25,9 @@ describe("utils", () => {
         expect(compareDateTime("2026-02-01T00:00:00Z", "2026-02-01T01:00:00Z")).toBe(-1);
         expect(compareDateTime("2026-02-01T01:00:00Z", "2026-02-01T00:00:00Z")).toBe(1);
     });
+    it("returns null for invalid UTC date-times", () => {
+        expect(compareDateTime("2026-99-99T00:00:00Z", "2026-02-01T00:00:00Z")).toBeNull();
+    });
     it("compares local date-times lexicographically", () => {
         expect(compareDateTime("2026-02-01T00:00:00", "2026-02-01T00:00:00")).toBe(0);
         expect(compareDateTime("2026-02-01T00:00:00", "2026-02-02T00:00:00")).toBe(-1);

package/dist/__tests__/validation.test.js

@@ -16,6 +16,12 @@ describe("validation", () => {
             descriptionContentType: "application/json",
         })).toThrowError("object.descriptionContentType: must be a text/* media type");
     });
+    it("rejects non-utf8 charset parameters", () => {
+        expect(() => new JsCal.Event({
+            start: "2026-02-01T10:00:00",
+            descriptionContentType: "text/plain; charset=ascii",
+        })).toThrowError("object.descriptionContentType: charset parameter must be utf-8");
+    });
     it("allows validation to be disabled for create, update, and patch", () => {
         const event = new JsCal.Event({ start: "2026-02-01T10:00:00Z" }, { validate: false });
         expect(event.get("start")).toBe("2026-02-01T10:00:00Z");
@@ -62,6 +68,113 @@ describe("validation", () => {
             },
         })).toThrowError("object.locations.bad id: must use base64url characters");
     });
+    it("rejects invalid content-id formats", () => {
+        expect(() => new JsCal.Event({
+            start: "2026-02-01T10:00:00",
+            links: {
+                l1: { "@type": "Link", href: "https://example.com", cid: "<a@example.com" },
+            },
+        })).toThrowError("object.links.l1.cid: must use matching angle brackets");
+    });
+    it("rejects boolean map entries that are not true", () => {
+        expect(() => new JsCal.Event({
+            start: "2026-02-01T10:00:00",
+            participants: {
+                // Intentionally violate the BooleanMap type to assert validation errors.
+                p1: { "@type": "Participant", roles: { attendee: false } },
+            },
+        })).toThrowError("object.participants.p1.roles.attendee: must be true");
+    });
+    it("rejects invalid time zone ids", () => {
+        expect(() => new JsCal.Event({
+            start: "2026-02-01T10:00:00",
+            // Intentionally bypass TimeZoneInput typing to test invalid IDs.
+            timeZone: "Mars/Phobos",
+        })).toThrowError("Unknown time zone: Mars/Phobos");
+    });
+    it("rejects invalid recurrence rule values", () => {
+        expect(() => new JsCal.Event({
+            start: "2026-02-01T10:00:00",
+            recurrenceRules: [
+                { "@type": "RecurrenceRule", frequency: "daily", byMonthDay: [0] },
+            ],
+        })).toThrowError("object.recurrenceRules[0].byMonthDay[0]: must be an integer between -31 and 31, excluding 0");
+    });
+    it("accepts extended common fields and nested validation", () => {
+        const event = new JsCal.Event({
+            start: "2026-02-01T10:00:00",
+            method: "publish",
+            keywords: { sprint: true },
+            categories: { meeting: true },
+            relatedTo: {
+                rel1: { "@type": "Relation", relation: { parent: true } },
+            },
+            replyTo: {
+                "mailto:team@example.com": "mailto:team@example.com",
+            },
+            locations: {
+                loc1: {
+                    "@type": "Location",
+                    name: "Room A",
+                    links: {
+                        link1: { "@type": "Link", href: "https://example.com" },
+                    },
+                },
+            },
+            virtualLocations: {
+                v1: {
+                    "@type": "VirtualLocation",
+                    uri: "https://example.com",
+                    features: { chat: true },
+                },
+            },
+            participants: {
+                p1: {
+                    "@type": "Participant",
+                    roles: { attendee: true },
+                    sendTo: { imap: "mailto:a@example.com" },
+                    kind: "individual",
+                },
+            },
+            alerts: {
+                a1: {
+                    "@type": "Alert",
+                    trigger: { "@type": "AbsoluteTrigger", when: "2026-02-01T00:00:00Z" },
+                },
+            },
+            localizations: {
+                en: { title: "Localized", keywords: ["a"] },
+            },
+            recurrenceOverrides: {
+                "2026-02-02T10:00:00": { title: null, locations: ["x"] },
+            },
+            timeZones: {
+                "Asia/Tokyo": {
+                    "@type": "TimeZone",
+                    tzId: "Asia/Tokyo",
+                    aliases: { JST: true },
+                    standard: [
+                        {
+                            "@type": "TimeZoneRule",
+                            start: "2026-01-01T00:00:00",
+                            offsetFrom: "+09:00",
+                            offsetTo: "+09:00",
+                            comments: ["note"],
+                        },
+                    ],
+                    daylight: [
+                        {
+                            "@type": "TimeZoneRule",
+                            start: "2026-06-01T00:00:00",
+                            offsetFrom: "+09:00",
+                            offsetTo: "+10:00",
+                        },
+                    ],
+                },
+            },
+        });
+        expect(event.get("method")).toBe("publish");
+    });
     it("rejects non-gregorian rscale values", () => {
         expect(() => new JsCal.Event({
             start: "2026-02-01T10:00:00",

package/dist/ical.d.ts

@@ -4,4 +4,10 @@ export type ICalOptions = {
     method?: string;
     includeXJSCalendar?: boolean;
 };
+/**
+ * Convert JSCalendar objects into an iCalendar string.
+ * @param objects JSCalendar objects to export.
+ * @param options Export options.
+ * @return iCalendar text.
+ */
 export declare function toICal(objects: JSCalendarObject[], options?: ICalOptions): string;

package/dist/ical.js

@@ -1,5 +1,14 @@
 import { normalizeUtcDateTime } from "./utils.js";
+const TYPE_EVENT = "Event";
+const TYPE_GROUP = "Group";
+const TYPE_TASK = "Task";
 const DEFAULT_PRODID = "-//craftguild//EN";
+/**
+ * Convert JSCalendar objects into an iCalendar string.
+ * @param objects JSCalendar objects to export.
+ * @param options Export options.
+ * @return iCalendar text.
+ */
 export function toICal(objects, options = {}) {
     const lines = [];
     const includeX = options.includeXJSCalendar !== false;
@@ -10,7 +19,7 @@ export function toICal(objects, options = {}) {
     if (method)
         lines.push(`METHOD:${method.toUpperCase()}`);
     for (const object of objects) {
-        if (object["@type"] === "Group") {
+        if (object["@type"] === TYPE_GROUP) {
             const group = object;
             if (includeX) {
                 lines.push(`X-JSCALENDAR-GROUP:${escapeText(JSON.stringify(stripEntries(group)))}`);
@@ -26,6 +35,11 @@ export function toICal(objects, options = {}) {
     lines.push("END:VCALENDAR");
     return foldLines(lines).join("\r\n");
 }
+/**
+ * Find the first METHOD value from objects.
+ * @param objects JSCalendar objects.
+ * @return METHOD value or undefined.
+ */
 function findMethod(objects) {
     for (const object of objects) {
         if (object.method)
@@ -33,13 +47,25 @@ function findMethod(objects) {
     }
     return undefined;
 }
+/**
+ * Build an iCalendar component from a JSCalendar object.
+ * @param object JSCalendar object.
+ * @param includeX Whether to include X-JSCALENDAR.
+ * @return iCalendar lines for the component.
+ */
 function buildComponent(object, includeX) {
-    if (object["@type"] === "Event")
+    if (object["@type"] === TYPE_EVENT)
         return buildEvent(object, includeX);
-    if (object["@type"] === "Task")
+    if (object["@type"] === TYPE_TASK)
         return buildTask(object, includeX);
     return [];
 }
+/**
+ * Build a VEVENT component.
+ * @param event Event object.
+ * @param includeX Whether to include X-JSCALENDAR.
+ * @return VEVENT lines.
+ */
 function buildEvent(event, includeX) {
     const lines = [];
     lines.push("BEGIN:VEVENT");
@@ -69,6 +95,12 @@ function buildEvent(event, includeX) {
     lines.push("END:VEVENT");
     return lines;
 }
+/**
+ * Build a VTODO component.
+ * @param task Task object.
+ * @param includeX Whether to include X-JSCALENDAR.
+ * @return VTODO lines.
+ */
 function buildTask(task, includeX) {
     const lines = [];
     lines.push("BEGIN:VTODO");
@@ -111,6 +143,12 @@ function buildTask(task, includeX) {
     lines.push("END:VTODO");
     return lines;
 }
+/**
+ * Append RRULE lines for recurrence rules.
+ * @param lines Lines to append to.
+ * @param rules Recurrence rules.
+ * @return Nothing.
+ */
 function appendRecurrence(lines, rules) {
     if (!rules)
         return;
@@ -120,6 +158,11 @@ function appendRecurrence(lines, rules) {
             lines.push(`RRULE:${rrule}`);
     }
 }
+/**
+ * Convert a RecurrenceRule to an RRULE string.
+ * @param rule Recurrence rule.
+ * @return RRULE value or null.
+ */
 function recurrenceRuleToRRule(rule) {
     const parts = [];
     parts.push(`FREQ=${rule.frequency.toUpperCase()}`);
@@ -159,6 +202,11 @@ function recurrenceRuleToRRule(rule) {
         parts.push(`SKIP=${rule.skip.toUpperCase()}`);
     return parts.join(";");
 }
+/**
+ * Format a UTCDateTime for iCalendar.
+ * @param value UTCDateTime string.
+ * @return iCalendar-formatted UTCDateTime.
+ */
 function formatUtcDateTime(value) {
     const normalized = normalizeUtcDateTime(value);
     return normalized
@@ -166,12 +214,22 @@ function formatUtcDateTime(value) {
         .replace(/\.\d+Z$/, "Z")
         .replace(/Z$/, "Z");
 }
+/**
+ * Format a LocalDateTime for iCalendar.
+ * @param value LocalDateTime string.
+ * @return iCalendar-formatted LocalDateTime.
+ */
 function formatLocalDateTime(value) {
     return value
         .replace(/[-:]/g, "")
         .replace(/\.\d+$/, "")
         .replace(/Z$/, "");
 }
+/**
+ * Escape text for iCalendar content lines.
+ * @param value Raw text.
+ * @return Escaped text.
+ */
 function escapeText(value) {
     return value
         .replace(/\\/g, "\\\\")
@@ -179,6 +237,11 @@ function escapeText(value) {
         .replace(/;/g, "\\;")
         .replace(/,/g, "\\,");
 }
+/**
+ * Fold iCalendar lines to 75 octets per RFC.
+ * @param lines Lines to fold.
+ * @return Folded lines.
+ */
 function foldLines(lines) {
     const result = [];
     for (const line of lines) {
@@ -196,6 +259,11 @@ function foldLines(lines) {
     }
     return result;
 }
+/**
+ * Strip group entries for X-JSCALENDAR-GROUP payload.
+ * @param group Group object.
+ * @return Group without entries.
+ */
 function stripEntries(group) {
     const { entries: _entries, ...rest } = group;
     return rest;