@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.
- package/lib/index.cjs +610 -337
- package/lib/index.js +608 -338
- package/lib/src/Ad4mClient.d.ts +1 -1
- package/lib/src/Ad4mClient.js +2 -1
- package/lib/src/agent/AgentClient.d.ts +16 -0
- package/lib/src/agent/AgentClient.js +74 -4
- package/lib/src/cache/PersistentCache.d.ts +40 -0
- package/lib/src/cache/PersistentCache.js +139 -0
- package/lib/src/expression/ExpressionClient.d.ts +8 -0
- package/lib/src/expression/ExpressionClient.js +113 -5
- package/lib/src/index.d.ts +1 -0
- package/lib/src/index.js +1 -0
- package/lib/src/model/Ad4mModel.js +29 -57
- package/lib/src/model/Ad4mModel.test.js +688 -1434
- package/lib/src/model/ModelQueryBuilder.js +0 -9
- package/lib/src/model/Subject.js +6 -6
- package/lib/src/model/query-surreal.d.ts +44 -0
- package/lib/src/model/query-surreal.js +249 -0
- package/lib/src/model/relation-filtering.test.js +15 -15
- package/lib/src/model/surreal-utils.d.ts +42 -0
- package/lib/src/model/surreal-utils.js +128 -0
- package/lib/src/model/types.d.ts +0 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +0 -1
- package/lib/src/perspectives/PerspectiveClient.js +5 -13
- package/lib/src/perspectives/PerspectiveProxy.js +0 -3
- package/lib/src/perspectives/PerspectiveResolver.d.ts +1 -0
- package/lib/src/perspectives/PerspectiveResolver.js +11 -0
- package/lib/src/runtime/RuntimeResolver.d.ts +1 -28
- package/lib/src/runtime/RuntimeResolver.js +4 -197
- package/lib/src/schema.gql +1 -27
- package/lib/src/shacl/SHACLShape.test.js +0 -82
- package/package.json +1 -1
- package/src/Ad4mClient.test.ts +14 -4
- package/src/Ad4mClient.ts +2 -1
- package/src/agent/AgentClient.ts +84 -2
- package/src/cache/PersistentCache.ts +145 -0
- package/src/cache/cache.test.ts +713 -0
- package/src/expression/ExpressionClient.ts +137 -3
- package/src/index.ts +1 -0
- package/src/model/Ad4mModel.test.ts +1 -61
- package/src/model/Ad4mModel.ts +31 -57
- package/src/model/ModelQueryBuilder.ts +0 -6
- package/src/model/types.ts +1 -1
- package/src/perspectives/PerspectiveClient.ts +7 -17
- package/src/perspectives/PerspectiveProxy.ts +0 -3
- package/lib/src/model/hydration-batch.d.ts +0 -34
- package/lib/src/model/hydration-batch.js +0 -147
- package/lib/src/model/hydration-batching.test.d.ts +0 -7
- package/lib/src/model/hydration-batching.test.js +0 -456
- package/lib/src/model/model-manifest.d.ts +0 -41
- package/lib/src/model/model-manifest.js +0 -11
- package/lib/src/model/query-cache.test.d.ts +0 -1
- package/lib/src/model/query-cache.test.js +0 -43
- package/lib/src/model/query-sparql-batch.d.ts +0 -17
- package/lib/src/model/query-sparql-batch.js +0 -260
- package/lib/src/model/query-sparql.test.d.ts +0 -1
- package/lib/src/model/query-sparql.test.js +0 -312
- package/lib/src/model/subscription-delta.test.d.ts +0 -24
- package/lib/src/model/subscription-delta.test.js +0 -180
- package/lib/src/model/subscription-pool.d.ts +0 -39
- package/lib/src/model/subscription-pool.js +0 -165
- package/lib/src/perspectives/PerspectiveClient.test.d.ts +0 -1
- package/lib/src/perspectives/PerspectiveClient.test.js +0 -224
package/src/agent/AgentClient.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
+
}
|