@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,5 +1,6 @@
1
1
  import { PerspectiveClient } from "./PerspectiveClient";
2
2
  import type { EventMap, ScopedEventName } from "../generated/api/Events";
3
+ import type { FlowFiredEntry } from "../generated/api/FlowFiredEntry";
3
4
  import type {
4
5
  FlowFireOutcome, FlowMintedReceipt, FlowOutputRef, FlowProposeResult,
5
6
  FlowReceiptVerdict, FlowStateEntry, FlowValidOutput,
@@ -16,7 +17,6 @@ import { NeighbourhoodExpression } from "../neighbourhood/Neighbourhood";
16
17
  import { AIClient } from "../ai/AIClient";
17
18
 
18
19
  import { getPropertiesMetadata, getRelationsMetadata } from "../model/decorators";
19
- import { getCachedResult, setCachedResult, invalidatePerspectiveCache } from "../model/query-cache";
20
20
  import { AllInstancesResult } from "../model/types";
21
21
  import { LiveQuery, LiveQueryStatus, Subscribed } from "./LiveQuery";
22
22
  import type { TranscriptTurn } from "../generated/api";
@@ -338,9 +338,7 @@ export class PerspectiveProxy {
338
338
  * @param batchId - Optional batch ID to group this operation with others
339
339
  */
340
340
  async executeAction(actions, expression, parameters: Parameter[], batchId?: string) {
341
- const result = await this.#client.executeCommands(this.#handle.uuid, JSON.stringify(actions), expression, JSON.stringify(parameters), batchId)
342
- invalidatePerspectiveCache(this.#handle.uuid);
343
- return result
341
+ return this.#client.executeCommands(this.#handle.uuid, JSON.stringify(actions), expression, JSON.stringify(parameters), batchId)
344
342
  }
345
343
 
346
344
  /**
@@ -623,12 +621,15 @@ export class PerspectiveProxy {
623
621
  }
624
622
 
625
623
  /**
626
- * The proposals of `instance` whose votes settled an edge, as this
627
- * agent's executor recorded them — the flow's history, sorted by URI.
624
+ * For each of `instances`, in order, the proposals whose votes settled an
625
+ * edge, as this agent's executor recorded them — the flow's history,
626
+ * sorted by URI (`fired: []` when none). One call covers up to 200
627
+ * instances (the executor refuses more with a 400); split a longer list
628
+ * into batches of 200.
628
629
  * Replaces the `resolvedAs` property proposals used to carry.
629
630
  */
630
- async flowFired(instance: string): Promise<string[]> {
631
- return await this.#client.flowFired(this.#handle.uuid, instance)
631
+ async flowFired(instances: string[]): Promise<FlowFiredEntry[]> {
632
+ return await this.#client.flowFired(this.#handle.uuid, instances)
632
633
  }
633
634
 
634
635
  /**
@@ -696,19 +697,18 @@ export class PerspectiveProxy {
696
697
  * keep its blocking thread busy until it completes; what's saved is the
697
698
  * serialise + network + client-deserialise tax on the result. Aborted
698
699
  * calls reject with `DOMException('Aborted', 'AbortError')` — match
699
- * `fetch()` for handling. Cached results bypass the round-trip entirely
700
- * and are returned synchronously, ignoring the signal.
700
+ * `fetch()` for handling. A call with `options` makes its own RPC.
701
+ *
702
+ * **Sharing:** concurrent identical calls without `options` share one RPC;
703
+ * each caller gets its own result object. Nothing is cached once the
704
+ * call settles: use a live query for repeated reads of the same data.
701
705
  *
702
706
  * @param query - SPARQL query string (read-only operations only)
703
707
  * @param options - Optional call options (e.g. AbortSignal for cancellation)
704
708
  * @returns Query results as parsed JSON
705
709
  */
706
710
  async querySparql<T = any>(query: string, options?: CallOptions): Promise<T> {
707
- const cached = getCachedResult(this.#handle.uuid, query);
708
- if (cached !== undefined) return cached as T;
709
- const result = await this.#client.querySparql(this.#handle.uuid, query, options);
710
- setCachedResult(this.#handle.uuid, query, result);
711
- return result as T;
711
+ return this.#client.querySparql<T>(this.#handle.uuid, query, options);
712
712
  }
713
713
 
714
714
  /**
@@ -722,9 +722,9 @@ export class PerspectiveProxy {
722
722
  * query over their union, whose rows carry `__subjectClass` and
723
723
  * `__subjectClasses` (#1238)
724
724
  * @param queryJson - Structured query as JSON string
725
- * @returns Object with `instances` array and `totalCount`
725
+ * @returns Object with `instances` array, and `totalCount` when the query sets `count: true`
726
726
  */
727
- async modelQuery(className: string | string[], queryJson: string, options?: CallOptions): Promise<{ instances: any[], totalCount: number }> {
727
+ async modelQuery(className: string | string[], queryJson: string, options?: CallOptions): Promise<{ instances: any[], totalCount?: number }> {
728
728
  return await this.#client.modelQuery(this.#handle.uuid, className, queryJson, options);
729
729
  }
730
730
 
@@ -825,9 +825,7 @@ export class PerspectiveProxy {
825
825
  * ```
826
826
  */
827
827
  async add(link: Link, status: LinkStatus = 'shared', batchId?: string): Promise<LinkExpression> {
828
- const result = await this.#client.addLink(this.#handle.uuid, link, status, batchId)
829
- invalidatePerspectiveCache(this.#handle.uuid);
830
- return result;
828
+ return this.#client.addLink(this.#handle.uuid, link, status, batchId)
831
829
  }
832
830
 
833
831
  /**
@@ -840,9 +838,7 @@ export class PerspectiveProxy {
840
838
  * @returns Array of created LinkExpressions
841
839
  */
842
840
  async addLinks(links: Link[], status: LinkStatus = 'shared', batchId?: string): Promise<LinkExpression[]> {
843
- const result = await this.#client.addLinks(this.#handle.uuid, links, status, batchId)
844
- invalidatePerspectiveCache(this.#handle.uuid);
845
- return result;
841
+ return this.#client.addLinks(this.#handle.uuid, links, status, batchId)
846
842
  }
847
843
 
848
844
  /**
@@ -853,9 +849,7 @@ export class PerspectiveProxy {
853
849
  * @returns Array of removed LinkExpressions
854
850
  */
855
851
  async removeLinks(links: LinkExpressionInput[], batchId?: string): Promise<LinkExpression[]> {
856
- const result = await this.#client.removeLinks(this.#handle.uuid, links, batchId)
857
- invalidatePerspectiveCache(this.#handle.uuid);
858
- return result;
852
+ return this.#client.removeLinks(this.#handle.uuid, links, batchId)
859
853
  }
860
854
 
861
855
  /**
@@ -867,9 +861,7 @@ export class PerspectiveProxy {
867
861
  * @returns Object containing results of the mutations
868
862
  */
869
863
  async linkMutations(mutations: LinkMutations, status: LinkStatus = 'shared'): Promise<LinkExpressionMutations> {
870
- const result = await this.#client.linkMutations(this.#handle.uuid, mutations, status)
871
- invalidatePerspectiveCache(this.#handle.uuid);
872
- return result;
864
+ return this.#client.linkMutations(this.#handle.uuid, mutations, status)
873
865
  }
874
866
 
875
867
  /**
@@ -898,9 +890,7 @@ export class PerspectiveProxy {
898
890
  * @param batchId - Optional batch ID to group this operation with others
899
891
  */
900
892
  async update(oldLink: LinkExpressionInput, newLink: Link, batchId?: string): Promise<LinkExpression> {
901
- const result = await this.#client.updateLink(this.#handle.uuid, oldLink, newLink, batchId)
902
- invalidatePerspectiveCache(this.#handle.uuid);
903
- return result;
893
+ return this.#client.updateLink(this.#handle.uuid, oldLink, newLink, batchId)
904
894
  }
905
895
 
906
896
  /**
@@ -948,9 +938,7 @@ export class PerspectiveProxy {
948
938
  } else {
949
939
  resolvedLink = link as LinkExpressionInput;
950
940
  }
951
- const result = await this.#client.removeLink(this.#handle.uuid, resolvedLink, batchId)
952
- invalidatePerspectiveCache(this.#handle.uuid);
953
- return result;
941
+ return this.#client.removeLink(this.#handle.uuid, resolvedLink, batchId)
954
942
  }
955
943
 
956
944
  /** Creates a new batch for grouping operations */
@@ -960,9 +948,7 @@ export class PerspectiveProxy {
960
948
 
961
949
  /** Commits a batch of operations */
962
950
  async commitBatch(batchId: string): Promise<LinkExpressionMutations> {
963
- const result = await this.#client.commitBatch(this.#handle.uuid, batchId)
964
- invalidatePerspectiveCache(this.#handle.uuid);
965
- return result;
951
+ return this.#client.commitBatch(this.#handle.uuid, batchId)
966
952
  }
967
953
 
968
954
  /**
@@ -1356,13 +1342,13 @@ export class PerspectiveProxy {
1356
1342
  }
1357
1343
 
1358
1344
  /**
1359
- * Get all SHACL shapes stored in this Perspective (one RPC call).
1360
- * The executor resolves all shapes in-process and returns them in bulk.
1345
+ * Get the SHACL shapes stored in this Perspective in one RPC call: all of
1346
+ * them, or only those named in `names` (unknown names are left out).
1361
1347
  * A shape that fails to decode is skipped with a `console.warn`, so it
1362
1348
  * does not hide the others.
1363
1349
  */
1364
- async getAllShacl(): Promise<Array<{name: string, shape: SHACLShape}>> {
1365
- const entries = await this.#client.getAllShacl(this.#handle.uuid);
1350
+ async getAllShacl(options?: { names?: string[] }): Promise<Array<{name: string, shape: SHACLShape}>> {
1351
+ const entries = await this.#client.getAllShacl(this.#handle.uuid, options?.names);
1366
1352
  const shapes: Array<{name: string, shape: SHACLShape}> = [];
1367
1353
  for (const { name, shapeUri, links } of entries) {
1368
1354
  try {
@@ -1640,7 +1626,6 @@ export class PerspectiveProxy {
1640
1626
  * record that the abstract class reads, under its own name. */
1641
1627
  async updateSubject(className: string, exprAddr: string, values: Record<string, any>, batchId?: string) {
1642
1628
  await this.#client.updateSubject(this.#handle.uuid, className, exprAddr, JSON.stringify(values), batchId);
1643
- invalidatePerspectiveCache(this.#handle.uuid);
1644
1629
  }
1645
1630
 
1646
1631
  /**
@@ -1660,44 +1645,27 @@ export class PerspectiveProxy {
1660
1645
  * const { baseUri } = await perspective.instanceCreate({ className: "Task", properties: { title: "Write" } });
1661
1646
  */
1662
1647
  async instanceCreate(body: InstanceCreate): Promise<InstanceCreated> {
1663
- const created = await this.#client.instanceCreate(this.#handle.uuid, body);
1664
- invalidatePerspectiveCache(this.#handle.uuid);
1665
- return created;
1648
+ return this.#client.instanceCreate(this.#handle.uuid, body);
1666
1649
  }
1667
1650
 
1668
1651
  /** Sets single-valued properties of an instance, validated; the others stay. See {@link instanceCreate}. */
1669
1652
  async instanceUpdate(body: InstanceUpdate): Promise<InstanceUpdated> {
1670
- const updated = await this.#client.instanceUpdate(this.#handle.uuid, body);
1671
- invalidatePerspectiveCache(this.#handle.uuid);
1672
- return updated;
1653
+ return this.#client.instanceUpdate(this.#handle.uuid, body);
1673
1654
  }
1674
1655
 
1675
1656
  /** Removes an instance and every link to and from it. See {@link instanceCreate}. */
1676
1657
  async instanceRemove(body: InstanceRemove): Promise<InstanceRemoved> {
1677
- // Outside a batch the links go one by one, so a rejection (`partiallyRemoved`) can
1678
- // come after some are gone: invalidate either way.
1679
- try {
1680
- return await this.#client.instanceRemove(this.#handle.uuid, body);
1681
- } finally {
1682
- invalidatePerspectiveCache(this.#handle.uuid);
1683
- }
1658
+ return this.#client.instanceRemove(this.#handle.uuid, body);
1684
1659
  }
1685
1660
 
1686
1661
  /** Adds an item to a collection of an instance, validated. See {@link instanceCreate}. */
1687
1662
  async instanceAddToCollection(body: InstanceAddToCollection): Promise<CollectionItemAdded> {
1688
- const added = await this.#client.instanceAddToCollection(this.#handle.uuid, body);
1689
- invalidatePerspectiveCache(this.#handle.uuid);
1690
- return added;
1663
+ return this.#client.instanceAddToCollection(this.#handle.uuid, body);
1691
1664
  }
1692
1665
 
1693
1666
  /** Removes an item from a collection of an instance. See {@link instanceCreate}. */
1694
1667
  async instanceRemoveFromCollection(body: InstanceRemoveFromCollection): Promise<CollectionItemRemoved> {
1695
- // Like instanceRemove, a rejection can come after some links are gone.
1696
- try {
1697
- return await this.#client.instanceRemoveFromCollection(this.#handle.uuid, body);
1698
- } finally {
1699
- invalidatePerspectiveCache(this.#handle.uuid);
1700
- }
1668
+ return this.#client.instanceRemoveFromCollection(this.#handle.uuid, body);
1701
1669
  }
1702
1670
 
1703
1671
  async getSubjectData<T>(subjectClass: T, exprAddr: string): Promise<T> {
@@ -1762,7 +1730,6 @@ export class PerspectiveProxy {
1762
1730
  const ctor = (subjectClass as any)?.constructor;
1763
1731
  if (typeof subjectClass === "object" && ctor && Object.prototype.hasOwnProperty.call(ctor, 'builtinUri')) {
1764
1732
  await this.#client.removeSubject(this.#handle.uuid, ctor.builtinUri, exprAddr, batchId);
1765
- invalidatePerspectiveCache(this.#handle.uuid);
1766
1733
  return;
1767
1734
  }
1768
1735
  let className = await this.stringOrTemplateObjectToSubjectClassName(subjectClass)
@@ -1773,7 +1740,6 @@ export class PerspectiveProxy {
1773
1740
  const markers = await this.get(new LinkQuery({ predicate: "ad4m://abstract" }));
1774
1741
  if (markers.some((link) => shapePattern.test(link.data.source))) {
1775
1742
  await this.#client.removeSubject(this.#handle.uuid, className, exprAddr, batchId);
1776
- invalidatePerspectiveCache(this.#handle.uuid);
1777
1743
  return;
1778
1744
  }
1779
1745
 
@@ -104,20 +104,4 @@ describe("TextContent", () => {
104
104
  await row.delete("batch");
105
105
  expect(calls[0]).toEqual(["removeSubject", "p", "ad4m://TextContent", "ad4m://m/1", "batch"]);
106
106
  });
107
-
108
- it("delete() through it drops the perspective's cached query results, like an update", async () => {
109
- const { setCachedResult, getCachedResult } = await import("../model/query-cache");
110
- const client: any = new Proxy({}, { get: () => async () => true });
111
- const { PerspectiveProxy } = await import("./PerspectiveProxy");
112
- const proxy = new PerspectiveProxy({ uuid: "p-cache" } as any, client);
113
- const row = new TextContent(proxy, "ad4m://m/1");
114
-
115
- setCachedResult("p-cache", "SELECT ?v", [{ v: "old" }]);
116
- await proxy.updateSubject("ad4m://TextContent", "ad4m://m/1", { text: "new" });
117
- expect(getCachedResult("p-cache", "SELECT ?v")).toBeUndefined();
118
-
119
- setCachedResult("p-cache", "SELECT ?v", [{ v: "old" }]);
120
- await row.delete();
121
- expect(getCachedResult("p-cache", "SELECT ?v")).toBeUndefined();
122
- });
123
107
  });
@@ -148,7 +148,7 @@ describe('PerspectiveProxy SHACL RPC delegation', () => {
148
148
 
149
149
  const shapes = await proxy.getAllShacl();
150
150
 
151
- expect(client.getAllShacl).toHaveBeenCalledWith('test-uuid');
151
+ expect(client.getAllShacl).toHaveBeenCalledWith('test-uuid', undefined);
152
152
  expect(shapes.length).toBe(2);
153
153
  expect(shapes[0].name).toBe('Message');
154
154
  expect(shapes[0].shape.targetClass).toBe('flux://Message');
@@ -1,30 +0,0 @@
1
- /**
2
- * Query Result TTL Cache
3
- *
4
- * Short-lived cache (200ms TTL) for SPARQL query results.
5
- * Prevents redundant queries during rapid render cycles where
6
- * multiple components issue the same query within milliseconds.
7
- *
8
- * Key: `perspectiveUUID + queryText`
9
- */
10
- /**
11
- * Get a cached query result if it exists and hasn't expired.
12
- */
13
- export declare function getCachedResult(perspectiveUUID: string, queryText: string): any | undefined;
14
- /**
15
- * Store a query result in the cache with TTL.
16
- */
17
- export declare function setCachedResult(perspectiveUUID: string, queryText: string, result: any, ttlMs?: number): void;
18
- /**
19
- * Invalidate all cache entries for a given perspective.
20
- * Called after write operations to ensure stale data isn't served.
21
- */
22
- export declare function invalidatePerspectiveCache(perspectiveUUID: string): void;
23
- /**
24
- * Clear all cache entries (useful for testing).
25
- */
26
- export declare function clearQueryCache(): void;
27
- /**
28
- * Get the current size of the cache (useful for testing).
29
- */
30
- export declare function queryCacheSize(): number;
@@ -1,66 +0,0 @@
1
- /**
2
- * Query Result TTL Cache
3
- *
4
- * Short-lived cache (200ms TTL) for SPARQL query results.
5
- * Prevents redundant queries during rapid render cycles where
6
- * multiple components issue the same query within milliseconds.
7
- *
8
- * Key: `perspectiveUUID + queryText`
9
- */
10
- const cache = new Map();
11
- const DEFAULT_TTL_MS = 200;
12
- function makeKey(perspectiveUUID, queryText) {
13
- return `${perspectiveUUID}:${queryText}`;
14
- }
15
- /**
16
- * Get a cached query result if it exists and hasn't expired.
17
- */
18
- export function getCachedResult(perspectiveUUID, queryText) {
19
- const key = makeKey(perspectiveUUID, queryText);
20
- const entry = cache.get(key);
21
- if (!entry)
22
- return undefined;
23
- if (Date.now() > entry.expiry) {
24
- cache.delete(key);
25
- return undefined;
26
- }
27
- return entry.result;
28
- }
29
- /**
30
- * Store a query result in the cache with TTL.
31
- */
32
- export function setCachedResult(perspectiveUUID, queryText, result, ttlMs = DEFAULT_TTL_MS) {
33
- // Lazy eviction of expired entries
34
- const now = Date.now();
35
- for (const [key, entry] of cache) {
36
- if (now > entry.expiry) {
37
- cache.delete(key);
38
- }
39
- }
40
- const cacheKey = makeKey(perspectiveUUID, queryText);
41
- cache.set(cacheKey, { result, expiry: now + ttlMs });
42
- }
43
- /**
44
- * Invalidate all cache entries for a given perspective.
45
- * Called after write operations to ensure stale data isn't served.
46
- */
47
- export function invalidatePerspectiveCache(perspectiveUUID) {
48
- const prefix = perspectiveUUID + ':';
49
- for (const [key] of cache) {
50
- if (key.startsWith(prefix)) {
51
- cache.delete(key);
52
- }
53
- }
54
- }
55
- /**
56
- * Clear all cache entries (useful for testing).
57
- */
58
- export function clearQueryCache() {
59
- cache.clear();
60
- }
61
- /**
62
- * Get the current size of the cache (useful for testing).
63
- */
64
- export function queryCacheSize() {
65
- return cache.size;
66
- }
@@ -1,54 +0,0 @@
1
- import { getCachedResult, setCachedResult, invalidatePerspectiveCache, clearQueryCache, queryCacheSize } from './query-cache';
2
-
3
- describe('query-cache', () => {
4
- beforeEach(() => {
5
- clearQueryCache();
6
- });
7
-
8
- describe('lazy eviction', () => {
9
- it('should remove expired entries when setting a new one', () => {
10
- // Insert with a very short TTL
11
- setCachedResult('p1', 'SELECT ?x', 'result1', 1);
12
- expect(queryCacheSize()).toBe(1);
13
-
14
- // Wait for expiry
15
- const start = Date.now();
16
- while (Date.now() - start < 5) { /* busy wait 5ms */ }
17
-
18
- // Expired entry should still be in the map (not yet evicted)
19
- // but getCachedResult should return undefined
20
- expect(getCachedResult('p1', 'SELECT ?x')).toBeUndefined();
21
-
22
- // Setting a new entry should evict the expired one
23
- setCachedResult('p2', 'SELECT ?y', 'result2', 10000);
24
- // Only the new entry should remain
25
- expect(queryCacheSize()).toBe(1);
26
- expect(getCachedResult('p2', 'SELECT ?y')).toBe('result2');
27
- });
28
- });
29
-
30
- describe('invalidatePerspectiveCache', () => {
31
- it('should remove all entries for a specific perspective', () => {
32
- setCachedResult('p1', 'query1', 'r1', 10000);
33
- setCachedResult('p1', 'query2', 'r2', 10000);
34
- setCachedResult('p2', 'query1', 'r3', 10000);
35
- expect(queryCacheSize()).toBe(3);
36
-
37
- invalidatePerspectiveCache('p1');
38
-
39
- expect(queryCacheSize()).toBe(1);
40
- expect(getCachedResult('p1', 'query1')).toBeUndefined();
41
- expect(getCachedResult('p1', 'query2')).toBeUndefined();
42
- expect(getCachedResult('p2', 'query1')).toBe('r3');
43
- });
44
-
45
- it('should not affect other perspectives', () => {
46
- setCachedResult('p1', 'q', 'r1', 10000);
47
- setCachedResult('p2', 'q', 'r2', 10000);
48
-
49
- invalidatePerspectiveCache('p3');
50
-
51
- expect(queryCacheSize()).toBe(2);
52
- });
53
- });
54
- });
@@ -1,79 +0,0 @@
1
- /**
2
- * Query Result TTL Cache
3
- *
4
- * Short-lived cache (200ms TTL) for SPARQL query results.
5
- * Prevents redundant queries during rapid render cycles where
6
- * multiple components issue the same query within milliseconds.
7
- *
8
- * Key: `perspectiveUUID + queryText`
9
- */
10
-
11
- interface CacheEntry {
12
- result: any;
13
- expiry: number;
14
- }
15
-
16
- const cache = new Map<string, CacheEntry>();
17
-
18
- const DEFAULT_TTL_MS = 200;
19
-
20
- function makeKey(perspectiveUUID: string, queryText: string): string {
21
- return `${perspectiveUUID}:${queryText}`;
22
- }
23
-
24
- /**
25
- * Get a cached query result if it exists and hasn't expired.
26
- */
27
- export function getCachedResult(perspectiveUUID: string, queryText: string): any | undefined {
28
- const key = makeKey(perspectiveUUID, queryText);
29
- const entry = cache.get(key);
30
- if (!entry) return undefined;
31
- if (Date.now() > entry.expiry) {
32
- cache.delete(key);
33
- return undefined;
34
- }
35
- return entry.result;
36
- }
37
-
38
- /**
39
- * Store a query result in the cache with TTL.
40
- */
41
- export function setCachedResult(perspectiveUUID: string, queryText: string, result: any, ttlMs: number = DEFAULT_TTL_MS): void {
42
- // Lazy eviction of expired entries
43
- const now = Date.now();
44
- for (const [key, entry] of cache) {
45
- if (now > entry.expiry) {
46
- cache.delete(key);
47
- }
48
- }
49
-
50
- const cacheKey = makeKey(perspectiveUUID, queryText);
51
- cache.set(cacheKey, { result, expiry: now + ttlMs });
52
- }
53
-
54
- /**
55
- * Invalidate all cache entries for a given perspective.
56
- * Called after write operations to ensure stale data isn't served.
57
- */
58
- export function invalidatePerspectiveCache(perspectiveUUID: string): void {
59
- const prefix = perspectiveUUID + ':';
60
- for (const [key] of cache) {
61
- if (key.startsWith(prefix)) {
62
- cache.delete(key);
63
- }
64
- }
65
- }
66
-
67
- /**
68
- * Clear all cache entries (useful for testing).
69
- */
70
- export function clearQueryCache(): void {
71
- cache.clear();
72
- }
73
-
74
- /**
75
- * Get the current size of the cache (useful for testing).
76
- */
77
- export function queryCacheSize(): number {
78
- return cache.size;
79
- }