deep signals improvements

sdk/js/alien-deepsignals/README.md

@@ -53,7 +53,7 @@ console.log(state.$count!()); // read via signal function
 
 ```ts
 type DeepSignalOptions = {
-    idGenerator?: () => string | number; // Custom ID generator function
+    idGenerator?: (pathToObject: (string | number)[]) => string | number; // Custom ID generator function
     addIdToObjects?: boolean; // Automatically add @id to plain objects
 };
 ```
@@ -84,7 +84,7 @@ When `addIdToObjects: true`, plain objects automatically receive a readonly, enu
 const state = deepSignal(
     { data: {} },
     { 
-        idGenerator: () => `urn:uuid:${crypto.randomUUID()}`,
+        idGenerator: (_path) => `urn:uuid:${crypto.randomUUID()}`,
         addIdToObjects: true 
     }
 );
@@ -191,7 +191,7 @@ import { addWithId, setSetEntrySyntheticId } from "@ng-org/alien-deepsignals";
 const state = deepSignal(
     { items: new Set() },
     { 
-        idGenerator: () => `urn:uuid:${crypto.randomUUID()}`,
+        idGenerator: (_path) => `urn:uuid:${crypto.randomUUID()}`,
         addIdToObjects: true 
     }
 );
@@ -250,7 +250,7 @@ state.s.add({ data: "test" });
 const state = deepSignal(
     { users: new Set() }, 
     { 
-        idGenerator: () => `urn:user:${crypto.randomUUID()}`,
+        idGenerator: (path) => `urn:user:${path.join("-")}:${crypto.randomUUID()}`,
         addIdToObjects: true 
     }
 );

sdk/js/alien-deepsignals/src/deepSignal.ts

@@ -59,7 +59,7 @@ export type DeepPatchSubscriber = (patches: DeepPatch[]) => void;
 /** Options for configuring deepSignal behavior. */
 export interface DeepSignalOptions {
     /** Custom function to generate synthetic IDs for objects without @id. */
-    idGenerator?: () => string | number;
+    idGenerator?: (pathToObject: (string | number)[]) => string | number;
     /** If true, add @id property to all objects in the tree. */
     addIdToObjects?: boolean;
 }
@@ -156,7 +156,7 @@ function queueDeepPatches(
     ) {
         let syntheticId: string | number;
         if (options.idGenerator) {
-            syntheticId = options.idGenerator();
+            syntheticId = options.idGenerator(basePath);
         } else {
             syntheticId = assignBlankNodeId(val);
         }
@@ -516,6 +516,7 @@ function getFromSet(
     };
     // Pre-pass to ensure any existing non-proxied object entries are proxied (enables deep patches after iteration)
     if (meta) raw.forEach(ensureEntryProxy);
+
     if (key === "add" || key === "delete" || key === "clear") {
         const fn: Function = (raw as any)[key];
         return function (this: any, ...args: any[]) {
@@ -545,7 +546,8 @@ function getFromSet(
                         ) {
                             let syntheticId: string | number;
                             if (metaNow.options.idGenerator) {
-                                syntheticId = metaNow.options.idGenerator();
+                                syntheticId =
+                                    metaNow.options.idGenerator(containerPath);
                             } else {
                                 syntheticId = assignBlankNodeId(entry);
                             }

sdk/js/alien-deepsignals/src/test/patchOptimized.test.ts

@@ -8,40 +8,40 @@ import { watch } from "../watch";
 // times traverse() executes under each strategy.
 
 describe("watch patch-only simplified performance placeholder", () => {
-  let store: any;
+    let store: any;
-  const build = (breadth = 3, depth = 3) => {
+    const build = (breadth = 3, depth = 3) => {
-    const make = (d: number): any => {
+        const make = (d: number): any => {
-      if (d === 0) return { v: 0 };
+            if (d === 0) return { v: 0 };
-      const obj: any = {};
+            const obj: any = {};
-      for (let i = 0; i < breadth; i++) obj["k" + i] = make(d - 1);
+            for (let i = 0; i < breadth; i++) obj["k" + i] = make(d - 1);
-      return obj;
+            return obj;
+        };
+        return make(depth);
     };
-    return make(depth);
-  };
 
-  beforeEach(() => {
+    beforeEach(() => {
-    store = deepSignal(build());
+        store = deepSignal(build());
-  });
+    });
 
-  function mutateAll(breadth = 3, depth = 3) {
+    function mutateAll(breadth = 3, depth = 3) {
-    const visit = (node: any, d: number) => {
+        const visit = (node: any, d: number) => {
-      if (d === 0) {
+            if (d === 0) {
-        node.v++;
+                node.v++;
-        return;
+                return;
-      }
+            }
-      for (let i = 0; i < breadth; i++) visit(node["k" + i], d - 1);
+            for (let i = 0; i < breadth; i++) visit(node["k" + i], d - 1);
-    };
+        };
-    visit(store, depth);
+        visit(store, depth);
-  }
+    }
 
-  it("receives a single batch of patches after deep mutations", async () => {
+    it("receives a single batch of patches after deep mutations", async () => {
-    let batches = 0;
+        let batches = 0;
-    const { stopListening: stop } = watch(store, ({ patches }) => {
+        const { stopListening: stop } = watch(store, ({ patches }) => {
-      if (patches.length) batches++;
+            if (patches.length) batches++;
+        });
+        mutateAll();
+        await Promise.resolve();
+        expect(batches).toBe(1);
+        stop();
     });
-    mutateAll();
-    await Promise.resolve();
-    expect(batches).toBe(1);
-    stop();
-  });
 });

sdk/js/alien-deepsignals/src/test/tier3.test.ts

@@ -1,148 +1,148 @@
 import { describe, it, expect } from "vitest";
 import { deepSignal, getDeepSignalRootId, peek } from "../deepSignal";
 import {
-  watch,
+    watch,
-  __traverseCount,
+    __traverseCount,
-  __resetTraverseCount,
+    __resetTraverseCount,
-  traverse,
+    traverse,
 } from "../watch";
 import { effect } from "../core";
 
 describe("watch advanced", () => {
-  it("basic patch watcher fires on deep mutations", async () => {
+    it("basic patch watcher fires on deep mutations", async () => {
-    const st = deepSignal({ a: { b: { c: 1 } } });
+        const st = deepSignal({ a: { b: { c: 1 } } });
-    let batches: number = 0;
+        let batches: number = 0;
-    watch(st, ({ patches }) => {
+        watch(st, ({ patches }) => {
-      if (patches.length) batches++;
+            if (patches.length) batches++;
+        });
+        st.a.b.c = 2;
+        st.a.b = { c: 3 } as any;
+        await Promise.resolve();
+        expect(batches).toBeGreaterThan(0);
     });
-    st.a.b.c = 2;
-    st.a.b = { c: 3 } as any;
-    await Promise.resolve();
-    expect(batches).toBeGreaterThan(0);
-  });
 
-  // multi-source value mode removed; patch-only now - skip equivalent
+    // multi-source value mode removed; patch-only now - skip equivalent
 
-  // getter source value mode removed in patch-only watcher
+    // getter source value mode removed in patch-only watcher
 
-  it("watch once option still stops after first batch", async () => {
+    it("watch once option still stops after first batch", async () => {
-    const st = deepSignal({ a: 1 });
+        const st = deepSignal({ a: 1 });
-    let count = 0;
+        let count = 0;
-    watch(
+        watch(
-      st,
+            st,
-      () => {
+            () => {
-        count++;
+                count++;
-      },
+            },
-      { once: true, immediate: true }
+            { once: true, immediate: true }
-    );
+        );
-    st.a = 2;
+        st.a = 2;
-    st.a = 3;
+        st.a = 3;
-    await Promise.resolve();
+        await Promise.resolve();
-    expect(count).toBe(1);
+        expect(count).toBe(1);
-  });
+    });
 
-  // observe value mode removed; observe is alias of watch
+    // observe value mode removed; observe is alias of watch
 });
 
 describe("patches & root ids", () => {
-  it("root ids are unique", () => {
+    it("root ids are unique", () => {
-    const a = deepSignal({});
+        const a = deepSignal({});
-    const b = deepSignal({});
+        const b = deepSignal({});
-    expect(getDeepSignalRootId(a)).not.toBe(getDeepSignalRootId(b));
+        expect(getDeepSignalRootId(a)).not.toBe(getDeepSignalRootId(b));
-  });
+    });
 
-  // legacy watchPatches API removed; patch mode only valid for deepSignal roots
+    // legacy watchPatches API removed; patch mode only valid for deepSignal roots
-  it("watch throws on non-deepSignal input", () => {
+    it("watch throws on non-deepSignal input", () => {
-    expect(() => watch({} as any, () => {})).toThrow();
+        expect(() => watch({} as any, () => {})).toThrow();
-  });
+    });
 
-  it("Map unsupported does not emit patches", async () => {
+    it("Map unsupported does not emit patches", async () => {
-    const m = new Map<string, number>();
+        const m = new Map<string, number>();
-    const st = deepSignal({ m });
+        const st = deepSignal({ m });
-    const patches: any[] = [];
+        const patches: any[] = [];
-    const { stopListening: stop } = watch(st, ({ patches: batch }) =>
+        const { stopListening: stop } = watch(st, ({ patches: batch }) =>
-      patches.push(batch)
+            patches.push(batch)
-    );
+        );
-    m.set("a", 1);
+        m.set("a", 1);
-    await Promise.resolve();
+        await Promise.resolve();
-    await Promise.resolve();
+        await Promise.resolve();
-    expect(patches.length).toBe(0);
+        expect(patches.length).toBe(0);
-    stop();
+        stop();
-  });
+    });
 });
 
 describe("tier3: Set iteration variants", () => {
-  it("entries() iteration proxies nested mutation", async () => {
+    it("entries() iteration proxies nested mutation", async () => {
-    const st = deepSignal({ s: new Set<any>() });
+        const st = deepSignal({ s: new Set<any>() });
-    st.s.add({ id: "eEnt", inner: { v: 1 } });
+        st.s.add({ id: "eEnt", inner: { v: 1 } });
-    const paths: string[] = [];
+        const paths: string[] = [];
-    const { stopListening: stop } = watch(st, ({ patches }) =>
+        const { stopListening: stop } = watch(st, ({ patches }) =>
-      paths.push(...patches.map((pp: any) => pp.path.join(".")))
+            paths.push(...patches.map((pp: any) => pp.path.join(".")))
-    );
+        );
-    for (const [val] of st.s.entries()) {
+        for (const [val] of st.s.entries()) {
-      (val as any).inner.v;
+            (val as any).inner.v;
-    } // ensure proxy
+        } // ensure proxy
-    for (const [val] of st.s.entries()) {
+        for (const [val] of st.s.entries()) {
-      (val as any).inner.v = 2;
+            (val as any).inner.v = 2;
-    }
+        }
-    await Promise.resolve();
+        await Promise.resolve();
-    await Promise.resolve();
+        await Promise.resolve();
-    expect(paths.some((p) => p.endsWith("eEnt.inner.v"))).toBe(true);
+        expect(paths.some((p) => p.endsWith("eEnt.inner.v"))).toBe(true);
-    stop();
+        stop();
-  });
+    });
 
-  it("forEach iteration proxies nested mutation", async () => {
+    it("forEach iteration proxies nested mutation", async () => {
-    const st = deepSignal({ s: new Set<any>() });
+        const st = deepSignal({ s: new Set<any>() });
-    st.s.add({ id: "fe1", data: { n: 1 } });
+        st.s.add({ id: "fe1", data: { n: 1 } });
-    const { stopListening: stop } = watch(st, () => {});
+        const { stopListening: stop } = watch(st, () => {});
-    st.s.forEach((e) => (e as any).data.n); // access
+        st.s.forEach((e) => (e as any).data.n); // access
-    st.s.forEach((e) => {
+        st.s.forEach((e) => {
-      (e as any).data.n = 2;
+            (e as any).data.n = 2;
+        });
+        await Promise.resolve();
+        await Promise.resolve();
+        stop();
     });
-    await Promise.resolve();
-    await Promise.resolve();
-    stop();
-  });
 
-  it("keys() iteration returns proxies", async () => {
+    it("keys() iteration returns proxies", async () => {
-    const st = deepSignal({ s: new Set<any>() });
+        const st = deepSignal({ s: new Set<any>() });
-    st.s.add({ id: "k1", foo: { x: 1 } });
+        st.s.add({ id: "k1", foo: { x: 1 } });
-    const { stopListening: stop } = watch(st, () => {});
+        const { stopListening: stop } = watch(st, () => {});
-    for (const e of st.s.keys()) {
+        for (const e of st.s.keys()) {
-      (e as any).foo.x = 2;
+            (e as any).foo.x = 2;
-    }
+        }
-    await Promise.resolve();
+        await Promise.resolve();
-    await Promise.resolve();
+        await Promise.resolve();
-    stop();
+        stop();
-  });
+    });
 });
 
 describe("tier3: peek behavior", () => {
-  it("peek does not create reactive dependency on property", async () => {
+    it("peek does not create reactive dependency on property", async () => {
-    const st = deepSignal({ a: 1 });
+        const st = deepSignal({ a: 1 });
-    let runs = 0;
+        let runs = 0;
-    effect(() => {
+        effect(() => {
-      runs++;
+            runs++;
-      peek(st, "a");
+            peek(st, "a");
+        });
+        expect(runs).toBe(1);
+        st.a = 2;
+        // Flush microtasks
+        await Promise.resolve();
+        await Promise.resolve();
+        expect(runs).toBe(1); // no rerun
     });
-    expect(runs).toBe(1);
-    st.a = 2;
-    // Flush microtasks
-    await Promise.resolve();
-    await Promise.resolve();
-    expect(runs).toBe(1); // no rerun
-  });
 });
 
 describe("tier3: traverse helper direct calls (symbols & sets)", () => {
-  it("traverse counts and respects depth param", () => {
+    it("traverse counts and respects depth param", () => {
-    __resetTraverseCount();
+        __resetTraverseCount();
-    const obj: any = { a: { b: { c: 1 } } };
+        const obj: any = { a: { b: { c: 1 } } };
-    traverse(obj, 1);
+        traverse(obj, 1);
-    const shallowCount = __traverseCount;
+        const shallowCount = __traverseCount;
-    __resetTraverseCount();
+        __resetTraverseCount();
-    traverse(obj, 3);
+        traverse(obj, 3);
-    const deepCount = __traverseCount;
+        const deepCount = __traverseCount;
-    expect(deepCount).toBeGreaterThan(shallowCount);
+        expect(deepCount).toBeGreaterThan(shallowCount);
-  });
+    });
 });

sdk/js/alien-deepsignals/src/test/watch.test.ts

@@ -4,88 +4,88 @@ import { watch } from "../watch";
 import { watchEffect } from "../watchEffect";
 
 describe("watch", () => {
-  it("watch immediate", () => {
+    it("watch immediate", () => {
-    const store = deepSignal({
+        const store = deepSignal({
-      userinfo: {
+            userinfo: {
-        name: "tom",
+                name: "tom",
-      },
+            },
+        });
+        let val!: string;
+        watch(
+            store,
+            ({ newValue }) => {
+                val = newValue.userinfo.name;
+            },
+            { immediate: true }
+        );
+        expect(val).toEqual("tom");
     });
-    let val!: string;
+    it("watch deep", () => {
-    watch(
+        const store = deepSignal({
-      store,
+            userinfo: {
-      ({ newValue }) => {
+                name: "tom",
-        val = newValue.userinfo.name;
+            },
-      },
+        });
-      { immediate: true }
+        let val!: string;
-    );
+        watch(
-    expect(val).toEqual("tom");
+            store,
-  });
+            ({ newValue }) => {
-  it("watch deep", () => {
+                val = newValue.userinfo.name;
-    const store = deepSignal({
+            },
-      userinfo: {
+            { immediate: true }
-        name: "tom",
+        );
-      },
+        let value2!: string;
+        watch(
+            store,
+            ({ newValue }) => {
+                value2 = newValue.userinfo.name;
+            },
+            { immediate: true }
+        );
+        expect(val).toEqual("tom");
+        store.userinfo.name = "jon";
+        // patch delivery async (microtask)
+        return Promise.resolve().then(() => {
+            expect(val).toEqual("jon");
+            // With refactored watch using native effect, shallow watcher now also updates root reference
+            expect(value2).toEqual("jon");
+        });
     });
-    let val!: string;
-    watch(
-      store,
-      ({ newValue }) => {
-        val = newValue.userinfo.name;
-      },
-      { immediate: true }
-    );
-    let value2!: string;
-    watch(
-      store,
-      ({ newValue }) => {
-        value2 = newValue.userinfo.name;
-      },
-      { immediate: true }
-    );
-    expect(val).toEqual("tom");
-    store.userinfo.name = "jon";
-    // patch delivery async (microtask)
-    return Promise.resolve().then(() => {
-      expect(val).toEqual("jon");
-      // With refactored watch using native effect, shallow watcher now also updates root reference
-      expect(value2).toEqual("jon");
-    });
-  });
 
-  it("watch once", () => {
+    it("watch once", () => {
-    const store = deepSignal({
+        const store = deepSignal({
-      userinfo: {
+            userinfo: {
-        name: "tom",
+                name: "tom",
-      },
+            },
+        });
+        let val!: string;
+        watch(
+            store,
+            ({ newValue }) => {
+                val = newValue.userinfo.name;
+            },
+            { immediate: true, once: true }
+        );
+
+        expect(val).toEqual("tom");
+        store.userinfo.name = "jon";
+        // once watcher shouldn't update after first run
+        expect(val).toEqual("tom");
     });
-    let val!: string;
-    watch(
-      store,
-      ({ newValue }) => {
-        val = newValue.userinfo.name;
-      },
-      { immediate: true, once: true }
-    );
 
-    expect(val).toEqual("tom");
+    it("watch effect", () => {
-    store.userinfo.name = "jon";
+        const store = deepSignal({
-    // once watcher shouldn't update after first run
+            userinfo: {
-    expect(val).toEqual("tom");
+                name: "tom",
-  });
+            },
+        });
+        let x = undefined;
+        watchEffect(() => {
+            x = store.userinfo.name;
+        });
 
-  it("watch effect", () => {
+        expect(x).toEqual("tom");
-    const store = deepSignal({
+        store.userinfo.name = "jon";
-      userinfo: {
+        expect(x).toEqual("jon");
-        name: "tom",
-      },
     });
-    let x = undefined;
-    watchEffect(() => {
-      x = store.userinfo.name;
-    });
-
-    expect(x).toEqual("tom");
-    store.userinfo.name = "jon";
-    expect(x).toEqual("jon");
-  });
 });

sdk/js/alien-deepsignals/src/watch.ts

@@ -1,10 +1,10 @@
 import { isObject, isPlainObject, isSet, isMap, isArray } from "./utils";
 import { isSignal } from "./core";
 import {
-  isDeepSignal,
+    isDeepSignal,
-  subscribeDeepMutations,
+    subscribeDeepMutations,
-  getDeepSignalRootId,
+    getDeepSignalRootId,
-  DeepPatch,
+    DeepPatch,
 } from "./deepSignal";
 import { ReactiveFlags } from "./contents";
 
@@ -15,125 +15,125 @@ export type WatchEffect = (registerCleanup: RegisterCleanup) => void;
 
 /** Options for {@link watch}. */
 export interface WatchOptions {
-  /** Trigger the callback immediately with the current value (default: false). */
+    /** Trigger the callback immediately with the current value (default: false). */
-  immediate?: boolean;
+    immediate?: boolean;
-  /** Auto-stop the watcher after the first callback run that delivers patches (or immediate call if no patches). */
+    /** Auto-stop the watcher after the first callback run that delivers patches (or immediate call if no patches). */
-  once?: boolean;
+    once?: boolean;
-  /** Allow legacy/unknown options (ignored) to avoid hard breaks while migrating. */
+    /** Allow legacy/unknown options (ignored) to avoid hard breaks while migrating. */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  [legacy: string]: any;
+    [legacy: string]: any;
 }
 
 export interface WatchPatchEvent<Root = any> {
-  /** Patch batch that triggered this callback (may be empty for immediate). */
+    /** Patch batch that triggered this callback (may be empty for immediate). */
-  patches: DeepPatch[];
+    patches: DeepPatch[];
-  /** Previous snapshot (deep-cloned) of the root value before these patches. Undefined on first call. */
+    /** Previous snapshot (deep-cloned) of the root value before these patches. Undefined on first call. */
-  oldValue: Root | undefined;
+    oldValue: Root | undefined;
-  /** Current root value (live proxy). */
+    /** Current root value (live proxy). */
-  newValue: Root;
+    newValue: Root;
 }
 
 export type WatchPatchCallback<Root = any> = (
-  event: WatchPatchEvent<Root>
+    event: WatchPatchEvent<Root>
 ) => any;
 
 // Internal helper kept for external compatibility.
 export const remove = <T>(arr: T[], el: T): void => {
-  const i = arr.indexOf(el);
+    const i = arr.indexOf(el);
-  if (i > -1) arr.splice(i, 1);
+    if (i > -1) arr.splice(i, 1);
 };
 
 /** Observe patch batches on a deep signal root. */
 export function watch<Root = any>(
-  source: Root,
+    source: Root,
-  callback: WatchPatchCallback<Root>,
+    callback: WatchPatchCallback<Root>,
-  options: WatchOptions = {}
+    options: WatchOptions = {}
 ) {
-  if (!isDeepSignal(source)) {
+    if (!isDeepSignal(source)) {
-    throw new Error(
+        throw new Error(
-      "watch() now only supports deepSignal roots (patch mode only)"
+            "watch() now only supports deepSignal roots (patch mode only)"
-    );
+        );
-  }
-  const { immediate, once } = options;
-
-  const rootId = getDeepSignalRootId(source as any)!;
-
-  let active = true;
-  let cleanup: (() => void) | undefined;
-  const registerCleanup: RegisterCleanup = (fn) => {
-    cleanup = fn;
-  };
-  const runCleanup = () => {
-    if (cleanup) {
-      try {
-        cleanup();
-      } catch {
-        /* ignore */
-      } finally {
-        cleanup = undefined;
-      }
     }
-  };
+    const { immediate, once } = options;
-
+
-  // Deep clone snapshot helper (JSON clone sufficient for typical reactive plain data)
+    const rootId = getDeepSignalRootId(source as any)!;
-  const clone = (v: any) => {
+
-    try {
+    let active = true;
-      return JSON.parse(JSON.stringify(v));
+    let cleanup: (() => void) | undefined;
-    } catch {
+    const registerCleanup: RegisterCleanup = (fn) => {
-      return undefined as any;
+        cleanup = fn;
-    }
+    };
-  };
+    const runCleanup = () => {
-  let lastSnapshot: Root | undefined = clone(source);
+        if (cleanup) {
-
+            try {
-  const stopListening = () => {
+                cleanup();
-    if (!active) return;
+            } catch {
-    active = false;
+                /* ignore */
-    runCleanup();
+            } finally {
-    unsubscribe && unsubscribe();
+                cleanup = undefined;
-  };
+            }
-
+        }
-  const deliver = (patches: DeepPatch[]) => {
+    };
-    if (!active) return;
+
-    runCleanup();
+    // Deep clone snapshot helper (JSON clone sufficient for typical reactive plain data)
-    const prev = lastSnapshot;
+    const clone = (v: any) => {
-    const next = source as any as Root; // live proxy
+        try {
-    try {
+            return JSON.parse(JSON.stringify(v));
-      callback({
+        } catch {
-        patches,
+            return undefined as any;
-        oldValue: prev,
+        }
-        newValue: next,
+    };
-      });
+    let lastSnapshot: Root | undefined = clone(source);
-    } finally {
+
-      if (active) lastSnapshot = clone(next);
+    const stopListening = () => {
-      if (once) stopListening();
+        if (!active) return;
+        active = false;
+        runCleanup();
+        unsubscribe && unsubscribe();
+    };
+
+    const deliver = (patches: DeepPatch[]) => {
+        if (!active) return;
+        runCleanup();
+        const prev = lastSnapshot;
+        const next = source as any as Root; // live proxy
+        try {
+            callback({
+                patches,
+                oldValue: prev,
+                newValue: next,
+            });
+        } finally {
+            if (active) lastSnapshot = clone(next);
+            if (once) stopListening();
+        }
+    };
+
+    const unsubscribe = subscribeDeepMutations(rootId, (patches) => {
+        if (!patches.length) return; // ignore empty batches
+        deliver(patches);
+    });
+
+    if (immediate) {
+        // Immediate call with empty patch list (snapshot only)
+        deliver([]);
     }
-  };
+
-
+    return {
-  const unsubscribe = subscribeDeepMutations(rootId, (patches) => {
+        /** Stop listening to future patch batches; idempotent. */
-    if (!patches.length) return; // ignore empty batches
+        stopListening,
-    deliver(patches);
+        /** Register a cleanup callback run before the next invocation / stop. */
-  });
+        registerCleanup,
-
+    };
-  if (immediate) {
-    // Immediate call with empty patch list (snapshot only)
-    deliver([]);
-  }
-
-  return {
-    /** Stop listening to future patch batches; idempotent. */
-    stopListening,
-    /** Register a cleanup callback run before the next invocation / stop. */
-    registerCleanup,
-  };
 }
 
 // observe alias
 export function observe(
-  source: any,
+    source: any,
-  cb: WatchPatchCallback,
+    cb: WatchPatchCallback,
-  options?: WatchOptions
+    options?: WatchOptions
 ) {
-  return watch(source, cb, options);
+    return watch(source, cb, options);
 }
 
 // Instrumentation counter for performance tests (number of traverse invocations)
@@ -141,7 +141,7 @@ export function observe(
 export let __traverseCount = 0; // retained for external tooling/tests although watch no longer uses traversal
 /** Reset the traversal instrumentation counter back to 0. */
 export function __resetTraverseCount() {
-  __traverseCount = 0;
+    __traverseCount = 0;
 }
 
 /**
@@ -149,40 +149,40 @@ export function __resetTraverseCount() {
  * Depth-limited; protects against cycles via `seen` set; respects ReactiveFlags.SKIP opt-out.
  */
 export function traverse(
-  value: unknown,
+    value: unknown,
-  depth: number = Infinity,
+    depth: number = Infinity,
-  seen?: Set<unknown>
+    seen?: Set<unknown>
 ): unknown {
-  __traverseCount++;
+    __traverseCount++;
-  if (depth <= 0 || !isObject(value) || (value as any)[ReactiveFlags.SKIP]) {
+    if (depth <= 0 || !isObject(value) || (value as any)[ReactiveFlags.SKIP]) {
-    return value;
+        return value;
-  }
-
-  seen = seen || new Set();
-  if (seen.has(value)) {
-    return value;
-  }
-  seen.add(value);
-  depth--;
-  if (isSignal(value)) {
-    traverse((value as any)(), depth, seen);
-  } else if (isArray(value)) {
-    for (let i = 0; i < value.length; i++) {
-      traverse(value[i], depth, seen);
     }
-  } else if (isSet(value) || isMap(value)) {
+
-    value.forEach((v: any) => {
+    seen = seen || new Set();
-      traverse(v, depth, seen);
+    if (seen.has(value)) {
-    });
+        return value;
-  } else if (isPlainObject(value)) {
-    for (const key in value) {
-      traverse(value[key], depth, seen);
     }
-    for (const key of Object.getOwnPropertySymbols(value)) {
+    seen.add(value);
-      if (Object.prototype.propertyIsEnumerable.call(value, key)) {
+    depth--;
-        traverse(value[key as any], depth, seen);
+    if (isSignal(value)) {
-      }
+        traverse((value as any)(), depth, seen);
+    } else if (isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            traverse(value[i], depth, seen);
+        }
+    } else if (isSet(value) || isMap(value)) {
+        value.forEach((v: any) => {
+            traverse(v, depth, seen);
+        });
+    } else if (isPlainObject(value)) {
+        for (const key in value) {
+            traverse(value[key], depth, seen);
+        }
+        for (const key of Object.getOwnPropertySymbols(value)) {
+            if (Object.prototype.propertyIsEnumerable.call(value, key)) {
+                traverse(value[key as any], depth, seen);
+            }
+        }
     }
-  }
+    return value;
-  return value;
 }

sdk/js/examples/multi-framework-signals/src/shapes/orm/catShape.schema.ts

@@ -19,7 +19,7 @@ export const catShapeSchema: Schema = {
         maxCardinality: 1,
         minCardinality: 1,
         iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
-        readablePredicate: "type",
+        readablePredicate: "@type",
       },
       {
         dataTypes: [

sdk/js/examples/multi-framework-signals/src/shapes/orm/catShape.typings.ts

@@ -10,11 +10,11 @@ export type IRI = string;
  * Cat Type
  */
 export interface Cat {
-  id: IRI;
+  readonly "@id": IRI;
   /**
    * Original IRI: http://www.w3.org/1999/02/22-rdf-syntax-ns#type
    */
-  type: string;
+  "@type": string;
   /**
    * Original IRI: http://example.org/name
    */
@@ -31,7 +31,7 @@ export interface Cat {
    * Original IRI: http://example.org/address
    */
   address: {
-    id: IRI;
+    readonly "@id": IRI;
     /**
      * Original IRI: http://example.org/street
      */

sdk/js/examples/multi-framework-signals/src/shapes/orm/personShape.schema.ts

@@ -19,7 +19,7 @@ export const personShapeSchema: Schema = {
         maxCardinality: 1,
         minCardinality: 1,
         iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
-        readablePredicate: "type",
+        readablePredicate: "@type",
       },
       {
         dataTypes: [

sdk/js/examples/multi-framework-signals/src/shapes/orm/personShape.typings.ts

@@ -10,11 +10,11 @@ export type IRI = string;
  * Person Type
  */
 export interface Person {
-  id: IRI;
+  readonly "@id": IRI;
   /**
    * Original IRI: http://www.w3.org/1999/02/22-rdf-syntax-ns#type
    */
-  type: string;
+  "@type": string;
   /**
    * Original IRI: http://example.org/name
    */
@@ -23,7 +23,7 @@ export interface Person {
    * Original IRI: http://example.org/address
    */
   address: {
-    id: IRI;
+    readonly "@id": IRI;
     /**
      * Original IRI: http://example.org/street
      */

sdk/js/examples/multi-framework-signals/src/shapes/orm/testShape.schema.ts

@@ -19,7 +19,7 @@ export const testShapeSchema: Schema = {
         maxCardinality: 1,
         minCardinality: 1,
         iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
-        readablePredicate: "type",
+        readablePredicate: "@type",
         extra: true,
       },
       {

sdk/js/examples/multi-framework-signals/src/shapes/orm/testShape.typings.ts

@@ -10,11 +10,11 @@ export type IRI = string;
  * TestObject Type
  */
 export interface TestObject {
-  id: IRI;
+  readonly "@id": IRI;
   /**
    * Original IRI: http://www.w3.org/1999/02/22-rdf-syntax-ns#type
    */
-  type: string;
+  "@type": string;
   /**
    * Original IRI: http://example.org/stringValue
    */
@@ -35,7 +35,7 @@ export interface TestObject {
    * Original IRI: http://example.org/objectValue
    */
   objectValue: {
-    id: IRI;
+    readonly "@id": IRI;
     /**
      * Original IRI: http://example.org/nestedString
      */
@@ -55,7 +55,7 @@ export interface TestObject {
   anotherObject?: Record<
     IRI,
     {
-      id: IRI;
+      readonly "@id": IRI;
       /**
        * Original IRI: http://example.org/prop1
        */

sdk/js/signals/src/connector/applyDiff.test.ts

@@ -52,74 +52,169 @@ describe("applyDiff - set operations (primitives)", () => {
     });
 });
 
-describe("applyDiff - set operations (object sets)", () => {
+describe("applyDiff - multi-valued objects (Set-based)", () => {
-    test("add object entries to new object-set", () => {
+    test("create multi-object container (Set) without @id", () => {
-        const state: any = {};
+        const state: any = { "urn:person1": {} };
         const diff: Patch[] = [
             {
                 op: "add",
-                valType: "set",
+                valType: "object",
-                path: p("users"),
+                path: p("urn:person1", "children"),
-                value: { u1: { id: "u1", n: 1 }, u2: { id: "u2", n: 2 } },
             },
         ];
         applyDiff(state, diff);
-        expect(state.users.u1).toEqual({ id: "u1", n: 1 });
+        expect(state["urn:person1"].children).toBeInstanceOf(Set);
-        expect(state.users.u2).toEqual({ id: "u2", n: 2 });
     });
-    test("merge object entries into existing object-set", () => {
+
-        const state: any = { users: { u1: { id: "u1", n: 1 } } };
+    test("add object to Set with @id", () => {
+        const state: any = { "urn:person1": { children: new Set() } };
         const diff: Patch[] = [
+            // First patch creates the object in the Set
             {
                 op: "add",
-                valType: "set",
+                valType: "object",
-                path: p("users"),
+                path: p("urn:person1", "children", "urn:child1"),
-                value: { u2: { id: "u2", n: 2 } },
+            },
+            // Second patch adds the @id property
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child1", "@id"),
+                value: "urn:child1",
             },
         ];
         applyDiff(state, diff);
-        expect(Object.keys(state.users).sort()).toEqual(["u1", "u2"]);
+        const children = state["urn:person1"].children;
+        expect(children).toBeInstanceOf(Set);
+        expect(children.size).toBe(1);
+        const child = [...children][0];
+        expect(child["@id"]).toBe("urn:child1");
     });
-    test("remove object entries from object-set", () => {
+
-        const state: any = { users: { u1: {}, u2: {}, u3: {} } };
+    test("add properties to object in Set", () => {
+        const obj = { "@id": "urn:child1" };
+        const state: any = { "urn:person1": { children: new Set([obj]) } };
         const diff: Patch[] = [
             {
-                op: "remove",
+                op: "add",
-                valType: "set",
+                path: p("urn:person1", "children", "urn:child1", "name"),
-                path: p("users"),
+                value: "Alice",
-                value: ["u1", "u3"],
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child1", "age"),
+                value: 10,
             },
         ];
         applyDiff(state, diff);
-        expect(Object.keys(state.users)).toEqual(["u2"]);
+        const child = [...state["urn:person1"].children][0];
+        expect(child.name).toBe("Alice");
+        expect(child.age).toBe(10);
+    });
+
+    test("remove object from Set by @id", () => {
+        const obj1 = { "@id": "urn:child1", name: "Alice" };
+        const obj2 = { "@id": "urn:child2", name: "Bob" };
+        const state: any = {
+            "urn:person1": { children: new Set([obj1, obj2]) },
+        };
+        const diff: Patch[] = [
+            { op: "remove", path: p("urn:person1", "children", "urn:child1") },
+        ];
+        applyDiff(state, diff);
+        const children = state["urn:person1"].children;
+        expect(children.size).toBe(1);
+        const remaining = [...children][0];
+        expect(remaining["@id"]).toBe("urn:child2");
     });
-    test("adding primitives to existing object-set replaces with Set", () => {
+
-        const state: any = { mixed: { a: {}, b: {} } };
+    test("create nested Set (multi-valued property within object in Set)", () => {
+        const parent: any = { "@id": "urn:parent1" };
+        const state: any = { root: { parents: new Set([parent]) } };
         const diff: Patch[] = [
-            { op: "add", valType: "set", path: p("mixed"), value: [1, 2] },
+            {
+                op: "add",
+                valType: "object",
+                path: p("root", "parents", "urn:parent1", "children"),
+            },
+            {
+                op: "add",
+                valType: "object",
+                path: p(
+                    "root",
+                    "parents",
+                    "urn:parent1",
+                    "children",
+                    "urn:child1"
+                ),
+            },
+            {
+                op: "add",
+                path: p(
+                    "root",
+                    "parents",
+                    "urn:parent1",
+                    "children",
+                    "urn:child1",
+                    "@id"
+                ),
+                value: "urn:child1",
+            },
         ];
         applyDiff(state, diff);
-        expect(state.mixed).toBeInstanceOf(Set);
+        const nestedChildren = parent.children;
-        expect([...state.mixed]).toEqual([1, 2]);
+        expect(nestedChildren).toBeInstanceOf(Set);
+        expect(nestedChildren.size).toBe(1);
     });
 });
 
 describe("applyDiff - object & literal operations", () => {
-    test("add object (create empty object)", () => {
+    test("create single object (with @id)", () => {
+        const state: any = { "urn:person1": {} };
+        const diff: Patch[] = [
+            { op: "add", path: p("urn:person1", "address"), valType: "object" },
+            {
+                op: "add",
+                path: p("urn:person1", "address", "@id"),
+                value: "urn:addr1",
+            },
+        ];
+        applyDiff(state, diff);
+        expect(state["urn:person1"].address).toEqual({ "@id": "urn:addr1" });
+        expect(state["urn:person1"].address).not.toBeInstanceOf(Set);
+    });
+
+    test("create multi-object container (without @id) -> Set", () => {
+        const state: any = { "urn:person1": {} };
+        const diff: Patch[] = [
+            {
+                op: "add",
+                path: p("urn:person1", "addresses"),
+                valType: "object",
+            },
+        ];
+        applyDiff(state, diff);
+        expect(state["urn:person1"].addresses).toBeInstanceOf(Set);
+    });
+
+    test("add object (create empty object with @id)", () => {
         const state: any = {};
         const diff: Patch[] = [
             { op: "add", path: p("address"), valType: "object" },
+            { op: "add", path: p("address", "@id"), value: "urn:addr1" },
         ];
         applyDiff(state, diff);
-        expect(state.address).toEqual({});
+        expect(state.address).toEqual({ "@id": "urn:addr1" });
+        expect(state.address).not.toBeInstanceOf(Set);
     });
-    test("add nested object path with ensurePathExists", () => {
+    test("add nested object path with ensurePathExists and @id", () => {
         const state: any = {};
         const diff: Patch[] = [
             { op: "add", path: p("a", "b", "c"), valType: "object" },
+            { op: "add", path: p("a", "b", "c", "@id"), value: "urn:c1" },
         ];
         applyDiff(state, diff, true);
-        expect(state.a.b.c).toEqual({});
+        expect(state.a.b.c).toEqual({ "@id": "urn:c1" });
+        expect(state.a.b.c).not.toBeInstanceOf(Set);
     });
     test("add primitive value", () => {
         const state: any = { address: {} };
@@ -156,23 +251,46 @@ describe("applyDiff - object & literal operations", () => {
 describe("applyDiff - multiple mixed patches in a single diff", () => {
     test("sequence of mixed set/object/literal add & remove", () => {
         const state: any = {
-            users: { u1: { id: "u1" } },
+            "urn:person1": {},
             tags: new Set(["old"]),
         };
         const diff: Patch[] = [
+            // Create multi-object Set
             {
                 op: "add",
-                valType: "set",
+                valType: "object",
-                path: p("users"),
+                path: p("urn:person1", "addresses"),
-                value: { u2: { id: "u2" } },
+            },
+            {
+                op: "add",
+                valType: "object",
+                path: p("urn:person1", "addresses", "urn:addr1"),
             },
+            {
+                op: "add",
+                path: p("urn:person1", "addresses", "urn:addr1", "@id"),
+                value: "urn:addr1",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "addresses", "urn:addr1", "street"),
+                value: "Main St",
+            },
+            // Create single object
             { op: "add", path: p("profile"), valType: "object" },
+            { op: "add", path: p("profile", "@id"), value: "urn:profile1" },
             { op: "add", path: p("profile", "name"), value: "Alice" },
+            // Primitive set operations
             { op: "add", valType: "set", path: p("tags"), value: ["new"] },
             { op: "remove", valType: "set", path: p("tags"), value: "old" },
         ];
-        applyDiff(state, diff);
+        applyDiff(state, diff); // Enable ensurePathExists for nested object creation
-        expect(Object.keys(state.users).sort()).toEqual(["u1", "u2"]);
+        expect(state["urn:person1"].addresses).toBeInstanceOf(Set);
+        expect(state["urn:person1"].addresses.size).toBe(1);
+        const addr = [...state["urn:person1"].addresses][0];
+        expect(addr["@id"]).toBe("urn:addr1");
+        expect(addr.street).toBe("Main St");
+        expect(state.profile["@id"]).toBe("urn:profile1");
         expect(state.profile.name).toBe("Alice");
         expect([...state.tags]).toEqual(["new"]);
     });
@@ -180,8 +298,11 @@ describe("applyDiff - multiple mixed patches in a single diff", () => {
     test("complex nested path creation and mutations with ensurePathExists", () => {
         const state: any = {};
         const diff: Patch[] = [
+            // Create b as a single object (with @id)
             { op: "add", path: p("a", "b"), valType: "object" },
+            { op: "add", path: p("a", "b", "@id"), value: "urn:b1" },
             { op: "add", path: p("a", "b", "c"), value: 1 },
+            // Create a primitive set
             {
                 op: "add",
                 valType: "set",
@@ -193,6 +314,7 @@ describe("applyDiff - multiple mixed patches in a single diff", () => {
             { op: "remove", path: p("a", "b", "c") },
         ];
         applyDiff(state, diff, true);
+        expect(state.a.b["@id"]).toBe("urn:b1");
         expect(state.a.b.c).toBeUndefined();
         expect(state.a.b.d).toBe(2);
         expect(state.a.nums).toBeInstanceOf(Set);
@@ -200,20 +322,166 @@ describe("applyDiff - multiple mixed patches in a single diff", () => {
     });
 });
 
-describe("applyDiff - ignored / invalid scenarios", () => {
+describe("applyDiff - complete workflow example", () => {
-    test("skip patch with non-leading slash path", () => {
+    test("full example: create person with single address and multiple children", () => {
         const state: any = {};
         const diff: Patch[] = [
-            { op: "add", path: "address/street", value: "x" },
+            // Create root person object
+            { op: "add", path: p("urn:person1"), valType: "object" },
+            { op: "add", path: p("urn:person1", "@id"), value: "urn:person1" },
+            { op: "add", path: p("urn:person1", "name"), value: "John" },
+
+            // Add single address object
+            { op: "add", path: p("urn:person1", "address"), valType: "object" },
+            {
+                op: "add",
+                path: p("urn:person1", "address", "@id"),
+                value: "urn:addr1",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "address", "street"),
+                value: "1st Street",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "address", "country"),
+                value: "Greece",
+            },
+
+            // Create multi-valued children Set
+            {
+                op: "add",
+                path: p("urn:person1", "children"),
+                valType: "object",
+            },
+
+            // Add first child
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child1"),
+                valType: "object",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child1", "@id"),
+                value: "urn:child1",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child1", "name"),
+                value: "Alice",
+            },
+
+            // Add second child
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child2"),
+                valType: "object",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child2", "@id"),
+                value: "urn:child2",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child2", "name"),
+                value: "Bob",
+            },
+
+            // Add primitive set (tags)
+            {
+                op: "add",
+                valType: "set",
+                path: p("urn:person1", "tags"),
+                value: ["developer", "parent"],
+            },
         ];
-        applyDiff(state, diff);
+
-        expect(state).toEqual({});
+        applyDiff(state, diff); // Enable ensurePathExists to create nested objects
+
+        // Verify person
+        expect(state["urn:person1"]["@id"]).toBe("urn:person1");
+        expect(state["urn:person1"].name).toBe("John");
+
+        // Verify single address (plain object)
+        expect(state["urn:person1"].address).not.toBeInstanceOf(Set);
+        expect(state["urn:person1"].address["@id"]).toBe("urn:addr1");
+        expect(state["urn:person1"].address.street).toBe("1st Street");
+        expect(state["urn:person1"].address.country).toBe("Greece");
+
+        // Verify children Set
+        const children = state["urn:person1"].children;
+        expect(children).toBeInstanceOf(Set);
+        expect(children.size).toBe(2);
+
+        const childrenArray = [...children];
+        const alice = childrenArray.find((c: any) => c["@id"] === "urn:child1");
+        const bob = childrenArray.find((c: any) => c["@id"] === "urn:child2");
+        expect(alice.name).toBe("Alice");
+        expect(bob.name).toBe("Bob");
+
+        // Verify primitive set
+        expect(state["urn:person1"].tags).toBeInstanceOf(Set);
+        expect([...state["urn:person1"].tags].sort()).toEqual([
+            "developer",
+            "parent",
+        ]);
     });
-    test("missing parent without ensurePathExists -> patch skipped and no mutation", () => {
+
-        const state: any = {};
+    test("update and remove operations on complex structure", () => {
-        const diff: Patch[] = [{ op: "add", path: p("a", "b", "c"), value: 1 }];
+        // Start with pre-existing structure
-        applyDiff(state, diff, false);
+        const child1 = { "@id": "urn:child1", name: "Alice" };
-        expect(state).toEqual({});
+        const child2 = { "@id": "urn:child2", name: "Bob" };
+        const state: any = {
+            "urn:person1": {
+                "@id": "urn:person1",
+                name: "John",
+                address: {
+                    "@id": "urn:addr1",
+                    street: "1st Street",
+                    country: "Greece",
+                },
+                children: new Set([child1, child2]),
+                tags: new Set(["developer", "parent"]),
+            },
+        };
+
+        const diff: Patch[] = [
+            // Update address property
+            {
+                op: "add",
+                path: p("urn:person1", "address", "street"),
+                value: "2nd Street",
+            },
+
+            // Remove one child
+            { op: "remove", path: p("urn:person1", "children", "urn:child1") },
+
+            // Update child property
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child2", "age"),
+                value: 12,
+            },
+
+            // Remove tag
+            {
+                op: "remove",
+                valType: "set",
+                path: p("urn:person1", "tags"),
+                value: "developer",
+            },
+        ];
+
+        applyDiff(state, diff);
+
+        expect(state["urn:person1"].address.street).toBe("2nd Street");
+        expect(state["urn:person1"].children.size).toBe(1);
+        expect([...state["urn:person1"].children][0]["@id"]).toBe("urn:child2");
+        expect([...state["urn:person1"].children][0].age).toBe(12);
+        expect([...state["urn:person1"].tags]).toEqual(["parent"]);
     });
 });
 

sdk/js/signals/src/connector/applyDiff.ts

@@ -21,14 +21,8 @@ export interface SetAddPatch {
      * New value for set mutations:
      *  - A single primitive
      *  - An array of primitives
-     *  - An object (id -> object) for object "set" additions
      */
-    value:
+    value: number | string | boolean | (number | string | boolean)[];
-        | number
-        | string
-        | boolean
-        | (number | string | boolean)[]
-        | { [id: string]: object };
 }
 
 export interface SetRemovePatch {
@@ -37,8 +31,8 @@ export interface SetRemovePatch {
     valType: "set";
     /**
      * The value(s) to be removed from the set. Either:
-     *  - A single primitive / id
+     *  - A single primitive
-     *  - An array of primitives / ids
+     *  - An array of primitives
      */
     value: number | string | boolean | (number | string | boolean)[];
 }
@@ -67,57 +61,113 @@ function isPrimitive(v: unknown): v is string | number | boolean {
     );
 }
 
-// TODO: Escape slashes and tildes (~1, ~0)
+/**
+ * Find an object in a Set by its @id property.
+ * Returns the object if found, otherwise undefined.
+ */
+function findInSetById(set: Set<any>, id: string): any | undefined {
+    // TODO: We could optimize that by leveraging the key @id to object mapping in sets of deepSignals.
+
+    for (const item of set) {
+        if (typeof item === "object" && item !== null && item["@id"] === id) {
+            return item;
+        }
+    }
+    return undefined;
+}
+
 /**
  * Apply a diff to an object.
  *
- *  * The syntax is inspired by RFC 6902 but it is not compatible.
+ * The syntax is inspired by RFC 6902 but it is not compatible.
+ *
+ * It supports Sets for multi-valued properties:
+ *   - Primitive values are added as Sets (Set<string | number | boolean>)
+ *   - Multi-valued objects are stored in Sets, accessed by their @id property
+ *   - Single objects are plain objects with an @id property
+ *
+ * Path traversal:
+ *   - When traversing through a Set, the path segment is treated as an @id to find the object
+ *   - When traversing through a plain object, the path segment is a property name
  *
- * It supports sets:
- *   - Primitive values are added as sets,
- *   - Sets of objects are represented as objects with their id being the key.
  * @example operations
  *   ```jsonc
- *     // Add one or more objects to a set.
+ *     // === SINGLE OBJECT ===
- *     { "op": "add", "type": "set", "path": "/address", "value": { "ID1": {...}, "ID2": {...} } },
+ *     // Creating a single object (has @id at same level)
- *     // Remove one or more objects from a set.
+ *     { "op": "add", "path": "/urn:example:person1/address", "valType": "object" }
- *     { "op": "remove", "type": "set", "path": "/address", "value": ["ID1","ID2"] }
+ *     { "op": "add", "path": "/urn:example:person1/address/@id", "value": "urn:test:address1" }
- *     // Add primitive types to a sets (URIs are treated just like strings)
+ *     // Adding primitives to single object
- *     { "op": "add", "type": "set", "path": "/address", "value": [1,2,3] }
+ *     { "op": "add", "path": "/urn:example:person1/address/street", "value": "1st street" }
- *     // Remove primitive types from a set.
+ *     { "op": "add", "path": "/urn:example:person1/address/country", "value": "Greece" }
- *     { "op": "remove", "type": "set", "path": "/address", "value": [1,2] }
+ *     // Remove a primitive from object
+ *     { "op": "remove", "path": "/urn:example:person1/address/street" }
+ *     // Remove the entire object
+ *     { "op": "remove", "path": "/urn:example:person1/address" }
+ *
+ *     // === MULTI-VALUED OBJECTS (Set) ===
+ *     // Creating a multi-object container (NO @id at this level -> creates Set)
+ *     { "op": "add", "path": "/urn:example:person1/children", "valType": "object" }
+ *     // Adding an object to the Set (path includes object's @id)
+ *     { "op": "add", "path": "/urn:example:person1/children/urn:example:child1", "valType": "object" }
+ *     { "op": "add", "path": "/urn:example:person1/children/urn:example:child1/@id", "value": "urn:example:child1" }
+ *     // Adding properties to object in Set
+ *     { "op": "add", "path": "/urn:example:person1/children/urn:example:child1/name", "value": "Alice" }
+ *     // Remove an object from Set
+ *     { "op": "remove", "path": "/urn:example:person1/children/urn:example:child1" }
+ *     // Remove all objects (the Set itself)
+ *     { "op": "remove", "path": "/urn:example:person1/children" }
  *
- *     // Creating an object.
+ *     // === PRIMITIVE SETS ===
- *     { "op": "add", "path": "/address", "type": "object" }
+ *     // Add primitive types to Sets
- *     // Adding primitives.
+ *     { "op": "add", "valType": "set", "path": "/urn:example:person1/tags", "value": [1,2,3] }
- *     { "op": "add", "path": "/address/street", value: "1st street" }
+ *     // Remove primitive types from a Set
- *     { "op": "add", "path": "/address/country", value: "Greece" }
+ *     { "op": "remove", "valType": "set", "path": "/urn:example:person1/tags", "value": [1,2] }
- *     // Remove a primitive.
- *     { "op": "remove", "path": "/address/street" }
- *     // Remove an object
- *     { "op": "remove", "path": "/address" }
  * ```
  *
  * @param currentState The object before the patch
- * @param diff An array of patches to apply to the object.
+ * @param patches An array of patches to apply to the object.
  * @param ensurePathExists If true, create nested objects along the path if the path does not exist.
  */
 export function applyDiff(
     currentState: Record<string, any>,
-    diff: Patch[],
+    patches: Patch[],
     ensurePathExists: boolean = false
 ) {
-    for (const patch of diff) {
+    for (let patchIndex = 0; patchIndex < patches.length; patchIndex++) {
+        const patch = patches[patchIndex];
         if (!patch.path.startsWith("/")) continue;
-        const pathParts = patch.path.slice(1).split("/").filter(Boolean);
+        const pathParts = patch.path
+            .slice(1)
+            .split("/")
+            .filter(Boolean)
+            .map(decodePathSegment);
 
         if (pathParts.length === 0) continue; // root not supported
         const lastKey = pathParts[pathParts.length - 1];
         let parentVal: any = currentState;
         let parentMissing = false;
-        // Traverse only intermediate segments
+        // Traverse only intermediate segments (to leaf object at path)
         for (let i = 0; i < pathParts.length - 1; i++) {
             const seg = pathParts[i];
+
+            // Handle Sets: if parentVal is a Set, find object by @id
+            if (parentVal instanceof Set) {
+                const foundObj = findInSetById(parentVal, seg);
+                if (foundObj) {
+                    parentVal = foundObj;
+                } else if (ensurePathExists) {
+                    // Create new object in the set with this @id
+                    const newObj = { "@id": seg };
+                    parentVal.add(newObj);
+                    parentVal = newObj;
+                } else {
+                    parentMissing = true;
+                    break;
+                }
+                continue;
+            }
+
+            // Handle regular objects
             if (
                 parentVal != null &&
                 typeof parentVal === "object" &&
@@ -147,46 +197,71 @@ export function applyDiff(
             continue;
         }
 
-        // parentVal now should be an object into which we apply lastKey
+        // parentVal now should be an object or Set into which we apply lastKey
-        if (parentVal == null || typeof parentVal !== "object") {
+        if (
+            parentVal == null ||
+            (typeof parentVal !== "object" && !(parentVal instanceof Set))
+        ) {
             console.warn(
-                `[applyDiff] Skipping patch because parent is not an object: ${patch.path}`
+                `[applyDiff] Skipping patch because parent is not an object or Set: ${patch.path}`
             );
             continue;
         }
         const key = lastKey;
-        // If parent does not exist and we cannot create it, skip this patch
-        if (parentVal == null || typeof parentVal !== "object") continue;
 
-        // Handle set additions
+        // Special handling when parent is a Set
-        if (patch.op === "add" && patch.valType === "set") {
+        if (parentVal instanceof Set) {
-            const existing = parentVal[key];
+            // The key represents the @id of an object within the Set
-
+            const targetObj = findInSetById(parentVal, key);
-            // Normalize value
-            const raw = (patch as SetAddPatch).value;
-            if (raw == null) continue;
 
-            // Object-set (id -> object)
+            // Handle object creation in a Set
-            if (
+            if (patch.op === "add" && patch.valType === "object") {
-                typeof raw === "object" &&
+                if (!targetObj) {
-                !Array.isArray(raw) &&
+                    // Determine if this will be a single object or nested Set
-                !isPrimitive(raw)
+                    const hasId = patches
-            ) {
+                        .at(patchIndex + 1)
-                if (
+                        ?.path.endsWith("@id");
-                    existing &&
+                    const newObj: any = hasId ? {} : new Set();
-                    (existing instanceof Set || Array.isArray(existing))
+                    // Pre-assign the @id so subsequent patches can find this object
-                ) {
+                    if (hasId) {
-                    // Replace incompatible representation
+                        newObj["@id"] = key;
-                    parentVal[key] = {};
+                    }
+                    parentVal.add(newObj);
                 }
-                if (!parentVal[key] || typeof parentVal[key] !== "object") {
+                continue;
-                    parentVal[key] = {};
+            }
+
+            // Handle remove from Set
+            if (patch.op === "remove" && !patch.valType) {
+                if (targetObj) {
+                    parentVal.delete(targetObj);
                 }
-                Object.assign(parentVal[key], raw);
                 continue;
             }
 
-            // Set primitive(s)
+            // All other operations require the target object to exist
+            if (!targetObj) {
+                console.warn(
+                    `[applyDiff] Target object with @id=${key} not found in Set for path: ${patch.path}`
+                );
+                continue;
+            }
+
+            // This shouldn't happen - we handle all intermediate segments in the traversal loop
+            console.warn(
+                `[applyDiff] Unexpected: reached end of path with Set as parent: ${patch.path}`
+            );
+            continue;
+        }
+
+        // Regular object handling (parentVal is a plain object, not a Set)
+        // Handle primitive set additions
+        if (patch.op === "add" && patch.valType === "set") {
+            const existing = parentVal[key];
+            const raw = (patch as SetAddPatch).value;
+            if (raw == null) continue;
+
+            // Normalize to array of primitives
             const toAdd: (string | number | boolean)[] = Array.isArray(raw)
                 ? raw.filter(isPrimitive)
                 : isPrimitive(raw)
@@ -195,51 +270,48 @@ export function applyDiff(
 
             if (!toAdd.length) continue;
 
+            // Ensure we have a Set, create or add to existing
             if (existing instanceof Set) {
                 for (const v of toAdd) existing.add(v);
-            } else if (
-                existing &&
-                typeof existing === "object" &&
-                !Array.isArray(existing) &&
-                !(existing instanceof Set)
-            ) {
-                // Existing is object-set (objects); adding primitives -> replace with Set
-                parentVal[key] = new Set(toAdd);
             } else {
-                // No existing or incompatible -> create a Set
+                // Create new Set (replaces any incompatible existing value)
                 parentVal[key] = new Set(toAdd);
             }
             continue;
         }
 
-        // Handle set removals
+        // Handle primitive set removals
         if (patch.op === "remove" && patch.valType === "set") {
             const existing = parentVal[key];
             const raw = (patch as SetRemovePatch).value;
             if (raw == null) continue;
+
             const toRemove: (string | number | boolean)[] = Array.isArray(raw)
                 ? raw
                 : [raw];
 
             if (existing instanceof Set) {
                 for (const v of toRemove) existing.delete(v);
-            } else if (existing && typeof existing === "object") {
-                for (const v of toRemove) delete existing[v as any];
             }
             continue;
         }
 
-        // Add object (ensure object exists)
+        // Add object (if it does not exist yet).
+        // Distinguish between single objects and multi-object containers:
+        // - If an @id patch follows for this path, it's a single object -> create {}
+        // - If no @id patch follows, it's a container for multi-valued objects -> create set.
         if (patch.op === "add" && patch.valType === "object") {
-            const cur = parentVal[key];
+            const leafVal = parentVal[key];
-            if (
+            const hasId = patches.at(patchIndex + 1)?.path.endsWith("@id");
-                cur === undefined ||
+
-                cur === null ||
+            // If the leafVal does not exist and it should be a set, create.
-                typeof cur !== "object" ||
+            if (!hasId && !leafVal) {
-                cur instanceof Set
+                parentVal[key] = new Set();
-            ) {
+            } else if (!(typeof leafVal === "object")) {
+                // If the leave does not exist yet (as object), create it.
                 parentVal[key] = {};
             }
+
             continue;
         }
 
@@ -267,3 +339,7 @@ export function applyDiffToDeepSignal(currentState: object, diff: Patch[]) {
         applyDiff(currentState as Record<string, any>, diff);
     });
 }
+
+function decodePathSegment(segment: string): string {
+    return segment.replace("~1", "/").replace("~0", "~");
+}

sdk/js/signals/src/connector/createSignalObjectForShape.ts

@@ -1,7 +1,7 @@
 import type { Diff, Scope } from "../types.js";
 import { applyDiff } from "./applyDiff.js";
 
-import type * as NG from "@ng-org/lib-wasm";
+import * as NG from "@ng-org/lib-wasm";
 
 import { deepSignal, watch, batch } from "@ng-org/alien-deepsignals";
 import type { DeepPatch, DeepSignalObject } from "@ng-org/alien-deepsignals";
@@ -42,9 +42,19 @@ function canonicalScope(scope: Scope | undefined): string {
         : String(scope);
 }
 
+function decodePathSegment(segment: string): string {
+    return segment.replace("~1", "/").replace("~0", "~");
+}
+
+function escapePathSegment(segment: string): string {
+    return segment.replace("~", "~0").replace("/", "~1");
+}
+
 export function deepPatchesToDiff(patches: DeepPatch[]): Diff {
     return patches.map((patch) => {
-        const path = "/" + patch.path.join("/");
+        const path =
+            "/" +
+            patch.path.map((el) => escapePathSegment(el.toString())).join("/");
         return { ...patch, path };
     }) as Diff;
 }
@@ -62,7 +72,10 @@ const recurseArrayToSet = (obj: any): any => {
     }
 };
 
-const setUpConnection = (entry: PoolEntry<any>, wasmMessage: WasmMessage) => {
+const handleInitialResponse = (
+    entry: PoolEntry<any>,
+    wasmMessage: WasmMessage
+) => {
     const { connectionId, initialData } = wasmMessage;
 
     const { signalObject } = entry;
@@ -125,7 +138,7 @@ const onMessage = (event: MessageEvent<WasmMessage>) => {
     if (type === "Stop") return;
 
     if (type === "InitialResponse") {
-        setUpConnection(entry, event.data);
+        handleInitialResponse(entry, event.data);
     } else if (type === "BackendUpdate" && diff) {
         applyDiff(entry.signalObject, diff);
     } else {
@@ -133,6 +146,7 @@ const onMessage = (event: MessageEvent<WasmMessage>) => {
     }
 };
 
+// TODO: Should those be WeekMaps?
 const keyToEntry = new Map<string, PoolEntry<any>>();
 const connectionIdToEntry = new Map<string, PoolEntry<any>>();
 
@@ -150,8 +164,15 @@ const cleanupSignalRegistry =
           })
         : null;
 
+/**
+ *
+ * @param shapeType
+ * @param scope
+ * @returns
+ */
 export function createSignalObjectForShape<T extends BaseType>(
     shapeType: ShapeType<T>,
+    ng: typeof NG,
     scope?: Scope
 ) {
     const scopeKey = canonicalScope(scope);
@@ -168,11 +189,13 @@ export function createSignalObjectForShape<T extends BaseType>(
     }
 
     // Otherwise, create a new signal object and an entry for it.
-    const signalObject = deepSignal<T | {}>({});
+    const signalObject = deepSignal<T | {}>(new Set());
 
+    // Create entry to keep track of the connection with the backend.
     const entry: PoolEntry<T> = {
         key,
         // The id for future communication between wasm and js land.
+        // TODO
         connectionId: `${key}_${new Date().toISOString()}`,
         shapeType,
         scopeKey,
@@ -184,7 +207,7 @@ export function createSignalObjectForShape<T extends BaseType>(
         readyPromise: Promise.resolve(),
         resolveReady: () => {},
         // Function to manually release the connection.
-        // Only releases if no more references exist.
+        // Only releases if refCount is 0.
         release: () => {
             if (entry.refCount > 0) entry.refCount--;
             if (entry.refCount === 0) {

sdk/js/signals/src/connector/ormConnectionHandler.ts

@@ -0,0 +1,217 @@
+import type { Diff as Patches, Scope } from "../types.ts";
+import { applyDiff } from "./applyDiff.ts";
+
+import * as NG from "@ng-org/lib-wasm";
+
+import {
+    deepSignal,
+    watch as watchDeepSignal,
+    batch,
+} from "@ng-org/alien-deepsignals";
+import type {
+    DeepPatch,
+    DeepSignalObject,
+    WatchPatchCallback,
+    WatchPatchEvent,
+} from "@ng-org/alien-deepsignals";
+import type { ShapeType, BaseType } from "@ng-org/shex-orm";
+
+export class OrmConnection<T extends BaseType> {
+    // TODO: WeakMaps?
+    private static idToEntry = new Map<string, OrmConnection<any>>();
+
+    private ng: typeof NG;
+    readonly shapeType: ShapeType<T>;
+    readonly scope: Scope;
+    readonly signalObject: DeepSignalObject<T | {}>;
+    private refCount: number;
+    /*** Identifier as a combination of shape type and scope. Prevents duplications. */
+    private identifier: string;
+    ready: boolean;
+    sessionId: number;
+    suspendDeepWatcher: boolean;
+    readyPromise: Promise<void>;
+    // Promise that resolves once initial data has been applied.
+    resolveReady!: () => void;
+
+    // FinalizationRegistry to clean up connections when signal objects are GC'd.
+    private static cleanupSignalRegistry =
+        typeof FinalizationRegistry === "function"
+            ? new FinalizationRegistry<string>((connectionId) => {
+                  // Best-effort fallback; look up by id and clean
+                  const entry = this.idToEntry.get(connectionId);
+                  if (!entry) return;
+                  entry.release();
+              })
+            : null;
+
+    private constructor(shapeType: ShapeType<T>, scope: Scope, ng: typeof NG) {
+        this.shapeType = shapeType;
+        this.scope = scope;
+        this.ng = ng;
+        this.refCount = 0;
+        this.ready = false;
+        this.suspendDeepWatcher = false;
+        this.identifier = `${shapeType.shape}::${canonicalScope(scope)}`;
+        this.signalObject = deepSignal<T | {}>(new Set(), {
+            addIdToObjects: true,
+            idGenerator: this.generateSubjectIri,
+        });
+
+        // TODO:
+        this.sessionId = 1;
+
+        // Schedule cleanup of the connection when the signal object is GC'd.
+        OrmConnection.cleanupSignalRegistry?.register(
+            this.signalObject,
+            this.identifier,
+            this.signalObject
+        );
+
+        // Add listener to deep signal object to report changes back to wasm land.
+        watchDeepSignal(this.signalObject as T, this.onSignalObjectUpdate);
+
+        // Initialize per-entry readiness promise that resolves in setUpConnection
+        this.readyPromise = new Promise<void>((resolve) => {
+            this.resolveReady = resolve;
+        });
+
+        // Establish connection to wasm land.
+        ng.orm_start(scope, shapeType, this.sessionId, this.onBackendMessage);
+    }
+
+    /**
+     * Get a connection which contains the ORM and lifecycle methods.
+     * @param shapeType
+     * @param scope
+     * @param ng
+     * @returns
+     */
+    public static getConnection<T extends BaseType>(
+        shapeType: ShapeType<T>,
+        scope: Scope,
+        ng: typeof NG
+    ): OrmConnection<T> {
+        const scopeKey = canonicalScope(scope);
+
+        // Unique identifier for a given shape type and scope.
+        const identifier = `${shapeType.shape}::${scopeKey}`;
+
+        // If we already have an object for this shape+scope,
+        // return it and just increase the reference count.
+        // Otherwise, create new one.
+        const connection =
+            OrmConnection.idToEntry.get(identifier) ??
+            new OrmConnection(shapeType, scope, ng);
+
+        connection.refCount += 1;
+
+        return connection;
+    }
+
+    public release() {
+        if (this.refCount > 0) this.refCount--;
+        if (this.refCount === 0) {
+            OrmConnection.idToEntry.delete(this.identifier);
+
+            OrmConnection.cleanupSignalRegistry?.unregister(this.signalObject);
+        }
+    }
+
+    private onSignalObjectUpdate({ patches }: WatchPatchEvent<T>) {
+        if (this.suspendDeepWatcher || !this.ready || !patches.length) return;
+
+        const ormPatches = deepPatchesToDiff(patches);
+
+        this.ng.orm_update(
+            this.scope,
+            this.shapeType.shape,
+            ormPatches,
+            this.sessionId
+        );
+    }
+
+    private onBackendMessage(...message: any) {
+        this.handleInitialResponse(message);
+    }
+
+    private handleInitialResponse(...param: any) {
+        console.log("RESPONSE FROM BACKEND", param);
+
+        // TODO: This will break, just provisionary.
+        const wasmMessage: WasmMessage = param;
+        const { initialData } = wasmMessage;
+
+        // Assign initial data to empty signal object without triggering watcher at first.
+        this.suspendDeepWatcher = true;
+        batch(() => {
+            // Convert arrays to sets and apply to signalObject (we only have sets but can only transport arrays).
+            Object.assign(this.signalObject, recurseArrayToSet(initialData)!);
+        });
+
+        queueMicrotask(() => {
+            this.suspendDeepWatcher = false;
+            // Resolve readiness after initial data is committed and watcher armed.
+            this.resolveReady?.();
+        });
+
+        this.ready = true;
+    }
+    private onBackendUpdate(...params: any) {
+        // Apply diff
+    }
+
+    /** Function to create random subject IRIs for newly created nested objects. */
+    private generateSubjectIri(path: (string | number)[]): string {
+        // Generate random string.
+        let b = Buffer.alloc(33);
+        crypto.getRandomValues(b);
+        const randomString = b.toString("base64url");
+
+        if (path.length > 0 && path[0].toString().startsWith("did:ng:o:")) {
+            // If the root is a nuri, use that as a base IRI.
+            let rootNuri = path[0] as string;
+
+            return rootNuri.substring(0, 9 + 44) + ":q:" + randomString;
+        } else {
+            // Else, just generate a random IRI.
+            return "did:ng:q:" + randomString;
+        }
+    }
+}
+
+//
+//
+
+function escapePathSegment(segment: string): string {
+    return segment.replace("~", "~0").replace("/", "~1");
+}
+
+export function deepPatchesToDiff(patches: DeepPatch[]): Patches {
+    return patches.map((patch) => {
+        const path =
+            "/" +
+            patch.path.map((el) => escapePathSegment(el.toString())).join("/");
+        return { ...patch, path };
+    }) as Patches;
+}
+
+const recurseArrayToSet = (obj: any): any => {
+    if (Array.isArray(obj)) {
+        return new Set(obj.map(recurseArrayToSet));
+    } else if (obj && typeof obj === "object") {
+        for (const key of Object.keys(obj)) {
+            obj[key] = recurseArrayToSet(obj[key]);
+        }
+        return obj;
+    } else {
+        return obj;
+    }
+};
+
+function canonicalScope(scope: Scope | undefined): string {
+    if (scope == null) return "";
+    return Array.isArray(scope)
+        ? scope.slice().sort().join(",")
+        : String(scope);
+}