@coasys/ad4m 0.13.0-test-7 → 0.13.0-test-8-profile-cache-fix
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 +1121 -835
- package/lib/index.js +1108 -835
- package/lib/src/Ad4mClient.d.ts +4 -1
- package/lib/src/Ad4mClient.js +2 -2
- package/lib/src/agent/AgentClient.d.ts +3 -0
- package/lib/src/agent/AgentClient.js +27 -5
- package/lib/src/ai/AIClient.js +1 -1
- package/lib/src/apiClient.d.ts +5 -1
- package/lib/src/apiClient.js +14 -6
- package/lib/src/index.d.ts +4 -0
- package/lib/src/index.js +4 -0
- package/lib/src/model/Ad4mModel.d.ts +30 -36
- package/lib/src/model/Ad4mModel.js +93 -382
- package/lib/src/model/ModelQueryBuilder.d.ts +5 -10
- package/lib/src/model/ModelQueryBuilder.js +142 -62
- package/lib/src/model/decorators.d.ts +7 -4
- package/lib/src/model/decorators.js +0 -7
- package/lib/src/model/query-sparql.d.ts +0 -10
- package/lib/src/model/query-sparql.js +12 -17
- package/lib/src/model/shacl-gen.js +120 -47
- package/lib/src/model/types.d.ts +140 -4
- package/lib/src/perspectives/PerspectiveClient.d.ts +13 -4
- package/lib/src/perspectives/PerspectiveClient.js +22 -6
- package/lib/src/perspectives/PerspectiveProxy.d.ts +27 -7
- package/lib/src/perspectives/PerspectiveProxy.js +60 -12
- package/lib/src/perspectives/SparqlBindings.d.ts +47 -0
- package/lib/src/perspectives/SparqlBindings.js +65 -0
- package/lib/src/perspectives/WakerSubscriptionManager.js +5 -4
- package/lib/src/shacl/NodeExpression.d.ts +44 -0
- package/lib/src/shacl/NodeExpression.js +39 -0
- package/lib/src/shacl/SHACLShape.d.ts +23 -0
- package/lib/src/shacl/SHACLShape.js +115 -1
- package/lib/src/shacl/builders.d.ts +58 -0
- package/lib/src/shacl/builders.js +76 -0
- package/lib/src/shacl/index.d.ts +36 -0
- package/lib/src/shacl/index.js +33 -0
- package/package.json +1 -1
- package/src/Ad4mClient.ts +7 -2
- package/src/agent/AgentClient.ts +35 -7
- package/src/ai/AIClient.ts +1 -1
- package/src/apiClient.ts +17 -6
- package/src/index.ts +4 -0
- package/src/model/Ad4mModel.test.ts +274 -72
- package/src/model/Ad4mModel.ts +140 -420
- package/src/model/ModelQueryBuilder.ts +136 -71
- package/src/model/decorators.ts +7 -13
- package/src/model/query-sparql.test.ts +36 -20
- package/src/model/query-sparql.ts +12 -18
- package/src/model/relation-filtering.test.ts +46 -39
- package/src/model/shacl-gen.ts +128 -54
- package/src/model/shacl-roundtrip.test.ts +197 -0
- package/src/model/types-typed-query.test.ts +360 -0
- package/src/model/types.ts +196 -4
- package/src/perspectives/PerspectiveClient.ts +24 -8
- package/src/perspectives/PerspectiveProxy.test.ts +85 -1
- package/src/perspectives/PerspectiveProxy.ts +65 -20
- package/src/perspectives/SparqlBindings.ts +79 -0
- package/src/perspectives/WakerSubscriptionManager.ts +5 -4
- package/src/shacl/NodeExpression.ts +54 -0
- package/src/shacl/SHACLShape.test.ts +172 -0
- package/src/shacl/SHACLShape.ts +173 -1
- package/src/shacl/builders.ts +86 -0
- package/src/shacl/index.ts +72 -0
package/lib/src/Ad4mClient.d.ts
CHANGED
|
@@ -16,7 +16,10 @@ import { AIClient } from './ai/AIClient';
|
|
|
16
16
|
*/
|
|
17
17
|
export declare class Ad4mClient {
|
|
18
18
|
#private;
|
|
19
|
-
constructor(baseUrl: string, token?: string, subscribe?: boolean
|
|
19
|
+
constructor(baseUrl: string, token?: string, subscribe?: boolean, options?: {
|
|
20
|
+
webSocketImpl?: new (url: string) => WebSocket;
|
|
21
|
+
fetchImpl?: typeof fetch;
|
|
22
|
+
});
|
|
20
23
|
get agent(): AgentClient;
|
|
21
24
|
get expression(): ExpressionClient;
|
|
22
25
|
get languages(): LanguageClient;
|
package/lib/src/Ad4mClient.js
CHANGED
|
@@ -29,7 +29,7 @@ import { Ad4mModel } from './model/Ad4mModel';
|
|
|
29
29
|
* for the respective functionality.
|
|
30
30
|
*/
|
|
31
31
|
export class Ad4mClient {
|
|
32
|
-
constructor(baseUrl, token, subscribe = true) {
|
|
32
|
+
constructor(baseUrl, token, subscribe = true, options) {
|
|
33
33
|
_Ad4mClient_baseUrl.set(this, void 0);
|
|
34
34
|
_Ad4mClient_token.set(this, void 0);
|
|
35
35
|
_Ad4mClient_apiClient.set(this, void 0);
|
|
@@ -42,7 +42,7 @@ export class Ad4mClient {
|
|
|
42
42
|
_Ad4mClient_aiClient.set(this, void 0);
|
|
43
43
|
__classPrivateFieldSet(this, _Ad4mClient_baseUrl, baseUrl, "f");
|
|
44
44
|
__classPrivateFieldSet(this, _Ad4mClient_token, token, "f");
|
|
45
|
-
__classPrivateFieldSet(this, _Ad4mClient_apiClient, new ApiClient(baseUrl, token), "f");
|
|
45
|
+
__classPrivateFieldSet(this, _Ad4mClient_apiClient, new ApiClient(baseUrl, token, options?.webSocketImpl, options?.fetchImpl), "f");
|
|
46
46
|
__classPrivateFieldSet(this, _Ad4mClient_agentClient, new AgentClient(baseUrl, token, subscribe, __classPrivateFieldGet(this, _Ad4mClient_apiClient, "f")), "f");
|
|
47
47
|
__classPrivateFieldSet(this, _Ad4mClient_expressionClient, new ExpressionClient(baseUrl, token, __classPrivateFieldGet(this, _Ad4mClient_apiClient, "f")), "f");
|
|
48
48
|
__classPrivateFieldSet(this, _Ad4mClient_languageClient, new LanguageClient(baseUrl, token, __classPrivateFieldGet(this, _Ad4mClient_apiClient, "f")), "f");
|
|
@@ -20,6 +20,9 @@ export declare class AgentClient {
|
|
|
20
20
|
#private;
|
|
21
21
|
/** TTL for remote (non-self) agent profiles in L1 cache (ms). */
|
|
22
22
|
static REMOTE_AGENT_TTL_MS: number;
|
|
23
|
+
/** TTL for remote agent profiles in the L2 (IndexedDB) cache (ms).
|
|
24
|
+
* After this window any restart triggers a fresh network fetch. */
|
|
25
|
+
static REMOTE_AGENT_TTL_L2_MS: number;
|
|
23
26
|
constructor(baseUrl: string, token?: string, subscribe?: boolean, sharedApiClient?: ApiClient);
|
|
24
27
|
me(): Promise<Agent>;
|
|
25
28
|
status(): Promise<AgentStatus>;
|
|
@@ -31,6 +31,7 @@ export class AgentClient {
|
|
|
31
31
|
// L1: in-memory promise cache with timestamps for TTL
|
|
32
32
|
_AgentClient_memCache.set(this, new Map());
|
|
33
33
|
// L2: persistent cache (IndexedDB in browser, NullCache in Node)
|
|
34
|
+
// Entries are wrapped with a timestamp so the TTL can be enforced across restarts.
|
|
34
35
|
_AgentClient_persistent.set(this, void 0);
|
|
35
36
|
// Self-DID for event-driven invalidation (no TTL for own profile)
|
|
36
37
|
_AgentClient_selfDid.set(this, null);
|
|
@@ -54,6 +55,11 @@ export class AgentClient {
|
|
|
54
55
|
const agent = await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.get');
|
|
55
56
|
let agentObject = new Agent(agent.did, agent.perspective);
|
|
56
57
|
agentObject.directMessageLanguage = agent.directMessageLanguage;
|
|
58
|
+
// Auto-set selfDid so event-driven cache invalidation works
|
|
59
|
+
// without requiring apps to call setSelfDid() manually
|
|
60
|
+
if (agentObject.did && !__classPrivateFieldGet(this, _AgentClient_selfDid, "f")) {
|
|
61
|
+
__classPrivateFieldSet(this, _AgentClient_selfDid, agentObject.did, "f");
|
|
62
|
+
}
|
|
57
63
|
return agentObject;
|
|
58
64
|
}
|
|
59
65
|
async status() {
|
|
@@ -90,13 +96,14 @@ export class AgentClient {
|
|
|
90
96
|
// Deduplicate: store the promise immediately so concurrent calls share one RPC
|
|
91
97
|
const promise = (async () => {
|
|
92
98
|
// L2: check persistent cache before network
|
|
93
|
-
const
|
|
94
|
-
|
|
95
|
-
|
|
99
|
+
const entry = await __classPrivateFieldGet(this, _AgentClient_persistent, "f").get(did);
|
|
100
|
+
// entry.agent may be undefined for pre-TTL cache entries (migration) — treat as expired
|
|
101
|
+
if (entry?.agent && (now - (entry.ts ?? 0)) < AgentClient.REMOTE_AGENT_TTL_L2_MS) {
|
|
102
|
+
return entry.agent;
|
|
96
103
|
}
|
|
97
104
|
// L3: network fetch
|
|
98
105
|
const result = await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.byDid', { did });
|
|
99
|
-
__classPrivateFieldGet(this, _AgentClient_persistent, "f").put(did, result); // fire-and-forget write to L2
|
|
106
|
+
__classPrivateFieldGet(this, _AgentClient_persistent, "f").put(did, { agent: result, ts: Date.now() }); // fire-and-forget write to L2
|
|
100
107
|
return result;
|
|
101
108
|
})();
|
|
102
109
|
__classPrivateFieldGet(this, _AgentClient_memCache, "f").set(did, { promise, ts: now });
|
|
@@ -141,6 +148,12 @@ export class AgentClient {
|
|
|
141
148
|
const a = await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.updateProfile', { publicPerspective: cleanedPerspective });
|
|
142
149
|
const agent = new Agent(a.did, a.perspective);
|
|
143
150
|
agent.directMessageLanguage = a.directMessageLanguage;
|
|
151
|
+
// Immediately update byDID cache so subsequent byDID() calls
|
|
152
|
+
// return fresh data without waiting for the subscription event
|
|
153
|
+
if (agent.did) {
|
|
154
|
+
__classPrivateFieldGet(this, _AgentClient_memCache, "f").set(agent.did, { promise: Promise.resolve(agent), ts: Date.now() });
|
|
155
|
+
__classPrivateFieldGet(this, _AgentClient_persistent, "f").put(agent.did, { agent, ts: Date.now() }); // fire-and-forget
|
|
156
|
+
}
|
|
144
157
|
return agent;
|
|
145
158
|
}
|
|
146
159
|
async mutatePublicPerspective(mutations) {
|
|
@@ -165,6 +178,12 @@ export class AgentClient {
|
|
|
165
178
|
const a = await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.updateProfile', { dmLanguage: directMessageLanguage });
|
|
166
179
|
const agent = new Agent(a.did, a.perspective);
|
|
167
180
|
agent.directMessageLanguage = a.directMessageLanguage;
|
|
181
|
+
// Immediately update byDID cache so subsequent byDID() calls
|
|
182
|
+
// return fresh data without waiting for the subscription event
|
|
183
|
+
if (agent.did) {
|
|
184
|
+
__classPrivateFieldGet(this, _AgentClient_memCache, "f").set(agent.did, { promise: Promise.resolve(agent), ts: Date.now() });
|
|
185
|
+
__classPrivateFieldGet(this, _AgentClient_persistent, "f").put(agent.did, { agent, ts: Date.now() }); // fire-and-forget
|
|
186
|
+
}
|
|
168
187
|
return agent;
|
|
169
188
|
}
|
|
170
189
|
async addEntanglementProofs(proofs) {
|
|
@@ -195,7 +214,7 @@ export class AgentClient {
|
|
|
195
214
|
promise: Promise.resolve(agent),
|
|
196
215
|
ts: Date.now(),
|
|
197
216
|
});
|
|
198
|
-
__classPrivateFieldGet(this, _AgentClient_persistent, "f").put(agent.did, agent); // fire-and-forget
|
|
217
|
+
__classPrivateFieldGet(this, _AgentClient_persistent, "f").put(agent.did, { agent, ts: Date.now() }); // fire-and-forget
|
|
199
218
|
}
|
|
200
219
|
__classPrivateFieldGet(this, _AgentClient_updatedCallbacks, "f").forEach((cb) => cb(agent));
|
|
201
220
|
}
|
|
@@ -299,3 +318,6 @@ export class AgentClient {
|
|
|
299
318
|
_AgentClient_apiClient = new WeakMap(), _AgentClient_baseUrl = new WeakMap(), _AgentClient_token = new WeakMap(), _AgentClient_appsChangedCallback = new WeakMap(), _AgentClient_updatedCallbacks = new WeakMap(), _AgentClient_agentStatusChangedCallbacks = new WeakMap(), _AgentClient_hostingUserInfoChangedCallbacks = new WeakMap(), _AgentClient_computeLogUpdatedCallbacks = new WeakMap(), _AgentClient_unsubscribers = new WeakMap(), _AgentClient_memCache = new WeakMap(), _AgentClient_persistent = new WeakMap(), _AgentClient_selfDid = new WeakMap();
|
|
300
319
|
/** TTL for remote (non-self) agent profiles in L1 cache (ms). */
|
|
301
320
|
AgentClient.REMOTE_AGENT_TTL_MS = 5 * 60000; // 5 minutes
|
|
321
|
+
/** TTL for remote agent profiles in the L2 (IndexedDB) cache (ms).
|
|
322
|
+
* After this window any restart triggers a fresh network fetch. */
|
|
323
|
+
AgentClient.REMOTE_AGENT_TTL_L2_MS = 5 * 60000; // 5 minutes
|
package/lib/src/ai/AIClient.js
CHANGED
|
@@ -120,7 +120,7 @@ export class AIClient {
|
|
|
120
120
|
// Use slice to get only the relevant portion of the underlying ArrayBuffer
|
|
121
121
|
// (Float32Array may be a view over a larger buffer)
|
|
122
122
|
const bodyBuffer = typedAudio.buffer.slice(typedAudio.byteOffset, typedAudio.byteOffset + typedAudio.byteLength);
|
|
123
|
-
const response = await
|
|
123
|
+
const response = await __classPrivateFieldGet(this, _AIClient_apiClient, "f").doFetch(`${baseUrl}/api/v1/ai/transcription/feed`, {
|
|
124
124
|
method: 'POST',
|
|
125
125
|
headers: {
|
|
126
126
|
'Content-Type': 'application/octet-stream',
|
package/lib/src/apiClient.d.ts
CHANGED
|
@@ -14,9 +14,13 @@ export declare class RpcError extends Error {
|
|
|
14
14
|
export declare class ApiClient {
|
|
15
15
|
private baseUrl;
|
|
16
16
|
private token?;
|
|
17
|
-
|
|
17
|
+
private readonly _webSocketImpl?;
|
|
18
|
+
private readonly _fetchImpl?;
|
|
19
|
+
constructor(baseUrl: string, token?: string, webSocketImpl?: new (url: string) => WebSocket, fetchImpl?: typeof fetch);
|
|
18
20
|
getBaseUrl(): string;
|
|
19
21
|
getToken(): string | undefined;
|
|
22
|
+
/** Perform an HTTP request, using an injected fetch implementation if provided. */
|
|
23
|
+
doFetch(url: string, init: RequestInit): Promise<Response>;
|
|
20
24
|
setToken(token: string): void;
|
|
21
25
|
private _ws;
|
|
22
26
|
private _wsCallbacks;
|
package/lib/src/apiClient.js
CHANGED
|
@@ -19,7 +19,7 @@ function nextId() {
|
|
|
19
19
|
return String(++_idCounter);
|
|
20
20
|
}
|
|
21
21
|
export class ApiClient {
|
|
22
|
-
constructor(baseUrl, token) {
|
|
22
|
+
constructor(baseUrl, token, webSocketImpl, fetchImpl) {
|
|
23
23
|
// ── WebSocket RPC core ──────────────────────────────────────────────────
|
|
24
24
|
this._ws = null;
|
|
25
25
|
this._wsCallbacks = new Set();
|
|
@@ -32,9 +32,15 @@ export class ApiClient {
|
|
|
32
32
|
this._wsPingTimer = null;
|
|
33
33
|
this.baseUrl = baseUrl;
|
|
34
34
|
this.token = token;
|
|
35
|
+
this._webSocketImpl = webSocketImpl;
|
|
36
|
+
this._fetchImpl = fetchImpl;
|
|
35
37
|
}
|
|
36
38
|
getBaseUrl() { return this.baseUrl; }
|
|
37
39
|
getToken() { return this.token; }
|
|
40
|
+
/** Perform an HTTP request, using an injected fetch implementation if provided. */
|
|
41
|
+
doFetch(url, init) {
|
|
42
|
+
return this._fetchImpl ? this._fetchImpl(url, init) : fetch(url, init);
|
|
43
|
+
}
|
|
38
44
|
setToken(token) {
|
|
39
45
|
this.token = token;
|
|
40
46
|
}
|
|
@@ -47,7 +53,7 @@ export class ApiClient {
|
|
|
47
53
|
return tokenParam ? `${wsBase}${path}?${tokenParam}` : `${wsBase}${path}`;
|
|
48
54
|
}
|
|
49
55
|
_ensureWs() {
|
|
50
|
-
if (this._ws && (this._ws.readyState ===
|
|
56
|
+
if (this._ws && (this._ws.readyState === 1 /* OPEN */ || this._ws.readyState === 0 /* CONNECTING */)) {
|
|
51
57
|
return;
|
|
52
58
|
}
|
|
53
59
|
// Prevent duplicate connections from concurrent callers
|
|
@@ -58,7 +64,8 @@ export class ApiClient {
|
|
|
58
64
|
this._wsReadyResolve = resolve;
|
|
59
65
|
});
|
|
60
66
|
const url = this._getWsUrl();
|
|
61
|
-
const
|
|
67
|
+
const WsImpl = this._webSocketImpl ?? WebSocket;
|
|
68
|
+
const ws = new WsImpl(url);
|
|
62
69
|
this._ws = ws;
|
|
63
70
|
ws.onopen = () => {
|
|
64
71
|
this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
|
|
@@ -108,12 +115,13 @@ export class ApiClient {
|
|
|
108
115
|
// Reset the readiness promise so future calls reconnect
|
|
109
116
|
this._wsReady = null;
|
|
110
117
|
// Reject all pending calls
|
|
118
|
+
const hadPendingCalls = this._pendingCalls.size > 0;
|
|
111
119
|
for (const [id, pending] of this._pendingCalls) {
|
|
112
120
|
clearTimeout(pending.timer);
|
|
113
121
|
pending.reject(new RpcError(503, 'WebSocket connection closed'));
|
|
114
122
|
}
|
|
115
123
|
this._pendingCalls.clear();
|
|
116
|
-
if (!this._wsClosed && (this._wsCallbacks.size > 0 ||
|
|
124
|
+
if (!this._wsClosed && (this._wsCallbacks.size > 0 || hadPendingCalls)) {
|
|
117
125
|
this._scheduleReconnect();
|
|
118
126
|
}
|
|
119
127
|
};
|
|
@@ -121,7 +129,7 @@ export class ApiClient {
|
|
|
121
129
|
_startPing() {
|
|
122
130
|
this._stopPing();
|
|
123
131
|
this._wsPingTimer = setInterval(() => {
|
|
124
|
-
if (this._ws && this._ws.readyState ===
|
|
132
|
+
if (this._ws && this._ws.readyState === 1 /* OPEN */) {
|
|
125
133
|
this._ws.send(JSON.stringify({ type: 'ping' }));
|
|
126
134
|
}
|
|
127
135
|
}, 30000);
|
|
@@ -174,7 +182,7 @@ export class ApiClient {
|
|
|
174
182
|
reject,
|
|
175
183
|
timer,
|
|
176
184
|
});
|
|
177
|
-
if (this._ws && this._ws.readyState ===
|
|
185
|
+
if (this._ws && this._ws.readyState === 1 /* OPEN */) {
|
|
178
186
|
this._ws.send(JSON.stringify(message));
|
|
179
187
|
}
|
|
180
188
|
else {
|
package/lib/src/index.d.ts
CHANGED
|
@@ -16,6 +16,7 @@ export * from "./Literal";
|
|
|
16
16
|
export * from "./perspectives/Perspective";
|
|
17
17
|
export * from "./perspectives/PerspectiveHandle";
|
|
18
18
|
export * from "./perspectives/PerspectiveProxy";
|
|
19
|
+
export * from "./perspectives/SparqlBindings";
|
|
19
20
|
export * from "./perspectives/WakerSubscriptionManager";
|
|
20
21
|
export * from "./perspectives/PerspectiveDiff";
|
|
21
22
|
export * from "./perspectives/LinkQuery";
|
|
@@ -33,6 +34,9 @@ export * from "./runtime/RuntimeTypes";
|
|
|
33
34
|
export { Model as AIModel, ModelApi, TokenizerSource, LocalModel, ModelType, ModelApiInput, TokenizerSourceInput, LocalModelInput, ModelInput, VoiceActivityParamsInput } from "./ai/AITypes";
|
|
34
35
|
export * from './shacl/SHACLShape';
|
|
35
36
|
export { SHACLFlow, FlowState, FlowTransition, LinkPattern, FlowableCondition } from './shacl/SHACLFlow';
|
|
37
|
+
export * from './shacl/NodeExpression';
|
|
38
|
+
export * from './shacl/builders';
|
|
39
|
+
export { fileToDataUri } from './shacl/index';
|
|
36
40
|
export * from "./generated/api";
|
|
37
41
|
export { RpcError } from "./apiClient";
|
|
38
42
|
/** @deprecated Use `RpcError` instead. */
|
package/lib/src/index.js
CHANGED
|
@@ -16,6 +16,7 @@ export * from "./Literal";
|
|
|
16
16
|
export * from "./perspectives/Perspective";
|
|
17
17
|
export * from "./perspectives/PerspectiveHandle";
|
|
18
18
|
export * from "./perspectives/PerspectiveProxy";
|
|
19
|
+
export * from "./perspectives/SparqlBindings";
|
|
19
20
|
export * from "./perspectives/WakerSubscriptionManager";
|
|
20
21
|
export * from "./perspectives/PerspectiveDiff";
|
|
21
22
|
export * from "./perspectives/LinkQuery";
|
|
@@ -33,6 +34,9 @@ export * from "./runtime/RuntimeTypes";
|
|
|
33
34
|
export { Model as AIModel, ModelApi, TokenizerSource, LocalModel, ModelApiInput, TokenizerSourceInput, LocalModelInput, ModelInput, VoiceActivityParamsInput } from "./ai/AITypes";
|
|
34
35
|
export * from './shacl/SHACLShape';
|
|
35
36
|
export { SHACLFlow } from './shacl/SHACLFlow';
|
|
37
|
+
export * from './shacl/NodeExpression';
|
|
38
|
+
export * from './shacl/builders';
|
|
39
|
+
export { fileToDataUri } from './shacl/index';
|
|
36
40
|
export * from "./generated/api";
|
|
37
41
|
export { RpcError } from "./apiClient";
|
|
38
42
|
/** @deprecated Use `RpcError` instead. */
|
|
@@ -2,7 +2,7 @@ import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
|
|
|
2
2
|
import type { SHACLShape } from "../shacl/SHACLShape";
|
|
3
3
|
import type { JSONSchema, JSONSchemaToModelOptions } from "./json-schema";
|
|
4
4
|
import { ModelQueryBuilder } from "./ModelQueryBuilder";
|
|
5
|
-
import type { ParentScope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata } from "./types";
|
|
5
|
+
import type { ParentScope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata, TypedQuery, IncludeExtras, IncludeOf } from "./types";
|
|
6
6
|
/**
|
|
7
7
|
* Base class for defining data models in AD4M.
|
|
8
8
|
*
|
|
@@ -229,7 +229,8 @@ export declare class Ad4mModel {
|
|
|
229
229
|
* • `null` / empty object — skip ALL relations (used by bare
|
|
230
230
|
* subscriptions that don't eagerly load relations).
|
|
231
231
|
*/
|
|
232
|
-
|
|
232
|
+
/** @internal */
|
|
233
|
+
protected takeSnapshot(includedRelations?: Record<string, any> | null): void;
|
|
233
234
|
/**
|
|
234
235
|
* Returns `true` if any tracked property or relation has changed
|
|
235
236
|
* since the last hydration (or since `takeSnapshot()` was last called).
|
|
@@ -299,13 +300,14 @@ export declare class Ad4mModel {
|
|
|
299
300
|
static queryToSPARQL(perspective: PerspectiveProxy, query: Query): Promise<string>;
|
|
300
301
|
/**
|
|
301
302
|
* Build the JSON parameters needed for a model query/subscription endpoint.
|
|
302
|
-
* Returns the className
|
|
303
|
+
* Returns the className and queryJson that the Rust executor expects.
|
|
304
|
+
* Shape resolution happens server-side from the perspective's SHACL triples.
|
|
303
305
|
* @internal
|
|
304
306
|
*/
|
|
305
307
|
static prepareModelQueryParams(query?: Query, classNameOverride?: string | null): {
|
|
306
308
|
className: string;
|
|
307
309
|
queryJson: string;
|
|
308
|
-
|
|
310
|
+
metadata: ModelMetadata;
|
|
309
311
|
};
|
|
310
312
|
/**
|
|
311
313
|
* Parse raw model query/subscription result JSON into typed model instances.
|
|
@@ -313,21 +315,6 @@ export declare class Ad4mModel {
|
|
|
313
315
|
* @internal
|
|
314
316
|
*/
|
|
315
317
|
static parseModelResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, raw: any, include?: IncludeMap, properties?: string[]): T[];
|
|
316
|
-
/**
|
|
317
|
-
* Resolve non-literal (file-language) properties on an array of already-constructed
|
|
318
|
-
* model instances. Handles two cases:
|
|
319
|
-
*
|
|
320
|
-
* 1. The Rust executor returned a raw URI string → fetch via `getExpression` then apply transform.
|
|
321
|
-
* 2. The Rust executor already resolved the expression and returned a `FileData` object
|
|
322
|
-
* (happens when the perspective backend eagerly fetches file content) → apply transform
|
|
323
|
-
* (or `defaultFileDecode` if no transform is registered on the class, e.g. for SHACL-
|
|
324
|
-
* synthesised model classes).
|
|
325
|
-
*
|
|
326
|
-
* Extracted as a public static so `ModelQueryBuilder.subscribe()` can reuse it without
|
|
327
|
-
* duplicating logic or introducing a circular dependency.
|
|
328
|
-
* @internal
|
|
329
|
-
*/
|
|
330
|
-
static resolveNonLiteralProps<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, instances: T[]): Promise<void>;
|
|
331
318
|
/**
|
|
332
319
|
* Execute a model query via the executor-side endpoint.
|
|
333
320
|
*
|
|
@@ -342,15 +329,14 @@ export declare class Ad4mModel {
|
|
|
342
329
|
*
|
|
343
330
|
* @param perspective - The perspective to search in
|
|
344
331
|
* @param query - Optional query parameters to filter results
|
|
345
|
-
* @param
|
|
332
|
+
* @param _engine - **Deprecated.** Accepted for backward compatibility but ignored.
|
|
333
|
+
* All queries now use the Rust SPARQL pipeline.
|
|
346
334
|
* @returns Array of matching models
|
|
347
335
|
*
|
|
348
336
|
* @example
|
|
349
337
|
* ```typescript
|
|
350
|
-
* // Get all recipes (uses SPARQL by default)
|
|
351
338
|
* const allRecipes = await Recipe.findAll(perspective);
|
|
352
339
|
*
|
|
353
|
-
* // Get recipes with specific criteria (uses SPARQL)
|
|
354
340
|
* const recipes = await Recipe.findAll(perspective, {
|
|
355
341
|
* where: {
|
|
356
342
|
* name: "Pasta",
|
|
@@ -359,12 +345,9 @@ export declare class Ad4mModel {
|
|
|
359
345
|
* order: { createdAt: "DESC" },
|
|
360
346
|
* limit: 10
|
|
361
347
|
* });
|
|
362
|
-
*
|
|
363
|
-
* // Explicitly use Prolog (legacy, for backward compatibility)
|
|
364
|
-
* const recipesProlog = await Recipe.findAll(perspective, {}, false);
|
|
365
348
|
* ```
|
|
366
349
|
*/
|
|
367
|
-
static findAll<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?:
|
|
350
|
+
static findAll<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Q): Promise<(T & IncludeExtras<T, IncludeOf<Q>>)[]>;
|
|
368
351
|
/**
|
|
369
352
|
* Finds the first instance matching the query, or `null` if none exists.
|
|
370
353
|
*
|
|
@@ -372,7 +355,7 @@ export declare class Ad4mModel {
|
|
|
372
355
|
*
|
|
373
356
|
* @param perspective - The perspective to search in
|
|
374
357
|
* @param query - Optional query parameters to filter results
|
|
375
|
-
* @param
|
|
358
|
+
* @param _engine - **Deprecated.** Accepted for backward compatibility but ignored.
|
|
376
359
|
* @returns The first matching instance, or `null`
|
|
377
360
|
*
|
|
378
361
|
* @example
|
|
@@ -385,13 +368,13 @@ export declare class Ad4mModel {
|
|
|
385
368
|
* }
|
|
386
369
|
* ```
|
|
387
370
|
*/
|
|
388
|
-
static findOne<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?:
|
|
371
|
+
static findOne<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Q): Promise<(T & IncludeExtras<T, IncludeOf<Q>>) | null>;
|
|
389
372
|
/**
|
|
390
373
|
* Gets all instances with count of total matches without offset & limit applied.
|
|
391
374
|
*
|
|
392
375
|
* @param perspective - The perspective to search in
|
|
393
376
|
* @param query - Optional query parameters to filter results
|
|
394
|
-
* @param
|
|
377
|
+
* @param _engine - **Deprecated.** Accepted for backward compatibility but ignored.
|
|
395
378
|
* @returns Object containing results array and total count
|
|
396
379
|
*
|
|
397
380
|
* @example
|
|
@@ -401,12 +384,9 @@ export declare class Ad4mModel {
|
|
|
401
384
|
* limit: 10
|
|
402
385
|
* });
|
|
403
386
|
* console.log(`Showing 10 of ${totalCount} dessert recipes`);
|
|
404
|
-
*
|
|
405
|
-
* // Use Prolog explicitly (legacy)
|
|
406
|
-
* const { results, totalCount } = await Recipe.findAllAndCount(perspective, {}, false);
|
|
407
387
|
* ```
|
|
408
388
|
*/
|
|
409
|
-
static findAllAndCount<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?:
|
|
389
|
+
static findAllAndCount<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Q): Promise<ResultsWithTotalCount<T & IncludeExtras<T, IncludeOf<Q>>>>;
|
|
410
390
|
/**
|
|
411
391
|
* Helper function for pagination with explicit page size and number.
|
|
412
392
|
*
|
|
@@ -424,7 +404,7 @@ export declare class Ad4mModel {
|
|
|
424
404
|
* console.log(`Page ${page.pageNumber} of recipes, ${page.results.length} items`);
|
|
425
405
|
* ```
|
|
426
406
|
*/
|
|
427
|
-
static paginate<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, pageSize: number, pageNumber: number, query?:
|
|
407
|
+
static paginate<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, pageSize: number, pageNumber: number, query?: Q): Promise<PaginationResult<T & IncludeExtras<T, IncludeOf<Q>>>>;
|
|
428
408
|
/**
|
|
429
409
|
* Generates a SPARQL COUNT query for the model.
|
|
430
410
|
*
|
|
@@ -449,7 +429,7 @@ export declare class Ad4mModel {
|
|
|
449
429
|
* });
|
|
450
430
|
* ```
|
|
451
431
|
*/
|
|
452
|
-
static count(perspective: PerspectiveProxy, query?:
|
|
432
|
+
static count<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: TypedQuery<T>): Promise<number>;
|
|
453
433
|
private setProperty;
|
|
454
434
|
/** Resolve a relation argument to a plain string ID. Accepts either a raw
|
|
455
435
|
* string ID or an Ad4mModel instance (in which case `.id` is used). */
|
|
@@ -651,6 +631,20 @@ export declare class Ad4mModel {
|
|
|
651
631
|
* ```
|
|
652
632
|
*/
|
|
653
633
|
static register(this: typeof Ad4mModel, perspective: PerspectiveProxy): Promise<void>;
|
|
634
|
+
/**
|
|
635
|
+
* Batch-registers multiple model classes on a perspective in a single RPC call.
|
|
636
|
+
* This is significantly faster than calling `register()` on each model individually
|
|
637
|
+
* because it eliminates N-1 round-trips and mutex acquisitions.
|
|
638
|
+
*
|
|
639
|
+
* @param perspective - The perspective to register the models on
|
|
640
|
+
* @param models - Array of Ad4mModel subclasses to register
|
|
641
|
+
*
|
|
642
|
+
* @example
|
|
643
|
+
* ```typescript
|
|
644
|
+
* await Ad4mModel.registerAll(perspective, [Community, Channel, Message, Task]);
|
|
645
|
+
* ```
|
|
646
|
+
*/
|
|
647
|
+
static registerAll(perspective: PerspectiveProxy, models: (typeof Ad4mModel)[]): Promise<void>;
|
|
654
648
|
/**
|
|
655
649
|
* Executes a set of model operations inside a single batch (transaction).
|
|
656
650
|
*
|
|
@@ -704,7 +698,7 @@ export declare class Ad4mModel {
|
|
|
704
698
|
* });
|
|
705
699
|
* ```
|
|
706
700
|
*/
|
|
707
|
-
static query<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?:
|
|
701
|
+
static query<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: TypedQuery<T>): ModelQueryBuilder<T>;
|
|
708
702
|
/**
|
|
709
703
|
* Creates an Ad4mModel class from a JSON Schema definition.
|
|
710
704
|
*
|