@coasys/ad4m 0.13.1-staging.13 → 0.13.1-staging.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/lib/index.cjs +548 -477
  2. package/lib/index.js +548 -473
  3. package/lib/src/agent/AgentClient.d.ts +9 -8
  4. package/lib/src/agent/AgentClient.js +46 -67
  5. package/lib/src/cache/KeyedCache.d.ts +51 -0
  6. package/lib/src/cache/KeyedCache.js +142 -0
  7. package/lib/src/expression/ExpressionClient.d.ts +14 -3
  8. package/lib/src/expression/ExpressionClient.js +49 -111
  9. package/lib/src/generated/api/ExpressionLookupError.d.ts +7 -0
  10. package/lib/src/generated/api/ExpressionLookupError.js +2 -0
  11. package/lib/src/generated/api/ExpressionManyEntry.d.ts +6 -0
  12. package/lib/src/generated/api/ExpressionManyEntry.js +1 -0
  13. package/lib/src/generated/api/FlowFiredEntry.d.ts +11 -0
  14. package/lib/src/generated/api/FlowFiredEntry.js +2 -0
  15. package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +3 -3
  16. package/lib/src/generated/api/RpcMethods.d.ts +4 -2
  17. package/lib/src/model/Ad4mModel.d.ts +26 -2
  18. package/lib/src/model/Ad4mModel.js +125 -82
  19. package/lib/src/model/ModelQueryBuilder.d.ts +3 -0
  20. package/lib/src/model/ModelQueryBuilder.js +42 -14
  21. package/lib/src/model/index.d.ts +0 -1
  22. package/lib/src/model/index.js +0 -1
  23. package/lib/src/model/query-common.d.ts +8 -0
  24. package/lib/src/model/query-common.js +12 -0
  25. package/lib/src/model/types.d.ts +12 -3
  26. package/lib/src/perspectives/FlowModels.js +1 -1
  27. package/lib/src/perspectives/LiveQuery.d.ts +1 -1
  28. package/lib/src/perspectives/PerspectiveClient.d.ts +17 -6
  29. package/lib/src/perspectives/PerspectiveClient.js +83 -44
  30. package/lib/src/perspectives/PerspectiveProxy.d.ts +19 -10
  31. package/lib/src/perspectives/PerspectiveProxy.js +31 -69
  32. package/package.json +2 -2
  33. package/src/Ad4mClient.test.ts +17 -6
  34. package/src/agent/AgentClient.ts +46 -74
  35. package/src/cache/KeyedCache.test.ts +162 -0
  36. package/src/cache/KeyedCache.ts +179 -0
  37. package/src/cache/cache.test.ts +294 -71
  38. package/src/expression/ExpressionClient.ts +46 -131
  39. package/src/generated/api/ExpressionLookupError.ts +6 -0
  40. package/src/generated/api/ExpressionManyEntry.ts +8 -0
  41. package/src/generated/api/FlowFiredEntry.ts +11 -0
  42. package/src/generated/api/PerspectiveFlowFiredParams.ts +3 -3
  43. package/src/generated/api/RpcMethods.ts +4 -2
  44. package/src/model/Ad4mModel.test.ts +237 -43
  45. package/src/model/Ad4mModel.ts +132 -98
  46. package/src/model/ModelQueryBuilder.ts +41 -15
  47. package/src/model/count-result-type.test.ts +72 -0
  48. package/src/model/index.ts +0 -1
  49. package/src/model/query-common.ts +13 -0
  50. package/src/model/relation-filtering.test.ts +3 -5
  51. package/src/model/types.ts +9 -3
  52. package/src/model/write-round-trips.test.ts +30 -6
  53. package/src/perspectives/FlowModels.ts +1 -1
  54. package/src/perspectives/LiveQuery.ts +1 -1
  55. package/src/perspectives/PerspectiveClient.test.ts +287 -0
  56. package/src/perspectives/PerspectiveClient.ts +101 -66
  57. package/src/perspectives/PerspectiveProxy.test.ts +6 -14
  58. package/src/perspectives/PerspectiveProxy.ts +33 -67
  59. package/src/perspectives/TextContent.test.ts +0 -16
  60. package/src/perspectives/shacl-rpc.test.ts +1 -1
  61. package/lib/src/model/query-cache.d.ts +0 -30
  62. package/lib/src/model/query-cache.js +0 -66
  63. package/src/model/query-cache.test.ts +0 -54
  64. package/src/model/query-cache.ts +0 -79
@@ -1,161 +1,78 @@
1
- import { ApiClient } from "../apiClient";
1
+ import { ApiClient, RpcError } from "../apiClient";
2
2
  import { InteractionCall, InteractionMeta } from "../language/Language";
3
3
  import { ExpressionRendered } from "./Expression";
4
4
  import { Literal } from "../Literal";
5
- import { PersistentCache, createPersistentCache } from "../cache/PersistentCache";
5
+ import { createPersistentCache } from "../cache/PersistentCache";
6
+ import { KeyedCache, StoredEntry } from "../cache/KeyedCache";
6
7
 
7
- interface CachedExpression {
8
- data: ExpressionRendered;
9
- size: number;
10
- }
8
+ /** Most URLs the executor takes in one `expression.getMany` call. */
9
+ const MAX_URLS_PER_CALL = 200;
11
10
 
12
11
  export class ExpressionClient {
13
12
  #apiClient: ApiClient
14
13
 
15
- // L1: in-memory LRU cache (hot path, sub-ms)
16
- #memCache = new Map<string, CachedExpression>();
17
- #inflight = new Map<string, Promise<ExpressionRendered>>();
18
- /** Maximum number of entries in the L1 memory cache. */
14
+ /** Maximum number of expressions kept in memory. */
19
15
  static MAX_MEM_ENTRIES = 200;
20
- /** Maximum total size (in bytes) of L1 memory cache values. */
16
+ /** Maximum total size (in bytes of JSON) of the expressions kept in memory. */
21
17
  static MAX_MEM_BYTES = 5 * 1024 * 1024; // 5 MB
22
- #totalMemBytes = 0;
18
+ /**
19
+ * TTL of every cached expression, in memory and in the persistent cache
20
+ * (ms). A language may change what a URL returns, and no event tells the
21
+ * client, so a cached expression expires instead of staying stale.
22
+ */
23
+ static EXPRESSION_TTL_MS = 5 * 60_000; // 5 minutes
23
24
 
24
- // L2: persistent cache (IndexedDB in browser, NullCache in Node)
25
- #persistent: PersistentCache<ExpressionRendered>;
25
+ // A `get` miss is its own `expression.get`, so it waits for no slower
26
+ // expression and has its own call timeout. The misses of the `getMany`
27
+ // calls made in one tick go out in `expression.getMany` calls of at most
28
+ // MAX_URLS_PER_CALL URLs, which answer per URL what `expression.get` would.
29
+ #expressions: KeyedCache<ExpressionRendered>;
26
30
 
27
31
  constructor(baseUrl: string, token?: string, sharedApiClient?: ApiClient) {
28
32
  this.#apiClient = sharedApiClient || new ApiClient(baseUrl, token)
29
- this.#persistent = createPersistentCache<ExpressionRendered>('ad4m-expression-cache', 'expressions');
33
+ this.#expressions = new KeyedCache<ExpressionRendered>({
34
+ load: (url) => this.#apiClient.call('expression.get', { url }),
35
+ loadMany: async (urls) => (await this.#apiClient.call('expression.getMany', { urls })).map(entry =>
36
+ entry && 'code' in entry ? new RpcError(entry.code, entry.message) : entry as ExpressionRendered | null),
37
+ maxBatch: MAX_URLS_PER_CALL,
38
+ persistent: createPersistentCache<StoredEntry<ExpressionRendered>>('ad4m-expression-cache', 'expressions'),
39
+ maxAgeMs: () => ExpressionClient.EXPRESSION_TTL_MS,
40
+ persistentMaxAgeMs: () => ExpressionClient.EXPRESSION_TTL_MS,
41
+ limits: () => ({ entries: ExpressionClient.MAX_MEM_ENTRIES, bytes: ExpressionClient.MAX_MEM_BYTES }),
42
+ });
30
43
  }
31
44
 
45
+ /** The expression at `url`; `alwaysGet` skips the literal fast path and the cache. */
32
46
  async get(url: string, alwaysGet: boolean = false): Promise<ExpressionRendered> {
33
- // Existing literal fast-path
34
- if(!alwaysGet){
35
- try {
36
- let literalValue = Literal.fromUrl(url).get();
37
- if (typeof literalValue === 'object' && literalValue !== null) {
38
- if ('author' in literalValue && 'timestamp' in literalValue && 'data' in literalValue && 'proof' in literalValue) {
39
- return literalValue;
40
- }
41
- }
42
- } catch(e) {}
43
- }
44
-
45
- // L1: memory hit
46
- if (!alwaysGet) {
47
- const memHit = this.#memCache.get(url);
48
- if (memHit) return memHit.data;
49
- }
50
-
51
- // Deduplicate in-flight requests
52
- if (!alwaysGet) {
53
- const existing = this.#inflight.get(url);
54
- if (existing) return existing;
55
- }
56
-
57
- // L2 check + L3 network
58
- const promise = (async () => {
59
- if (!alwaysGet) {
60
- const persisted = await this.#persistent.get(url);
61
- if (persisted) {
62
- this.#memCacheResult(url, persisted); // promote to L1
63
- return persisted;
64
- }
65
- }
66
-
67
- // L3: network fetch
47
+ if (alwaysGet) {
68
48
  const result = await this.#apiClient.call('expression.get', { url });
69
- this.#memCacheResult(url, result);
70
- this.#persistent.put(url, result); // fire-and-forget write to L2
49
+ if (result) this.#expressions.set(url, result);
71
50
  return result;
72
- })();
73
-
74
- this.#inflight.set(url, promise);
75
-
76
- try {
77
- return await promise;
78
- } finally {
79
- this.#inflight.delete(url);
80
- }
81
- }
82
-
83
- async getMany(urls: string[]): Promise<ExpressionRendered[]> {
84
- // Check L1 first
85
- const results: (ExpressionRendered | null)[] = urls.map(
86
- u => this.#memCache.get(u)?.data ?? null
87
- );
88
- let uncachedIndices = results
89
- .map((r, i) => r === null ? i : -1)
90
- .filter(i => i >= 0);
91
-
92
- if (uncachedIndices.length === 0) return results as ExpressionRendered[];
93
-
94
- // Check L2 for remaining misses
95
- const l2Results = await Promise.all(
96
- uncachedIndices.map(i => this.#persistent.get(urls[i]))
97
- );
98
- const stillMissing: number[] = [];
99
- for (let j = 0; j < uncachedIndices.length; j++) {
100
- const idx = uncachedIndices[j];
101
- if (l2Results[j]) {
102
- results[idx] = l2Results[j]!;
103
- this.#memCacheResult(urls[idx], l2Results[j]!); // promote to L1
104
- } else {
105
- stillMissing.push(idx);
106
- }
107
51
  }
108
-
109
- if (stillMissing.length === 0) return results as ExpressionRendered[];
110
-
111
- // L3: fetch only truly uncached URLs
112
- const uncachedUrls = stillMissing.map(i => urls[i]);
113
- const fetched = await this.#apiClient.call(
114
- 'expression.getMany', { urls: uncachedUrls }
115
- );
116
-
117
- for (let i = 0; i < stillMissing.length; i++) {
118
- const idx = stillMissing[i];
119
- results[idx] = fetched[i];
120
- if (fetched[i]) {
121
- this.#memCacheResult(uncachedUrls[i], fetched[i]);
122
- this.#persistent.put(uncachedUrls[i], fetched[i]); // fire-and-forget
52
+ try {
53
+ let literalValue = Literal.fromUrl(url).get();
54
+ if (typeof literalValue === 'object' && literalValue !== null) {
55
+ if ('author' in literalValue && 'timestamp' in literalValue && 'data' in literalValue && 'proof' in literalValue) {
56
+ return literalValue;
57
+ }
123
58
  }
124
- }
125
-
126
- return results as ExpressionRendered[];
59
+ } catch(e) {}
60
+ return this.#expressions.get(url);
127
61
  }
128
62
 
129
63
  /**
130
- * Insert a result into L1 memory cache with LRU eviction.
64
+ * The expressions at `urls`, in order (`null` when not found); the misses go
65
+ * out in calls of at most 200 URLs. Rejects with the `RpcError` `get` gives when a URL's read fails.
131
66
  */
132
- #memCacheResult(url: string, data: ExpressionRendered): void {
133
- const size = JSON.stringify(data).length;
134
-
135
- // Evict oldest entries if we'd exceed limits
136
- while (
137
- this.#memCache.size >= ExpressionClient.MAX_MEM_ENTRIES ||
138
- this.#totalMemBytes + size > ExpressionClient.MAX_MEM_BYTES
139
- ) {
140
- const oldest = this.#memCache.keys().next().value;
141
- if (!oldest) break;
142
- const entry = this.#memCache.get(oldest)!;
143
- this.#totalMemBytes -= entry.size;
144
- this.#memCache.delete(oldest);
145
- }
146
-
147
- this.#memCache.set(url, { data, size });
148
- this.#totalMemBytes += size;
67
+ async getMany(urls: string[]): Promise<ExpressionRendered[]> {
68
+ return this.#expressions.getMany(urls);
149
69
  }
150
70
 
151
71
  /**
152
- * Clear both L1 (memory) and L2 (persistent) expression caches.
72
+ * Clear both the memory and the persistent expression caches.
153
73
  */
154
74
  clearCache(): void {
155
- this.#memCache.clear();
156
- this.#inflight.clear();
157
- this.#totalMemBytes = 0;
158
- this.#persistent.clear(); // fire-and-forget
75
+ this.#expressions.clear(true);
159
76
  }
160
77
 
161
78
  async getRaw(url: string): Promise<string> {
@@ -174,9 +91,7 @@ export class ExpressionClient {
174
91
  async interact(url: string, interactionCall: InteractionCall): Promise<string|null> {
175
92
  const result = await this.#apiClient.call('expression.interact', { url, interactionCall });
176
93
  // Interactions can mutate the expression — invalidate cache so next get() fetches fresh
177
- this.#memCache.delete(url);
178
- this.#inflight.delete(url);
179
- this.#persistent.delete(url); // fire-and-forget
94
+ this.#expressions.delete(url);
180
95
  return result;
181
96
  }
182
97
  }
@@ -0,0 +1,6 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+
3
+ /**
4
+ * The error `expression.get` fails with, reported per URL by `expression.getMany`.
5
+ */
6
+ export type ExpressionLookupError = { code: number, message: string, };
@@ -0,0 +1,8 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ import type { ExpressionLookupError } from "./ExpressionLookupError";
3
+ import type { ExpressionRendered } from "./ExpressionRendered";
4
+
5
+ /**
6
+ * One `expression.getMany` entry (`null` when `expression.get` returns `null`).
7
+ */
8
+ export type ExpressionManyEntry = ExpressionLookupError | ExpressionRendered;
@@ -0,0 +1,11 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+
3
+ /**
4
+ * The proposals of one instance this agent has marked fired, as
5
+ * `perspective.flowFired` returns them.
6
+ */
7
+ export type FlowFiredEntry = { instance: string,
8
+ /**
9
+ * Sorted; empty when this agent has marked none.
10
+ */
11
+ fired: Array<string>, };
@@ -1,7 +1,7 @@
1
1
  // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
2
 
3
3
  /**
4
- * `perspective.flowFired`: the proposals of `instance` the calling agent's
5
- * pass has recorded as fired, sorted.
4
+ * `perspective.flowFired`: for each of `instances`, in order, the proposals
5
+ * the calling agent's pass has recorded as fired, sorted.
6
6
  */
7
- export type PerspectiveFlowFiredParams = { uuid: string, instance: string, };
7
+ export type PerspectiveFlowFiredParams = { uuid: string, instances: Array<string>, };
@@ -62,10 +62,12 @@ import type { EntanglementProofsWrapper } from "./EntanglementProofsWrapper";
62
62
  import type { EventName } from "./Events";
63
63
  import type { ExportRequest } from "./ExportRequest";
64
64
  import type { ExpressionInteractRequest } from "./ExpressionInteractRequest";
65
+ import type { ExpressionManyEntry } from "./ExpressionManyEntry";
65
66
  import type { ExpressionManyRequest } from "./ExpressionManyRequest";
66
67
  import type { ExpressionRendered } from "./ExpressionRendered";
67
68
  import type { ExpressionUrlRequest } from "./ExpressionUrlRequest";
68
69
  import type { FireOutcome } from "./FireOutcome";
70
+ import type { FlowFiredEntry } from "./FlowFiredEntry";
69
71
  import type { FlowStateEntry } from "./FlowStateEntry";
70
72
  import type { FriendsListRequest } from "./FriendsListRequest";
71
73
  import type { GenerateAgentRequest } from "./GenerateAgentRequest";
@@ -310,7 +312,7 @@ export interface RpcMethods {
310
312
  "events.watch": { params: Partial<Record<EventName, Array<string> | null>>; result: boolean };
311
313
  "expression.create": { params: CreateExpressionRequest; result: string };
312
314
  "expression.get": { params: ExpressionUrlRequest; result: ExpressionRendered | null };
313
- "expression.getMany": { params: ExpressionManyRequest; result: Array<ExpressionRendered | null> };
315
+ "expression.getMany": { params: ExpressionManyRequest; result: Array<ExpressionManyEntry | null> };
314
316
  "expression.getRaw": { params: ExpressionUrlRequest; result: string | null };
315
317
  "expression.interact": { params: ExpressionInteractRequest; result: string };
316
318
  "expression.interactions": { params: ExpressionUrlRequest; result: Array<InteractionMeta> };
@@ -366,7 +368,7 @@ export interface RpcMethods {
366
368
  "perspective.disposeSparql": { params: PerspectiveSubscriptionParams; result: boolean };
367
369
  "perspective.evaluateGetters": { params: PerspectiveEvaluateGettersParams; result: string };
368
370
  "perspective.executeCommands": { params: PerspectiveExecuteCommandsParams; result: null };
369
- "perspective.flowFired": { params: PerspectiveFlowFiredParams; result: Array<string> };
371
+ "perspective.flowFired": { params: PerspectiveFlowFiredParams; result: Array<FlowFiredEntry> };
370
372
  "perspective.flowStates": { params: PerspectiveFlowStatesParams; result: Array<FlowStateEntry> };
371
373
  "perspective.flowValidOutputs": { params: PerspectiveFlowValidOutputsParams; result: Array<ValidOutput> };
372
374
  "perspective.get": { params: PerspectiveUuidParams; result: PerspectiveHandle | null };
@@ -1340,6 +1340,69 @@ describe("ModelQueryBuilder subscribe callback timing", () => {
1340
1340
  });
1341
1341
  });
1342
1342
 
1343
+ describe("totalCount is asked for only by the readers of it (P3)", () => {
1344
+ const { Ad4mModel, Model, Flag, Property } = require("./index");
1345
+
1346
+ @Model({ name: "CountedThing" })
1347
+ class CountedThing extends Ad4mModel {
1348
+ @Flag({ through: "test://type", value: "test://counted" })
1349
+ type: string = "test://counted";
1350
+ @Property({ through: "test://name" })
1351
+ name: string = "";
1352
+ }
1353
+
1354
+ function perspective() {
1355
+ const client = {
1356
+ modelSubscribe: jest.fn().mockResolvedValue({
1357
+ subscriptionId: "count-sub",
1358
+ revision: 0,
1359
+ result: { instances: [], totalCount: 4 },
1360
+ }),
1361
+ onQueryUpdate: jest.fn(() => () => {}),
1362
+ onReconnect: jest.fn(() => () => {}),
1363
+ disposeQuerySubscription: jest.fn().mockResolvedValue(true),
1364
+ };
1365
+ return {
1366
+ uuid: "count-uuid",
1367
+ client,
1368
+ modelQuery: jest.fn().mockResolvedValue({ instances: [], totalCount: 4 }),
1369
+ modelSubscribe: jest.fn((className: string, queryJson: string) =>
1370
+ client.modelSubscribe("count-uuid", className, queryJson),
1371
+ ),
1372
+ } as any;
1373
+ }
1374
+ const sentQuery = (fn: jest.Mock) => JSON.parse(fn.mock.calls[0][1]);
1375
+
1376
+ it("findAll() and get() send no count", async () => {
1377
+ const p = perspective();
1378
+ await CountedThing.findAll(p, { limit: 5 });
1379
+ expect(sentQuery(p.modelQuery)).not.toHaveProperty("count");
1380
+ const q = perspective();
1381
+ await CountedThing.query(q).limit(5).get();
1382
+ expect(sentQuery(q.modelQuery)).not.toHaveProperty("count");
1383
+ });
1384
+
1385
+ it("findAllAndCount(), count() and the builder's count() send count: true", async () => {
1386
+ for (const run of [
1387
+ (p: any) => CountedThing.findAllAndCount(p, { limit: 5 }),
1388
+ (p: any) => CountedThing.count(p),
1389
+ (p: any) => CountedThing.query(p).count(),
1390
+ ]) {
1391
+ const p = perspective();
1392
+ await run(p);
1393
+ expect(sentQuery(p.modelQuery).count).toBe(true);
1394
+ }
1395
+ });
1396
+
1397
+ it("countSubscribe() opens its subscription with count: true", async () => {
1398
+ const p = perspective();
1399
+ const builder = CountedThing.query(p);
1400
+ expect(await builder.countSubscribe(() => {})).toBe(4);
1401
+ expect(sentQuery(p.modelSubscribe)).toMatchObject({ limit: 0, count: true });
1402
+ builder.dispose();
1403
+ });
1404
+ });
1405
+
1343
1406
  describe("ModelQueryBuilder paginateSubscribe", () => {
1344
1407
  // The subscription is the paged query itself (PERF-11). Since #1237 the
1345
1408
  // executor re-runs a paged subscription when a record outside the page
@@ -1521,6 +1584,51 @@ describe("ModelQueryBuilder paginateSubscribe", () => {
1521
1584
  errorSpy.mockRestore();
1522
1585
  }
1523
1586
  });
1587
+
1588
+ it("paginateSubscribe() rejects a first answer without totalCount and ends its subscription", async () => {
1589
+ const { mockClient, mockPerspective } = buildMocks({ instances: [] });
1590
+ const builder = testModel("PaginateNoCount").query(mockPerspective);
1591
+
1592
+ await expect(builder.paginateSubscribe(10, 1, () => {})).rejects.toThrow(/totalCount/);
1593
+
1594
+ expect(mockClient.disposeQuerySubscription).toHaveBeenCalledWith("test-uuid", "paginate-sub");
1595
+ // The failed call left nothing for the builder to end.
1596
+ builder.dispose();
1597
+ expect(mockClient.disposeQuerySubscription).toHaveBeenCalledTimes(1);
1598
+ });
1599
+
1600
+ it("countSubscribe() rejects a first answer without totalCount and ends its subscription", async () => {
1601
+ const { mockClient, mockPerspective } = buildMocks({ instances: [] });
1602
+ const builder = testModel("CountNoCount").query(mockPerspective);
1603
+
1604
+ await expect(builder.countSubscribe(() => {})).rejects.toThrow(/totalCount/);
1605
+
1606
+ expect(mockClient.disposeQuerySubscription).toHaveBeenCalledWith("test-uuid", "paginate-sub");
1607
+ builder.dispose();
1608
+ expect(mockClient.disposeQuerySubscription).toHaveBeenCalledTimes(1);
1609
+ });
1610
+
1611
+ it("countSubscribe() skips a pushed update without totalCount and keeps delivering", async () => {
1612
+ const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
1613
+ try {
1614
+ const { mockPerspective, push } = buildMocks({ instances: [], totalCount: 1 });
1615
+ const counts: number[] = [];
1616
+ const builder = testModel("CountPushNoCount").query(mockPerspective);
1617
+ expect(await builder.countSubscribe(c => counts.push(c))).toBe(1);
1618
+
1619
+ // The push runs the client's update dispatch: it must not throw.
1620
+ expect(() => push({ result: { instances: [] } })).not.toThrow();
1621
+ expect(counts).toEqual([]);
1622
+ push({ result: { instances: [], totalCount: 2 } });
1623
+ await settle();
1624
+
1625
+ expect(counts).toEqual([2]);
1626
+ expect(errorSpy.mock.calls.some(args => args[0] === "Count subscription error:")).toBe(true);
1627
+ builder.dispose();
1628
+ } finally {
1629
+ errorSpy.mockRestore();
1630
+ }
1631
+ });
1524
1632
  });
1525
1633
 
1526
1634
  // ============================================================================
@@ -1622,51 +1730,8 @@ describe("ModelQueryBuilder reconnect", () => {
1622
1730
  // Performance Optimisation Tests
1623
1731
  // ============================================================================
1624
1732
 
1625
- import { getCachedResult, setCachedResult, clearQueryCache, queryCacheSize } from "./query-cache";
1626
1733
  import { getPropertiesMetadata, getRelationsMetadata, getMemoizedSHACL } from "./decorators";
1627
1734
 
1628
- describe("QueryCache", () => {
1629
- beforeEach(() => clearQueryCache());
1630
-
1631
- it("should return undefined for cache miss", () => {
1632
- expect(getCachedResult("uuid1", "SELECT ?s WHERE {}")).toBeUndefined();
1633
- });
1634
-
1635
- it("should return cached result within TTL", () => {
1636
- const result = [{ s: "test" }];
1637
- setCachedResult("uuid1", "SELECT ?s WHERE {}", result);
1638
- expect(getCachedResult("uuid1", "SELECT ?s WHERE {}")).toBe(result);
1639
- });
1640
-
1641
- it("should expire after TTL", async () => {
1642
- setCachedResult("uuid1", "SELECT ?s WHERE {}", [{ s: "test" }], 50);
1643
- await new Promise(r => setTimeout(r, 60));
1644
- expect(getCachedResult("uuid1", "SELECT ?s WHERE {}")).toBeUndefined();
1645
- });
1646
-
1647
- it("should cache independently per perspective", () => {
1648
- setCachedResult("uuid1", "SELECT ?s WHERE {}", "result1");
1649
- setCachedResult("uuid2", "SELECT ?s WHERE {}", "result2");
1650
- expect(getCachedResult("uuid1", "SELECT ?s WHERE {}")).toBe("result1");
1651
- expect(getCachedResult("uuid2", "SELECT ?s WHERE {}")).toBe("result2");
1652
- });
1653
-
1654
- it("should cache independently per query", () => {
1655
- setCachedResult("uuid1", "query1", "r1");
1656
- setCachedResult("uuid1", "query2", "r2");
1657
- expect(getCachedResult("uuid1", "query1")).toBe("r1");
1658
- expect(getCachedResult("uuid1", "query2")).toBe("r2");
1659
- });
1660
-
1661
- it("should clear all entries", () => {
1662
- setCachedResult("uuid1", "q1", "r1");
1663
- setCachedResult("uuid2", "q2", "r2");
1664
- expect(queryCacheSize()).toBe(2);
1665
- clearQueryCache();
1666
- expect(queryCacheSize()).toBe(0);
1667
- });
1668
- });
1669
-
1670
1735
  describe("SHACL Memoisation", () => {
1671
1736
  it("should memoise generateSHACL() per class", () => {
1672
1737
  @Model({ name: "MemoTest1" })
@@ -3652,3 +3717,132 @@ describe("Ad4mModel.findAllOf / queryOf (one query over several classes, #1238)"
3652
3717
  ).toThrow(/different predicates/);
3653
3718
  });
3654
3719
  });
3720
+
3721
+ import { valueToLiteralIri } from "./query-sparql";
3722
+
3723
+ describe("Model writes: one executeAction call per write (P4)", () => {
3724
+ @Model({ name: "P4Card" })
3725
+ class P4Card extends Ad4mModel {
3726
+ @Optional({ through: "p4://title" })
3727
+ title?: string;
3728
+
3729
+ @Optional({ through: "p4://note", local: true })
3730
+ note?: string;
3731
+
3732
+ @Optional({ through: "p4://rank" })
3733
+ rank?: number;
3734
+
3735
+ @HasMany({ through: "p4://tag" })
3736
+ tags: string[] = [];
3737
+
3738
+ @HasMany({ through: "p4://link" })
3739
+ links: string[] = [];
3740
+ }
3741
+
3742
+ const makePerspective = () =>
3743
+ ({
3744
+ executeAction: jest.fn().mockResolvedValue(undefined),
3745
+ uuid: "test-perspective-uuid",
3746
+ }) as any;
3747
+
3748
+ /**
3749
+ * The links each `executeAction` call writes, resolved as the executor's
3750
+ * `execute_commands` resolves them: one left-to-right pass, longest
3751
+ * parameter name first; `this` is the instance; `collectionSetter` takes
3752
+ * every parameter of its call as a member.
3753
+ */
3754
+ const resolved = (perspective: any) =>
3755
+ perspective.executeAction.mock.calls.flatMap(([commands, expression, parameters]: any[]) => {
3756
+ const names = [...(parameters ?? [])].sort((a: any, b: any) => b.name.length - a.name.length);
3757
+ const sub = (input?: string) => {
3758
+ if (input == null) return input;
3759
+ let out = "";
3760
+ for (let i = 0; i < input.length;) {
3761
+ const p = names.find((p: any) => p.name && input.startsWith(p.name, i));
3762
+ if (p) { out += p.value; i += p.name.length; } else { out += input[i]; i += 1; }
3763
+ }
3764
+ return out;
3765
+ };
3766
+ const self = (s?: string) => (s === "this" ? expression : s);
3767
+ return commands.map((c: any) => ({
3768
+ action: c.action,
3769
+ source: self(sub(c.source)),
3770
+ predicate: self(sub(c.predicate)),
3771
+ target: c.action === "collectionSetter" ? (parameters ?? []).map((p: any) => p.value) : sub(c.target),
3772
+ local: !!c.local,
3773
+ }));
3774
+ });
3775
+
3776
+ const edited = (perspective: any) => {
3777
+ const card = new P4Card(perspective, "p4://card/1") as any;
3778
+ card.takeSnapshot();
3779
+ card.title = "Hello";
3780
+ card.note = "private";
3781
+ card.rank = 3;
3782
+ return card;
3783
+ };
3784
+
3785
+ it("an update of three scalar fields makes one call with each field's link and status", async () => {
3786
+ const perspective = makePerspective();
3787
+ await edited(perspective).save("batch-1");
3788
+
3789
+ expect(perspective.executeAction).toHaveBeenCalledTimes(1);
3790
+ expect(perspective.executeAction.mock.calls[0][3]).toBe("batch-1");
3791
+ expect(resolved(perspective)).toEqual([
3792
+ { action: "setSingleTarget", source: "p4://card/1", predicate: "p4://title", target: "literal:string:Hello", local: false },
3793
+ { action: "setSingleTarget", source: "p4://card/1", predicate: "p4://note", target: "literal:string:private", local: true },
3794
+ { action: "setSingleTarget", source: "p4://card/1", predicate: "p4://rank", target: valueToLiteralIri(3), local: false },
3795
+ ]);
3796
+ });
3797
+
3798
+ it("adder and remover values join the scalar writes; each collection set is a call of its own", async () => {
3799
+ const perspective = makePerspective();
3800
+ // No snapshot: every field is written, in field order (tags, links, then the scalars).
3801
+ const card = new P4Card(perspective, "p4://card/1") as any;
3802
+ card.tags = { action: "adder", value: ["t1", "t2"] };
3803
+ card.links = ["l1", "l2"];
3804
+ card.title = "Hello";
3805
+ card.note = "private";
3806
+ card.rank = 3;
3807
+ await card.innerUpdate(true, "batch-1");
3808
+
3809
+ // tags (two adds) in one call; links (collectionSetter) alone; the three scalars in one.
3810
+ expect(perspective.executeAction).toHaveBeenCalledTimes(3);
3811
+ expect(resolved(perspective)).toEqual([
3812
+ { action: "addLink", source: "p4://card/1", predicate: "p4://tag", target: "t1", local: false },
3813
+ { action: "addLink", source: "p4://card/1", predicate: "p4://tag", target: "t2", local: false },
3814
+ { action: "collectionSetter", source: "p4://card/1", predicate: "p4://link", target: ["l1", "l2"], local: false },
3815
+ { action: "setSingleTarget", source: "p4://card/1", predicate: "p4://title", target: "literal:string:Hello", local: false },
3816
+ { action: "setSingleTarget", source: "p4://card/1", predicate: "p4://note", target: "literal:string:private", local: true },
3817
+ { action: "setSingleTarget", source: "p4://card/1", predicate: "p4://rank", target: valueToLiteralIri(3), local: false },
3818
+ ]);
3819
+ });
3820
+
3821
+ it("a long run of writes is split into calls of at most 200 writes, in order", async () => {
3822
+ const perspective = makePerspective();
3823
+ const card = new P4Card(perspective, "p4://card/1") as any;
3824
+ const tags = Array.from({ length: 450 }, (_, i) => `t${i}`);
3825
+ card.tags = { action: "adder", value: tags };
3826
+ await card.innerUpdate(true, "batch-1");
3827
+
3828
+ const tagCalls = perspective.executeAction.mock.calls.filter(([commands]: any[]) => commands[0].action === "addLink");
3829
+ expect(tagCalls.map((call: any[]) => call[2].length)).toEqual([200, 200, 50]);
3830
+ const added = resolved(perspective).filter((c: any) => c.action === "addLink");
3831
+ expect(added.map((c: any) => c.target)).toEqual(tags);
3832
+ });
3833
+
3834
+ it("a single write is sent as before, with its `value` parameter", async () => {
3835
+ const perspective = makePerspective();
3836
+ const card = new P4Card(perspective, "p4://card/1") as any;
3837
+ card.takeSnapshot();
3838
+ card.title = "Only";
3839
+ await card.save("batch-1");
3840
+
3841
+ expect(perspective.executeAction.mock.calls).toEqual([[
3842
+ [{ action: "setSingleTarget", source: "this", predicate: "p4://title", target: "value" }],
3843
+ "p4://card/1",
3844
+ [{ name: "value", value: "literal:string:Only" }],
3845
+ "batch-1",
3846
+ ]]);
3847
+ });
3848
+ });