@craftguild/jscalendar 0.4.1 → 0.5.1

package/README.md

@@ -22,14 +22,38 @@ pnpm add @craftguild/jscalendar
 ```ts
 import { JsCal } from "@craftguild/jscalendar";
 
+// Create a recurring event and a simple task, then expand occurrences.
 const event = new JsCal.Event({
-  title: "Kickoff",
-  start: "2026-02-03T09:00:00",
-  timeZone: "America/New_York",
-  duration: "PT1H",
+  title: "Weekly Sync",
+  start: new Date(2026, 0, 1, 0, 0, 0, 0),
+  recurrenceRules: [
+    JsCal.RecurrenceRule({
+      frequency: "weekly",
+      byDay: [JsCal.ByDay({ day: "th" })],
+    }),
+  ],
+});
+
+const task = new JsCal.Task({
+  title: "Prepare Notes",
+  start: new Date(2026, 0, 1, 0, 0, 0, 0),
 });
 
-const items = [event.eject()];
+const from = new Date(2026, 0, 1, 0, 0, 0, 0);
+const to = new Date(2026, 0, 31, 0, 0, 0, 0);
+const generator = JsCal.expandRecurrence([event, task], { from, to });
+
+for (const item of generator) {
+  // Expanded JSCalendar objects for events and tasks in the range.
+  console.log(JSON.stringify(item));
+}
+```
+
+Sample output (truncated):
+```txt
+{"title":"Weekly Sync","@type":"Event","start":"2026-01-01T00:00:00",...}
+{"title":"Prepare Notes","@type":"Task","start":"2026-01-01T00:00:00",...}
+{"title":"Weekly Sync","@type":"Event","start":"2026-01-08T00:00:00",...}
 ```
 
 ## Object Creation
@@ -93,14 +117,14 @@ 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", roles: { attendee: true } }),
-    JsCal.Participant({ name: "Bob", roles: { attendee: true } }),
+    { value: JsCal.Participant({ name: "Alice", email: "a@example.com", roles: { attendee: true } }) },
+    { value: JsCal.Participant({ name: "Bob", roles: { attendee: true } }) },
   ]),
   locations: JsCal.locations([
-    JsCal.Location({ name: "Room A" }),
+    { value: JsCal.Location({ name: "Room A" }) },
   ]),
   alerts: JsCal.alerts([
-    JsCal.Alert({ trigger: JsCal.OffsetTrigger({ offset: JsCal.duration.minutes(-15) }) }),
+    { value: JsCal.Alert({ trigger: JsCal.OffsetTrigger({ offset: JsCal.duration.minutes(-15) }) }) },
   ]),
 });
 ```
@@ -112,7 +136,7 @@ const task = new JsCal.Task({
   title: "Imported task",
   start: "2026-02-11T09:00:00",
   participants: {
-    p1: { "@type": "Participant", name: "Alice", email: "a@example.com" },
+    p1: { "@type": "Participant", name: "Alice", email: "a@example.com", roles: { attendee: true } },
   },
   locations: {
     l1: { "@type": "Location", name: "Room A" },
@@ -143,8 +167,8 @@ 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`.
+- Class instances are convenient for building and updating objects with
+  helpers like `patch`.
 - 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).
@@ -163,24 +187,59 @@ JSON.stringify(plain);
 
 // Changes do not affect each other.
 plain.title = "Exported";
-event.update({ title: "Live" });
+const updated = event.patch({ title: "Live" });
+```
+
+## Patch Usage
+
+Patch helpers return new instances and keep metadata such as
+`updated` and `sequence` consistent. Use `patch` for RFC 8984 PatchObject
+semantics. You can set raw values directly, or use helper methods if you
+prefer validated, type-safe inputs.
+
+```ts
+const patchedEvent = event.patch({ title: "Updated title" });
+const patchedAgain = patchedEvent.patch({ title: "Patched title" });
+```
+
+You can also patch nested maps by replacing the full map in one call:
+
+```ts
+const withParticipants = event.patch({
+  participants: {
+    p1: { "@type": "Participant", roles: { attendee: true }, email: "a@example.com" },
+  },
+});
 ```
 
-## Updates and Mutations
+Two common patterns for nested patches:
 
-Mutation helpers update the underlying data and keep metadata such as
-`updated` and `sequence` consistent. Use `update` for shallow updates
-and `patch` for RFC 8984 PatchObject semantics.
+1) Set raw values directly
+```ts
+const withLocations = event.patch({
+  locations: {
+    l1: { "@type": "Location", name: "Room A" },
+  },
+});
+```
 
+2) Use helpers to build or merge map values
 ```ts
-event.update({ title: "Updated title" });
-event.patch({ title: "Patched title" });
-
-event.addLocation({ name: "Room A" });
-event.addVirtualLocation({ name: "Zoom", uri: "https://example.com" });
-event.addParticipant({ roles: { attendee: true }, email: "a@example.com" });
-event.addAlert({
-  trigger: { "@type": "AbsoluteTrigger", when: "2026-02-10T09:00:00Z" },
+const withLocations = event.patch({
+  locations: JsCal.locations([
+    { id: "l1", value: JsCal.Location({ name: "Room A" }) },
+    { value: JsCal.Location({ name: "Room B" }) },
+  ]),
+});
+```
+
+To merge into an existing map, pass the current map as the second argument:
+```ts
+const withLocations = event.patch({
+  locations: JsCal.locations(
+    [{ value: JsCal.Location({ name: "Room C" }) }],
+    event.data.locations,
+  ),
 });
 ```
 
@@ -320,26 +379,6 @@ const icalMany = JsCal.toICal([event, task], { includeXJSCalendar: true });
 console.log(icalMany);
 ```
 
-## Practical Example
-
-**Weekly engineering sync (every Wednesday 10:30, 1 hour)**
-
-```ts
-const weekly = new JsCal.Event({
-  title: "Engineering Sync",
-  start: "2026-02-04T10:30:00",
-  timeZone: "Asia/Tokyo",
-  duration: JsCal.duration.hours(1),
-  recurrenceRules: [
-    {
-      "@type": "RecurrenceRule",
-      frequency: "weekly",
-      byDay: [{ "@type": "NDay", day: "we" }],
-    },
-  ],
-});
-```
-
 ## Compliance and Deviations
 
 ### RFC 8984 Conformance (Implemented)

package/dist/__tests__/builders.test.js

@@ -34,17 +34,30 @@ describe("builders", () => {
     });
     it("builds id maps with generated ids", () => {
         const participants = JsCal.participants([
-            { name: "Alice", roles: { attendee: true } },
-            { name: "Bob", roles: { attendee: true } },
+            { value: { name: "Alice", roles: { attendee: true } } },
+            { value: { name: "Bob", roles: { attendee: true } } },
         ]);
         expect(Object.keys(participants).length).toBe(2);
-        const locations = JsCal.locations([{ name: "Room A" }]);
+        const locations = JsCal.locations([{ value: { name: "Room A" } }]);
         expect(Object.keys(locations).length).toBe(1);
-        const links = JsCal.links([{ href: "https://example.com" }]);
+        const links = JsCal.links([{ value: { href: "https://example.com" } }]);
         expect(Object.keys(links).length).toBe(1);
-        const related = JsCal.relatedTo([{ relation: { parent: true } }]);
+        const related = JsCal.relatedTo([{ value: { relation: { parent: true } } }]);
         expect(Object.keys(related).length).toBe(1);
     });
+    it("merges id maps with explicit ids", () => {
+        const existing = JsCal.locations([{ id: "loc-1", value: { name: "Room A" } }]);
+        const merged = JsCal.locations([
+            { id: "loc-1", value: { name: "Room A Updated" } },
+            { value: { name: "Room B" } },
+        ], existing);
+        expect(existing["loc-1"]?.name).toBe("Room A");
+        expect(merged["loc-1"]?.name).toBe("Room A Updated");
+        expect(Object.keys(merged).length).toBe(2);
+    });
+    it("rejects wrapper inputs that mix value and direct fields", () => {
+        expect(() => JsCal.locations([{ name: "Room A" }])).toThrowError();
+    });
     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" }] },
@@ -52,7 +65,7 @@ describe("builders", () => {
         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}`);
+        const map = buildIdMap([{ value: { name: "A" } }], (item) => item, (_item, index) => `id-${index}`);
         expect(Object.keys(map)).toEqual(["id-0"]);
     });
     it("throws when @type mismatches", () => {

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

@@ -1,6 +1,5 @@
 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({
@@ -12,8 +11,9 @@ describe("JsCal helpers", () => {
     it("creates group and adds entry", () => {
         const group = new JsCal.Group({ entries: [] }, { now: fixedNow });
         const event = makeEvent();
-        group.addEntry(event.data);
-        expect(group.data.entries.length).toBe(1);
+        const nextGroup = group.addEntry(event.data);
+        expect(group.data.entries.length).toBe(0);
+        expect(nextGroup.data.entries.length).toBe(1);
     });
     it("accepts JsCal instances and ejected entries in groups", () => {
         const event = makeEvent();
@@ -31,10 +31,12 @@ describe("JsCal helpers", () => {
     });
     it("adds locations and virtual locations", () => {
         const event = makeEvent();
-        const locId = event.addLocation({ name: "Room A" });
-        const vlocId = event.addVirtualLocation({ name: "Zoom", uri: "https://example.com" });
-        const locations = event.data.locations;
-        const virtualLocations = event.data.virtualLocations;
+        const locId = "loc-1";
+        const vlocId = "vloc-1";
+        const withLocation = event.addLocation({ name: "Room A" }, locId);
+        const withVirtualLocation = withLocation.addVirtualLocation({ name: "Zoom", uri: "https://example.com" }, vlocId);
+        const locations = withVirtualLocation.data.locations;
+        const virtualLocations = withVirtualLocation.data.virtualLocations;
         expect(locations).toBeDefined();
         expect(virtualLocations).toBeDefined();
         if (!locations || !virtualLocations)
@@ -44,10 +46,12 @@ describe("JsCal helpers", () => {
     });
     it("adds participants and alerts", () => {
         const event = makeEvent();
-        const participantId = event.addParticipant({ roles: { attendee: true }, email: "a@example.com" });
-        const alertId = event.addAlert({ trigger: { "@type": "AbsoluteTrigger", when: "2026-02-01T01:00:00Z" } });
-        const participants = event.data.participants;
-        const alerts = event.data.alerts;
+        const participantId = "p1";
+        const alertId = "a1";
+        const withParticipant = event.addParticipant({ roles: { attendee: true }, email: "a@example.com" }, participantId);
+        const withAlert = withParticipant.addAlert({ trigger: { "@type": "AbsoluteTrigger", when: "2026-02-01T01:00:00Z" } }, alertId);
+        const participants = withAlert.data.participants;
+        const alerts = withAlert.data.alerts;
         expect(participants).toBeDefined();
         expect(alerts).toBeDefined();
         if (!participants || !alerts)
@@ -63,8 +67,9 @@ describe("JsCal helpers", () => {
     });
     it("defaults relativeTo for offset triggers", () => {
         const event = makeEvent();
-        const alertId = event.addAlert({ trigger: { "@type": "OffsetTrigger", offset: "PT15M" } });
-        const alerts = event.data.alerts;
+        const alertId = "a1";
+        const withAlert = event.addAlert({ trigger: { "@type": "OffsetTrigger", offset: "PT15M" } }, alertId);
+        const alerts = withAlert.data.alerts;
         expect(alerts).toBeDefined();
         if (!alerts)
             throw new Error("Missing alerts");
@@ -76,10 +81,10 @@ describe("JsCal helpers", () => {
     it("updates sequence for alerts but not for participants", () => {
         const event = makeEvent();
         const initialSequence = event.data.sequence ?? 0;
-        event.addParticipant({ roles: { attendee: true }, email: "a@example.com" });
-        expect(event.data.sequence ?? 0).toBe(initialSequence);
-        event.addAlert({ trigger: { "@type": "AbsoluteTrigger", when: "2026-02-01T01:00:00Z" } });
-        expect(event.data.sequence ?? 0).toBe(initialSequence + 1);
+        const withParticipant = event.addParticipant({ roles: { attendee: true }, email: "a@example.com" }, "p1");
+        expect(withParticipant.data.sequence ?? 0).toBe(initialSequence);
+        const withAlert = withParticipant.addAlert({ trigger: { "@type": "AbsoluteTrigger", when: "2026-02-01T01:00:00Z" } }, "a1");
+        expect(withAlert.data.sequence ?? 0).toBe(initialSequence + 1);
     });
     it("clones and eject return deep copies", () => {
         const event = makeEvent();
@@ -90,12 +95,6 @@ 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({
@@ -106,8 +105,8 @@ describe("JsCal helpers", () => {
     });
     it("builds participant maps with stable ids", () => {
         const participants = JsCal.participants([
-            { name: "Alice", roles: { attendee: true } },
-            { name: "Bob", roles: { attendee: true } },
+            { value: { name: "Alice", roles: { attendee: true } } },
+            { value: { name: "Bob", roles: { attendee: true } } },
         ]);
         const task = new JsCal.Task({
             start: "2026-02-02T10:00:00",
@@ -207,8 +206,9 @@ describe("JsCal helpers", () => {
     it("supports get/set helpers", () => {
         const event = makeEvent();
         expect(event.get("title")).toBe("Kickoff");
-        event.set("title", "Updated");
-        expect(event.get("title")).toBe("Updated");
+        const updated = event.set("title", "Updated");
+        expect(event.get("title")).toBe("Kickoff");
+        expect(updated.get("title")).toBe("Updated");
     });
     it("exposes type guards", () => {
         const event = makeEvent().eject();

package/dist/__tests__/calendar.test.js

@@ -56,36 +56,29 @@ describe("JsCal.Event", () => {
         expect(negative.data.duration).toBe("PT0S");
     });
 });
-describe("Event.update", () => {
-    it("increments sequence on non-participant updates", () => {
-        const event = makeEvent();
-        event.update({ title: "Updated" }, { now: fixedNow });
-        expect(event.data.sequence).toBe(1);
-    });
-    it("does not increment sequence when only participants change", () => {
+describe("Event.patch", () => {
+    it("increments sequence on non-participant patches", () => {
         const event = makeEvent();
-        const initialSequence = event.data.sequence ?? 0;
-        event.addParticipant({ roles: { attendee: true }, email: "a@example.com" });
-        expect(event.data.sequence ?? 0).toBe(initialSequence);
+        const patched = event.patch({ title: "Updated" }, { now: fixedNow });
+        expect(patched.data.sequence).toBe(1);
+        expect(event.data.sequence).toBe(0);
     });
     it("respects touch=false", () => {
         const event = makeEvent();
         const before = event.data.updated;
-        event.update({ title: "No touch" }, { touch: false, now: () => "2026-02-02T00:00:00Z" });
-        expect(event.data.updated).toBe(before);
+        const patched = event.patch({ title: "No touch" }, { touch: false, now: () => "2026-02-02T00:00:00Z" });
+        expect(patched.data.updated).toBe(before);
     });
-});
-describe("Event.patch", () => {
     it("applies patch and updates metadata", () => {
         const event = makeEvent();
-        event.patch({ title: "Patched" }, { now: fixedNow });
-        expect(event.data.title).toBe("Patched");
-        expect(event.data.updated).toBe("2026-02-01T00:00:00Z");
-        expect(event.data.sequence).toBe(1);
+        const patched = event.patch({ title: "Patched" }, { now: fixedNow });
+        expect(patched.data.title).toBe("Patched");
+        expect(patched.data.updated).toBe("2026-02-01T00:00:00Z");
+        expect(patched.data.sequence).toBe(1);
     });
     it("does not increment sequence for participants-only patch", () => {
         const event = makeEvent();
-        event.patch({
+        const patched = event.patch({
             participants: {
                 p1: {
                     "@type": "Participant",
@@ -93,7 +86,7 @@ describe("Event.patch", () => {
                 },
             },
         }, { now: fixedNow });
-        expect(event.data.sequence ?? 0).toBe(0);
+        expect(patched.data.sequence ?? 0).toBe(0);
     });
 });
 describe("createUid", () => {

package/dist/__tests__/recurrence.test.js

@@ -9,6 +9,25 @@ function collect(gen) {
     return result;
 }
 describe("recurrence expansion", () => {
+    it("sorts occurrences by recurrenceId across items", () => {
+        const first = new JsCal.Event({
+            title: "First",
+            start: "2026-02-01T09:00:00",
+        });
+        const second = new JsCal.Event({
+            title: "Second",
+            start: "2026-02-03T09:00:00",
+        });
+        const occ = collect(JsCal.expandRecurrence([second, first], {
+            from: new Date("2026-02-01"),
+            to: new Date("2026-02-10"),
+        }));
+        const starts = occ.map((o) => o.recurrenceId ?? ("start" in o ? o.start : undefined));
+        expect(starts).toEqual([
+            "2026-02-01T09:00:00",
+            "2026-02-03T09:00:00",
+        ]);
+    });
     it("expands weekly byDay", () => {
         const event = new JsCal.Event({
             title: "Weekly",
@@ -535,7 +554,7 @@ describe("recurrence expansion", () => {
                 { "@type": "RecurrenceRule", frequency: "daily", count: 2 },
             ],
             recurrenceOverrides: {
-                "2026-02-02T10:00:00": { "/due": "2026-02-05T10:00:00" },
+                "2026-02-02T10:00:00": { due: "2026-02-05T10:00:00" },
             },
         });
         const occ = Array.from(JsCal.expandRecurrence([task], {

package/dist/__tests__/validation.test.js

@@ -22,11 +22,10 @@ describe("validation", () => {
             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", () => {
+    it("allows validation to be disabled for create 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");
-        event.update({ start: "2026-02-01T10:00:00Z" }, { validate: false });
-        event.patch({ "/start": "2026-02-01T10:00:00Z" }, { validate: false });
+        event.patch({ start: "2026-02-01T10:00:00Z" }, { validate: false });
     });
     it("throws ValidationError with path and message", () => {
         expect(() => new JsCal.Event({ start: "2026-02-01T10:00:00Z" })).toThrowError(ValidationError);
@@ -159,10 +158,15 @@ describe("validation", () => {
                 },
             },
             localizations: {
-                en: { title: "Localized", keywords: ["a"] },
+                en: { title: "Localized", keywords: { a: true } },
             },
             recurrenceOverrides: {
-                "2026-02-02T10:00:00": { title: null, locations: ["x"] },
+                "2026-02-02T10:00:00": {
+                    title: null,
+                    locations: {
+                        loc1: { "@type": "Location", name: "Room A" },
+                    },
+                },
             },
             timeZones: {
                 "Asia/Tokyo": {

package/dist/jscal/base.d.ts

@@ -1,6 +1,6 @@
-import type { Alert, Id, JSCalendarObject, Location, Participant, PatchObject, VirtualLocation } from "../types.js";
+import type { Alert, Id, JSCalendarObject, Location, Participant, PatchLike, VirtualLocation } from "../types.js";
 import type { UpdateOptions } from "./types.js";
-export declare class Base<T extends JSCalendarObject> {
+export declare abstract class Base<T extends JSCalendarObject, TPatch extends PatchLike, TSelf extends Base<T, TPatch, TSelf>> {
     data: T;
     /**
      * Create a new base instance that wraps a JSCalendar object.
@@ -8,6 +8,12 @@ export declare class Base<T extends JSCalendarObject> {
      * @return Result.
      */
     constructor(data: T);
+    /**
+     * Wrap updated data in a new instance.
+     * @param data Updated JSCalendar data.
+     * @return New instance containing the data.
+     */
+    protected abstract wrap(data: T): TSelf;
     /**
      * Return a deep-cloned plain object for safe serialization.
      * @return Cloned JSCalendar data.
@@ -17,7 +23,7 @@ export declare class Base<T extends JSCalendarObject> {
      * Clone the current instance with a deep-cloned payload.
      * @return New instance with cloned data.
      */
-    clone(): Base<T>;
+    clone(): TSelf;
     /**
      * Read a field value from the underlying data.
      * @param key Field key.
@@ -28,63 +34,56 @@ export declare class Base<T extends JSCalendarObject> {
      * Set a field value and update metadata as needed.
      * @param key Field key.
      * @param value Field value.
-     * @return Updated instance.
-     */
-    set<K extends keyof T>(key: K, value: T[K]): this;
-    /**
-     * Apply shallow updates and touch updated/sequence metadata.
-     * @param values Partial values to merge.
-     * @param options Update options.
-     * @return Updated instance.
+     * @return New instance with the updated field.
      */
-    update(values: Partial<T>, options?: UpdateOptions): this;
+    set<K extends keyof T>(key: K, value: T[K]): TSelf;
     /**
      * Apply a PatchObject and touch updated/sequence metadata.
      * @param patch Patch to apply.
      * @param options Update options.
-     * @return Updated instance.
+     * @return New instance with applied patch.
      */
-    patch(patch: PatchObject, options?: UpdateOptions): this;
+    patch(patch: TPatch, options?: UpdateOptions): TSelf;
     /**
-     * Add a physical location and return its generated ID.
+     * Add a physical location and return a new instance.
      * @param location Location data (without @type).
      * @param id Optional location ID.
-     * @return Location ID.
+     * @return New instance with the added location.
      */
-    addLocation(location: Omit<Location, "@type"> & Partial<Pick<Location, "@type">>, id?: Id): Id;
+    addLocation(location: Omit<Location, "@type"> & Partial<Pick<Location, "@type">>, id?: Id): TSelf;
     /**
-     * Add a virtual location and return its generated ID.
+     * Add a virtual location and return a new instance.
      * @param location Virtual location data (without @type).
      * @param id Optional virtual location ID.
-     * @return Virtual location ID.
+     * @return New instance with the added virtual location.
      */
-    addVirtualLocation(location: Omit<VirtualLocation, "@type"> & Partial<Pick<VirtualLocation, "@type">>, id?: Id): Id;
+    addVirtualLocation(location: Omit<VirtualLocation, "@type"> & Partial<Pick<VirtualLocation, "@type">>, id?: Id): TSelf;
     /**
-     * Add a participant and return its generated ID.
+     * Add a participant and return a new instance.
      * @param participant Participant data (without @type).
      * @param id Optional participant ID.
-     * @return Participant ID.
+     * @return New instance with the added participant.
      */
-    addParticipant(participant: Omit<Participant, "@type"> & Partial<Pick<Participant, "@type">>, id?: Id): Id;
+    addParticipant(participant: Omit<Participant, "@type"> & Partial<Pick<Participant, "@type">>, id?: Id): TSelf;
     /**
-     * Add an alert and return its generated ID.
+     * Add an alert and return a new instance.
      * @param alert Alert data (without @type).
      * @param id Optional alert ID.
-     * @return Alert ID.
+     * @return New instance with the added alert.
      */
-    addAlert(alert: Omit<Alert, "@type"> & Partial<Pick<Alert, "@type">>, id?: Id): Id;
+    addAlert(alert: Omit<Alert, "@type"> & Partial<Pick<Alert, "@type">>, id?: Id): TSelf;
     /**
      * Update updated/sequence metadata for modified keys.
      * @param keys Modified keys.
      * @param options Update options.
      * @return Updated instance.
      */
-    protected touchKeys(keys: string[], options?: UpdateOptions): this;
+    protected touchKeys(data: T, keys: string[], options?: UpdateOptions): T;
     /**
      * Update updated/sequence metadata for PatchObject changes.
      * @param patch Patch applied to the object.
      * @param options Update options.
      * @return Updated instance.
      */
-    protected touchFromPatch(patch: PatchObject, options?: UpdateOptions): this;
+    protected touchFromPatch(data: T, patch: PatchLike, options?: UpdateOptions): T;
 }