@craftguild/jscalendar 0.1.0 → 0.3.0

package/README.md

@@ -62,13 +62,110 @@ const task = new JsCal.Task({
 
 ### Group
 
+`entries` accepts either plain JSCalendar objects (including `eject()` results)
+or `JsCal.Event`/`JsCal.Task` instances.
+
 ```ts
 const group = new JsCal.Group({
   title: "Project A",
-  entries: [event.eject(), task.eject()],
+  entries: [event, task.eject()],
 });
 ```
 
+## 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
+`data` field that stores the RFC 8984 object. `eject()` returns a deep
+clone of that underlying JSCalendar object for serialization, storage,
+or passing across app boundaries.
+
+Why `eject()` exists:
+- Class instances are convenient for building and mutating objects with
+  helpers like `update`, `patch`, and `addParticipant`.
+- External APIs, storage layers, and JSON stringify expect plain objects.
+- A deep clone makes it safe to hand off data without accidental mutation
+  from the original instance (and vice versa).
+
+What changes after `eject()`:
+- You lose helper methods; the result is just a plain JSCalendar object.
+- Mutating the plain object does not affect the original instance.
+- The instance can still be used and updated independently.
+
+```ts
+const event = new JsCal.Event({ title: "Kickoff", start: "2026-02-02T10:00:00" });
+const plain = event.eject();
+
+// Plain object is ready for JSON / storage / network.
+JSON.stringify(plain);
+
+// Changes do not affect each other.
+plain.title = "Exported";
+event.update({ title: "Live" });
+```
+
 ## Updates and Mutations
 
 Mutation helpers update the underlying data and keep metadata such as

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;