NextGraph
/
nextgraph-rs
1
6
Fork 2
Code Issues 4 Pull Requests 1 Packages Projects 2 Releases 3 Activity

Merge remote-tracking branch 'origin/feat/orm-diffs' into refactor

Browse Source
refactor
Niko PLP 1 day ago
parent d23759bb1c e979f0233a
commit e9a3b2fe88
20 changed files with 2922 additions and 1492 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 189
      sdk/js/alien-deepsignals/README.md
  2. 1429
      sdk/js/alien-deepsignals/src/deepSignal.ts
  3. 340
      sdk/js/alien-deepsignals/src/test/deepSignalOptions.test.ts
  4. 62
      sdk/js/alien-deepsignals/src/test/patchOptimized.test.ts
  5. 234
      sdk/js/alien-deepsignals/src/test/tier3.test.ts
  6. 154
      sdk/js/alien-deepsignals/src/test/watch.test.ts
  7. 836
      sdk/js/alien-deepsignals/src/test/watchPatches.test.ts
  8. 268
      sdk/js/alien-deepsignals/src/watch.ts
  9. 2
      sdk/js/examples/multi-framework-signals/src/shapes/orm/catShape.schema.ts
  10. 6
      sdk/js/examples/multi-framework-signals/src/shapes/orm/catShape.typings.ts
  11. 2
      sdk/js/examples/multi-framework-signals/src/shapes/orm/personShape.schema.ts
  12. 6
      sdk/js/examples/multi-framework-signals/src/shapes/orm/personShape.typings.ts
  13. 2
      sdk/js/examples/multi-framework-signals/src/shapes/orm/testShape.schema.ts
  14. 8
      sdk/js/examples/multi-framework-signals/src/shapes/orm/testShape.typings.ts
  15. 18
      sdk/js/shex-orm/src/schema-converter/transformers/ShexJTypingTransformer.ts
  16. 2
      sdk/js/shex-orm/src/types.ts
  17. 360
      sdk/js/signals/src/connector/applyDiff.test.ts
  18. 244
      sdk/js/signals/src/connector/applyDiff.ts
  19. 35
      sdk/js/signals/src/connector/createSignalObjectForShape.ts
  20. 217
      sdk/js/signals/src/connector/ormConnectionHandler.ts

189
sdk/js/alien-deepsignals/README.md
Unescape View File

@ -13,7 +13,8 @@ Core idea: wrap a data tree in a `Proxy` that lazily creates per-property signal
- Patch stream: microtask‑batched granular mutations (paths + op) for syncing external stores / framework adapters. - Patch stream: microtask‑batched granular mutations (paths + op) for syncing external stores / framework adapters.
- Getter => computed: property getters become derived (readonly) signals automatically. - Getter => computed: property getters become derived (readonly) signals automatically.
- `$` accessors: TypeScript exposes `$prop` for each non‑function key plus `$` / `$length` for arrays. - `$` accessors: TypeScript exposes `$prop` for each non‑function key plus `$` / `$length` for arrays.
- Sets: structural `add/delete/clear` emit patches; object entries get synthetic stable ids (prefers `id` / `@id` fields or auto‑generated blank IDs). - Sets: structural `add/delete/clear` emit patches; object entries get synthetic stable ids via `@id` property.
- `@id` property system: configurable automatic ID assignment to objects with custom generators.
- Shallow escape hatch: wrap sub-objects with `shallow(obj)` to track only reference replacement. - Shallow escape hatch: wrap sub-objects with `shallow(obj)` to track only reference replacement.
## Install ## Install
@ -46,6 +47,68 @@ state.$count!.set(5); // update via signal
console.log(state.$count!()); // read via signal function console.log(state.$count!()); // read via signal function
``` ```
## Configuration options
`deepSignal(obj, options?)` accepts an optional configuration object:
```ts
type DeepSignalOptions = {
idGenerator?: (pathToObject: (string | number)[]) => string | number; // Custom ID generator function
addIdToObjects?: boolean; // Automatically add @id to plain objects
};
```
### Custom ID generation
Provide a custom function to generate synthetic IDs instead of auto-generated blank node IDs:
```ts
let counter = 0;
const state = deepSignal(
{ items: new Set() },
{
idGenerator: () => `urn:item:${++counter}`,
addIdToObjects: true
}
);
state.items.add({ name: "Item 1" }); // Gets @id: "urn:item:1"
state.items.add({ name: "Item 2" }); // Gets @id: "urn:item:2"
```
### The `@id` property
When `addIdToObjects: true`, plain objects automatically receive a readonly, enumerable `@id` property:
```ts
const state = deepSignal(
{ data: {} },
{
idGenerator: (_path) => `urn:uuid:${crypto.randomUUID()}`,
addIdToObjects: true
}
);
state.data.user = { name: "Ada" };
console.log(state.data.user["@id"]); // e.g., "urn:uuid:550e8400-e29b-41d4-a716-446655440000"
// @id is readonly
state.data.user["@id"] = "new-id"; // TypeError in strict mode
// @id assignment emits a patch
watch(state, ({ patches }) => {
// patches includes: { op: "add", path: ["data", "user", "@id"], value: "..." }
});
```
**Key behaviors:**
- `@id` is assigned **before** the object is proxied, ensuring it's available immediately
- `@id` properties are **readonly** and **enumerable**
- Assigning `@id` emits a patch just like any other property
- Objects with existing `@id` properties keep their values (not overwritten)
- Options propagate to nested objects created after initialization
## Watching patches ## Watching patches
`watch(root, cb, options?)` observes a deepSignal root and invokes your callback with microtask‑batched mutation patches plus snapshots. `watch(root, cb, options?)` observes a deepSignal root and invokes your callback with microtask‑batched mutation patches plus snapshots.
@ -113,23 +176,103 @@ Notes:
## Sets & synthetic ids ## Sets & synthetic ids
Object entries inside Sets need a stable key. Priority: Object entries inside Sets need a stable key for patch paths. The synthetic ID resolution follows this priority:
1. `entry.id` 1. Explicit custom ID via `setSetEntrySyntheticId(entry, 'myId')` (before `add`)
2. `entry['@id']` 2. Existing `entry['@id']` property
3. Custom via `setSetEntrySyntheticId(entry, 'myId')` before `add` 3. Auto-generated blank node ID (`_bN` format)
4. Auto `_bN` blank id
Helpers: ### Working with Sets
```ts ```ts
import { addWithId, setSetEntrySyntheticId } from "alien-deepsignals"; import { addWithId, setSetEntrySyntheticId } from "@ng-org/alien-deepsignals";
// Option 1: Use @id from configuration
const state = deepSignal(
{ items: new Set() },
{
idGenerator: (_path) => `urn:uuid:${crypto.randomUUID()}`,
addIdToObjects: true
}
);
const item = { name: "Item 1" };
state.items.add(item); // Automatically gets @id before being added
console.log(item["@id"]); // e.g., "urn:uuid:550e8400-..."
// Option 2: Manually set synthetic ID
const obj = { value: 42 };
setSetEntrySyntheticId(obj, "urn:custom:my-id");
state.items.add(obj);
// Option 3: Use convenience helper
addWithId(state.items as any, { value: 99 }, "urn:item:special");
// Option 4: Pre-assign @id property
const preTagged = { "@id": "urn:explicit:123", data: "..." };
state.items.add(preTagged); // Uses "urn:explicit:123" as synthetic ID
```
### Set entry patches and paths
When objects are added to Sets, their **synthetic ID becomes part of the patch path**. This allows patches to uniquely identify which Set entry is being mutated.
```ts
const state = deepSignal(
{ s: new Set() },
{
idGenerator: () => "urn:entry:set-entry-1",
addIdToObjects: true
}
);
watch(state, ({ patches }) => {
console.log(JSON.stringify(patches));
// [
// {"path":["s","urn:entry:set-entry-1"],"op":"add","type":"object"},
// {"path":["s","urn:entry:set-entry-1","@id"],"op":"add","value":"urn:entry:set-entry-1"},
// {"path":["s","urn:entry:set-entry-1","data"],"op":"add","value":"test"}
// ]
});
setSetEntrySyntheticId(obj, "custom"); state.s.add({ data: "test" });
state.settings.add(obj);
addWithId(state.settings as any, { x: 1 }, "x1");
``` ```
**Path structure explained:**
- `["s", "urn:entry:set-entry-1"]` - The structural Set patch; the IRI identifies the entry
- `["s", "urn:entry:set-entry-1", "@id"]` - Patch for the @id property assignment
- `["s", "urn:entry:set-entry-1", "data"]` - Nested property patch; the IRI identifies which Set entry
- The synthetic ID (the IRI) is stable across mutations, allowing tracking of the same object
**Mutating nested properties:**
```ts
const state = deepSignal(
{ users: new Set() },
{
idGenerator: (path) => `urn:user:${path.join("-")}:${crypto.randomUUID()}`,
addIdToObjects: true
}
);
const user = { name: "Ada", age: 30 };
state.users.add(user); // Gets @id, e.g., "urn:user:550e8400-..."
watch(state, ({ patches }) => {
console.log(JSON.stringify(patches));
// [{"path":["users","urn:user:550e8400-...","age"],"op":"add","value":31}]
});
// Later mutation: synthetic ID identifies which Set entry changed
user.age = 31;
```
The path `["users", "urn:user:550e8400-...", "age"]` shows:
1. `users` - the Set container
2. `urn:user:550e8400-...` - the IRI identifying which object in the Set
3. `age` - the property being mutated
This structure enables precise tracking of nested changes within Set entries, critical for syncing state changes or implementing undo/redo.
## Shallow ## Shallow
Skip deep proxying of a subtree (only reference replacement tracked): Skip deep proxying of a subtree (only reference replacement tracked):
@ -152,18 +295,18 @@ const n: number = state.$count!(); // typed number
## API surface ## API surface
| Function | Description | | Function | Description |
| ---------------------------------- | --------------------------------------- | | ---------------------------------- | ------------------------------------------------- |
| `deepSignal(obj)` | Create (or reuse) reactive deep proxy. | | `deepSignal(obj, options?)` | Create (or reuse) reactive deep proxy with optional configuration. |
| `watch(root, cb, opts?)` | Observe batched deep mutations. | | `watch(root, cb, opts?)` | Observe batched deep mutations. |
| `observe(root, cb, opts?)` | Alias of `watch`. | | `observe(root, cb, opts?)` | Alias of `watch`. |
| `peek(obj,key)` | Untracked property read. | | `peek(obj,key)` | Untracked property read. |
| `shallow(obj)` | Mark object to skip deep proxying. | | `shallow(obj)` | Mark object to skip deep proxying. |
| `isDeepSignal(val)` | Runtime predicate. | | `isDeepSignal(val)` | Runtime predicate. |
| `isShallow(val)` | Was value marked shallow. | | `isShallow(val)` | Was value marked shallow. |
| `setSetEntrySyntheticId(obj,id)` | Assign custom Set entry id. | | `setSetEntrySyntheticId(obj,id)` | Assign custom Set entry id (highest priority). |
| `addWithId(set, entry, id)` | Insert with desired synthetic id. | | `addWithId(set, entry, id)` | Insert with desired synthetic id (convenience). |
| `subscribeDeepMutations(root, cb)` | Low-level patch stream (used by watch). | | `subscribeDeepMutations(root, cb)` | Low-level patch stream (used by watch). |
## Credits ## Credits

1429
sdk/js/alien-deepsignals/src/deepSignal.ts
View File

File diff suppressed because it is too large Load Diff

340
sdk/js/alien-deepsignals/src/test/deepSignalOptions.test.ts
Unescape View File

@ -0,0 +1,340 @@
import { describe, it, expect } from "vitest";
import { deepSignal, DeepPatch, DeepSignalOptions } from "../deepSignal";
import { watch } from "../watch";
describe("deepSignal options", () => {
describe("custom ID generator", () => {
it("uses custom ID generator for objects without @id", async () => {
let counter = 1000;
const options: DeepSignalOptions = {
idGenerator: () => `custom-${counter++}`,
addIdToObjects: true,
};
const state = deepSignal({ data: {} as any }, options);
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches: batch }) =>
patches.push(batch)
);
state.data.user = { name: "Alice" };
await Promise.resolve();
// Check that @id was assigned
expect((state.data.user as any)["@id"]).toBe("custom-1000");
// Check that patch was emitted for @id
const flat = patches.flat().map((p) => p.path.join("."));
expect(flat).toContain("data.user.@id");
stop();
});
it("respects existing @id on objects", async () => {
const options: DeepSignalOptions = {
idGenerator: () => "should-not-be-used",
addIdToObjects: true,
};
const state = deepSignal({ items: [] as any[] }, options);
state.items.push({ "@id": "existing-123", value: 42 });
// Should use the existing @id
expect((state.items[0] as any)["@id"]).toBe("existing-123");
});
it("uses @id property from objects added to Sets", async () => {
const options: DeepSignalOptions = {
idGenerator: () => "fallback-id",
addIdToObjects: true,
};
const state = deepSignal({ s: new Set<any>() }, options);
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches: batch }) =>
patches.push(batch)
);
const obj = { "@id": "set-entry-1", data: "test" };
state.s.add(obj);
await Promise.resolve();
const flat = patches.flat().map((p) => p.path.join("."));
// Path should use the @id as synthetic key
expect(flat.some((p) => p.startsWith("s.set-entry-1"))).toBe(true);
stop();
});
});
describe("addIdToObjects option", () => {
it("adds @id to all nested objects when enabled", async () => {
const options: DeepSignalOptions = {
addIdToObjects: true,
};
const state = deepSignal({ root: {} as any }, options);
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches: batch }) =>
patches.push(batch)
);
state.root.level1 = {
level2: {
level3: { value: "deep" },
},
};
await Promise.resolve();
// Check all levels have @id
expect((state.root.level1 as any)["@id"]).toBeDefined();
expect((state.root.level1.level2 as any)["@id"]).toBeDefined();
expect(
(state.root.level1.level2.level3 as any)["@id"]
).toBeDefined();
// Check patches were emitted for all @id fields
const flat = patches.flat().map((p) => p.path.join("."));
expect(flat).toContain("root.level1.@id");
expect(flat).toContain("root.level1.level2.@id");
expect(flat).toContain("root.level1.level2.level3.@id");
stop();
});
it("does not add @id when option is false", () => {
const state = deepSignal({ data: { nested: {} } });
// Should not have @id
expect("@id" in (state.data as any)).toBe(false);
expect("@id" in (state.data.nested as any)).toBe(false);
});
it("adds @id to objects in arrays", async () => {
const options: DeepSignalOptions = {
addIdToObjects: true,
};
const state = deepSignal({ items: [] as any[] }, options);
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches: batch }) =>
patches.push(batch)
);
state.items.push({ name: "Item 1" }, { name: "Item 2" });
await Promise.resolve();
// Both items should have @id
expect((state.items[0] as any)["@id"]).toBeDefined();
expect((state.items[1] as any)["@id"]).toBeDefined();
// Check patches
const flat = patches.flat().map((p) => p.path.join("."));
expect(flat).toContain("items.0.@id");
expect(flat).toContain("items.1.@id");
stop();
});
it("adds @id to objects in Sets", async () => {
const options: DeepSignalOptions = {
idGenerator: () =>
`gen-${Math.random().toString(36).substr(2, 9)}`,
addIdToObjects: true,
};
const state = deepSignal({ s: new Set<any>() }, options);
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches: batch }) =>
patches.push(batch)
);
const obj1 = { value: 1 };
const obj2 = { value: 2 };
state.s.add(obj1);
state.s.add(obj2);
await Promise.resolve();
// Get proxied objects from Set
const proxiedObjs = Array.from(state.s);
expect((proxiedObjs[0] as any)["@id"]).toBeDefined();
expect((proxiedObjs[1] as any)["@id"]).toBeDefined();
// @id should be used as synthetic key in paths
const flat = patches.flat().map((p) => p.path.join("."));
const obj1Id = (proxiedObjs[0] as any)["@id"];
const obj2Id = (proxiedObjs[1] as any)["@id"];
expect(flat.some((p) => p.startsWith(`s.${obj1Id}`))).toBe(true);
expect(flat.some((p) => p.startsWith(`s.${obj2Id}`))).toBe(true);
stop();
});
});
describe("@id property behavior", () => {
it("makes @id readonly", () => {
const options: DeepSignalOptions = {
addIdToObjects: true,
};
const state = deepSignal({ obj: {} as any }, options);
state.obj.data = { value: 1 };
// Attempting to modify @id should throw
expect(() => {
(state.obj.data as any)["@id"] = "new-id";
}).toThrow("Cannot modify readonly property '@id'");
});
it("makes @id enumerable", () => {
const options: DeepSignalOptions = {
addIdToObjects: true,
};
const state = deepSignal({ obj: {} as any }, options);
state.obj.data = { value: 1 };
// @id should show up in Object.keys()
const keys = Object.keys(state.obj.data);
expect(keys).toContain("@id");
});
it("emits patches for @id even on objects with existing @id", async () => {
const options: DeepSignalOptions = {
addIdToObjects: true,
};
const state = deepSignal({ container: {} as any }, options);
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches: batch }) =>
patches.push(batch)
);
// Object already has @id before being added
const objWithId = { "@id": "pre-existing", data: "test" };
state.container.item = objWithId;
await Promise.resolve();
const flat = patches.flat().map((p) => p.path.join("."));
// Patch should still be emitted for @id
expect(flat).toContain("container.item.@id");
// Verify the value in the patch
const idPatch = patches
.flat()
.find((p) => p.path.join(".") === "container.item.@id");
expect((idPatch as any).value).toBe("pre-existing");
stop();
});
});
describe("options inheritance", () => {
it("child objects inherit options from root", async () => {
let idCounter = 5000;
const options: DeepSignalOptions = {
idGenerator: () => `inherited-${idCounter++}`,
addIdToObjects: true,
};
const state = deepSignal({ root: {} as any }, options);
// Add nested structure
state.root.child = {
grandchild: {
value: "nested",
},
};
// All should have IDs generated by the custom generator
expect((state.root.child as any)["@id"]).toMatch(/^inherited-/);
expect((state.root.child.grandchild as any)["@id"]).toMatch(
/^inherited-/
);
});
it("objects added to Sets inherit options", async () => {
let counter = 9000;
const options: DeepSignalOptions = {
idGenerator: () => `set-child-${counter++}`,
addIdToObjects: true,
};
const state = deepSignal({ s: new Set<any>() }, options);
const obj = { nested: { value: 1 } };
state.s.add(obj);
// Iterate to get proxied object
const proxied = Array.from(state.s)[0];
// Object and nested object should have custom IDs
expect((proxied as any)["@id"]).toMatch(/^set-child-/);
expect((proxied.nested as any)["@id"]).toMatch(/^set-child-/);
});
});
describe("backward compatibility", () => {
it("still works without options", async () => {
const state = deepSignal({ data: { value: 1 } });
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches: batch }) =>
patches.push(batch)
);
state.data.value = 2;
await Promise.resolve();
expect(patches.flat().length).toBeGreaterThan(0);
stop();
});
// TODO: Delete duplicate logic for `id`. Only accept @id.
it("objects with id property still work for Sets", async () => {
const state = deepSignal({ s: new Set<any>() });
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches: batch }) =>
patches.push(batch)
);
state.s.add({ id: "legacy-id", value: 1 });
await Promise.resolve();
const flat = patches.flat().map((p) => p.path.join("."));
// Should use id as synthetic key
expect(flat.some((p) => p.startsWith("s.legacy-id"))).toBe(true);
stop();
});
it("@id takes precedence over id property", async () => {
const state = deepSignal({ s: new Set<any>() });
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches: batch }) =>
patches.push(batch)
);
state.s.add({
id: "should-not-use",
"@id": "should-use",
value: 1,
});
await Promise.resolve();
const flat = patches.flat().map((p) => p.path.join("."));
// Should use @id, not id
expect(flat.some((p) => p.startsWith("s.should-use"))).toBe(true);
expect(flat.some((p) => p.startsWith("s.should-not-use"))).toBe(
false
);
stop();
});
});
});

62
sdk/js/alien-deepsignals/src/test/patchOptimized.test.ts
Unescape View File

@ -8,40 +8,40 @@ import { watch } from "../watch";
// times traverse() executes under each strategy. // times traverse() executes under each strategy.
describe("watch patch-only simplified performance placeholder", () => { 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();
});
}); });

234
sdk/js/alien-deepsignals/src/test/tier3.test.ts
Unescape View File

@ -1,148 +1,148 @@
import { describe, it, expect } from "vitest"; import { describe, it, expect } from "vitest";
import { deepSignal, getDeepSignalRootId, peek } from "../deepSignal"; import { deepSignal, getDeepSignalRootId, peek } from "../deepSignal";
import { import {
watch, watch,
__traverseCount, __traverseCount,
__resetTraverseCount, __resetTraverseCount,
traverse, traverse,
} from "../watch"; } from "../watch";
import { effect } from "../core"; import { effect } from "../core";
describe("watch advanced", () => { 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", () => { 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", () => { 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", () => { 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)", () => { 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);
}); });
}); });

154
sdk/js/alien-deepsignals/src/test/watch.test.ts
Unescape View File

@ -4,88 +4,88 @@ import { watch } from "../watch";
import { watchEffect } from "../watchEffect"; import { watchEffect } from "../watchEffect";
describe("watch", () => { 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");
});
}); });

836
sdk/js/alien-deepsignals/src/test/watchPatches.test.ts
Unescape View File

@ -1,357 +1,531 @@
import { describe, it, expect } from "vitest"; import { describe, it, expect } from "vitest";
import { import {
deepSignal, deepSignal,
setSetEntrySyntheticId, setSetEntrySyntheticId,
addWithId, addWithId,
DeepPatch, DeepPatch,
} from "../deepSignal"; } from "../deepSignal";
import { watch, observe } from "../watch"; import { watch, observe } from "../watch";
describe("watch (patch mode)", () => { describe("watch (patch mode)", () => {
it("emits set patches with correct paths and batching", async () => { it("emits set patches with correct paths and batching", async () => {
const state = deepSignal({ a: { b: 1 }, arr: [1, { x: 2 }] }); const state = deepSignal({ a: { b: 1 }, arr: [1, { x: 2 }] });
const received: DeepPatch[][] = []; const received: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches }) => { const { stopListening: stop } = watch(state, ({ patches }) => {
received.push(patches); received.push(patches);
});
state.a.b = 2;
(state.arr[1] as any).x = 3;
state.arr.push(5);
await Promise.resolve();
expect(received.length).toBe(1);
const batch = received[0];
const paths = batch.map((p) => p.path.join(".")).sort();
expect(paths).toContain("a.b");
expect(paths).toContain("arr.1.x");
expect(paths).toContain("arr.2");
const addOps = batch.filter((p) => p.op === "add").length;
expect(addOps).toBe(batch.length);
stop();
}); });
state.a.b = 2;
(state.arr[1] as any).x = 3;
state.arr.push(5);
await Promise.resolve();
expect(received.length).toBe(1);
const batch = received[0];
const paths = batch.map((p) => p.path.join(".")).sort();
expect(paths).toContain("a.b");
expect(paths).toContain("arr.1.x");
expect(paths).toContain("arr.2");
const addOps = batch.filter((p) => p.op === "add").length;
expect(addOps).toBe(batch.length);
stop();
});
it("emits delete patches without value", async () => { it("emits delete patches without value", async () => {
const state = deepSignal<{ a: { b?: number }; c?: number }>({ const state = deepSignal<{ a: { b?: number }; c?: number }>({
a: { b: 1 }, a: { b: 1 },
c: 2, c: 2,
});
const out: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches }) =>
out.push(patches)
);
delete state.a.b;
delete state.c;
await Promise.resolve();
expect(out.length).toBe(1);
const [batch] = out;
const deletePatches = batch.filter((p) => p.op === "remove");
const delPaths = deletePatches.map((p) => p.path.join(".")).sort();
expect(delPaths).toEqual(["a.b", "c"]);
deletePatches.forEach((p: any) => expect(p.value).toBeUndefined());
stop();
}); });
const out: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches }) =>
out.push(patches)
);
delete state.a.b;
delete state.c;
await Promise.resolve();
expect(out.length).toBe(1);
const [batch] = out;
const deletePatches = batch.filter((p) => p.op === "remove");
const delPaths = deletePatches.map((p) => p.path.join(".")).sort();
expect(delPaths).toEqual(["a.b", "c"]);
deletePatches.forEach((p: any) => expect(p.value).toBeUndefined());
stop();
});
it("observe patch mode mirrors watch patch mode", async () => { it("observe patch mode mirrors watch patch mode", async () => {
const state = deepSignal({ a: 1 }); const state = deepSignal({ a: 1 });
const wp: DeepPatch[][] = []; const wp: DeepPatch[][] = [];
const ob: DeepPatch[][] = []; const ob: DeepPatch[][] = [];
const { stopListening: stop1 } = watch(state, ({ patches }) => const { stopListening: stop1 } = watch(state, ({ patches }) =>
wp.push(patches) wp.push(patches)
); );
const { stopListening: stop2 } = observe(state, ({ patches }) => const { stopListening: stop2 } = observe(state, ({ patches }) =>
ob.push(patches) ob.push(patches)
); );
state.a = 2; state.a = 2;
await Promise.resolve(); await Promise.resolve();
expect(wp.length).toBe(1); expect(wp.length).toBe(1);
expect(ob.length).toBe(1); expect(ob.length).toBe(1);
expect(wp[0][0].path.join(".")).toBe("a"); expect(wp[0][0].path.join(".")).toBe("a");
stop1(); stop1();
stop2(); stop2();
}); });
it("filters out patches from other roots", async () => { it("filters out patches from other roots", async () => {
const a = deepSignal({ x: 1 }); const a = deepSignal({ x: 1 });
const b = deepSignal({ y: 2 }); const b = deepSignal({ y: 2 });
const out: DeepPatch[][] = []; const out: DeepPatch[][] = [];
const { stopListening: stop } = watch(a, ({ patches }) => const { stopListening: stop } = watch(a, ({ patches }) =>
out.push(patches) out.push(patches)
); );
b.y = 3; b.y = 3;
a.x = 2; a.x = 2;
await Promise.resolve(); await Promise.resolve();
expect(out.length).toBe(1); expect(out.length).toBe(1);
expect(out[0][0].path.join(".")).toBe("x"); expect(out[0][0].path.join(".")).toBe("x");
stop(); stop();
}); });
it("emits patches for Set structural mutations (add/delete)", async () => { it("emits patches for Set structural mutations (add/delete)", async () => {
const state = deepSignal<{ s: Set<number> }>({ s: new Set([1, 2]) }); const state = deepSignal<{ s: Set<number> }>({ s: new Set([1, 2]) });
const batches: DeepPatch[][] = []; const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches }) => const { stopListening: stop } = watch(state, ({ patches }) =>
batches.push(patches) batches.push(patches)
); );
state.s.add(3); state.s.add(3);
state.s.delete(1); state.s.delete(1);
await Promise.resolve(); await Promise.resolve();
expect(batches.length >= 1).toBe(true); expect(batches.length >= 1).toBe(true);
const allPaths = batches.flatMap((b) => b.map((p) => p.path.join("."))); const allPaths = batches.flatMap((b) => b.map((p) => p.path.join(".")));
expect(allPaths.some((p) => p.startsWith("s."))).toBe(true); // For primitives, the path should be just "s" (the Set itself)
stop(); expect(allPaths.every((p) => p === "s")).toBe(true);
}); // Check the values
const patches = batches.flat();
const addPatches = patches.filter((p) => p.op === "add");
const deletePatches = patches.filter((p) => p.op === "remove");
expect(addPatches.length).toBe(1);
expect(deletePatches.length).toBe(1);
expect((addPatches[0] as any).value[0]).toBe(3);
expect((deletePatches[0] as any).value).toBe(1);
stop();
});
it("emits patches for nested objects added after initialization", async () => { it("emits patches for nested objects added after initialization", async () => {
const state = deepSignal<{ root: any }>({ root: {} }); const state = deepSignal<{ root: any }>({ root: {} });
const patches: DeepPatch[][] = []; const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(state, ({ patches: batch }) => const { stopListening: stop } = watch(state, ({ patches: batch }) =>
patches.push(batch) patches.push(batch)
); );
state.root.child = { level: { value: 1 } }; state.root.child = { level: { value: 1 }, l1: "val" };
state.root.child.level.value = 2; await Promise.resolve();
await Promise.resolve(); const flat = patches.flat().map((p) => p.path.join("."));
const flat = patches.flat().map((p) => p.path.join(".")); expect(flat).toContain("root.child");
expect(flat).toContain("root.child"); expect(flat).toContain("root.child.level.value");
expect(flat).toContain("root.child.level.value"); stop();
stop(); });
});
it("emits structural patches for sets of sets", async () => { it("emits patches for deeply nested arrays and objects", async () => {
const innerA = new Set<any>([{ id: "node1", x: 1 }]); const state = deepSignal<{ data: any }>({ data: null });
const s = new Set<any>([innerA]); const patches: DeepPatch[][] = [];
const state = deepSignal<{ graph: Set<any> }>({ graph: s }); const { stopListening: stop } = watch(state, ({ patches: batch }) =>
const batches: DeepPatch[][] = []; patches.push(batch)
const { stopListening: stop } = watch(state, ({ patches }) => );
batches.push(patches) state.data = {
); users: [
const innerB = new Set<any>([{ id: "node2", x: 5 }]); {
state.graph.add(innerB); id: 1,
([...innerA][0] as any).x = 2; profile: { name: "Alice", settings: { theme: "dark" } },
await Promise.resolve(); },
const pathStrings = batches.flat().map((p) => p.path.join(".")); {
expect(pathStrings.some((p) => p.startsWith("graph."))).toBe(true); id: 2,
stop(); profile: { name: "Bob", settings: { theme: "light" } },
}); },
],
meta: { count: 2, active: true },
};
await Promise.resolve();
it("tracks deep nested object mutation inside a Set entry after iteration", async () => { const flat = patches.flat().map((p) => p.path.join("."));
const rawEntry = { id: "n1", data: { val: 1 } }; // Check for root object
const st = deepSignal({ bag: new Set<any>([rawEntry]) }); expect(flat).toContain("data");
const collected: DeepPatch[][] = []; // Check for nested array
const { stopListening: stop } = watch(st, ({ patches }) => expect(flat).toContain("data.users");
collected.push(patches) // Check for array elements
); expect(flat).toContain("data.users.0");
let proxied: any; expect(flat).toContain("data.users.1");
for (const e of st.bag.values()) { // Check for deeply nested properties
proxied = e; expect(flat).toContain("data.users.0.profile.settings.theme");
e.data.val; expect(flat).toContain("data.users.1.profile.settings.theme");
} expect(flat).toContain("data.meta.count");
proxied.data.val = 2; expect(flat).toContain("data.meta.active");
await Promise.resolve(); stop();
const flat = collected.flat().map((p: DeepPatch) => p.path.join(".")); });
expect(flat.some((p: string) => p.endsWith("n1.data.val"))).toBe(true);
stop();
});
it("allows custom synthetic id for Set entry", async () => { it("emits patches for Set with nested objects added as one operation", async () => {
const node = { name: "x" }; const state = deepSignal<{ container: any }>({ container: {} });
const state = deepSignal({ s: new Set<any>() }); const patches: DeepPatch[][] = [];
const collected2: DeepPatch[][] = []; const { stopListening: stop } = watch(state, ({ patches: batch }) =>
const { stopListening: stop } = watch(state, ({ patches }) => patches.push(batch)
collected2.push(patches) );
); state.container.items = new Set([
addWithId(state.s as any, node, "custom123"); { id: "a", data: { nested: { value: 1 } } },
await Promise.resolve(); { id: "b", data: { nested: { value: 2 } } },
const flat = collected2.flat().map((p: DeepPatch) => p.path.join(".")); ]);
expect(flat.some((p: string) => p === "s.custom123")).toBe(true); await Promise.resolve();
stop();
});
describe("Set", () => { const flat = patches.flat().map((p) => p.path.join("."));
it("emits single structural patch on Set.clear()", async () => {
const st = deepSignal({ s: new Set<any>() }); // Check for the Set itself
addWithId(st.s as any, { id: "a", x: 1 }, "a"); expect(flat).toContain("container.items");
addWithId(st.s as any, { id: "b", x: 2 }, "b"); // Check for Set entries (using their id as synthetic key)
const batches: DeepPatch[][] = []; expect(flat.some((p) => p.startsWith("container.items.a"))).toBe(true);
const { stopListening: stop } = watch(st, ({ patches }) => expect(flat.some((p) => p.startsWith("container.items.b"))).toBe(true);
batches.push(patches) // Check for deeply nested properties within Set entries
); expect(flat).toContain("container.items.a.data.nested.value");
st.s.clear(); expect(flat).toContain("container.items.b.data.nested.value");
await Promise.resolve(); stop();
const all = batches.flat().map((p) => p.path.join("."));
expect(all).toEqual(["s"]);
stop();
});
it("emits delete patch for object entry", async () => {
const st = deepSignal({ s: new Set<any>() });
const obj = { id: "n1", x: 1 };
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
st.s.add(obj);
st.s.delete(obj);
await Promise.resolve();
const all = patches
.flat()
.filter((p) => p.op === "remove")
.map((p) => p.path.join("."));
expect(all).toContain("s.n1");
stop();
});
it("does not emit patch for duplicate add", async () => {
const st = deepSignal({ s: new Set<number>([1]) });
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
st.s.add(1);
await Promise.resolve();
expect(patches.length).toBe(0);
stop();
});
it("does not emit patch deleting non-existent entry", async () => {
const st = deepSignal({ s: new Set<number>([1]) });
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
st.s.delete(2);
await Promise.resolve();
expect(patches.length).toBe(0);
stop();
});
it("addWithId primitive returns primitive and emits patch with primitive key", async () => {
const st = deepSignal({ s: new Set<any>() });
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
const ret = addWithId(st.s as any, 5, "ignored");
expect(ret).toBe(5);
await Promise.resolve();
const paths = patches.flat().map((p) => p.path.join("."));
expect(paths).toContain("s.5");
stop();
});
it("setSetEntrySyntheticId applies custom id without helper", async () => {
const st = deepSignal({ s: new Set<any>() });
const obj = { name: "x" };
setSetEntrySyntheticId(obj, "customX");
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
st.s.add(obj);
await Promise.resolve();
const paths = patches.flat().map((p) => p.path.join("."));
expect(paths).toContain("s.customX");
stop();
});
it("values/entries/forEach proxy nested mutation", async () => {
const st = deepSignal({ s: new Set<any>() });
const entry = addWithId(st.s as any, { id: "e1", inner: { v: 1 } }, "e1");
const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches }) =>
batches.push(patches)
);
for (const e of st.s.values()) {
e.inner.v;
}
entry.inner.v = 2;
await Promise.resolve();
const vPaths = batches.flat().map((p) => p.path.join("."));
expect(vPaths.some((p) => p.endsWith("e1.inner.v"))).toBe(true);
stop();
}); });
it("raw reference mutation produces no deep patch while proxied does", async () => {
const raw = { id: "id1", data: { x: 1 } }; it("emits structural patches for sets of sets", async () => {
const st = deepSignal({ s: new Set<any>([raw]) }); const innerA = new Set<any>([{ id: "node1", x: 1 }]);
const batches: DeepPatch[][] = []; const s = new Set<any>([innerA]);
const { stopListening: stop } = watch(st, ({ patches }) => const state = deepSignal<{ graph: Set<any> }>({ graph: s });
batches.push(patches) const batches: DeepPatch[][] = [];
); const { stopListening: stop } = watch(state, ({ patches }) =>
raw.data.x = 2; batches.push(patches)
await Promise.resolve(); );
const afterRaw = batches.flat().map((p) => p.path.join(".")); const innerB = new Set<any>([{ id: "node2", x: 5 }]);
expect(afterRaw.some((p) => p.endsWith("id1.data.x"))).toBe(false); state.graph.add(innerB);
let proxied: any; ([...innerA][0] as any).x = 2;
for (const e of st.s.values()) proxied = e; await Promise.resolve();
proxied.data.x = 3; const pathStrings = batches.flat().map((p) => p.path.join("."));
await Promise.resolve(); expect(pathStrings.some((p) => p.startsWith("graph."))).toBe(true);
const afterProxied = batches.flat().map((p) => p.path.join(".")); stop();
expect(afterProxied.some((p) => p.endsWith("id1.data.x"))).toBe(true);
stop();
}); });
it("synthetic id collision assigns unique blank node id", async () => {
const st = deepSignal({ s: new Set<any>() }); it("tracks deep nested object mutation inside a Set entry after iteration", async () => {
const a1 = { id: "dup", v: 1 }; const rawEntry = { id: "n1", data: { val: 1 } };
const a2 = { id: "dup", v: 2 }; const st = deepSignal({ bag: new Set<any>([rawEntry]) });
const patches: DeepPatch[][] = []; const collected: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) => const { stopListening: stop } = watch(st, ({ patches }) =>
patches.push(batch) collected.push(patches)
); );
st.s.add(a1); let proxied: any;
st.s.add(a2); for (const e of st.bag.values()) {
await Promise.resolve(); proxied = e;
const keys = patches e.data.val;
.flat() }
.filter((p) => p.op === "add") proxied.data.val = 2;
.map((p) => p.path.slice(-1)[0]); await Promise.resolve();
expect(new Set(keys).size).toBe(2); const flat = collected.flat().map((p: DeepPatch) => p.path.join("."));
stop(); expect(flat.some((p: string) => p.endsWith("n1.data.val"))).toBe(true);
stop();
}); });
it("allows Array.from() and spread on Set without brand errors and tracks nested mutation", async () => { it("allows custom synthetic id for Set entry", async () => {
const st = deepSignal({ const node = { name: "x" };
s: new Set<any>([{ id: "eIter", inner: { v: 1 } }]), const state = deepSignal({ s: new Set<any>() });
}); const collected2: DeepPatch[][] = [];
// Regression: previously 'values method called on incompatible Proxy' was thrown here. const { stopListening: stop } = watch(state, ({ patches }) =>
const arr = Array.from(st.s); collected2.push(patches)
expect(arr.length).toBe(1); );
expect(arr[0].inner.v).toBe(1); addWithId(state.s as any, node, "custom123");
const spread = [...st.s]; await Promise.resolve();
expect(spread[0].inner.v).toBe(1); const flat = collected2.flat().map((p: DeepPatch) => p.path.join("."));
const batches: DeepPatch[][] = []; expect(flat.some((p: string) => p === "s.custom123")).toBe(true);
const { stopListening: stop } = watch(st, ({ patches }) => stop();
batches.push(patches)
);
spread[0].inner.v = 2; // mutate nested field of iterated (proxied) entry
await Promise.resolve();
const flat = batches.flat().map((p) => p.path.join("."));
expect(flat.some((p) => p.endsWith("eIter.inner.v"))).toBe(true);
stop();
}); });
});
describe("Arrays & mixed batch", () => { describe("Set", () => {
it("emits patches for splice/unshift/shift in single batch", async () => { it("emits patches for primitive adds", async () => {
const st = deepSignal({ arr: [1, 2, 3] }); const st = deepSignal({ s: new Set<any>() });
const batches: DeepPatch[][] = []; const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches }) => const { stopListening: stop } = watch(st, ({ patches }) =>
batches.push(patches) batches.push(patches)
); );
st.arr.splice(1, 1, 99, 100); st.s.add(true);
st.arr.unshift(0); st.s.add(2);
st.arr.shift(); st.s.add("3");
await Promise.resolve(); await Promise.resolve();
const paths = batches.flat().map((p) => p.path.join("."));
expect(paths.some((p) => p.startsWith("arr."))).toBe(true); expect(batches.length).toBe(1);
stop(); const patches = batches[0];
expect(patches.length).toBe(3);
// All patches should have the same path (the Set itself)
patches.forEach((p) => {
expect(p.path.join(".")).toBe("s");
expect(p.op).toBe("add");
expect((p as any).type).toBe("set");
});
// Check that values are in the value field, not in path
const values = patches.map((p: any) => p.value[0]);
expect(values).toContain(true);
expect(values).toContain(2);
expect(values).toContain("3");
stop();
});
it("emits patches for primitive deletes", async () => {
const st = deepSignal({ s: new Set<any>([true, 2, "3"]) });
const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches }) =>
batches.push(patches)
);
st.s.delete(true);
st.s.delete(2);
await Promise.resolve();
expect(batches.length).toBe(1);
const patches = batches[0];
expect(patches.length).toBe(2);
// All patches should have the same path (the Set itself)
patches.forEach((p) => {
expect(p.path.join(".")).toBe("s");
expect(p.op).toBe("remove");
expect((p as any).type).toBe("set");
});
// Check that values are in the value field
const values = patches.map((p: any) => p.value);
expect(values).toContain(true);
expect(values).toContain(2);
stop();
});
it("does not emit patches for non-existent primitives", async () => {
const st = deepSignal({ s: new Set<any>([1, 2]) });
const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches }) =>
batches.push(patches)
);
st.s.delete("nonexistent");
st.s.delete(999);
await Promise.resolve();
expect(batches.length).toBe(0);
stop();
});
it("does not emit patches for already added primitive", async () => {
const st = deepSignal({ s: new Set<any>([1, "test", true]) });
const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches }) =>
batches.push(patches)
);
st.s.add(1);
st.s.add("test");
st.s.add(true);
await Promise.resolve();
expect(batches.length).toBe(0);
stop();
});
it("emits single structural patch on Set.clear()", async () => {
const st = deepSignal({ s: new Set<any>() });
addWithId(st.s as any, { id: "a", x: 1 }, "a");
addWithId(st.s as any, { id: "b", x: 2 }, "b");
const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches }) =>
batches.push(patches)
);
st.s.clear();
await Promise.resolve();
// clear() emits a single structural patch for the Set itself (op: "add", value: [])
const structuralPatches = batches
.flat()
.filter((p) => p.path.length === 1 && p.path[0] === "s");
expect(structuralPatches.length).toBe(1);
expect(structuralPatches[0].op).toBe("add");
expect((structuralPatches[0] as any).value).toEqual([]);
stop();
});
it("emits delete patch for object entry", async () => {
const st = deepSignal({ s: new Set<any>() });
const obj = { id: "n1", x: 1 };
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
st.s.add(obj);
st.s.delete(obj);
await Promise.resolve();
const all = patches
.flat()
.filter((p) => p.op === "remove")
.map((p) => p.path.join("."));
expect(all).toContain("s.n1");
stop();
});
it("does not emit patch for duplicate add", async () => {
const st = deepSignal({ s: new Set<number>([1]) });
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
st.s.add(1);
await Promise.resolve();
expect(patches.length).toBe(0);
stop();
});
it("does not emit patch deleting non-existent entry", async () => {
const st = deepSignal({ s: new Set<number>([1]) });
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
st.s.delete(2);
await Promise.resolve();
expect(patches.length).toBe(0);
stop();
});
it("addWithId primitive returns primitive and emits patch with primitive key", async () => {
const st = deepSignal({ s: new Set<any>() });
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
const ret = addWithId(st.s as any, 5, "ignored");
expect(ret).toBe(5);
await Promise.resolve();
// For primitives, path should be just "s" and value should be in the value field
const paths = patches.flat().map((p) => p.path.join("."));
expect(paths).toContain("s");
const values = patches.flat().map((p: any) => p.value?.[0]);
expect(values).toContain(5);
stop();
});
it("setSetEntrySyntheticId applies custom id without helper", async () => {
const st = deepSignal({ s: new Set<any>() });
const obj = { name: "x" };
setSetEntrySyntheticId(obj, "customX");
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
st.s.add(obj);
await Promise.resolve();
const paths = patches.flat().map((p) => p.path.join("."));
expect(paths).toContain("s.customX");
stop();
});
it("values/entries/forEach proxy nested mutation", async () => {
const st = deepSignal({ s: new Set<any>() });
const entry = addWithId(
st.s as any,
{ id: "e1", inner: { v: 1 } },
"e1"
);
const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches }) =>
batches.push(patches)
);
for (const e of st.s.values()) {
e.inner.v;
}
entry.inner.v = 2;
await Promise.resolve();
const vPaths = batches.flat().map((p) => p.path.join("."));
expect(vPaths.some((p) => p.endsWith("e1.inner.v"))).toBe(true);
stop();
});
it("raw reference mutation produces no deep patch while proxied does", async () => {
const raw = { id: "id1", data: { x: 1 } };
const st = deepSignal({ s: new Set<any>([raw]) });
const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches }) =>
batches.push(patches)
);
raw.data.x = 2;
await Promise.resolve();
const afterRaw = batches.flat().map((p) => p.path.join("."));
expect(afterRaw.some((p) => p.endsWith("id1.data.x"))).toBe(false);
let proxied: any;
for (const e of st.s.values()) proxied = e;
proxied.data.x = 3;
await Promise.resolve();
const afterProxied = batches.flat().map((p) => p.path.join("."));
expect(afterProxied.some((p) => p.endsWith("id1.data.x"))).toBe(
true
);
stop();
});
it("synthetic id collision assigns unique blank node id", async () => {
const st = deepSignal({ s: new Set<any>() });
const a1 = { id: "dup", v: 1 };
const a2 = { id: "dup", v: 2 };
const patches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches: batch }) =>
patches.push(batch)
);
st.s.add(a1);
st.s.add(a2);
await Promise.resolve();
// Filter for Set structural patches only (path length 2: ['s', syntheticId])
const setAddPatches = patches
.flat()
.filter(
(p) =>
p.op === "add" &&
p.path.length === 2 &&
p.path[0] === "s"
);
const keys = setAddPatches.map((p) => p.path.slice(-1)[0]);
// Both objects should have unique synthetic IDs despite id collision
expect(new Set(keys).size).toBe(2);
stop();
});
it("allows Array.from() and spread on Set without brand errors and tracks nested mutation", async () => {
const st = deepSignal({
s: new Set<any>([{ id: "eIter", inner: { v: 1 } }]),
});
// Regression: previously 'values method called on incompatible Proxy' was thrown here.
const arr = Array.from(st.s);
expect(arr.length).toBe(1);
expect(arr[0].inner.v).toBe(1);
const spread = [...st.s];
expect(spread[0].inner.v).toBe(1);
const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches }) =>
batches.push(patches)
);
spread[0].inner.v = 2; // mutate nested field of iterated (proxied) entry
await Promise.resolve();
const flat = batches.flat().map((p) => p.path.join("."));
expect(flat.some((p) => p.endsWith("eIter.inner.v"))).toBe(true);
stop();
});
}); });
it("mixed object/array/Set mutations batch together", async () => {
const st = deepSignal({ o: { a: 1 }, arr: [1], s: new Set<any>() }); describe("Arrays & mixed batch", () => {
const batches: DeepPatch[][] = []; it("emits patches for splice/unshift/shift in single batch", async () => {
const { stopListening: stop } = watch(st, ({ patches }) => const st = deepSignal({ arr: [1, 2, 3] });
batches.push(patches) const batches: DeepPatch[][] = [];
); const { stopListening: stop } = watch(st, ({ patches }) =>
st.o.a = 2; batches.push(patches)
st.arr.push(2); );
addWithId(st.s as any, { id: "z", v: 1 }, "z"); st.arr.splice(1, 1, 99, 100);
await Promise.resolve(); st.arr.unshift(0);
expect(batches.length).toBe(1); st.arr.shift();
const paths = batches[0].map((p) => p.path.join(".")); await Promise.resolve();
expect(paths).toContain("o.a"); const paths = batches.flat().map((p) => p.path.join("."));
expect(paths).toContain("arr.1"); expect(paths.some((p) => p.startsWith("arr."))).toBe(true);
expect(paths.some((p) => p.startsWith("s."))).toBe(true); stop();
stop(); });
it("mixed object/array/Set mutations batch together", async () => {
const st = deepSignal({ o: { a: 1 }, arr: [1], s: new Set<any>() });
const batches: DeepPatch[][] = [];
const { stopListening: stop } = watch(st, ({ patches }) =>
batches.push(patches)
);
st.o.a = 2;
st.arr.push(2);
addWithId(st.s as any, { id: "z", v: 1 }, "z");
await Promise.resolve();
expect(batches.length).toBe(1);
const paths = batches[0].map((p) => p.path.join("."));
expect(paths).toContain("o.a");
expect(paths).toContain("arr.1");
expect(paths.some((p) => p.startsWith("s."))).toBe(true);
stop();
});
}); });
});
}); });

268
sdk/js/alien-deepsignals/src/watch.ts
Unescape View File

@ -1,10 +1,10 @@
import { isObject, isPlainObject, isSet, isMap, isArray } from "./utils"; import { isObject, isPlainObject, isSet, isMap, isArray } from "./utils";
import { isSignal } from "./core"; import { isSignal } from "./core";
import { import {
isDeepSignal, isDeepSignal,
subscribeDeepMutations, subscribeDeepMutations,
getDeepSignalRootId, getDeepSignalRootId,
DeepPatch, DeepPatch,
} from "./deepSignal"; } from "./deepSignal";
import { ReactiveFlags } from "./contents"; import { ReactiveFlags } from "./contents";
@ -15,125 +15,125 @@ export type WatchEffect = (registerCleanup: RegisterCleanup) => void;
/** Options for {@link watch}. */ /** Options for {@link watch}. */
export interface WatchOptions { 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> { 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> = ( export type WatchPatchCallback<Root = any> = (
event: WatchPatchEvent<Root> event: WatchPatchEvent<Root>
) => any; ) => any;
// Internal helper kept for external compatibility. // Internal helper kept for external compatibility.
export const remove = <T>(arr: T[], el: T): void => { 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. */ /** Observe patch batches on a deep signal root. */
export function watch<Root = any>( 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 // observe alias
export function observe( 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) // 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 export let __traverseCount = 0; // retained for external tooling/tests although watch no longer uses traversal
/** Reset the traversal instrumentation counter back to 0. */ /** Reset the traversal instrumentation counter back to 0. */
export function __resetTraverseCount() { 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. * Depth-limited; protects against cycles via `seen` set; respects ReactiveFlags.SKIP opt-out.
*/ */
export function traverse( export function traverse(
value: unknown, value: unknown,
depth: number = Infinity, depth: number = Infinity,
seen?: Set<unknown> seen?: Set<unknown>
): 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;
} }

2
sdk/js/examples/multi-framework-signals/src/shapes/orm/catShape.schema.ts
Unescape View File

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

6
sdk/js/examples/multi-framework-signals/src/shapes/orm/catShape.typings.ts
Unescape View File

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

2
sdk/js/examples/multi-framework-signals/src/shapes/orm/personShape.schema.ts
Unescape View File

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

6
sdk/js/examples/multi-framework-signals/src/shapes/orm/personShape.typings.ts
Unescape View File

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

2
sdk/js/examples/multi-framework-signals/src/shapes/orm/testShape.schema.ts
Unescape View File

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

8
sdk/js/examples/multi-framework-signals/src/shapes/orm/testShape.typings.ts
Unescape View File

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

18
sdk/js/shex-orm/src/schema-converter/transformers/ShexJTypingTransformer.ts
Unescape View File

@ -225,7 +225,7 @@ function dedupeCompactProperties(
return merged; return merged;
} }
// Helpers to add id: IRI to anonymous object(-union) types // Helpers to add @id: IRI to anonymous object(-union) types
function ensureIdOnMembers(members?: any[]): void { function ensureIdOnMembers(members?: any[]): void {
if (!members) return; if (!members) return;
const props = (members.filter?.((m: any) => m?.kind === "property") || const props = (members.filter?.((m: any) => m?.kind === "property") ||
@ -233,9 +233,9 @@ function ensureIdOnMembers(members?: any[]): void {
if (!props.some((m) => m.name === "id")) { if (!props.some((m) => m.name === "id")) {
members.unshift( members.unshift(
dom.create.property( dom.create.property(
"id", "@id",
dom.create.namedTypeReference("IRI"), dom.create.namedTypeReference("IRI"),
dom.DeclarationFlags.None dom.DeclarationFlags.ReadOnly
) )
); );
} }
@ -322,15 +322,15 @@ export const ShexJTypingTransformerCompact = ShexJTraverser.createTransformer<
shapeInterface.shapeId = shapeDecl.id; shapeInterface.shapeId = shapeDecl.id;
if ( if (
!shapeInterface.members.find( !shapeInterface.members.find(
(m) => m.kind === "property" && m.name === "id" (m) => m.kind === "property" && m.name === "@id"
) )
) { ) {
shapeInterface.members.unshift( shapeInterface.members.unshift(
dom.create.property( dom.create.property(
"id", "@id",
dom.create.namedTypeReference("IRI"), dom.create.namedTypeReference("IRI"),
// Root interfaces should have mandatory id // Root interfaces should have mandatory @id
dom.DeclarationFlags.None dom.DeclarationFlags.ReadOnly
) )
); );
} }
@ -380,7 +380,7 @@ export const ShexJTypingTransformerCompact = ShexJTraverser.createTransformer<
const merged = [ const merged = [
...extInt.members.filter( ...extInt.members.filter(
(m) => (m) =>
!(m.kind === "property" && m.name === "id") !(m.kind === "property" && m.name === "@id")
), ),
...newInterface.members, ...newInterface.members,
].filter( ].filter(
@ -394,7 +394,7 @@ export const ShexJTypingTransformerCompact = ShexJTraverser.createTransformer<
// Final pass: ensure only a single id property // Final pass: ensure only a single id property
const idSeen = new Set<number>(); const idSeen = new Set<number>();
newInterface.members = newInterface.members.filter((m, idx) => { newInterface.members = newInterface.members.filter((m, idx) => {
if (m.kind !== "property" || m.name !== "id") return true; if (m.kind !== "property" || m.name !== "@id") return true;
if (idSeen.size === 0) { if (idSeen.size === 0) {
idSeen.add(idx); idSeen.add(idx);
// normalize id type to IRI // normalize id type to IRI

2
sdk/js/shex-orm/src/types.ts
Unescape View File

@ -4,7 +4,7 @@ export interface ShapeType<T extends BaseType> {
} }
export interface BaseType extends Record<string, any> { export interface BaseType extends Record<string, any> {
id: string; "@id": string;
} }
export type Schema = { export type Schema = {

360
sdk/js/signals/src/connector/applyDiff.test.ts
Unescape View File

@ -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[] = [ const diff: Patch[] = [
{ {
op: "add", 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); 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[] = [ const diff: Patch[] = [
// First patch creates the object in the Set
{ {
op: "add", 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); 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[] = [ 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); 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[] = [ 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); 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", () => { 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 state: any = {};
const diff: Patch[] = [ const diff: Patch[] = [
{ op: "add", path: p("address"), valType: "object" }, { op: "add", path: p("address"), valType: "object" },
{ op: "add", path: p("address", "@id"), value: "urn:addr1" },
]; ];
applyDiff(state, diff); 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 state: any = {};
const diff: Patch[] = [ const diff: Patch[] = [
{ op: "add", path: p("a", "b", "c"), valType: "object" }, { op: "add", path: p("a", "b", "c"), valType: "object" },
{ op: "add", path: p("a", "b", "c", "@id"), value: "urn:c1" },
]; ];
applyDiff(state, diff, true); 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", () => { test("add primitive value", () => {
const state: any = { address: {} }; const state: any = { address: {} };
@ -156,23 +251,46 @@ describe("applyDiff - object & literal operations", () => {
describe("applyDiff - multiple mixed patches in a single diff", () => { describe("applyDiff - multiple mixed patches in a single diff", () => {
test("sequence of mixed set/object/literal add & remove", () => { test("sequence of mixed set/object/literal add & remove", () => {
const state: any = { const state: any = {
users: { u1: { id: "u1" } }, "urn:person1": {},
tags: new Set(["old"]), tags: new Set(["old"]),
}; };
const diff: Patch[] = [ const diff: Patch[] = [
// Create multi-object Set
{ {
op: "add", 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"), valType: "object" },
{ op: "add", path: p("profile", "@id"), value: "urn:profile1" },
{ op: "add", path: p("profile", "name"), value: "Alice" }, { op: "add", path: p("profile", "name"), value: "Alice" },
// Primitive set operations
{ op: "add", valType: "set", path: p("tags"), value: ["new"] }, { op: "add", valType: "set", path: p("tags"), value: ["new"] },
{ op: "remove", valType: "set", path: p("tags"), value: "old" }, { 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.profile.name).toBe("Alice");
expect([...state.tags]).toEqual(["new"]); 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", () => { test("complex nested path creation and mutations with ensurePathExists", () => {
const state: any = {}; const state: any = {};
const diff: Patch[] = [ 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"), valType: "object" },
{ op: "add", path: p("a", "b", "@id"), value: "urn:b1" },
{ op: "add", path: p("a", "b", "c"), value: 1 }, { op: "add", path: p("a", "b", "c"), value: 1 },
// Create a primitive set
{ {
op: "add", op: "add",
valType: "set", valType: "set",
@ -193,6 +314,7 @@ describe("applyDiff - multiple mixed patches in a single diff", () => {
{ op: "remove", path: p("a", "b", "c") }, { op: "remove", path: p("a", "b", "c") },
]; ];
applyDiff(state, diff, true); applyDiff(state, diff, true);
expect(state.a.b["@id"]).toBe("urn:b1");
expect(state.a.b.c).toBeUndefined(); expect(state.a.b.c).toBeUndefined();
expect(state.a.b.d).toBe(2); expect(state.a.b.d).toBe(2);
expect(state.a.nums).toBeInstanceOf(Set); 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 state: any = {};
const diff: Patch[] = [ 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"]);
}); });
}); });

244
sdk/js/signals/src/connector/applyDiff.ts
Unescape View File

@ -21,14 +21,8 @@ export interface SetAddPatch {
* New value for set mutations: * New value for set mutations:
* - A single primitive * - A single primitive
* - An array of primitives * - 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 { export interface SetRemovePatch {
@ -37,8 +31,8 @@ export interface SetRemovePatch {
valType: "set"; valType: "set";
/** /**
* The value(s) to be removed from the set. Either: * 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)[]; 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. * 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 * @example operations
* ```jsonc * ```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 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. * @param ensurePathExists If true, create nested objects along the path if the path does not exist.
*/ */
export function applyDiff( export function applyDiff(
currentState: Record<string, any>, currentState: Record<string, any>,
diff: Patch[], patches: Patch[],
ensurePathExists: boolean = false 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; 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 if (pathParts.length === 0) continue; // root not supported
const lastKey = pathParts[pathParts.length - 1]; const lastKey = pathParts[pathParts.length - 1];
let parentVal: any = currentState; let parentVal: any = currentState;
let parentMissing = false; 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++) { for (let i = 0; i < pathParts.length - 1; i++) {
const seg = pathParts[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 ( if (
parentVal != null && parentVal != null &&
typeof parentVal === "object" && typeof parentVal === "object" &&
@ -147,46 +197,71 @@ export function applyDiff(
continue; 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( 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; continue;
} }
const key = lastKey; 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; 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) const toAdd: (string | number | boolean)[] = Array.isArray(raw)
? raw.filter(isPrimitive) ? raw.filter(isPrimitive)
: isPrimitive(raw) : isPrimitive(raw)
@ -195,51 +270,48 @@ export function applyDiff(
if (!toAdd.length) continue; if (!toAdd.length) continue;
// Ensure we have a Set, create or add to existing
if (existing instanceof Set) { if (existing instanceof Set) {
for (const v of toAdd) existing.add(v); 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 { } else {
// No existing or incompatible -> create a Set // Create new Set (replaces any incompatible existing value)
parentVal[key] = new Set(toAdd); parentVal[key] = new Set(toAdd);
} }
continue; continue;
} }
// Handle set removals // Handle primitive set removals
if (patch.op === "remove" && patch.valType === "set") { if (patch.op === "remove" && patch.valType === "set") {
const existing = parentVal[key]; const existing = parentVal[key];
const raw = (patch as SetRemovePatch).value; const raw = (patch as SetRemovePatch).value;
if (raw == null) continue; if (raw == null) continue;
const toRemove: (string | number | boolean)[] = Array.isArray(raw) const toRemove: (string | number | boolean)[] = Array.isArray(raw)
? raw ? raw
: [raw]; : [raw];
if (existing instanceof Set) { if (existing instanceof Set) {
for (const v of toRemove) existing.delete(v); 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; 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") { 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] = {}; parentVal[key] = {};
} }
continue; continue;
} }
@ -267,3 +339,7 @@ export function applyDiffToDeepSignal(currentState: object, diff: Patch[]) {
applyDiff(currentState as Record<string, any>, diff); applyDiff(currentState as Record<string, any>, diff);
}); });
} }
function decodePathSegment(segment: string): string {
return segment.replace("~1", "/").replace("~0", "~");
}

35
sdk/js/signals/src/connector/createSignalObjectForShape.ts
Unescape View File

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

217
sdk/js/signals/src/connector/ormConnectionHandler.ts
Unescape View File

@ -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);
}
Write Preview
Loading…
Cancel
Save