@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.
- package/lib/index.cjs +548 -477
- package/lib/index.js +548 -473
- package/lib/src/agent/AgentClient.d.ts +9 -8
- package/lib/src/agent/AgentClient.js +46 -67
- package/lib/src/cache/KeyedCache.d.ts +51 -0
- package/lib/src/cache/KeyedCache.js +142 -0
- package/lib/src/expression/ExpressionClient.d.ts +14 -3
- package/lib/src/expression/ExpressionClient.js +49 -111
- package/lib/src/generated/api/ExpressionLookupError.d.ts +7 -0
- package/lib/src/generated/api/ExpressionLookupError.js +2 -0
- package/lib/src/generated/api/ExpressionManyEntry.d.ts +6 -0
- package/lib/src/generated/api/ExpressionManyEntry.js +1 -0
- package/lib/src/generated/api/FlowFiredEntry.d.ts +11 -0
- package/lib/src/generated/api/FlowFiredEntry.js +2 -0
- package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +3 -3
- package/lib/src/generated/api/RpcMethods.d.ts +4 -2
- package/lib/src/model/Ad4mModel.d.ts +26 -2
- package/lib/src/model/Ad4mModel.js +125 -82
- package/lib/src/model/ModelQueryBuilder.d.ts +3 -0
- package/lib/src/model/ModelQueryBuilder.js +42 -14
- package/lib/src/model/index.d.ts +0 -1
- package/lib/src/model/index.js +0 -1
- package/lib/src/model/query-common.d.ts +8 -0
- package/lib/src/model/query-common.js +12 -0
- package/lib/src/model/types.d.ts +12 -3
- package/lib/src/perspectives/FlowModels.js +1 -1
- package/lib/src/perspectives/LiveQuery.d.ts +1 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +17 -6
- package/lib/src/perspectives/PerspectiveClient.js +83 -44
- package/lib/src/perspectives/PerspectiveProxy.d.ts +19 -10
- package/lib/src/perspectives/PerspectiveProxy.js +31 -69
- package/package.json +2 -2
- package/src/Ad4mClient.test.ts +17 -6
- package/src/agent/AgentClient.ts +46 -74
- package/src/cache/KeyedCache.test.ts +162 -0
- package/src/cache/KeyedCache.ts +179 -0
- package/src/cache/cache.test.ts +294 -71
- package/src/expression/ExpressionClient.ts +46 -131
- package/src/generated/api/ExpressionLookupError.ts +6 -0
- package/src/generated/api/ExpressionManyEntry.ts +8 -0
- package/src/generated/api/FlowFiredEntry.ts +11 -0
- package/src/generated/api/PerspectiveFlowFiredParams.ts +3 -3
- package/src/generated/api/RpcMethods.ts +4 -2
- package/src/model/Ad4mModel.test.ts +237 -43
- package/src/model/Ad4mModel.ts +132 -98
- package/src/model/ModelQueryBuilder.ts +41 -15
- package/src/model/count-result-type.test.ts +72 -0
- package/src/model/index.ts +0 -1
- package/src/model/query-common.ts +13 -0
- package/src/model/relation-filtering.test.ts +3 -5
- package/src/model/types.ts +9 -3
- package/src/model/write-round-trips.test.ts +30 -6
- package/src/perspectives/FlowModels.ts +1 -1
- package/src/perspectives/LiveQuery.ts +1 -1
- package/src/perspectives/PerspectiveClient.test.ts +287 -0
- package/src/perspectives/PerspectiveClient.ts +101 -66
- package/src/perspectives/PerspectiveProxy.test.ts +6 -14
- package/src/perspectives/PerspectiveProxy.ts +33 -67
- package/src/perspectives/TextContent.test.ts +0 -16
- package/src/perspectives/shacl-rpc.test.ts +1 -1
- package/lib/src/model/query-cache.d.ts +0 -30
- package/lib/src/model/query-cache.js +0 -66
- package/src/model/query-cache.test.ts +0 -54
- 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
|
+
}
|