@coasys/ad4m 0.13.0-test-model-layer → 0.13.0-test-flows-1
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 +817 -65
- package/lib/index.js +814 -66
- package/lib/src/ai/AIClient.d.ts +13 -0
- package/lib/src/ai/AIClient.js +15 -0
- package/lib/src/ai/AITypes.d.ts +5 -0
- package/lib/src/index.js +2 -0
- package/lib/src/model/Ad4mModel.d.ts +6 -1
- package/lib/src/model/Ad4mModel.js +41 -6
- package/lib/src/model/ModelQueryBuilder.d.ts +47 -3
- package/lib/src/model/ModelQueryBuilder.js +97 -6
- package/lib/src/model/query-common.d.ts +10 -1
- package/lib/src/model/query-common.js +16 -0
- package/lib/src/model/query-sparql.d.ts +11 -0
- package/lib/src/model/query-sparql.js +93 -1
- package/lib/src/model/query-utils.js +16 -0
- package/lib/src/model/shacl-gen.js +12 -0
- package/lib/src/model/types.d.ts +320 -3
- package/lib/src/model/types.js +9 -0
- package/lib/src/perspectives/AutoProcessor.d.ts +8 -0
- package/lib/src/perspectives/FlowInstance.d.ts +176 -12
- package/lib/src/perspectives/FlowInstance.js +77 -13
- package/lib/src/perspectives/FlowModels.d.ts +40 -9
- package/lib/src/perspectives/FlowModels.js +59 -13
- package/lib/src/perspectives/PerspectiveClient.d.ts +18 -0
- package/lib/src/perspectives/PerspectiveClient.js +30 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +69 -2
- package/lib/src/perspectives/PerspectiveProxy.js +157 -7
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +55 -5
- package/lib/src/perspectives/WakerSubscriptionManager.js +183 -8
- package/lib/src/shacl/SHACLFlow.d.ts +43 -0
- package/package.json +1 -1
- package/src/ai/AIClient.ts +16 -0
- package/src/ai/AITypes.ts +5 -0
- package/src/index.ts +2 -0
- package/src/model/Ad4mModel.test.ts +442 -0
- package/src/model/Ad4mModel.ts +39 -7
- package/src/model/ModelQueryBuilder.ts +101 -10
- package/src/model/query-common.ts +20 -1
- package/src/model/query-sparql.test.ts +115 -0
- package/src/model/query-sparql.ts +97 -1
- package/src/model/query-utils.ts +18 -0
- package/src/model/relation-filtering.test.ts +7 -0
- package/src/model/shacl-gen.ts +12 -0
- package/src/model/shacl-roundtrip.test.ts +71 -0
- package/src/model/types-typed-query.test.ts +42 -0
- package/src/model/types.ts +316 -6
- package/src/perspectives/AutoProcessor.ts +8 -0
- package/src/perspectives/FlowInstance.ts +194 -13
- package/src/perspectives/FlowModels.ts +53 -13
- package/src/perspectives/PerspectiveClient.ts +62 -0
- package/src/perspectives/PerspectiveProxy.test.ts +272 -0
- package/src/perspectives/PerspectiveProxy.ts +163 -7
- package/src/perspectives/WakerSubscriptionManager.test.ts +199 -0
- package/src/perspectives/WakerSubscriptionManager.ts +197 -9
- package/src/shacl/SHACLFlow.ts +44 -0
package/lib/src/ai/AIClient.d.ts
CHANGED
|
@@ -6,6 +6,19 @@ export declare class AIClient {
|
|
|
6
6
|
constructor(baseUrl: string, token?: string, subscribe?: boolean, sharedApiClient?: ApiClient);
|
|
7
7
|
private serializeModelInput;
|
|
8
8
|
getModels(): Promise<Model[]>;
|
|
9
|
+
/**
|
|
10
|
+
* Ask a remote endpoint which models it serves, before adding one.
|
|
11
|
+
*
|
|
12
|
+
* Takes the credentials of a model that does not exist yet — a settings
|
|
13
|
+
* form is being filled in and wants the list to pick from. Rejects when
|
|
14
|
+
* the endpoint is unreachable or the key is refused, which makes this the
|
|
15
|
+
* credential check too: without it a bad key surfaces later as a failed
|
|
16
|
+
* completion carrying an error from a different layer.
|
|
17
|
+
*
|
|
18
|
+
* `apiType` defaults to the OpenAI shape, which is what every endpoint
|
|
19
|
+
* that is not Anthropic speaks.
|
|
20
|
+
*/
|
|
21
|
+
discoverModels(baseUrl: string, apiKey?: string, apiType?: string): Promise<string[]>;
|
|
9
22
|
addModel(model: ModelInput): Promise<string>;
|
|
10
23
|
updateModel(modelId: string, model: ModelInput): Promise<boolean>;
|
|
11
24
|
removeModel(modelId: string): Promise<boolean>;
|
package/lib/src/ai/AIClient.js
CHANGED
|
@@ -32,6 +32,21 @@ export class AIClient {
|
|
|
32
32
|
async getModels() {
|
|
33
33
|
return __classPrivateFieldGet(this, _AIClient_apiClient, "f").call('ai.models');
|
|
34
34
|
}
|
|
35
|
+
/**
|
|
36
|
+
* Ask a remote endpoint which models it serves, before adding one.
|
|
37
|
+
*
|
|
38
|
+
* Takes the credentials of a model that does not exist yet — a settings
|
|
39
|
+
* form is being filled in and wants the list to pick from. Rejects when
|
|
40
|
+
* the endpoint is unreachable or the key is refused, which makes this the
|
|
41
|
+
* credential check too: without it a bad key surfaces later as a failed
|
|
42
|
+
* completion carrying an error from a different layer.
|
|
43
|
+
*
|
|
44
|
+
* `apiType` defaults to the OpenAI shape, which is what every endpoint
|
|
45
|
+
* that is not Anthropic speaks.
|
|
46
|
+
*/
|
|
47
|
+
async discoverModels(baseUrl, apiKey, apiType) {
|
|
48
|
+
return __classPrivateFieldGet(this, _AIClient_apiClient, "f").call('ai.discoverModels', { baseUrl, apiKey, apiType });
|
|
49
|
+
}
|
|
35
50
|
async addModel(model) {
|
|
36
51
|
return __classPrivateFieldGet(this, _AIClient_apiClient, "f").call('ai.addModel', { model: this.serializeModelInput(model) });
|
|
37
52
|
}
|
package/lib/src/ai/AITypes.d.ts
CHANGED
|
@@ -3,6 +3,9 @@ export declare class ModelApi {
|
|
|
3
3
|
apiKey: string;
|
|
4
4
|
model: string;
|
|
5
5
|
apiType: String;
|
|
6
|
+
/** Optional ceiling for the provider's context window (tokens).
|
|
7
|
+
* Read by the Ollama provider to bound num_ctx / KV-cache VRAM. */
|
|
8
|
+
maxNumCtx?: number;
|
|
6
9
|
}
|
|
7
10
|
export declare class TokenizerSource {
|
|
8
11
|
repo: string;
|
|
@@ -28,6 +31,8 @@ export declare class ModelApiInput {
|
|
|
28
31
|
apiKey: string;
|
|
29
32
|
model: string;
|
|
30
33
|
apiType: string;
|
|
34
|
+
/** Optional ceiling for the provider's context window (tokens). */
|
|
35
|
+
maxNumCtx?: number;
|
|
31
36
|
}
|
|
32
37
|
export declare class TokenizerSourceInput {
|
|
33
38
|
repo: string;
|
package/lib/src/index.js
CHANGED
|
@@ -19,6 +19,8 @@ export * from "./perspectives/PerspectiveProxy";
|
|
|
19
19
|
export * from "./perspectives/AutoProcessor";
|
|
20
20
|
export * from "./perspectives/InterpretationModels";
|
|
21
21
|
export * from "./perspectives/FlowModels";
|
|
22
|
+
// Also exports FlowFireOutcome / FlowProposeResult, the result shapes of the
|
|
23
|
+
// flow write API — they live beside the `proposeTransition()` surface.
|
|
22
24
|
export * from "./perspectives/FlowInstance";
|
|
23
25
|
export * from "./perspectives/SparqlBindings";
|
|
24
26
|
export * from "./perspectives/WakerSubscriptionManager";
|
|
@@ -3,7 +3,7 @@ import { CallOptions } from "../apiClient";
|
|
|
3
3
|
import type { SHACLShape } from "../shacl/SHACLShape";
|
|
4
4
|
import type { JSONSchema, JSONSchemaToModelOptions } from "./json-schema";
|
|
5
5
|
import { ModelQueryBuilder } from "./ModelQueryBuilder";
|
|
6
|
-
import type { Scope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata, TypedQuery, IncludeExtras, IncludeOf } from "./types";
|
|
6
|
+
import type { Scope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata, TypedQuery, IncludeExtras, IncludeOf, LinksMap } from "./types";
|
|
7
7
|
/**
|
|
8
8
|
* Base class for defining data models in AD4M.
|
|
9
9
|
*
|
|
@@ -123,6 +123,11 @@ export declare class Ad4mModel {
|
|
|
123
123
|
author: string;
|
|
124
124
|
createdAt: any;
|
|
125
125
|
updatedAt: any;
|
|
126
|
+
/**
|
|
127
|
+
* Per-link rows for the entries asked for with `Query.links`, keyed as they
|
|
128
|
+
* were asked. Absent when the query did not ask for any.
|
|
129
|
+
*/
|
|
130
|
+
__links?: LinksMap;
|
|
126
131
|
/**
|
|
127
132
|
* Backwards compatibility alias for createdAt.
|
|
128
133
|
* @deprecated Use createdAt instead. This will be removed in a future version.
|
|
@@ -2,11 +2,12 @@ import { Link } from "../links/Links";
|
|
|
2
2
|
import { LinkQuery } from "../perspectives/LinkQuery";
|
|
3
3
|
import { makeRandomId } from "./util";
|
|
4
4
|
import { getPropertiesMetadata, getRelationsMetadata, setPropertyRegistryEntry, setRelationRegistryEntry, Model } from "./decorators";
|
|
5
|
-
import { resolveParentPredicate } from "./query-common";
|
|
5
|
+
import { requireSingleParent, resolveParentPredicate } from "./query-common";
|
|
6
6
|
import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
|
|
7
7
|
import { buildSPARQLQuery, valueToLiteralIri, effectiveLiteralStorage } from "./query-sparql";
|
|
8
8
|
import { ModelQueryBuilder } from "./ModelQueryBuilder";
|
|
9
9
|
import { normalizeValue, } from "./hydration";
|
|
10
|
+
import { isTraverseScope } from "./types";
|
|
10
11
|
// ---------------------------------------------------------------------------
|
|
11
12
|
// Helpers for Rust-side include resolution
|
|
12
13
|
// ---------------------------------------------------------------------------
|
|
@@ -895,7 +896,33 @@ export class Ad4mModel {
|
|
|
895
896
|
const queryInput = {};
|
|
896
897
|
if (query.parent) {
|
|
897
898
|
const parentPredicate = resolveParentPredicate(query.parent, this);
|
|
898
|
-
|
|
899
|
+
// A traversal keeps its own shape on the wire: the executor reads `ids`,
|
|
900
|
+
// and flattening it to one `id` here is how a request for a whole level
|
|
901
|
+
// would quietly become a request for one parent's children.
|
|
902
|
+
//
|
|
903
|
+
// Its fields are named rather than spread, because `model` — the class
|
|
904
|
+
// itself — is how the scope may name its predicate, and that is a
|
|
905
|
+
// constructor, not something to put in a query variable. The predicate is
|
|
906
|
+
// resolved above; what travels is the result.
|
|
907
|
+
if (isTraverseScope(query.parent)) {
|
|
908
|
+
const t = query.parent;
|
|
909
|
+
const traverse = {
|
|
910
|
+
ids: t.ids,
|
|
911
|
+
predicate: parentPredicate,
|
|
912
|
+
};
|
|
913
|
+
if (t.transitive !== undefined)
|
|
914
|
+
traverse.transitive = t.transitive;
|
|
915
|
+
if (t.direction !== undefined)
|
|
916
|
+
traverse.direction = t.direction;
|
|
917
|
+
if (t.limitPerAnchor !== undefined)
|
|
918
|
+
traverse.limitPerAnchor = t.limitPerAnchor;
|
|
919
|
+
if (t.levels !== undefined)
|
|
920
|
+
traverse.levels = t.levels;
|
|
921
|
+
queryInput.parent = traverse;
|
|
922
|
+
}
|
|
923
|
+
else {
|
|
924
|
+
queryInput.parent = { id: query.parent.id, predicate: parentPredicate };
|
|
925
|
+
}
|
|
899
926
|
}
|
|
900
927
|
if (query.properties)
|
|
901
928
|
queryInput.properties = query.properties;
|
|
@@ -957,7 +984,13 @@ export class Ad4mModel {
|
|
|
957
984
|
queryInput.limit = query.limit;
|
|
958
985
|
if (query.count !== undefined)
|
|
959
986
|
queryInput.count = query.count;
|
|
987
|
+
if (query.links)
|
|
988
|
+
queryInput.links = query.links;
|
|
960
989
|
queryInput.deepQuery = query.deepQuery ?? true;
|
|
990
|
+
if (query.linkStatus != null)
|
|
991
|
+
queryInput.linkStatus = query.linkStatus;
|
|
992
|
+
if (query.includeUnverified !== undefined)
|
|
993
|
+
queryInput.includeUnverified = query.includeUnverified;
|
|
961
994
|
// Conformance getters, where filters, and target shapes for includes
|
|
962
995
|
// are all resolved by the executor from the perspective's SHACL triples
|
|
963
996
|
// — no client-side pre-computation is needed any more.
|
|
@@ -1667,9 +1700,10 @@ export class Ad4mModel {
|
|
|
1667
1700
|
if (options?.parent && !options?.batchId) {
|
|
1668
1701
|
const batchId = await perspective.createBatch();
|
|
1669
1702
|
await instance.save(batchId);
|
|
1670
|
-
const
|
|
1703
|
+
const parent = requireSingleParent(options.parent);
|
|
1704
|
+
const predicate = resolveParentPredicate(parent, this);
|
|
1671
1705
|
const link = new Link({
|
|
1672
|
-
source:
|
|
1706
|
+
source: parent.id,
|
|
1673
1707
|
predicate,
|
|
1674
1708
|
target: instance.id,
|
|
1675
1709
|
});
|
|
@@ -1683,9 +1717,10 @@ export class Ad4mModel {
|
|
|
1683
1717
|
await instance.save(options?.batchId);
|
|
1684
1718
|
// Create parent → child link if a parent scope was provided
|
|
1685
1719
|
if (options?.parent) {
|
|
1686
|
-
const
|
|
1720
|
+
const parent = requireSingleParent(options.parent);
|
|
1721
|
+
const predicate = resolveParentPredicate(parent, this);
|
|
1687
1722
|
const link = new Link({
|
|
1688
|
-
source:
|
|
1723
|
+
source: parent.id,
|
|
1689
1724
|
predicate,
|
|
1690
1725
|
target: instance.id,
|
|
1691
1726
|
});
|
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
* running them once or subscribing to real-time updates.
|
|
6
6
|
*/
|
|
7
7
|
import type { Ad4mModel } from "./Ad4mModel";
|
|
8
|
-
import type { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
|
|
9
|
-
import type { Query, PaginationResult,
|
|
8
|
+
import type { LinkStatus, PerspectiveProxy } from "../perspectives/PerspectiveProxy";
|
|
9
|
+
import type { Query, PaginationResult, TypedQueryWhere, TypedOrder, TypedIncludeMap, PropertyKeysOf } from "./types";
|
|
10
10
|
/** Query builder for Ad4mModel queries.
|
|
11
11
|
* Allows building queries with a fluent interface and either running them once
|
|
12
12
|
* or subscribing to updates.
|
|
@@ -63,7 +63,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
63
63
|
* })
|
|
64
64
|
* ```
|
|
65
65
|
*/
|
|
66
|
-
where(conditions:
|
|
66
|
+
where(conditions: TypedQueryWhere<T>): ModelQueryBuilder<T>;
|
|
67
67
|
/**
|
|
68
68
|
* Sets the order for the query results.
|
|
69
69
|
*
|
|
@@ -157,6 +157,20 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
157
157
|
* ```
|
|
158
158
|
*/
|
|
159
159
|
properties(properties: PropertyKeysOf<T>[] | string[]): ModelQueryBuilder<T>;
|
|
160
|
+
/**
|
|
161
|
+
* Asks for the individual links behind each instance — author, timestamp
|
|
162
|
+
* and proof per link — under `instance.__links`. See `Query.links`.
|
|
163
|
+
*
|
|
164
|
+
* @param keys - Property / relation names, or absolute predicate IRIs
|
|
165
|
+
* @returns The query builder for chaining
|
|
166
|
+
*
|
|
167
|
+
* @example
|
|
168
|
+
* ```typescript
|
|
169
|
+
* const [post] = await Post.query(perspective).links(["comments"]).get();
|
|
170
|
+
* post.__links!.comments.map((l) => l.timestamp); // when each comment was attached
|
|
171
|
+
* ```
|
|
172
|
+
*/
|
|
173
|
+
links(keys: string[]): ModelQueryBuilder<T>;
|
|
160
174
|
/**
|
|
161
175
|
* Controls whether SPARQL property getters are evaluated during hydration.
|
|
162
176
|
*
|
|
@@ -176,6 +190,36 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
176
190
|
* ```
|
|
177
191
|
*/
|
|
178
192
|
deepQuery(enabled?: boolean): ModelQueryBuilder<T>;
|
|
193
|
+
/**
|
|
194
|
+
* Reads instances as they exist in links of one status only.
|
|
195
|
+
*
|
|
196
|
+
* `'shared'` leaves out every Local link, both from the values returned and
|
|
197
|
+
* from what decides which instances are returned. Use it when the data is
|
|
198
|
+
* shown to another user. `'local'` is the converse: it returns only
|
|
199
|
+
* instances flagged in a Local link, so a Local note on a card flagged only
|
|
200
|
+
* in a Shared link is read without `linkStatus`, not under `'local'`.
|
|
201
|
+
* See {@link Query.linkStatus}.
|
|
202
|
+
*
|
|
203
|
+
* @param status - `'shared'` or `'local'`
|
|
204
|
+
* @returns The query builder for chaining
|
|
205
|
+
*
|
|
206
|
+
* @example
|
|
207
|
+
* ```typescript
|
|
208
|
+
* const cards = await Card.query(perspective).linkStatus('shared').get();
|
|
209
|
+
* ```
|
|
210
|
+
*/
|
|
211
|
+
linkStatus(status: LinkStatus): ModelQueryBuilder<T>;
|
|
212
|
+
/**
|
|
213
|
+
* Also hydrate from links whose signature did not verify.
|
|
214
|
+
*
|
|
215
|
+
* Off by default: the executor withholds unverified links. Turn it on only
|
|
216
|
+
* to *display* an unverified claim, never for data you act on. See
|
|
217
|
+
* {@link Query.includeUnverified}.
|
|
218
|
+
*
|
|
219
|
+
* @param enabled - Whether to include unverified links (default: true)
|
|
220
|
+
* @returns The query builder for chaining
|
|
221
|
+
*/
|
|
222
|
+
includeUnverified(enabled?: boolean): ModelQueryBuilder<T>;
|
|
179
223
|
/**
|
|
180
224
|
* Specifies which relations to eager-load (hydrate into model instances).
|
|
181
225
|
*
|
|
@@ -200,6 +200,23 @@ export class ModelQueryBuilder {
|
|
|
200
200
|
this.queryParams.properties = properties;
|
|
201
201
|
return this;
|
|
202
202
|
}
|
|
203
|
+
/**
|
|
204
|
+
* Asks for the individual links behind each instance — author, timestamp
|
|
205
|
+
* and proof per link — under `instance.__links`. See `Query.links`.
|
|
206
|
+
*
|
|
207
|
+
* @param keys - Property / relation names, or absolute predicate IRIs
|
|
208
|
+
* @returns The query builder for chaining
|
|
209
|
+
*
|
|
210
|
+
* @example
|
|
211
|
+
* ```typescript
|
|
212
|
+
* const [post] = await Post.query(perspective).links(["comments"]).get();
|
|
213
|
+
* post.__links!.comments.map((l) => l.timestamp); // when each comment was attached
|
|
214
|
+
* ```
|
|
215
|
+
*/
|
|
216
|
+
links(keys) {
|
|
217
|
+
this.queryParams.links = keys;
|
|
218
|
+
return this;
|
|
219
|
+
}
|
|
203
220
|
/**
|
|
204
221
|
* Controls whether SPARQL property getters are evaluated during hydration.
|
|
205
222
|
*
|
|
@@ -222,6 +239,42 @@ export class ModelQueryBuilder {
|
|
|
222
239
|
this.queryParams.deepQuery = enabled;
|
|
223
240
|
return this;
|
|
224
241
|
}
|
|
242
|
+
/**
|
|
243
|
+
* Reads instances as they exist in links of one status only.
|
|
244
|
+
*
|
|
245
|
+
* `'shared'` leaves out every Local link, both from the values returned and
|
|
246
|
+
* from what decides which instances are returned. Use it when the data is
|
|
247
|
+
* shown to another user. `'local'` is the converse: it returns only
|
|
248
|
+
* instances flagged in a Local link, so a Local note on a card flagged only
|
|
249
|
+
* in a Shared link is read without `linkStatus`, not under `'local'`.
|
|
250
|
+
* See {@link Query.linkStatus}.
|
|
251
|
+
*
|
|
252
|
+
* @param status - `'shared'` or `'local'`
|
|
253
|
+
* @returns The query builder for chaining
|
|
254
|
+
*
|
|
255
|
+
* @example
|
|
256
|
+
* ```typescript
|
|
257
|
+
* const cards = await Card.query(perspective).linkStatus('shared').get();
|
|
258
|
+
* ```
|
|
259
|
+
*/
|
|
260
|
+
linkStatus(status) {
|
|
261
|
+
this.queryParams.linkStatus = status;
|
|
262
|
+
return this;
|
|
263
|
+
}
|
|
264
|
+
/**
|
|
265
|
+
* Also hydrate from links whose signature did not verify.
|
|
266
|
+
*
|
|
267
|
+
* Off by default: the executor withholds unverified links. Turn it on only
|
|
268
|
+
* to *display* an unverified claim, never for data you act on. See
|
|
269
|
+
* {@link Query.includeUnverified}.
|
|
270
|
+
*
|
|
271
|
+
* @param enabled - Whether to include unverified links (default: true)
|
|
272
|
+
* @returns The query builder for chaining
|
|
273
|
+
*/
|
|
274
|
+
includeUnverified(enabled = true) {
|
|
275
|
+
this.queryParams.includeUnverified = enabled;
|
|
276
|
+
return this;
|
|
277
|
+
}
|
|
225
278
|
/**
|
|
226
279
|
* Specifies which relations to eager-load (hydrate into model instances).
|
|
227
280
|
*
|
|
@@ -362,13 +415,10 @@ export class ModelQueryBuilder {
|
|
|
362
415
|
const unsubscribe = this.perspective.client.subscribeToQueryUpdates(subscriptionId, (rawResult) => {
|
|
363
416
|
try {
|
|
364
417
|
const results = parseResults(rawResult);
|
|
365
|
-
console.debug(`[ModelQueryBuilder.subscribe] Update received for ${subscriptionId}: ${results.length} instances`);
|
|
366
418
|
const fp = buildFingerprint(results);
|
|
367
419
|
if (fp === lastResultFingerprint) {
|
|
368
|
-
console.debug(`[ModelQueryBuilder.subscribe] Fingerprint unchanged, skipping callback`);
|
|
369
420
|
return;
|
|
370
421
|
}
|
|
371
|
-
console.debug(`[ModelQueryBuilder.subscribe] Fingerprint changed, calling callback with ${results.length} results`);
|
|
372
422
|
lastResultFingerprint = fp;
|
|
373
423
|
callback(results);
|
|
374
424
|
}
|
|
@@ -637,15 +687,56 @@ export class ModelQueryBuilder {
|
|
|
637
687
|
offset: pageSize * (pageNumber - 1),
|
|
638
688
|
count: true,
|
|
639
689
|
};
|
|
690
|
+
// One read in flight. A dispatch while a read is running sets `pending`
|
|
691
|
+
// so a fetch always completes after the last dispatch. The generation
|
|
692
|
+
// counter from #1020 dropped superseded fetches, but ordered them by
|
|
693
|
+
// start time rather than by how fresh the data they read was — two
|
|
694
|
+
// back-to-back dispatches could keep the fetch that saw 1 model and
|
|
695
|
+
// drop the one that saw 2, after which the server has nothing further
|
|
696
|
+
// to say (issue #1051 / CI: "Paginate callback did not see second model save").
|
|
697
|
+
// After dispose() no read starts and no result is delivered, including
|
|
698
|
+
// a read that was already in flight when dispose() ran.
|
|
699
|
+
let disposed = false;
|
|
700
|
+
let fetching = false;
|
|
701
|
+
let pending = false;
|
|
702
|
+
let coalesced = 0;
|
|
640
703
|
const processResults = async () => {
|
|
641
|
-
|
|
642
|
-
|
|
704
|
+
if (disposed)
|
|
705
|
+
return;
|
|
706
|
+
if (fetching) {
|
|
707
|
+
pending = true;
|
|
708
|
+
coalesced++;
|
|
709
|
+
return;
|
|
710
|
+
}
|
|
711
|
+
fetching = true;
|
|
712
|
+
try {
|
|
713
|
+
const { results, totalCount } = await ctor.executeModelQuery(this.perspective, paginatedQuery, this.modelClassName);
|
|
714
|
+
if (!disposed)
|
|
715
|
+
callback({ results, totalCount, pageSize, pageNumber });
|
|
716
|
+
}
|
|
717
|
+
finally {
|
|
718
|
+
fetching = false;
|
|
719
|
+
if (pending) {
|
|
720
|
+
const dispatches = coalesced;
|
|
721
|
+
pending = false;
|
|
722
|
+
coalesced = 0;
|
|
723
|
+
// Whether a trailing fetch actually starts is decided by the entry
|
|
724
|
+
// guard at the top of processResults, which returns when disposed.
|
|
725
|
+
// Log only what that guard will let through, or the dispose path
|
|
726
|
+
// announces a fetch it then drops.
|
|
727
|
+
if (!disposed) {
|
|
728
|
+
console.debug(`[ModelQueryBuilder.paginateSubscribe] ${dispatches} dispatch(es) during read for ${subscriptionId}, coalesced into one trailing fetch`);
|
|
729
|
+
}
|
|
730
|
+
// Detached from the caller's promise: needs its own handler, or a
|
|
731
|
+
// rejection here is unhandled.
|
|
732
|
+
processResults().catch(e => console.error('Paginate subscription error:', e));
|
|
733
|
+
}
|
|
734
|
+
}
|
|
643
735
|
};
|
|
644
736
|
const unsubscribe = this.perspective.client.subscribeToQueryUpdates(subscriptionId, (rawResult) => {
|
|
645
737
|
console.debug(`[ModelQueryBuilder.paginateSubscribe] Update received for ${subscriptionId}, re-fetching paginated data...`);
|
|
646
738
|
processResults().catch(e => console.error('Paginate subscription error:', e));
|
|
647
739
|
});
|
|
648
|
-
let disposed = false;
|
|
649
740
|
let keepaliveTimer;
|
|
650
741
|
let resubscribeAttempts = 0;
|
|
651
742
|
const MAX_RESUBSCRIBE_ATTEMPTS = 5;
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Shared query helpers used by both the Prolog and SPARQL query pipelines.
|
|
3
3
|
*/
|
|
4
|
-
import type { Scope } from "./types";
|
|
4
|
+
import type { Scope, TraverseScope } from "./types";
|
|
5
5
|
/**
|
|
6
6
|
* Resolves the predicate for a parent query.
|
|
7
7
|
*
|
|
@@ -11,4 +11,13 @@ import type { Scope } from "./types";
|
|
|
11
11
|
* - With `field`: direct key lookup
|
|
12
12
|
* - Without `field`: scan for a relation whose `target()` matches `childCtor`
|
|
13
13
|
*/
|
|
14
|
+
/**
|
|
15
|
+
* Narrow a scope to the one-parent forms, for the paths that write a link.
|
|
16
|
+
*
|
|
17
|
+
* A traversal describes a read outward from several anchors. Creating a record
|
|
18
|
+
* "under" one would have to pick which, and nothing in the scope says — so this
|
|
19
|
+
* refuses rather than guessing at the first of the list. The executor's write
|
|
20
|
+
* scopes refuse it for the same reason.
|
|
21
|
+
*/
|
|
22
|
+
export declare function requireSingleParent(parent: Scope): Exclude<Scope, TraverseScope>;
|
|
14
23
|
export declare function resolveParentPredicate(parent: Scope, childCtor: Function): string;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Shared query helpers used by both the Prolog and SPARQL query pipelines.
|
|
3
3
|
*/
|
|
4
|
+
import { isTraverseScope } from "./types";
|
|
4
5
|
import { getRelationsMetadata } from "./decorators";
|
|
5
6
|
/**
|
|
6
7
|
* Resolves the predicate for a parent query.
|
|
@@ -11,6 +12,21 @@ import { getRelationsMetadata } from "./decorators";
|
|
|
11
12
|
* - With `field`: direct key lookup
|
|
12
13
|
* - Without `field`: scan for a relation whose `target()` matches `childCtor`
|
|
13
14
|
*/
|
|
15
|
+
/**
|
|
16
|
+
* Narrow a scope to the one-parent forms, for the paths that write a link.
|
|
17
|
+
*
|
|
18
|
+
* A traversal describes a read outward from several anchors. Creating a record
|
|
19
|
+
* "under" one would have to pick which, and nothing in the scope says — so this
|
|
20
|
+
* refuses rather than guessing at the first of the list. The executor's write
|
|
21
|
+
* scopes refuse it for the same reason.
|
|
22
|
+
*/
|
|
23
|
+
export function requireSingleParent(parent) {
|
|
24
|
+
if (isTraverseScope(parent)) {
|
|
25
|
+
throw new Error('parent(): a traverse scope describes a read and names no single parent to write under. ' +
|
|
26
|
+
'Use { id, predicate } or { model, id } when creating a record under a parent.');
|
|
27
|
+
}
|
|
28
|
+
return parent;
|
|
29
|
+
}
|
|
14
30
|
export function resolveParentPredicate(parent, childCtor) {
|
|
15
31
|
// Raw form — explicit predicate
|
|
16
32
|
if ('predicate' in parent)
|
|
@@ -27,6 +27,17 @@ import type { Where, Query, ModelMetadata } from "./types";
|
|
|
27
27
|
* potentially discarding matches beyond the LIMIT.
|
|
28
28
|
*/
|
|
29
29
|
export declare function hasJsOnlyWhereFilters(metadata: ModelMetadata, allRelationsMetadata: Record<string, RelationMetadataEntry>, where?: Where): boolean;
|
|
30
|
+
/**
|
|
31
|
+
* Prepare a `where` for this client-side SPARQL builder: unwrap `{ eq: X }`
|
|
32
|
+
* to the bare `X`, and refuse a per-link `author`.
|
|
33
|
+
*
|
|
34
|
+
* A per-link `author` (nested, `{ agent: { eq: X, author: A } }`, or a
|
|
35
|
+
* top-level `author` beside link-backed property or relation conditions) is
|
|
36
|
+
* answered by the executor, which joins each matched link's reifier (#1114). This builder
|
|
37
|
+
* has no such join, and treating the author as instance-level here would
|
|
38
|
+
* answer a different, wider question. `findAll()`/`count()` answer it.
|
|
39
|
+
*/
|
|
40
|
+
export declare function normalizeWhereForSparql(metadata: ModelMetadata, where?: Where): Where | undefined;
|
|
30
41
|
/**
|
|
31
42
|
* Check whether a string value is a well-formed absolute IRI that can be
|
|
32
43
|
* stored verbatim as a link target (raw `NamedNode`) instead of being
|
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
*/
|
|
13
13
|
import { Literal } from "../Literal";
|
|
14
14
|
import { resolveParentPredicate } from "./query-common";
|
|
15
|
+
import { isTraverseScope } from "./types";
|
|
15
16
|
/**
|
|
16
17
|
* Check whether a `where` clause contains filters that cannot be pushed down
|
|
17
18
|
* to SPARQL and must be evaluated in JS after hydration.
|
|
@@ -69,6 +70,68 @@ export function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
|
|
|
69
70
|
}
|
|
70
71
|
return false;
|
|
71
72
|
}
|
|
73
|
+
/**
|
|
74
|
+
* Prepare a `where` for this client-side SPARQL builder: unwrap `{ eq: X }`
|
|
75
|
+
* to the bare `X`, and refuse a per-link `author`.
|
|
76
|
+
*
|
|
77
|
+
* A per-link `author` (nested, `{ agent: { eq: X, author: A } }`, or a
|
|
78
|
+
* top-level `author` beside link-backed property or relation conditions) is
|
|
79
|
+
* answered by the executor, which joins each matched link's reifier (#1114). This builder
|
|
80
|
+
* has no such join, and treating the author as instance-level here would
|
|
81
|
+
* answer a different, wider question. `findAll()`/`count()` answer it.
|
|
82
|
+
*/
|
|
83
|
+
export function normalizeWhereForSparql(metadata, where) {
|
|
84
|
+
if (!where)
|
|
85
|
+
return where;
|
|
86
|
+
assertNoPerLinkAuthor(metadata, where);
|
|
87
|
+
const out = {};
|
|
88
|
+
for (const [key, condition] of Object.entries(where)) {
|
|
89
|
+
out[key] = unwrapEq(key, condition);
|
|
90
|
+
}
|
|
91
|
+
return out;
|
|
92
|
+
}
|
|
93
|
+
function isOpsObject(condition) {
|
|
94
|
+
return typeof condition === "object" && condition !== null && !Array.isArray(condition);
|
|
95
|
+
}
|
|
96
|
+
function unwrapEq(key, condition) {
|
|
97
|
+
if (key === "OR" || key === "AND" || key === "NOT" || !isOpsObject(condition) || condition.eq === undefined) {
|
|
98
|
+
return condition;
|
|
99
|
+
}
|
|
100
|
+
if (Object.keys(condition).some((k) => k !== "eq")) {
|
|
101
|
+
throw new Error(`where.${key}: \`eq\` cannot be combined with another operator`);
|
|
102
|
+
}
|
|
103
|
+
return condition.eq;
|
|
104
|
+
}
|
|
105
|
+
function assertNoPerLinkAuthor(metadata, where) {
|
|
106
|
+
const refuse = (what) => {
|
|
107
|
+
throw new Error(`buildSPARQLQuery: ${what} is a per-link \`author\`, which the executor answers by ` +
|
|
108
|
+
"checking who wrote each matched link. This client-side SPARQL builder cannot express " +
|
|
109
|
+
"it. Use the model query path (findAll/count).");
|
|
110
|
+
};
|
|
111
|
+
// A property or a relation with a predicate, as the executor's `is_link_leaf`.
|
|
112
|
+
const linkBacked = (key) => {
|
|
113
|
+
const field = metadata.properties[key] ?? metadata.relations?.[key];
|
|
114
|
+
return !!field && !!field.predicate && !field.getter;
|
|
115
|
+
};
|
|
116
|
+
for (const [key, condition] of Object.entries(where)) {
|
|
117
|
+
if (key === "OR" || key === "AND") {
|
|
118
|
+
for (const branch of condition ?? [])
|
|
119
|
+
assertNoPerLinkAuthor(metadata, branch);
|
|
120
|
+
}
|
|
121
|
+
else if (key === "NOT") {
|
|
122
|
+
if (condition)
|
|
123
|
+
assertNoPerLinkAuthor(metadata, condition);
|
|
124
|
+
}
|
|
125
|
+
else if (key === "author") {
|
|
126
|
+
const sibling = Object.keys(where).find((k) => k !== "author" && linkBacked(k));
|
|
127
|
+
if (sibling)
|
|
128
|
+
refuse(`\`author\` beside \`${sibling}\``);
|
|
129
|
+
}
|
|
130
|
+
else if (isOpsObject(condition) && condition.author !== undefined) {
|
|
131
|
+
refuse(`\`${key}.author\``);
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
}
|
|
72
135
|
/**
|
|
73
136
|
* Check whether a string value is a well-formed absolute IRI that can be
|
|
74
137
|
* stored verbatim as a link target (raw `NamedNode`) instead of being
|
|
@@ -242,11 +305,40 @@ function mapPropertyToSPARQLVar(propertyName, metadata) {
|
|
|
242
305
|
export function buildSPARQLQuery(metadata, allRelationsMetadata, query, modelClass) {
|
|
243
306
|
const joinPatterns = [];
|
|
244
307
|
const filterExpressions = [];
|
|
308
|
+
query = { ...query, where: normalizeWhereForSparql(metadata, query.where) };
|
|
245
309
|
// Parent filter — direct triple pattern
|
|
246
310
|
if (query.parent) {
|
|
247
311
|
const parentPredicate = resolveParentPredicate(query.parent, modelClass);
|
|
248
|
-
|
|
312
|
+
if (isTraverseScope(query.parent)) {
|
|
313
|
+
const { ids, transitive, direction, limitPerAnchor, levels } = query.parent;
|
|
314
|
+
// `limitPerAnchor` and `levels` are applied by the executor between
|
|
315
|
+
// selecting ids and hydrating them, which is a shape this path does not
|
|
316
|
+
// have — it builds one query and reads the rows. Refused rather than
|
|
317
|
+
// ignored: quietly returning every reply where five per parent were
|
|
318
|
+
// asked for — or one unbounded level where a walk was asked for — is a
|
|
319
|
+
// wrong answer that looks like a right one.
|
|
320
|
+
if (limitPerAnchor !== undefined) {
|
|
321
|
+
throw new Error('buildSPARQLQuery: limitPerAnchor is applied by the executor between query phases and ' +
|
|
322
|
+
'has no equivalent here. Use the model query path for per-anchor limits.');
|
|
323
|
+
}
|
|
324
|
+
if (levels !== undefined) {
|
|
325
|
+
throw new Error('buildSPARQLQuery: levels is walked by the executor between query phases and ' +
|
|
326
|
+
'has no equivalent here. Use the model query path for level walks.');
|
|
327
|
+
}
|
|
328
|
+
const anchors = (Array.isArray(ids) ? ids : [ids]).map(iri).join(' ');
|
|
329
|
+
const path = transitive ? '+' : '';
|
|
330
|
+
joinPatterns.push(`
|
|
331
|
+
VALUES ?_anchor { ${anchors} }`);
|
|
332
|
+
joinPatterns.push(direction === 'in'
|
|
333
|
+
? `
|
|
334
|
+
?source ${iri(parentPredicate)}${path} ?_anchor .`
|
|
335
|
+
: `
|
|
336
|
+
?_anchor ${iri(parentPredicate)}${path} ?source .`);
|
|
337
|
+
}
|
|
338
|
+
else {
|
|
339
|
+
joinPatterns.push(`
|
|
249
340
|
${iri(query.parent.id)} ${iri(parentPredicate)} ?source .`);
|
|
341
|
+
}
|
|
250
342
|
}
|
|
251
343
|
// Required property JOIN patterns — direct triple patterns
|
|
252
344
|
let hasConformance = false;
|
|
@@ -55,6 +55,22 @@ export function formatQueryValue(value) {
|
|
|
55
55
|
* @returns A single SPARQL condition string
|
|
56
56
|
*/
|
|
57
57
|
export function buildWhereCondition(predicate, condition, opts) {
|
|
58
|
+
// `{ eq: X }` is the bare `X`. A nested `author` is a per-link condition
|
|
59
|
+
// the executor answers in model queries; a getter's SPARQL has no reifier
|
|
60
|
+
// join to answer it with, so it is refused rather than dropped (#1114).
|
|
61
|
+
if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
|
|
62
|
+
const ops = condition;
|
|
63
|
+
if (ops.author !== undefined) {
|
|
64
|
+
throw new Error(`buildWhereCondition: a nested \`author\` on <${predicate}> is a per-link condition ` +
|
|
65
|
+
'that only the model query path can answer');
|
|
66
|
+
}
|
|
67
|
+
if (ops.eq !== undefined) {
|
|
68
|
+
if (Object.keys(ops).some((k) => k !== 'eq')) {
|
|
69
|
+
throw new Error(`buildWhereCondition: \`eq\` on <${predicate}> cannot be combined with another operator`);
|
|
70
|
+
}
|
|
71
|
+
condition = ops.eq;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
58
74
|
const escapedPredicate = escapeQueryString(predicate);
|
|
59
75
|
// For deterministic-literal properties, values are stored as typed
|
|
60
76
|
// literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
|
|
@@ -100,6 +100,18 @@ interpretationHint) {
|
|
|
100
100
|
const propMeta = properties[propName];
|
|
101
101
|
if (!propMeta.through)
|
|
102
102
|
continue; // Skip properties without predicates
|
|
103
|
+
// `@BelongsToOne`/`@BelongsToMany` register in both maps: the relation
|
|
104
|
+
// registry describes the edge, and `applyPropertyMetadata` marks the
|
|
105
|
+
// accessor read-only so the non-owning side gets no setter. Both loops
|
|
106
|
+
// then emitted a shape for it, so an inverse relation appeared twice in
|
|
107
|
+
// the generated SHACL — once thinly, from here, and once with its target
|
|
108
|
+
// class, polymorphism and ordering, from the relation loop below.
|
|
109
|
+
//
|
|
110
|
+
// The relation loop is the complete description, so this one stands
|
|
111
|
+
// aside. Skipping by presence in the relation map rather than by kind
|
|
112
|
+
// keeps it right for any future decorator that registers in both.
|
|
113
|
+
if (allRelationsMeta[propName])
|
|
114
|
+
continue;
|
|
103
115
|
const propShape = {
|
|
104
116
|
name: propName,
|
|
105
117
|
path: propMeta.through,
|