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

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 (75) hide show
  1. package/lib/index.cjs +571 -480
  2. package/lib/index.js +571 -476
  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 +127 -83
  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/shacl-gen.js +2 -0
  26. package/lib/src/model/types.d.ts +12 -3
  27. package/lib/src/neighbourhood/SfuManager.d.ts +8 -1
  28. package/lib/src/neighbourhood/SfuManager.js +9 -2
  29. package/lib/src/perspectives/FlowModels.js +1 -1
  30. package/lib/src/perspectives/LiveQuery.d.ts +1 -1
  31. package/lib/src/perspectives/PerspectiveClient.d.ts +17 -6
  32. package/lib/src/perspectives/PerspectiveClient.js +83 -44
  33. package/lib/src/perspectives/PerspectiveProxy.d.ts +19 -10
  34. package/lib/src/perspectives/PerspectiveProxy.js +31 -69
  35. package/lib/src/shacl/SHACLShape.d.ts +4 -0
  36. package/lib/src/shacl/SHACLShape.js +10 -0
  37. package/package.json +2 -2
  38. package/src/Ad4mClient.test.ts +17 -6
  39. package/src/agent/AgentClient.ts +46 -74
  40. package/src/cache/KeyedCache.test.ts +162 -0
  41. package/src/cache/KeyedCache.ts +179 -0
  42. package/src/cache/cache.test.ts +294 -71
  43. package/src/expression/ExpressionClient.ts +46 -131
  44. package/src/generated/api/ExpressionLookupError.ts +6 -0
  45. package/src/generated/api/ExpressionManyEntry.ts +8 -0
  46. package/src/generated/api/FlowFiredEntry.ts +11 -0
  47. package/src/generated/api/PerspectiveFlowFiredParams.ts +3 -3
  48. package/src/generated/api/RpcMethods.ts +4 -2
  49. package/src/model/Ad4mModel.test.ts +237 -43
  50. package/src/model/Ad4mModel.ts +134 -99
  51. package/src/model/ModelQueryBuilder.ts +41 -15
  52. package/src/model/count-result-type.test.ts +72 -0
  53. package/src/model/index.ts +0 -1
  54. package/src/model/query-common.ts +13 -0
  55. package/src/model/relation-filtering.test.ts +3 -5
  56. package/src/model/shacl-gen.ts +1 -0
  57. package/src/model/shacl-roundtrip.test.ts +28 -0
  58. package/src/model/types.ts +9 -3
  59. package/src/model/write-round-trips.test.ts +30 -6
  60. package/src/neighbourhood/SfuManager.test.ts +57 -5
  61. package/src/neighbourhood/SfuManager.ts +10 -2
  62. package/src/perspectives/FlowModels.ts +1 -1
  63. package/src/perspectives/LiveQuery.ts +1 -1
  64. package/src/perspectives/PerspectiveClient.test.ts +287 -0
  65. package/src/perspectives/PerspectiveClient.ts +101 -66
  66. package/src/perspectives/PerspectiveProxy.test.ts +6 -14
  67. package/src/perspectives/PerspectiveProxy.ts +33 -67
  68. package/src/perspectives/TextContent.test.ts +0 -16
  69. package/src/perspectives/shacl-rpc.test.ts +1 -1
  70. package/src/shacl/SHACLShape.test.ts +21 -0
  71. package/src/shacl/SHACLShape.ts +16 -0
  72. package/lib/src/model/query-cache.d.ts +0 -30
  73. package/lib/src/model/query-cache.js +0 -66
  74. package/src/model/query-cache.test.ts +0 -54
  75. package/src/model/query-cache.ts +0 -79
@@ -14,11 +14,13 @@ export interface InitializeArgs {
14
14
  }
15
15
  export declare class AgentClient {
16
16
  #private;
17
- /** TTL for remote (non-self) agent profiles in L1 cache (ms). */
17
+ /**
18
+ * TTL of every cached profile, the own one too, in memory and in the
19
+ * persistent cache (ms). `agent-updated` only comes from this executor, so
20
+ * a profile changed through another executor of the same agent shows up
21
+ * when the entry expires.
22
+ */
18
23
  static REMOTE_AGENT_TTL_MS: number;
19
- /** TTL for remote agent profiles in the L2 (IndexedDB) cache (ms).
20
- * After this window any restart triggers a fresh network fetch. */
21
- static REMOTE_AGENT_TTL_L2_MS: number;
22
24
  constructor(baseUrl: string, token?: string, sharedApiClient?: ApiClient);
23
25
  me(): Promise<Agent>;
24
26
  status(): Promise<AgentStatus>;
@@ -29,12 +31,11 @@ export declare class AgentClient {
29
31
  import(args: InitializeArgs): Promise<AgentStatus>;
30
32
  lock(passphrase: string): Promise<AgentStatus>;
31
33
  unlock(passphrase: string, holochain?: boolean, options?: CallOptions): Promise<AgentStatus>;
32
- byDID(did: string): Promise<Agent>;
33
34
  /**
34
- * Set the current agent's own DID.
35
- * The self-DID receives event-driven invalidation and is never TTL-expired.
35
+ * The agent with this DID, or `null` when it is unknown. Concurrent calls
36
+ * for any DIDs share one `agent.byDIDs` request.
36
37
  */
37
- setSelfDid(did: string): void;
38
+ byDID(did: string): Promise<Agent>;
38
39
  /**
39
40
  * Invalidate a specific DID's cache entry in both L1 and L2.
40
41
  */
@@ -9,43 +9,40 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
9
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _AgentClient_instances, _AgentClient_apiClient, _AgentClient_memCache, _AgentClient_persistent, _AgentClient_selfDid, _AgentClient_cacheAgent, _AgentClient_signLinks, _AgentClient_listen, _AgentClient_onAgentUpdated;
13
- import { ApiClient } from '../apiClient';
12
+ var _AgentClient_instances, _AgentClient_apiClient, _AgentClient_agents, _AgentClient_loadAgents, _AgentClient_cacheAgent, _AgentClient_signLinks, _AgentClient_listen, _AgentClient_onAgentUpdated;
13
+ import { ApiClient, RpcError } from '../apiClient';
14
14
  import { Agent, } from "./Agent";
15
15
  import { HostingUserInfo } from "../runtime/RuntimeTypes";
16
16
  import { AgentStatus } from "./AgentStatus";
17
17
  import { AGENT_KIND } from "./AgentKind";
18
18
  import { LinkExpression, linkEqual } from "../links/Links";
19
19
  import { createPersistentCache } from "../cache/PersistentCache";
20
+ import { KeyedCache } from "../cache/KeyedCache";
20
21
  function toAgent(data) {
21
22
  return data ? Agent.fromWire(data) : null;
22
23
  }
24
+ /** Most DIDs the executor takes in one `agent.byDIDs` call. */
25
+ const MAX_DIDS_PER_CALL = 200;
23
26
  export class AgentClient {
24
27
  constructor(baseUrl, token, sharedApiClient) {
25
28
  _AgentClient_instances.add(this);
26
29
  _AgentClient_apiClient.set(this, void 0);
27
- // ── byDID cache ────────────────────────────────────────────────────
28
- // L1: in-memory promise cache with timestamps for TTL
29
- _AgentClient_memCache.set(this, new Map());
30
- // L2: persistent cache (IndexedDB in browser, NullCache in Node)
31
- // Entries are wrapped with a timestamp so the TTL can be enforced across restarts.
32
- _AgentClient_persistent.set(this, void 0);
33
- // Self-DID for event-driven invalidation (no TTL for own profile)
34
- _AgentClient_selfDid.set(this, null);
30
+ // byDID cache: concurrent misses go out in one `agent.byDIDs` call.
31
+ _AgentClient_agents.set(this, void 0);
35
32
  _AgentClient_onAgentUpdated.set(this, (event) => {
36
33
  __classPrivateFieldGet(this, _AgentClient_instances, "m", _AgentClient_cacheAgent).call(this, Agent.fromWire(event.agent));
37
34
  });
38
35
  __classPrivateFieldSet(this, _AgentClient_apiClient, sharedApiClient || new ApiClient(baseUrl, token), "f");
39
- __classPrivateFieldSet(this, _AgentClient_persistent, createPersistentCache('ad4m-agent-cache', 'agents'), "f");
36
+ __classPrivateFieldSet(this, _AgentClient_agents, new KeyedCache({
37
+ loadMany: (dids) => __classPrivateFieldGet(this, _AgentClient_instances, "m", _AgentClient_loadAgents).call(this, dids),
38
+ maxBatch: MAX_DIDS_PER_CALL,
39
+ persistent: createPersistentCache('ad4m-agent-cache', 'agents'),
40
+ maxAgeMs: () => AgentClient.REMOTE_AGENT_TTL_MS,
41
+ persistentMaxAgeMs: () => AgentClient.REMOTE_AGENT_TTL_MS,
42
+ }), "f");
40
43
  }
41
44
  async me() {
42
- const agentObject = toAgent(await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.get', {}));
43
- // Auto-set selfDid so event-driven cache invalidation works
44
- // without requiring apps to call setSelfDid() manually
45
- if (agentObject.did && !__classPrivateFieldGet(this, _AgentClient_selfDid, "f")) {
46
- __classPrivateFieldSet(this, _AgentClient_selfDid, agentObject.did, "f");
47
- }
48
- return agentObject;
45
+ return toAgent(await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.get', {}));
49
46
  }
50
47
  async status() {
51
48
  const agentStatus = await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.status', {});
@@ -70,61 +67,27 @@ export class AgentClient {
70
67
  const result = await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.unlock', { passphrase, holochain }, options);
71
68
  return new AgentStatus(result);
72
69
  }
73
- async byDID(did) {
74
- // agent-updated events keep cached entries fresh (the self-DID entry has no TTL).
75
- __classPrivateFieldGet(this, _AgentClient_instances, "m", _AgentClient_listen).call(this);
76
- const now = Date.now();
77
- const cached = __classPrivateFieldGet(this, _AgentClient_memCache, "f").get(did);
78
- if (cached) {
79
- const isSelf = did === __classPrivateFieldGet(this, _AgentClient_selfDid, "f");
80
- // Self-DID: L1 always valid (event-driven invalidation)
81
- // Remote DID: L1 valid within TTL
82
- if (isSelf || (now - cached.ts) < AgentClient.REMOTE_AGENT_TTL_MS) {
83
- return cached.promise;
84
- }
85
- }
86
- // Deduplicate: store the promise immediately so concurrent calls share one RPC
87
- const promise = (async () => {
88
- // L2: check persistent cache before network
89
- const entry = await __classPrivateFieldGet(this, _AgentClient_persistent, "f").get(did);
90
- // entry.agent may be undefined for pre-TTL cache entries (migration) — treat as expired
91
- if (entry?.agent && (now - (entry.ts ?? 0)) < AgentClient.REMOTE_AGENT_TTL_L2_MS) {
92
- return entry.agent;
93
- }
94
- // L3: network fetch
95
- const result = toAgent(await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.byDid', { did }));
96
- __classPrivateFieldGet(this, _AgentClient_persistent, "f").put(did, { agent: result, ts: Date.now() }); // fire-and-forget write to L2
97
- return result;
98
- })();
99
- __classPrivateFieldGet(this, _AgentClient_memCache, "f").set(did, { promise, ts: now });
100
- // Clean up on failure so next call retries
101
- promise.catch(() => {
102
- if (__classPrivateFieldGet(this, _AgentClient_memCache, "f").get(did)?.promise === promise) {
103
- __classPrivateFieldGet(this, _AgentClient_memCache, "f").delete(did);
104
- }
105
- });
106
- return promise;
107
- }
108
70
  /**
109
- * Set the current agent's own DID.
110
- * The self-DID receives event-driven invalidation and is never TTL-expired.
71
+ * The agent with this DID, or `null` when it is unknown. Concurrent calls
72
+ * for any DIDs share one `agent.byDIDs` request.
111
73
  */
112
- setSelfDid(did) {
113
- __classPrivateFieldSet(this, _AgentClient_selfDid, did, "f");
74
+ async byDID(did) {
75
+ // agent-updated events refresh cached entries before their TTL runs out.
76
+ __classPrivateFieldGet(this, _AgentClient_instances, "m", _AgentClient_listen).call(this);
77
+ return __classPrivateFieldGet(this, _AgentClient_agents, "f").get(did);
114
78
  }
115
79
  /**
116
80
  * Invalidate a specific DID's cache entry in both L1 and L2.
117
81
  */
118
82
  invalidateByDid(did) {
119
- __classPrivateFieldGet(this, _AgentClient_memCache, "f").delete(did);
120
- __classPrivateFieldGet(this, _AgentClient_persistent, "f").delete(did); // fire-and-forget
83
+ __classPrivateFieldGet(this, _AgentClient_agents, "f").delete(did);
121
84
  }
122
85
  /**
123
86
  * Clear the entire L1 (memory) byDID cache.
124
87
  * L2 (IndexedDB) is preserved — agent data remains valid across sessions.
125
88
  */
126
89
  clearByDidCache() {
127
- __classPrivateFieldGet(this, _AgentClient_memCache, "f").clear();
90
+ __classPrivateFieldGet(this, _AgentClient_agents, "f").clear();
128
91
  }
129
92
  async updatePublicPerspective(perspective) {
130
93
  // Send only the signed fields: the public perspective carries no link status.
@@ -256,11 +219,25 @@ export class AgentClient {
256
219
  return __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('hosting.requestPayment', { amountHOT });
257
220
  }
258
221
  }
259
- _AgentClient_apiClient = new WeakMap(), _AgentClient_memCache = new WeakMap(), _AgentClient_persistent = new WeakMap(), _AgentClient_selfDid = new WeakMap(), _AgentClient_onAgentUpdated = new WeakMap(), _AgentClient_instances = new WeakSet(), _AgentClient_cacheAgent = function _AgentClient_cacheAgent(agent) {
222
+ _AgentClient_apiClient = new WeakMap(), _AgentClient_agents = new WeakMap(), _AgentClient_onAgentUpdated = new WeakMap(), _AgentClient_instances = new WeakSet(), _AgentClient_loadAgents =
223
+ /**
224
+ * One `agent.byDIDs` call for the misses of one tick. The executor fails
225
+ * that call when one DID's lookup fails (500), so the DIDs of a failed
226
+ * batch are then read alone: each caller gets what a lone `byDID` gives.
227
+ */
228
+ async function _AgentClient_loadAgents(dids) {
229
+ try {
230
+ return (await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.byDIDs', { dids })).map(toAgent);
231
+ }
232
+ catch (error) {
233
+ if (dids.length === 1 || !(error instanceof RpcError) || error.status !== 500)
234
+ throw error;
235
+ return Promise.all(dids.map(did => __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.byDid', { did }).then(toAgent, (failure) => failure instanceof Error ? failure : new Error(String(failure)))));
236
+ }
237
+ }, _AgentClient_cacheAgent = function _AgentClient_cacheAgent(agent) {
260
238
  if (!agent.did)
261
239
  return;
262
- __classPrivateFieldGet(this, _AgentClient_memCache, "f").set(agent.did, { promise: Promise.resolve(agent), ts: Date.now() });
263
- __classPrivateFieldGet(this, _AgentClient_persistent, "f").put(agent.did, { agent, ts: Date.now() }); // fire-and-forget
240
+ __classPrivateFieldGet(this, _AgentClient_agents, "f").set(agent.did, agent);
264
241
  __classPrivateFieldGet(this, _AgentClient_instances, "m", _AgentClient_listen).call(this);
265
242
  }, _AgentClient_signLinks =
266
243
  /** Has the executor sign `links` as this agent, in a throwaway perspective. */
@@ -275,8 +252,10 @@ async function _AgentClient_signLinks(links) {
275
252
  }, _AgentClient_listen = function _AgentClient_listen() {
276
253
  __classPrivateFieldGet(this, _AgentClient_apiClient, "f").on('agent-updated', __classPrivateFieldGet(this, _AgentClient_onAgentUpdated, "f"));
277
254
  };
278
- /** TTL for remote (non-self) agent profiles in L1 cache (ms). */
255
+ /**
256
+ * TTL of every cached profile, the own one too, in memory and in the
257
+ * persistent cache (ms). `agent-updated` only comes from this executor, so
258
+ * a profile changed through another executor of the same agent shows up
259
+ * when the entry expires.
260
+ */
279
261
  AgentClient.REMOTE_AGENT_TTL_MS = 5 * 60000; // 5 minutes
280
- /** TTL for remote agent profiles in the L2 (IndexedDB) cache (ms).
281
- * After this window any restart triggers a fresh network fetch. */
282
- AgentClient.REMOTE_AGENT_TTL_L2_MS = 5 * 60000; // 5 minutes
@@ -0,0 +1,51 @@
1
+ import type { PersistentCache } from "./PersistentCache";
2
+ /** What a {@link KeyedCache} writes to its persistent store. */
3
+ export interface StoredEntry<V> {
4
+ value: V;
5
+ ts: number;
6
+ }
7
+ export interface KeyedCacheOptions<V> {
8
+ /**
9
+ * Reads many keys in one call: one entry per key, in order, `null` when
10
+ * not found, an `Error` when that key's read failed (it rejects that key's
11
+ * readers only).
12
+ */
13
+ loadMany(keys: string[]): Promise<Array<V | null | Error>>;
14
+ /**
15
+ * Reads one key (`null` when not found; rejects when the read failed).
16
+ * When set, a miss of {@link KeyedCache.get} is read alone with it, so it
17
+ * waits for no other key; only {@link KeyedCache.getMany} uses `loadMany`.
18
+ */
19
+ load?(key: string): Promise<V | null>;
20
+ /** Most keys per `loadMany` call. Default: no limit. */
21
+ maxBatch?: number;
22
+ /** Second tier, read on a memory miss (IndexedDB in browsers). */
23
+ persistent?: PersistentCache<StoredEntry<V>>;
24
+ /** How long a value stays fresh in memory, per key. Default: until evicted. */
25
+ maxAgeMs?(key: string): number;
26
+ /** How long a stored value stays fresh. Default: forever. */
27
+ persistentMaxAgeMs?(): number;
28
+ /** Memory limits; the oldest values go first. Default: none. */
29
+ limits?(): {
30
+ entries: number;
31
+ bytes: number;
32
+ };
33
+ }
34
+ /**
35
+ * Keyed read cache shared by profile and expression lookups. Concurrent reads
36
+ * of one key share one request; misses of one tick go out in one `loadMany`
37
+ * call, except a `get()` miss when the options have `load`. A `null` (not
38
+ * found) is returned but not kept.
39
+ */
40
+ export declare class KeyedCache<V> {
41
+ #private;
42
+ constructor(opts: KeyedCacheOptions<V>);
43
+ get(key: string): Promise<V | null>;
44
+ getMany(keys: string[]): Promise<Array<V | null>>;
45
+ /** Stores a value known to be current; a read in flight for the key is not kept. */
46
+ set(key: string, value: V): void;
47
+ /** Forgets a key in memory and in the persistent store. */
48
+ delete(key: string): void;
49
+ /** Forgets every key in memory, and in the persistent store when `persistent` is set. */
50
+ clear(persistent?: boolean): void;
51
+ }
@@ -0,0 +1,142 @@
1
+ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
2
+ if (kind === "m") throw new TypeError("Private method is not writable");
3
+ if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
4
+ if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
5
+ return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
6
+ };
7
+ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
8
+ if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
9
+ if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
+ return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
+ };
12
+ var _KeyedCache_instances, _KeyedCache_opts, _KeyedCache_values, _KeyedCache_bytes, _KeyedCache_pending, _KeyedCache_batch, _KeyedCache_read, _KeyedCache_enqueue, _KeyedCache_loadOne, _KeyedCache_loadBatch, _KeyedCache_stored, _KeyedCache_remember, _KeyedCache_forget;
13
+ /**
14
+ * Keyed read cache shared by profile and expression lookups. Concurrent reads
15
+ * of one key share one request; misses of one tick go out in one `loadMany`
16
+ * call, except a `get()` miss when the options have `load`. A `null` (not
17
+ * found) is returned but not kept.
18
+ */
19
+ export class KeyedCache {
20
+ constructor(opts) {
21
+ _KeyedCache_instances.add(this);
22
+ _KeyedCache_opts.set(this, void 0);
23
+ _KeyedCache_values.set(this, new Map());
24
+ _KeyedCache_bytes.set(this, 0);
25
+ _KeyedCache_pending.set(this, new Map());
26
+ _KeyedCache_batch.set(this, null);
27
+ __classPrivateFieldSet(this, _KeyedCache_opts, opts, "f");
28
+ }
29
+ get(key) {
30
+ const load = __classPrivateFieldGet(this, _KeyedCache_opts, "f").load;
31
+ return __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_read).call(this, key, load ? k => __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_loadOne).call(this, k, load) : k => __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_enqueue).call(this, k));
32
+ }
33
+ getMany(keys) {
34
+ return Promise.all(keys.map(key => __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_read).call(this, key, k => __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_enqueue).call(this, k))));
35
+ }
36
+ /** Stores a value known to be current; a read in flight for the key is not kept. */
37
+ set(key, value) {
38
+ __classPrivateFieldGet(this, _KeyedCache_pending, "f").delete(key);
39
+ __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_remember).call(this, key, value, true);
40
+ }
41
+ /** Forgets a key in memory and in the persistent store. */
42
+ delete(key) {
43
+ __classPrivateFieldGet(this, _KeyedCache_pending, "f").delete(key);
44
+ __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_forget).call(this, key);
45
+ __classPrivateFieldGet(this, _KeyedCache_opts, "f").persistent?.delete(key); // fire-and-forget
46
+ }
47
+ /** Forgets every key in memory, and in the persistent store when `persistent` is set. */
48
+ clear(persistent = false) {
49
+ __classPrivateFieldGet(this, _KeyedCache_pending, "f").clear();
50
+ __classPrivateFieldGet(this, _KeyedCache_values, "f").clear();
51
+ __classPrivateFieldSet(this, _KeyedCache_bytes, 0, "f");
52
+ if (persistent)
53
+ __classPrivateFieldGet(this, _KeyedCache_opts, "f").persistent?.clear(); // fire-and-forget
54
+ }
55
+ }
56
+ _KeyedCache_opts = new WeakMap(), _KeyedCache_values = new WeakMap(), _KeyedCache_bytes = new WeakMap(), _KeyedCache_pending = new WeakMap(), _KeyedCache_batch = new WeakMap(), _KeyedCache_instances = new WeakSet(), _KeyedCache_read = function _KeyedCache_read(key, fetch) {
57
+ const hit = __classPrivateFieldGet(this, _KeyedCache_values, "f").get(key);
58
+ if (hit && Date.now() - hit.ts < (__classPrivateFieldGet(this, _KeyedCache_opts, "f").maxAgeMs?.(key) ?? Infinity))
59
+ return Promise.resolve(hit.value);
60
+ const inFlight = __classPrivateFieldGet(this, _KeyedCache_pending, "f").get(key);
61
+ if (inFlight)
62
+ return inFlight;
63
+ const loading = fetch(key);
64
+ const promise = loading.then(({ value, stored }) => {
65
+ // A set(), delete() or clear() since the read started wins over its result.
66
+ if (__classPrivateFieldGet(this, _KeyedCache_pending, "f").get(key) === promise) {
67
+ __classPrivateFieldGet(this, _KeyedCache_pending, "f").delete(key);
68
+ if (value !== null)
69
+ __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_remember).call(this, key, value, !stored);
70
+ }
71
+ return value;
72
+ }, (error) => {
73
+ if (__classPrivateFieldGet(this, _KeyedCache_pending, "f").get(key) === promise)
74
+ __classPrivateFieldGet(this, _KeyedCache_pending, "f").delete(key);
75
+ throw error;
76
+ });
77
+ __classPrivateFieldGet(this, _KeyedCache_pending, "f").set(key, promise);
78
+ return promise;
79
+ }, _KeyedCache_enqueue = function _KeyedCache_enqueue(key) {
80
+ if (!__classPrivateFieldGet(this, _KeyedCache_batch, "f")) {
81
+ const keys = [];
82
+ const done = Promise.resolve().then(() => {
83
+ __classPrivateFieldSet(this, _KeyedCache_batch, null, "f");
84
+ return __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_loadBatch).call(this, keys);
85
+ });
86
+ __classPrivateFieldSet(this, _KeyedCache_batch, { keys, done }, "f");
87
+ }
88
+ __classPrivateFieldGet(this, _KeyedCache_batch, "f").keys.push(key);
89
+ return __classPrivateFieldGet(this, _KeyedCache_batch, "f").done.then(loaded => {
90
+ const entry = loaded.get(key);
91
+ if (entry.value instanceof Error)
92
+ throw entry.value;
93
+ return entry;
94
+ });
95
+ }, _KeyedCache_loadOne = async function _KeyedCache_loadOne(key, load) {
96
+ return (await __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_stored).call(this, key)) ?? { value: await load(key), stored: false };
97
+ }, _KeyedCache_loadBatch = async function _KeyedCache_loadBatch(keys) {
98
+ const loaded = new Map();
99
+ const stored = await Promise.all(keys.map(key => __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_stored).call(this, key)));
100
+ const misses = keys.filter((key, i) => {
101
+ if (stored[i])
102
+ loaded.set(key, stored[i]);
103
+ return !stored[i];
104
+ });
105
+ const size = __classPrivateFieldGet(this, _KeyedCache_opts, "f").maxBatch ?? Infinity;
106
+ const chunks = [];
107
+ for (let i = 0; i < misses.length; i += size)
108
+ chunks.push(misses.slice(i, i + size));
109
+ await Promise.all(chunks.map(async (chunk) => {
110
+ const values = await __classPrivateFieldGet(this, _KeyedCache_opts, "f").loadMany(chunk);
111
+ chunk.forEach((key, i) => loaded.set(key, { value: values[i] ?? null, stored: false }));
112
+ }));
113
+ return loaded;
114
+ }, _KeyedCache_stored = async function _KeyedCache_stored(key) {
115
+ const entry = await __classPrivateFieldGet(this, _KeyedCache_opts, "f").persistent?.get(key);
116
+ // An entry without `value` was written in an older format: a miss.
117
+ if (entry?.value == null || !(Date.now() - (entry.ts ?? 0) < (__classPrivateFieldGet(this, _KeyedCache_opts, "f").persistentMaxAgeMs?.() ?? Infinity)))
118
+ return null;
119
+ return { value: entry.value, stored: true };
120
+ }, _KeyedCache_remember = function _KeyedCache_remember(key, value, persist) {
121
+ const limits = __classPrivateFieldGet(this, _KeyedCache_opts, "f").limits?.();
122
+ const size = limits ? JSON.stringify(value).length : 0;
123
+ __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_forget).call(this, key);
124
+ if (limits) {
125
+ for (const oldest of __classPrivateFieldGet(this, _KeyedCache_values, "f").keys()) {
126
+ if (__classPrivateFieldGet(this, _KeyedCache_values, "f").size < limits.entries && __classPrivateFieldGet(this, _KeyedCache_bytes, "f") + size <= limits.bytes)
127
+ break;
128
+ __classPrivateFieldGet(this, _KeyedCache_instances, "m", _KeyedCache_forget).call(this, oldest);
129
+ }
130
+ }
131
+ const ts = Date.now();
132
+ __classPrivateFieldGet(this, _KeyedCache_values, "f").set(key, { value, ts, size });
133
+ __classPrivateFieldSet(this, _KeyedCache_bytes, __classPrivateFieldGet(this, _KeyedCache_bytes, "f") + size, "f");
134
+ if (persist)
135
+ __classPrivateFieldGet(this, _KeyedCache_opts, "f").persistent?.put(key, { value, ts }); // fire-and-forget
136
+ }, _KeyedCache_forget = function _KeyedCache_forget(key) {
137
+ const entry = __classPrivateFieldGet(this, _KeyedCache_values, "f").get(key);
138
+ if (!entry)
139
+ return;
140
+ __classPrivateFieldSet(this, _KeyedCache_bytes, __classPrivateFieldGet(this, _KeyedCache_bytes, "f") - entry.size, "f");
141
+ __classPrivateFieldGet(this, _KeyedCache_values, "f").delete(key);
142
+ };
@@ -3,15 +3,26 @@ import { InteractionCall, InteractionMeta } from "../language/Language";
3
3
  import { ExpressionRendered } from "./Expression";
4
4
  export declare class ExpressionClient {
5
5
  #private;
6
- /** Maximum number of entries in the L1 memory cache. */
6
+ /** Maximum number of expressions kept in memory. */
7
7
  static MAX_MEM_ENTRIES: number;
8
- /** Maximum total size (in bytes) of L1 memory cache values. */
8
+ /** Maximum total size (in bytes of JSON) of the expressions kept in memory. */
9
9
  static MAX_MEM_BYTES: number;
10
+ /**
11
+ * TTL of every cached expression, in memory and in the persistent cache
12
+ * (ms). A language may change what a URL returns, and no event tells the
13
+ * client, so a cached expression expires instead of staying stale.
14
+ */
15
+ static EXPRESSION_TTL_MS: number;
10
16
  constructor(baseUrl: string, token?: string, sharedApiClient?: ApiClient);
17
+ /** The expression at `url`; `alwaysGet` skips the literal fast path and the cache. */
11
18
  get(url: string, alwaysGet?: boolean): Promise<ExpressionRendered>;
19
+ /**
20
+ * The expressions at `urls`, in order (`null` when not found); the misses go
21
+ * out in calls of at most 200 URLs. Rejects with the `RpcError` `get` gives when a URL's read fails.
22
+ */
12
23
  getMany(urls: string[]): Promise<ExpressionRendered[]>;
13
24
  /**
14
- * Clear both L1 (memory) and L2 (persistent) expression caches.
25
+ * Clear both the memory and the persistent expression caches.
15
26
  */
16
27
  clearCache(): void;
17
28
  getRaw(url: string): Promise<string>;
@@ -9,115 +9,63 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
9
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _ExpressionClient_instances, _ExpressionClient_apiClient, _ExpressionClient_memCache, _ExpressionClient_inflight, _ExpressionClient_totalMemBytes, _ExpressionClient_persistent, _ExpressionClient_memCacheResult;
13
- import { ApiClient } from "../apiClient";
12
+ var _ExpressionClient_apiClient, _ExpressionClient_expressions;
13
+ import { ApiClient, RpcError } from "../apiClient";
14
14
  import { Literal } from "../Literal";
15
15
  import { createPersistentCache } from "../cache/PersistentCache";
16
+ import { KeyedCache } from "../cache/KeyedCache";
17
+ /** Most URLs the executor takes in one `expression.getMany` call. */
18
+ const MAX_URLS_PER_CALL = 200;
16
19
  export class ExpressionClient {
17
20
  constructor(baseUrl, token, sharedApiClient) {
18
- _ExpressionClient_instances.add(this);
19
21
  _ExpressionClient_apiClient.set(this, void 0);
20
- // L1: in-memory LRU cache (hot path, sub-ms)
21
- _ExpressionClient_memCache.set(this, new Map());
22
- _ExpressionClient_inflight.set(this, new Map());
23
- _ExpressionClient_totalMemBytes.set(this, 0);
24
- // L2: persistent cache (IndexedDB in browser, NullCache in Node)
25
- _ExpressionClient_persistent.set(this, void 0);
22
+ // A `get` miss is its own `expression.get`, so it waits for no slower
23
+ // expression and has its own call timeout. The misses of the `getMany`
24
+ // calls made in one tick go out in `expression.getMany` calls of at most
25
+ // MAX_URLS_PER_CALL URLs, which answer per URL what `expression.get` would.
26
+ _ExpressionClient_expressions.set(this, void 0);
26
27
  __classPrivateFieldSet(this, _ExpressionClient_apiClient, sharedApiClient || new ApiClient(baseUrl, token), "f");
27
- __classPrivateFieldSet(this, _ExpressionClient_persistent, createPersistentCache('ad4m-expression-cache', 'expressions'), "f");
28
+ __classPrivateFieldSet(this, _ExpressionClient_expressions, new KeyedCache({
29
+ load: (url) => __classPrivateFieldGet(this, _ExpressionClient_apiClient, "f").call('expression.get', { url }),
30
+ loadMany: async (urls) => (await __classPrivateFieldGet(this, _ExpressionClient_apiClient, "f").call('expression.getMany', { urls })).map(entry => entry && 'code' in entry ? new RpcError(entry.code, entry.message) : entry),
31
+ maxBatch: MAX_URLS_PER_CALL,
32
+ persistent: createPersistentCache('ad4m-expression-cache', 'expressions'),
33
+ maxAgeMs: () => ExpressionClient.EXPRESSION_TTL_MS,
34
+ persistentMaxAgeMs: () => ExpressionClient.EXPRESSION_TTL_MS,
35
+ limits: () => ({ entries: ExpressionClient.MAX_MEM_ENTRIES, bytes: ExpressionClient.MAX_MEM_BYTES }),
36
+ }), "f");
28
37
  }
38
+ /** The expression at `url`; `alwaysGet` skips the literal fast path and the cache. */
29
39
  async get(url, alwaysGet = false) {
30
- // Existing literal fast-path
31
- if (!alwaysGet) {
32
- try {
33
- let literalValue = Literal.fromUrl(url).get();
34
- if (typeof literalValue === 'object' && literalValue !== null) {
35
- if ('author' in literalValue && 'timestamp' in literalValue && 'data' in literalValue && 'proof' in literalValue) {
36
- return literalValue;
37
- }
38
- }
39
- }
40
- catch (e) { }
41
- }
42
- // L1: memory hit
43
- if (!alwaysGet) {
44
- const memHit = __classPrivateFieldGet(this, _ExpressionClient_memCache, "f").get(url);
45
- if (memHit)
46
- return memHit.data;
47
- }
48
- // Deduplicate in-flight requests
49
- if (!alwaysGet) {
50
- const existing = __classPrivateFieldGet(this, _ExpressionClient_inflight, "f").get(url);
51
- if (existing)
52
- return existing;
53
- }
54
- // L2 check + L3 network
55
- const promise = (async () => {
56
- if (!alwaysGet) {
57
- const persisted = await __classPrivateFieldGet(this, _ExpressionClient_persistent, "f").get(url);
58
- if (persisted) {
59
- __classPrivateFieldGet(this, _ExpressionClient_instances, "m", _ExpressionClient_memCacheResult).call(this, url, persisted); // promote to L1
60
- return persisted;
61
- }
62
- }
63
- // L3: network fetch
40
+ if (alwaysGet) {
64
41
  const result = await __classPrivateFieldGet(this, _ExpressionClient_apiClient, "f").call('expression.get', { url });
65
- __classPrivateFieldGet(this, _ExpressionClient_instances, "m", _ExpressionClient_memCacheResult).call(this, url, result);
66
- __classPrivateFieldGet(this, _ExpressionClient_persistent, "f").put(url, result); // fire-and-forget write to L2
42
+ if (result)
43
+ __classPrivateFieldGet(this, _ExpressionClient_expressions, "f").set(url, result);
67
44
  return result;
68
- })();
69
- __classPrivateFieldGet(this, _ExpressionClient_inflight, "f").set(url, promise);
70
- try {
71
- return await promise;
72
45
  }
73
- finally {
74
- __classPrivateFieldGet(this, _ExpressionClient_inflight, "f").delete(url);
46
+ try {
47
+ let literalValue = Literal.fromUrl(url).get();
48
+ if (typeof literalValue === 'object' && literalValue !== null) {
49
+ if ('author' in literalValue && 'timestamp' in literalValue && 'data' in literalValue && 'proof' in literalValue) {
50
+ return literalValue;
51
+ }
52
+ }
75
53
  }
54
+ catch (e) { }
55
+ return __classPrivateFieldGet(this, _ExpressionClient_expressions, "f").get(url);
76
56
  }
57
+ /**
58
+ * The expressions at `urls`, in order (`null` when not found); the misses go
59
+ * out in calls of at most 200 URLs. Rejects with the `RpcError` `get` gives when a URL's read fails.
60
+ */
77
61
  async getMany(urls) {
78
- // Check L1 first
79
- const results = urls.map(u => __classPrivateFieldGet(this, _ExpressionClient_memCache, "f").get(u)?.data ?? null);
80
- let uncachedIndices = results
81
- .map((r, i) => r === null ? i : -1)
82
- .filter(i => i >= 0);
83
- if (uncachedIndices.length === 0)
84
- return results;
85
- // Check L2 for remaining misses
86
- const l2Results = await Promise.all(uncachedIndices.map(i => __classPrivateFieldGet(this, _ExpressionClient_persistent, "f").get(urls[i])));
87
- const stillMissing = [];
88
- for (let j = 0; j < uncachedIndices.length; j++) {
89
- const idx = uncachedIndices[j];
90
- if (l2Results[j]) {
91
- results[idx] = l2Results[j];
92
- __classPrivateFieldGet(this, _ExpressionClient_instances, "m", _ExpressionClient_memCacheResult).call(this, urls[idx], l2Results[j]); // promote to L1
93
- }
94
- else {
95
- stillMissing.push(idx);
96
- }
97
- }
98
- if (stillMissing.length === 0)
99
- return results;
100
- // L3: fetch only truly uncached URLs
101
- const uncachedUrls = stillMissing.map(i => urls[i]);
102
- const fetched = await __classPrivateFieldGet(this, _ExpressionClient_apiClient, "f").call('expression.getMany', { urls: uncachedUrls });
103
- for (let i = 0; i < stillMissing.length; i++) {
104
- const idx = stillMissing[i];
105
- results[idx] = fetched[i];
106
- if (fetched[i]) {
107
- __classPrivateFieldGet(this, _ExpressionClient_instances, "m", _ExpressionClient_memCacheResult).call(this, uncachedUrls[i], fetched[i]);
108
- __classPrivateFieldGet(this, _ExpressionClient_persistent, "f").put(uncachedUrls[i], fetched[i]); // fire-and-forget
109
- }
110
- }
111
- return results;
62
+ return __classPrivateFieldGet(this, _ExpressionClient_expressions, "f").getMany(urls);
112
63
  }
113
64
  /**
114
- * Clear both L1 (memory) and L2 (persistent) expression caches.
65
+ * Clear both the memory and the persistent expression caches.
115
66
  */
116
67
  clearCache() {
117
- __classPrivateFieldGet(this, _ExpressionClient_memCache, "f").clear();
118
- __classPrivateFieldGet(this, _ExpressionClient_inflight, "f").clear();
119
- __classPrivateFieldSet(this, _ExpressionClient_totalMemBytes, 0, "f");
120
- __classPrivateFieldGet(this, _ExpressionClient_persistent, "f").clear(); // fire-and-forget
68
+ __classPrivateFieldGet(this, _ExpressionClient_expressions, "f").clear(true);
121
69
  }
122
70
  async getRaw(url) {
123
71
  return __classPrivateFieldGet(this, _ExpressionClient_apiClient, "f").call('expression.getRaw', { url });
@@ -132,28 +80,18 @@ export class ExpressionClient {
132
80
  async interact(url, interactionCall) {
133
81
  const result = await __classPrivateFieldGet(this, _ExpressionClient_apiClient, "f").call('expression.interact', { url, interactionCall });
134
82
  // Interactions can mutate the expression — invalidate cache so next get() fetches fresh
135
- __classPrivateFieldGet(this, _ExpressionClient_memCache, "f").delete(url);
136
- __classPrivateFieldGet(this, _ExpressionClient_inflight, "f").delete(url);
137
- __classPrivateFieldGet(this, _ExpressionClient_persistent, "f").delete(url); // fire-and-forget
83
+ __classPrivateFieldGet(this, _ExpressionClient_expressions, "f").delete(url);
138
84
  return result;
139
85
  }
140
86
  }
141
- _ExpressionClient_apiClient = new WeakMap(), _ExpressionClient_memCache = new WeakMap(), _ExpressionClient_inflight = new WeakMap(), _ExpressionClient_totalMemBytes = new WeakMap(), _ExpressionClient_persistent = new WeakMap(), _ExpressionClient_instances = new WeakSet(), _ExpressionClient_memCacheResult = function _ExpressionClient_memCacheResult(url, data) {
142
- const size = JSON.stringify(data).length;
143
- // Evict oldest entries if we'd exceed limits
144
- while (__classPrivateFieldGet(this, _ExpressionClient_memCache, "f").size >= ExpressionClient.MAX_MEM_ENTRIES ||
145
- __classPrivateFieldGet(this, _ExpressionClient_totalMemBytes, "f") + size > ExpressionClient.MAX_MEM_BYTES) {
146
- const oldest = __classPrivateFieldGet(this, _ExpressionClient_memCache, "f").keys().next().value;
147
- if (!oldest)
148
- break;
149
- const entry = __classPrivateFieldGet(this, _ExpressionClient_memCache, "f").get(oldest);
150
- __classPrivateFieldSet(this, _ExpressionClient_totalMemBytes, __classPrivateFieldGet(this, _ExpressionClient_totalMemBytes, "f") - entry.size, "f");
151
- __classPrivateFieldGet(this, _ExpressionClient_memCache, "f").delete(oldest);
152
- }
153
- __classPrivateFieldGet(this, _ExpressionClient_memCache, "f").set(url, { data, size });
154
- __classPrivateFieldSet(this, _ExpressionClient_totalMemBytes, __classPrivateFieldGet(this, _ExpressionClient_totalMemBytes, "f") + size, "f");
155
- };
156
- /** Maximum number of entries in the L1 memory cache. */
87
+ _ExpressionClient_apiClient = new WeakMap(), _ExpressionClient_expressions = new WeakMap();
88
+ /** Maximum number of expressions kept in memory. */
157
89
  ExpressionClient.MAX_MEM_ENTRIES = 200;
158
- /** Maximum total size (in bytes) of L1 memory cache values. */
90
+ /** Maximum total size (in bytes of JSON) of the expressions kept in memory. */
159
91
  ExpressionClient.MAX_MEM_BYTES = 5 * 1024 * 1024; // 5 MB
92
+ /**
93
+ * TTL of every cached expression, in memory and in the persistent cache
94
+ * (ms). A language may change what a URL returns, and no event tells the
95
+ * client, so a cached expression expires instead of staying stale.
96
+ */
97
+ ExpressionClient.EXPRESSION_TTL_MS = 5 * 60000; // 5 minutes
@@ -0,0 +1,7 @@
1
+ /**
2
+ * The error `expression.get` fails with, reported per URL by `expression.getMany`.
3
+ */
4
+ export type ExpressionLookupError = {
5
+ code: number;
6
+ message: string;
7
+ };
@@ -0,0 +1,2 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ export {};