@coasys/ad4m 0.13.0-test-4 → 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 (72) hide show
  1. package/lib/index.cjs +1507 -1372
  2. package/lib/index.js +1505 -1370
  3. package/lib/src/Ad4mClient.d.ts +1 -1
  4. package/lib/src/Ad4mClient.js +12 -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.d.ts +20 -7
  14. package/lib/src/model/Ad4mModel.js +102 -108
  15. package/lib/src/model/Ad4mModel.test.js +688 -1434
  16. package/lib/src/model/ModelQueryBuilder.d.ts +6 -6
  17. package/lib/src/model/ModelQueryBuilder.js +29 -20
  18. package/lib/src/model/Subject.js +6 -6
  19. package/lib/src/model/hydration.d.ts +2 -39
  20. package/lib/src/model/hydration.js +2 -260
  21. package/lib/src/model/query-surreal.d.ts +44 -0
  22. package/lib/src/model/query-surreal.js +249 -0
  23. package/lib/src/model/query-utils.d.ts +1 -0
  24. package/lib/src/model/query-utils.js +46 -1
  25. package/lib/src/model/relation-filtering.test.js +15 -15
  26. package/lib/src/model/surreal-utils.d.ts +42 -0
  27. package/lib/src/model/surreal-utils.js +128 -0
  28. package/lib/src/model/types.d.ts +4 -6
  29. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -1
  30. package/lib/src/perspectives/PerspectiveClient.js +15 -13
  31. package/lib/src/perspectives/PerspectiveProxy.d.ts +14 -0
  32. package/lib/src/perspectives/PerspectiveProxy.js +16 -3
  33. package/lib/src/perspectives/PerspectiveResolver.d.ts +1 -0
  34. package/lib/src/perspectives/PerspectiveResolver.js +11 -0
  35. package/lib/src/runtime/RuntimeResolver.d.ts +1 -28
  36. package/lib/src/runtime/RuntimeResolver.js +4 -197
  37. package/lib/src/schema.gql +1 -27
  38. package/lib/src/shacl/SHACLShape.test.js +0 -82
  39. package/package.json +11 -8
  40. package/src/Ad4mClient.test.ts +14 -4
  41. package/src/Ad4mClient.ts +12 -1
  42. package/src/agent/AgentClient.ts +84 -2
  43. package/src/cache/PersistentCache.ts +145 -0
  44. package/src/cache/cache.test.ts +713 -0
  45. package/src/expression/ExpressionClient.ts +137 -3
  46. package/src/index.ts +1 -0
  47. package/src/model/Ad4mModel.test.ts +59 -358
  48. package/src/model/Ad4mModel.ts +112 -108
  49. package/src/model/ModelQueryBuilder.ts +29 -17
  50. package/src/model/hydration.ts +2 -279
  51. package/src/model/query-utils.ts +47 -2
  52. package/src/model/types.ts +5 -6
  53. package/src/perspectives/PerspectiveClient.ts +26 -17
  54. package/src/perspectives/PerspectiveProxy.ts +24 -3
  55. package/lib/src/model/hydration-batch.d.ts +0 -34
  56. package/lib/src/model/hydration-batch.js +0 -147
  57. package/lib/src/model/hydration-batching.test.d.ts +0 -7
  58. package/lib/src/model/hydration-batching.test.js +0 -456
  59. package/lib/src/model/model-manifest.d.ts +0 -41
  60. package/lib/src/model/model-manifest.js +0 -11
  61. package/lib/src/model/query-cache.test.d.ts +0 -1
  62. package/lib/src/model/query-cache.test.js +0 -43
  63. package/lib/src/model/query-sparql-batch.d.ts +0 -17
  64. package/lib/src/model/query-sparql-batch.js +0 -260
  65. package/lib/src/model/query-sparql.test.d.ts +0 -1
  66. package/lib/src/model/query-sparql.test.js +0 -312
  67. package/lib/src/model/subscription-delta.test.d.ts +0 -24
  68. package/lib/src/model/subscription-delta.test.js +0 -180
  69. package/lib/src/model/subscription-pool.d.ts +0 -39
  70. package/lib/src/model/subscription-pool.js +0 -165
  71. package/lib/src/perspectives/PerspectiveClient.test.d.ts +0 -1
  72. package/lib/src/perspectives/PerspectiveClient.test.js +0 -224
@@ -333,86 +333,4 @@ describe('SHACLShape', () => {
333
333
  expect(prop.remover).toEqual(original.properties[0].remover);
334
334
  });
335
335
  });
336
- describe('sh:in round-trip', () => {
337
- it('preserves sh:in enum values through toLinks() → fromLinks()', () => {
338
- const original = new SHACLShape('test://Model');
339
- original.addProperty({
340
- name: 'status',
341
- path: 'test://status',
342
- datatype: 'xsd:string',
343
- in: [
344
- { value: 'active', label: 'Active' },
345
- { value: 'inactive', label: 'Inactive' },
346
- { value: 'archived' },
347
- ],
348
- });
349
- const links = original.toLinks();
350
- // Verify sh:in link was created
351
- const inLink = links.find(l => l.predicate === 'sh://in');
352
- expect(inLink).toBeDefined();
353
- expect(inLink.target).toContain('literal:string:');
354
- // Reconstruct and verify
355
- const reconstructed = SHACLShape.fromLinks(links, 'test://ModelShape');
356
- expect(reconstructed.properties[0].in).toBeDefined();
357
- expect(reconstructed.properties[0].in).toEqual([
358
- { value: 'active', label: 'Active' },
359
- { value: 'inactive', label: 'Inactive' },
360
- { value: 'archived' },
361
- ]);
362
- });
363
- it('handles sh:in with special characters in values', () => {
364
- const original = new SHACLShape('test://Model');
365
- original.addProperty({
366
- name: 'category',
367
- path: 'test://category',
368
- in: [
369
- { value: 'food & drink', label: 'Food & Drink' },
370
- { value: 'arts/crafts' },
371
- ],
372
- });
373
- const links = original.toLinks();
374
- const reconstructed = SHACLShape.fromLinks(links, 'test://ModelShape');
375
- expect(reconstructed.properties[0].in).toEqual(original.properties[0].in);
376
- });
377
- it('handles sh:in with empty array (no link created)', () => {
378
- const original = new SHACLShape('test://Model');
379
- original.addProperty({
380
- name: 'field',
381
- path: 'test://field',
382
- in: [],
383
- });
384
- const links = original.toLinks();
385
- const inLink = links.find(l => l.predicate === 'sh://in');
386
- expect(inLink).toBeUndefined();
387
- });
388
- it('handles sh:in with literal://string: prefix variant', () => {
389
- // fromLinks should handle both `literal:string:` and `literal://string:` prefixes
390
- const links = [
391
- { source: 'test://ModelShape', predicate: 'sh://targetClass', target: 'test://Model' },
392
- { source: 'test://ModelShape', predicate: 'sh://property', target: 'test://Model.status' },
393
- { source: 'test://Model.status', predicate: 'sh://path', target: 'test://status' },
394
- { source: 'test://Model.status', predicate: 'sh://in', target: 'literal://string:[{"value":"a"},{"value":"b"}]' },
395
- ];
396
- const reconstructed = SHACLShape.fromLinks(links, 'test://ModelShape');
397
- expect(reconstructed.properties[0].in).toEqual([
398
- { value: 'a' },
399
- { value: 'b' },
400
- ]);
401
- });
402
- it('preserves sh:in through toJSON() → fromJSON()', () => {
403
- const original = new SHACLShape('test://Model');
404
- original.addProperty({
405
- name: 'priority',
406
- path: 'test://priority',
407
- in: [
408
- { value: 'high', label: 'High' },
409
- { value: 'medium', label: 'Medium' },
410
- { value: 'low', label: 'Low' },
411
- ],
412
- });
413
- const json = original.toJSON();
414
- const reconstructed = SHACLShape.fromJSON(json);
415
- expect(reconstructed.properties[0].in).toEqual(original.properties[0].in);
416
- });
417
- });
418
336
  });
package/package.json CHANGED
@@ -5,6 +5,12 @@
5
5
  "module": "lib/index.js",
6
6
  "types": "lib/src/index.d.ts",
7
7
  "type": "module",
8
+ "scripts": {
9
+ "build": "patch-package && tsc && pnpm run bundle",
10
+ "bundle": "rollup -c rollup.config.js",
11
+ "test": "jest --forceExit",
12
+ "generate:api-types": "cd ../rust-executor && TS_RS_EXPORT_DIR=../core/src/generated/api/ cargo test --lib 2>/dev/null && echo \"API types generated to core/src/generated/api/\""
13
+ },
8
14
  "repository": {
9
15
  "type": "git",
10
16
  "url": "git+https://github.com/coasys/ad4m.git"
@@ -48,11 +54,8 @@
48
54
  "ws": "8.13.0"
49
55
  },
50
56
  "patchedDependencies": {},
51
- "version": "0.13.0-test-4",
52
- "scripts": {
53
- "build": "patch-package && tsc && pnpm run bundle",
54
- "bundle": "rollup -c rollup.config.js",
55
- "test": "jest --forceExit",
56
- "generate:api-types": "cd ../rust-executor && TS_RS_EXPORT_DIR=../core/src/generated/api/ cargo test --lib 2>/dev/null && echo \"API types generated to core/src/generated/api/\""
57
- }
58
- }
57
+ "pnpm": {
58
+ "patchedDependencies": {}
59
+ },
60
+ "version": "0.13.0-test-6"
61
+ }
@@ -148,9 +148,14 @@ const MOCK_RESPONSES: Record<string, RpcHandler> = {
148
148
  language: { address: 'lang://test' }, proof: { valid: true },
149
149
  };
150
150
  },
151
- 'expression.getMany': [
152
- { author: 'did:test:1', timestamp: '2023-01-01', data: { type: 'test' }, language: { address: 'lang://test' }, proof: { valid: true } },
153
- ],
151
+ 'expression.getMany': (p: Record<string, unknown>) => {
152
+ // Return one result per URL (aligned by index), matching real API behavior
153
+ const urls = (p.urls || []) as string[];
154
+ return urls.map((url: string) => ({
155
+ author: 'did:test:1', timestamp: '2023-01-01', data: { type: 'test' },
156
+ language: { address: 'lang://test' }, proof: { valid: true },
157
+ }));
158
+ },
154
159
  'expression.create': 'Qm-expression-hash',
155
160
  'expression.interactions': [{ label: 'interact1', name: 'doSomething', parameters: [] }],
156
161
  'expression.interact': 'interaction-result',
@@ -348,6 +353,9 @@ afterAll(() => {
348
353
  beforeEach(() => {
349
354
  lastRpcCall = null;
350
355
  MockWebSocket.instances = [];
356
+ // Clear caches to prevent cross-test interference
357
+ ad4m.agent.clearByDidCache();
358
+ ad4m.expression.clearCache();
351
359
  });
352
360
 
353
361
  // ===================== AGENT TESTS =====================
@@ -857,7 +865,9 @@ describe('ExpressionClient', () => {
857
865
 
858
866
  test('getMany() returns multiple expressions', async () => {
859
867
  const exprs = await ad4m.expression.getMany(['url1', 'url2']);
860
- expect(exprs).toHaveLength(1);
868
+ expect(exprs).toHaveLength(2);
869
+ expect(exprs[0].author).toBe('did:test:1');
870
+ expect(exprs[1].author).toBe('did:test:1');
861
871
  });
862
872
 
863
873
  test('getRaw() returns raw expression', async () => {
package/src/Ad4mClient.ts CHANGED
@@ -6,6 +6,7 @@ import { RuntimeClient } from './runtime/RuntimeClient'
6
6
  import { ExpressionClient } from './expression/ExpressionClient'
7
7
  import { AIClient } from './ai/AIClient'
8
8
  import { ApiClient } from './apiClient'
9
+ import { Ad4mModel } from './model/Ad4mModel'
9
10
 
10
11
  /**
11
12
  * Client for the Ad4m interface wrapping WebSocket RPC calls
@@ -42,6 +43,15 @@ export class Ad4mClient {
42
43
  this.#perspectiveClient.setNeighbourhoodClient(this.#neighbourhoodClient)
43
44
  this.#perspectiveClient.setAIClient(this.#aiClient)
44
45
  this.#runtimeClient = new RuntimeClient(baseUrl, token, subscribe, this.#apiClient)
46
+
47
+ // Register with AD4M DevTools if the bridge is installed (e.g. browser extension)
48
+ try {
49
+ const dt = (globalThis as any).__AD4M_DEVTOOLS__;
50
+ if (dt) {
51
+ dt._client = this;
52
+ dt._Ad4mModel = Ad4mModel;
53
+ }
54
+ } catch {}
45
55
  }
46
56
 
47
57
  get agent(): AgentClient {
@@ -80,8 +90,9 @@ export class Ad4mClient {
80
90
  this.#agentClient.subscribeAppsChanged()
81
91
  }
82
92
 
83
- /** Close all event connections */
93
+ /** Close all event connections and clear in-memory caches */
84
94
  close(): void {
95
+ this.#agentClient.clearByDidCache()
85
96
  this.#apiClient.closeAll()
86
97
  }
87
98
  }
@@ -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
+ }