@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
@@ -0,0 +1,179 @@
1
+ import type { PersistentCache } from "./PersistentCache";
2
+
3
+ /** What a {@link KeyedCache} writes to its persistent store. */
4
+ export interface StoredEntry<V> {
5
+ value: V;
6
+ ts: number;
7
+ }
8
+
9
+ export interface KeyedCacheOptions<V> {
10
+ /**
11
+ * Reads many keys in one call: one entry per key, in order, `null` when
12
+ * not found, an `Error` when that key's read failed (it rejects that key's
13
+ * readers only).
14
+ */
15
+ loadMany(keys: string[]): Promise<Array<V | null | Error>>;
16
+ /**
17
+ * Reads one key (`null` when not found; rejects when the read failed).
18
+ * When set, a miss of {@link KeyedCache.get} is read alone with it, so it
19
+ * waits for no other key; only {@link KeyedCache.getMany} uses `loadMany`.
20
+ */
21
+ load?(key: string): Promise<V | null>;
22
+ /** Most keys per `loadMany` call. Default: no limit. */
23
+ maxBatch?: number;
24
+ /** Second tier, read on a memory miss (IndexedDB in browsers). */
25
+ persistent?: PersistentCache<StoredEntry<V>>;
26
+ /** How long a value stays fresh in memory, per key. Default: until evicted. */
27
+ maxAgeMs?(key: string): number;
28
+ /** How long a stored value stays fresh. Default: forever. */
29
+ persistentMaxAgeMs?(): number;
30
+ /** Memory limits; the oldest values go first. Default: none. */
31
+ limits?(): { entries: number; bytes: number };
32
+ }
33
+
34
+ interface Loaded<V> {
35
+ value: V | null;
36
+ /** Came from the persistent store, so it is not written back. */
37
+ stored: boolean;
38
+ }
39
+
40
+ /**
41
+ * Keyed read cache shared by profile and expression lookups. Concurrent reads
42
+ * of one key share one request; misses of one tick go out in one `loadMany`
43
+ * call, except a `get()` miss when the options have `load`. A `null` (not
44
+ * found) is returned but not kept.
45
+ */
46
+ export class KeyedCache<V> {
47
+ #opts: KeyedCacheOptions<V>;
48
+ #values = new Map<string, { value: V; ts: number; size: number }>();
49
+ #bytes = 0;
50
+ #pending = new Map<string, Promise<V | null>>();
51
+ #batch: { keys: string[]; done: Promise<Map<string, Loaded<V | Error>>> } | null = null;
52
+
53
+ constructor(opts: KeyedCacheOptions<V>) {
54
+ this.#opts = opts;
55
+ }
56
+
57
+ get(key: string): Promise<V | null> {
58
+ const load = this.#opts.load;
59
+ return this.#read(key, load ? k => this.#loadOne(k, load) : k => this.#enqueue(k));
60
+ }
61
+
62
+ getMany(keys: string[]): Promise<Array<V | null>> {
63
+ return Promise.all(keys.map(key => this.#read(key, k => this.#enqueue(k))));
64
+ }
65
+
66
+ /** Stores a value known to be current; a read in flight for the key is not kept. */
67
+ set(key: string, value: V): void {
68
+ this.#pending.delete(key);
69
+ this.#remember(key, value, true);
70
+ }
71
+
72
+ /** Forgets a key in memory and in the persistent store. */
73
+ delete(key: string): void {
74
+ this.#pending.delete(key);
75
+ this.#forget(key);
76
+ this.#opts.persistent?.delete(key); // fire-and-forget
77
+ }
78
+
79
+ /** Forgets every key in memory, and in the persistent store when `persistent` is set. */
80
+ clear(persistent = false): void {
81
+ this.#pending.clear();
82
+ this.#values.clear();
83
+ this.#bytes = 0;
84
+ if (persistent) this.#opts.persistent?.clear(); // fire-and-forget
85
+ }
86
+
87
+ #read(key: string, fetch: (key: string) => Promise<Loaded<V>>): Promise<V | null> {
88
+ const hit = this.#values.get(key);
89
+ if (hit && Date.now() - hit.ts < (this.#opts.maxAgeMs?.(key) ?? Infinity)) return Promise.resolve(hit.value);
90
+ const inFlight = this.#pending.get(key);
91
+ if (inFlight) return inFlight;
92
+
93
+ const loading = fetch(key);
94
+ const promise: Promise<V | null> = loading.then(
95
+ ({ value, stored }) => {
96
+ // A set(), delete() or clear() since the read started wins over its result.
97
+ if (this.#pending.get(key) === promise) {
98
+ this.#pending.delete(key);
99
+ if (value !== null) this.#remember(key, value, !stored);
100
+ }
101
+ return value;
102
+ },
103
+ (error) => {
104
+ if (this.#pending.get(key) === promise) this.#pending.delete(key);
105
+ throw error;
106
+ },
107
+ );
108
+ this.#pending.set(key, promise);
109
+ return promise;
110
+ }
111
+
112
+ #enqueue(key: string): Promise<Loaded<V>> {
113
+ if (!this.#batch) {
114
+ const keys: string[] = [];
115
+ const done = Promise.resolve().then(() => {
116
+ this.#batch = null;
117
+ return this.#loadBatch(keys);
118
+ });
119
+ this.#batch = { keys, done };
120
+ }
121
+ this.#batch.keys.push(key);
122
+ return this.#batch.done.then(loaded => {
123
+ const entry = loaded.get(key)!;
124
+ if (entry.value instanceof Error) throw entry.value;
125
+ return entry as Loaded<V>;
126
+ });
127
+ }
128
+
129
+ async #loadOne(key: string, load: (key: string) => Promise<V | null>): Promise<Loaded<V>> {
130
+ return (await this.#stored(key)) ?? { value: await load(key), stored: false };
131
+ }
132
+
133
+ async #loadBatch(keys: string[]): Promise<Map<string, Loaded<V | Error>>> {
134
+ const loaded = new Map<string, Loaded<V | Error>>();
135
+ const stored = await Promise.all(keys.map(key => this.#stored(key)));
136
+ const misses = keys.filter((key, i) => {
137
+ if (stored[i]) loaded.set(key, stored[i]!);
138
+ return !stored[i];
139
+ });
140
+ const size = this.#opts.maxBatch ?? Infinity;
141
+ const chunks: string[][] = [];
142
+ for (let i = 0; i < misses.length; i += size) chunks.push(misses.slice(i, i + size));
143
+ await Promise.all(chunks.map(async chunk => {
144
+ const values = await this.#opts.loadMany(chunk);
145
+ chunk.forEach((key, i) => loaded.set(key, { value: values[i] ?? null, stored: false }));
146
+ }));
147
+ return loaded;
148
+ }
149
+
150
+ async #stored(key: string): Promise<Loaded<V> | null> {
151
+ const entry = await this.#opts.persistent?.get(key);
152
+ // An entry without `value` was written in an older format: a miss.
153
+ if (entry?.value == null || !(Date.now() - (entry.ts ?? 0) < (this.#opts.persistentMaxAgeMs?.() ?? Infinity))) return null;
154
+ return { value: entry.value, stored: true };
155
+ }
156
+
157
+ #remember(key: string, value: V, persist: boolean): void {
158
+ const limits = this.#opts.limits?.();
159
+ const size = limits ? JSON.stringify(value).length : 0;
160
+ this.#forget(key);
161
+ if (limits) {
162
+ for (const oldest of this.#values.keys()) {
163
+ if (this.#values.size < limits.entries && this.#bytes + size <= limits.bytes) break;
164
+ this.#forget(oldest);
165
+ }
166
+ }
167
+ const ts = Date.now();
168
+ this.#values.set(key, { value, ts, size });
169
+ this.#bytes += size;
170
+ if (persist) this.#opts.persistent?.put(key, { value, ts }); // fire-and-forget
171
+ }
172
+
173
+ #forget(key: string): void {
174
+ const entry = this.#values.get(key);
175
+ if (!entry) return;
176
+ this.#bytes -= entry.size;
177
+ this.#values.delete(key);
178
+ }
179
+ }