@coasys/ad4m 0.13.0-test-5 → 0.13.0-test-6

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 (63) hide show
  1. package/lib/index.cjs +610 -337
  2. package/lib/index.js +608 -338
  3. package/lib/src/Ad4mClient.d.ts +1 -1
  4. package/lib/src/Ad4mClient.js +2 -1
  5. package/lib/src/agent/AgentClient.d.ts +16 -0
  6. package/lib/src/agent/AgentClient.js +74 -4
  7. package/lib/src/cache/PersistentCache.d.ts +40 -0
  8. package/lib/src/cache/PersistentCache.js +139 -0
  9. package/lib/src/expression/ExpressionClient.d.ts +8 -0
  10. package/lib/src/expression/ExpressionClient.js +113 -5
  11. package/lib/src/index.d.ts +1 -0
  12. package/lib/src/index.js +1 -0
  13. package/lib/src/model/Ad4mModel.js +29 -57
  14. package/lib/src/model/Ad4mModel.test.js +688 -1434
  15. package/lib/src/model/ModelQueryBuilder.js +0 -9
  16. package/lib/src/model/Subject.js +6 -6
  17. package/lib/src/model/query-surreal.d.ts +44 -0
  18. package/lib/src/model/query-surreal.js +249 -0
  19. package/lib/src/model/relation-filtering.test.js +15 -15
  20. package/lib/src/model/surreal-utils.d.ts +42 -0
  21. package/lib/src/model/surreal-utils.js +128 -0
  22. package/lib/src/model/types.d.ts +0 -1
  23. package/lib/src/perspectives/PerspectiveClient.d.ts +0 -1
  24. package/lib/src/perspectives/PerspectiveClient.js +5 -13
  25. package/lib/src/perspectives/PerspectiveProxy.js +0 -3
  26. package/lib/src/perspectives/PerspectiveResolver.d.ts +1 -0
  27. package/lib/src/perspectives/PerspectiveResolver.js +11 -0
  28. package/lib/src/runtime/RuntimeResolver.d.ts +1 -28
  29. package/lib/src/runtime/RuntimeResolver.js +4 -197
  30. package/lib/src/schema.gql +1 -27
  31. package/lib/src/shacl/SHACLShape.test.js +0 -82
  32. package/package.json +1 -1
  33. package/src/Ad4mClient.test.ts +14 -4
  34. package/src/Ad4mClient.ts +2 -1
  35. package/src/agent/AgentClient.ts +84 -2
  36. package/src/cache/PersistentCache.ts +145 -0
  37. package/src/cache/cache.test.ts +713 -0
  38. package/src/expression/ExpressionClient.ts +137 -3
  39. package/src/index.ts +1 -0
  40. package/src/model/Ad4mModel.test.ts +1 -61
  41. package/src/model/Ad4mModel.ts +31 -57
  42. package/src/model/ModelQueryBuilder.ts +0 -6
  43. package/src/model/types.ts +1 -1
  44. package/src/perspectives/PerspectiveClient.ts +7 -17
  45. package/src/perspectives/PerspectiveProxy.ts +0 -3
  46. package/lib/src/model/hydration-batch.d.ts +0 -34
  47. package/lib/src/model/hydration-batch.js +0 -147
  48. package/lib/src/model/hydration-batching.test.d.ts +0 -7
  49. package/lib/src/model/hydration-batching.test.js +0 -456
  50. package/lib/src/model/model-manifest.d.ts +0 -41
  51. package/lib/src/model/model-manifest.js +0 -11
  52. package/lib/src/model/query-cache.test.d.ts +0 -1
  53. package/lib/src/model/query-cache.test.js +0 -43
  54. package/lib/src/model/query-sparql-batch.d.ts +0 -17
  55. package/lib/src/model/query-sparql-batch.js +0 -260
  56. package/lib/src/model/query-sparql.test.d.ts +0 -1
  57. package/lib/src/model/query-sparql.test.js +0 -312
  58. package/lib/src/model/subscription-delta.test.d.ts +0 -24
  59. package/lib/src/model/subscription-delta.test.js +0 -180
  60. package/lib/src/model/subscription-pool.d.ts +0 -39
  61. package/lib/src/model/subscription-pool.js +0 -165
  62. package/lib/src/perspectives/PerspectiveClient.test.d.ts +0 -1
  63. package/lib/src/perspectives/PerspectiveClient.test.js +0 -224
@@ -14,6 +14,7 @@ import { AgentStatus } from "./AgentStatus";
14
14
  import { LinkMutations, LinkExpression } from "../links/Links";
15
15
  import { PerspectiveClient } from "../perspectives/PerspectiveClient";
16
16
  import { VerificationRequestResult } from "../runtime/RuntimeTypes";
17
+ import { PersistentCache, createPersistentCache } from "../cache/PersistentCache";
17
18
  import type {
18
19
  GenerateAgentRequest,
19
20
  ImportAgentRequest,
@@ -48,6 +49,16 @@ export class AgentClient {
48
49
  #computeLogUpdatedCallbacks: ComputeLogUpdatedCallback[];
49
50
  #unsubscribers: (() => void)[];
50
51
 
52
+ // ── byDID cache ────────────────────────────────────────────────────
53
+ // L1: in-memory promise cache with timestamps for TTL
54
+ #memCache = new Map<string, { promise: Promise<Agent>; ts: number }>();
55
+ // L2: persistent cache (IndexedDB in browser, NullCache in Node)
56
+ #persistent: PersistentCache<Agent>;
57
+ // Self-DID for event-driven invalidation (no TTL for own profile)
58
+ #selfDid: string | null = null;
59
+ /** TTL for remote (non-self) agent profiles in L1 cache (ms). */
60
+ static REMOTE_AGENT_TTL_MS = 5 * 60_000; // 5 minutes
61
+
51
62
  constructor(baseUrl: string, token?: string, subscribe: boolean = true, sharedApiClient?: ApiClient) {
52
63
  this.#baseUrl = baseUrl;
53
64
  this.#token = token;
@@ -58,6 +69,7 @@ export class AgentClient {
58
69
  this.#hostingUserInfoChangedCallbacks = [];
59
70
  this.#computeLogUpdatedCallbacks = [];
60
71
  this.#unsubscribers = [];
72
+ this.#persistent = createPersistentCache<Agent>('ad4m-agent-cache', 'agents');
61
73
 
62
74
  if (subscribe) {
63
75
  this.subscribeAgentUpdated();
@@ -99,7 +111,66 @@ export class AgentClient {
99
111
  }
100
112
 
101
113
  async byDID(did: string): Promise<Agent> {
102
- return this.#apiClient.call<Agent>('agent.byDid', { did });
114
+ const now = Date.now();
115
+ const cached = this.#memCache.get(did);
116
+
117
+ if (cached) {
118
+ const isSelf = did === this.#selfDid;
119
+ // Self-DID: L1 always valid (event-driven invalidation)
120
+ // Remote DID: L1 valid within TTL
121
+ if (isSelf || (now - cached.ts) < AgentClient.REMOTE_AGENT_TTL_MS) {
122
+ return cached.promise;
123
+ }
124
+ }
125
+
126
+ // Deduplicate: store the promise immediately so concurrent calls share one RPC
127
+ const promise = (async () => {
128
+ // L2: check persistent cache before network
129
+ const persisted = await this.#persistent.get(did);
130
+ if (persisted) {
131
+ return persisted;
132
+ }
133
+
134
+ // L3: network fetch
135
+ const result = await this.#apiClient.call<Agent>('agent.byDid', { did });
136
+ this.#persistent.put(did, result); // fire-and-forget write to L2
137
+ return result;
138
+ })();
139
+
140
+ this.#memCache.set(did, { promise, ts: now });
141
+
142
+ // Clean up on failure so next call retries
143
+ promise.catch(() => {
144
+ if (this.#memCache.get(did)?.promise === promise) {
145
+ this.#memCache.delete(did);
146
+ }
147
+ });
148
+
149
+ return promise;
150
+ }
151
+
152
+ /**
153
+ * Set the current agent's own DID.
154
+ * The self-DID receives event-driven invalidation and is never TTL-expired.
155
+ */
156
+ setSelfDid(did: string): void {
157
+ this.#selfDid = did;
158
+ }
159
+
160
+ /**
161
+ * Invalidate a specific DID's cache entry in both L1 and L2.
162
+ */
163
+ invalidateByDid(did: string): void {
164
+ this.#memCache.delete(did);
165
+ this.#persistent.delete(did); // fire-and-forget
166
+ }
167
+
168
+ /**
169
+ * Clear the entire L1 (memory) byDID cache.
170
+ * L2 (IndexedDB) is preserved — agent data remains valid across sessions.
171
+ */
172
+ clearByDidCache(): void {
173
+ this.#memCache.clear();
103
174
  }
104
175
 
105
176
  async updatePublicPerspective(perspective: PerspectiveInput): Promise<Agent> {
@@ -175,7 +246,18 @@ export class AgentClient {
175
246
  subscribeAgentUpdated() {
176
247
  const unsub = this.#apiClient.subscribe((data) => {
177
248
  if (data.type === 'agent-updated') {
178
- this.#updatedCallbacks.forEach((cb) => cb((data.agent || data) as Agent));
249
+ const agent = (data.agent || data) as Agent;
250
+
251
+ // Update L1 and L2 cache from the event payload
252
+ if (agent.did) {
253
+ this.#memCache.set(agent.did, {
254
+ promise: Promise.resolve(agent),
255
+ ts: Date.now(),
256
+ });
257
+ this.#persistent.put(agent.did, agent); // fire-and-forget
258
+ }
259
+
260
+ this.#updatedCallbacks.forEach((cb) => cb(agent));
179
261
  }
180
262
  });
181
263
  this.#unsubscribers.push(unsub);
@@ -0,0 +1,145 @@
1
+ /**
2
+ * PersistentCache — two-tier persistent key-value cache abstraction.
3
+ *
4
+ * Provides an IndexedDB-backed implementation for browsers and a no-op
5
+ * NullCache fallback for Node.js / environments without IndexedDB.
6
+ *
7
+ * Design goals:
8
+ * - Lazy open: IDB connection is deferred until first access
9
+ * - Fire-and-forget writes: put() resolves immediately (best-effort persistence)
10
+ * - Graceful degradation: all IDB errors resolve (never reject), so callers
11
+ * never need try/catch around cache operations
12
+ * - Tree-shakeable: import only what you need
13
+ */
14
+
15
+ // ── Interface ────────────────────────────────────────────────────────
16
+
17
+ export interface PersistentCache<T = unknown> {
18
+ get(key: string): Promise<T | undefined>;
19
+ put(key: string, value: T): Promise<void>;
20
+ delete(key: string): Promise<void>;
21
+ clear(): Promise<void>;
22
+ }
23
+
24
+ // ── IndexedDB Implementation ─────────────────────────────────────────
25
+
26
+ export class IDBCache<T = unknown> implements PersistentCache<T> {
27
+ #dbName: string;
28
+ #storeName: string;
29
+ #dbPromise: Promise<IDBDatabase> | null = null;
30
+ #version = 1;
31
+
32
+ constructor(dbName: string, storeName: string) {
33
+ this.#dbName = dbName;
34
+ this.#storeName = storeName;
35
+ }
36
+
37
+ #open(): Promise<IDBDatabase> {
38
+ if (!this.#dbPromise) {
39
+ this.#dbPromise = new Promise<IDBDatabase>((resolve, reject) => {
40
+ const storeName = this.#storeName;
41
+ const req = indexedDB.open(this.#dbName, this.#version);
42
+ req.onupgradeneeded = () => {
43
+ const db = req.result;
44
+ if (!db.objectStoreNames.contains(storeName)) {
45
+ db.createObjectStore(storeName);
46
+ }
47
+ };
48
+ req.onsuccess = () => resolve(req.result);
49
+ req.onerror = () => reject(req.error);
50
+ });
51
+ }
52
+ return this.#dbPromise;
53
+ }
54
+
55
+ async get(key: string): Promise<T | undefined> {
56
+ try {
57
+ const db = await this.#open();
58
+ return new Promise<T | undefined>((resolve) => {
59
+ const tx = db.transaction(this.#storeName, 'readonly');
60
+ const store = tx.objectStore(this.#storeName);
61
+ const req = store.get(key);
62
+ req.onsuccess = () => resolve(req.result ?? undefined);
63
+ req.onerror = () => resolve(undefined);
64
+ });
65
+ } catch {
66
+ return undefined;
67
+ }
68
+ }
69
+
70
+ async put(key: string, value: T): Promise<void> {
71
+ try {
72
+ const db = await this.#open();
73
+ return new Promise<void>((resolve) => {
74
+ const tx = db.transaction(this.#storeName, 'readwrite');
75
+ const store = tx.objectStore(this.#storeName);
76
+ store.put(value, key);
77
+ tx.oncomplete = () => resolve();
78
+ tx.onerror = () => resolve(); // fire-and-forget
79
+ });
80
+ } catch {
81
+ // degrade gracefully
82
+ }
83
+ }
84
+
85
+ async delete(key: string): Promise<void> {
86
+ try {
87
+ const db = await this.#open();
88
+ return new Promise<void>((resolve) => {
89
+ const tx = db.transaction(this.#storeName, 'readwrite');
90
+ const store = tx.objectStore(this.#storeName);
91
+ store.delete(key);
92
+ tx.oncomplete = () => resolve();
93
+ tx.onerror = () => resolve();
94
+ });
95
+ } catch {
96
+ // degrade gracefully
97
+ }
98
+ }
99
+
100
+ async clear(): Promise<void> {
101
+ try {
102
+ const db = await this.#open();
103
+ return new Promise<void>((resolve) => {
104
+ const tx = db.transaction(this.#storeName, 'readwrite');
105
+ const store = tx.objectStore(this.#storeName);
106
+ store.clear();
107
+ tx.oncomplete = () => resolve();
108
+ tx.onerror = () => resolve();
109
+ });
110
+ } catch {
111
+ // degrade gracefully
112
+ }
113
+ }
114
+ }
115
+
116
+ // ── NullCache (no-op fallback for Node.js) ───────────────────────────
117
+
118
+ export class NullCache<T = unknown> implements PersistentCache<T> {
119
+ async get(_key: string): Promise<T | undefined> { return undefined; }
120
+ async put(_key: string, _value: T): Promise<void> {}
121
+ async delete(_key: string): Promise<void> {}
122
+ async clear(): Promise<void> {}
123
+ }
124
+
125
+ // ── Factory ──────────────────────────────────────────────────────────
126
+
127
+ /**
128
+ * Create a PersistentCache backed by IndexedDB (browser) or NullCache (Node.js).
129
+ *
130
+ * @param dbName - IndexedDB database name
131
+ * @param storeName - IndexedDB object store name
132
+ */
133
+ export function createPersistentCache<T = unknown>(
134
+ dbName: string,
135
+ storeName: string,
136
+ ): PersistentCache<T> {
137
+ try {
138
+ if (typeof indexedDB !== 'undefined') {
139
+ return new IDBCache<T>(dbName, storeName);
140
+ }
141
+ } catch {
142
+ // indexedDB access threw (e.g. in a worker with restricted globals)
143
+ }
144
+ return new NullCache<T>();
145
+ }