@coasys/ad4m 0.13.0-test-1 → 0.13.0-test-2
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 +1392 -777
- package/lib/index.js +1376 -775
- package/lib/src/Literal.js +6 -5
- package/lib/src/agent/AgentClient.d.ts +5 -1
- package/lib/src/agent/AgentClient.js +48 -2
- package/lib/src/expression/ExpressionRef.js +2 -2
- package/lib/src/language/Language.d.ts +41 -3
- package/lib/src/model/Ad4mModel.d.ts +28 -28
- package/lib/src/model/Ad4mModel.js +129 -101
- package/lib/src/model/Ad4mModel.test.js +1543 -535
- package/lib/src/model/ModelQueryBuilder.d.ts +48 -34
- package/lib/src/model/ModelQueryBuilder.js +163 -78
- package/lib/src/model/Subject.js +6 -6
- package/lib/src/model/decorators.d.ts +14 -8
- package/lib/src/model/decorators.js +41 -14
- package/lib/src/model/hydration-batch.d.ts +34 -0
- package/lib/src/model/hydration-batch.js +147 -0
- package/lib/src/model/hydration.d.ts +3 -3
- package/lib/src/model/hydration.js +106 -36
- package/lib/src/model/index.d.ts +4 -1
- package/lib/src/model/index.js +4 -1
- package/lib/src/model/json-schema.js +2 -2
- package/lib/src/model/query-cache.d.ts +30 -0
- package/lib/src/model/query-cache.js +66 -0
- package/lib/src/model/query-cache.test.d.ts +1 -0
- package/lib/src/model/query-cache.test.js +43 -0
- package/lib/src/model/query-common.d.ts +1 -1
- package/lib/src/model/query-common.js +1 -1
- package/lib/src/model/query-sparql-batch.d.ts +17 -0
- package/lib/src/model/query-sparql-batch.js +260 -0
- package/lib/src/model/query-sparql.d.ts +47 -0
- package/lib/src/model/query-sparql.js +336 -0
- package/lib/src/model/query-utils.d.ts +45 -0
- package/lib/src/model/query-utils.js +140 -0
- package/lib/src/model/relation-filtering.test.js +15 -15
- package/lib/src/model/sdna.js +1 -1
- package/lib/src/model/shacl-gen.js +42 -18
- package/lib/src/model/subscription-pool.d.ts +39 -0
- package/lib/src/model/subscription-pool.js +119 -0
- package/lib/src/model/types.d.ts +3 -3
- package/lib/src/model/types.js +1 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +1 -17
- package/lib/src/perspectives/PerspectiveClient.js +5 -57
- package/lib/src/perspectives/PerspectiveProxy.d.ts +51 -30
- package/lib/src/perspectives/PerspectiveProxy.js +224 -177
- package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
- package/lib/src/perspectives/PerspectiveResolver.js +0 -11
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
- package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
- package/lib/src/runtime/RuntimeResolver.d.ts +11 -0
- package/lib/src/runtime/RuntimeResolver.js +56 -0
- package/lib/src/schema.gql +11 -1
- package/lib/src/shacl/SHACLFlow.d.ts +1 -1
- package/lib/src/shacl/SHACLFlow.js +9 -9
- package/lib/src/shacl/SHACLShape.d.ts +1 -1
- package/lib/src/shacl/SHACLShape.js +38 -38
- package/lib/src/typeDefs.js +11 -1
- package/lib/src/utils.d.ts +6 -6
- package/lib/src/utils.js +6 -6
- package/package.json +1 -1
- package/src/Literal.test.ts +10 -5
- package/src/Literal.ts +6 -5
- package/src/agent/AgentClient.ts +53 -1
- package/src/expression/ExpressionRef.ts +2 -2
- package/src/language/Language.ts +48 -3
- package/src/model/Ad4mModel.test.ts +1515 -565
- package/src/model/Ad4mModel.ts +142 -102
- package/src/model/ModelQueryBuilder.ts +185 -86
- package/src/model/Subject.ts +6 -6
- package/src/model/decorators.ts +51 -22
- package/src/model/hydration-batch.ts +205 -0
- package/src/model/hydration.ts +102 -39
- package/src/model/index.ts +4 -1
- package/src/model/json-schema.ts +2 -2
- package/src/model/query-cache.test.ts +54 -0
- package/src/model/query-cache.ts +79 -0
- package/src/model/query-common.ts +1 -1
- package/src/model/query-sparql-batch.ts +301 -0
- package/src/model/query-sparql.ts +363 -0
- package/src/model/{surreal-utils.ts → query-utils.ts} +40 -27
- package/src/model/relation-filtering.test.ts +15 -15
- package/src/model/sdna.ts +1 -1
- package/src/model/shacl-gen.ts +42 -17
- package/src/model/subscription-pool.ts +163 -0
- package/src/model/types.ts +3 -3
- package/src/perspectives/PerspectiveClient.ts +5 -61
- package/src/perspectives/PerspectiveProxy.ts +226 -181
- package/src/perspectives/PerspectiveResolver.ts +0 -8
- package/src/perspectives/WakerSubscriptionManager.ts +8 -9
- package/src/runtime/RuntimeResolver.ts +43 -0
- package/src/shacl/SHACLFlow.ts +9 -9
- package/src/shacl/SHACLShape.ts +39 -39
- package/src/utils.ts +6 -6
- package/src/model/query-surreal.ts +0 -280
package/src/model/decorators.ts
CHANGED
|
@@ -2,7 +2,7 @@ import { capitalize } from "./util";
|
|
|
2
2
|
import type { Where } from "./types";
|
|
3
3
|
import { buildSDNA } from "./sdna";
|
|
4
4
|
import { buildSHACL } from "./shacl-gen";
|
|
5
|
-
import {
|
|
5
|
+
import { escapeQueryString } from "../utils";
|
|
6
6
|
import type { ConformanceCondition } from "../shacl/SHACLShape";
|
|
7
7
|
|
|
8
8
|
// ============================================================================
|
|
@@ -32,7 +32,7 @@ export interface RelationMetadataEntry {
|
|
|
32
32
|
maxCount?: number;
|
|
33
33
|
local?: boolean;
|
|
34
34
|
/**
|
|
35
|
-
* Custom
|
|
35
|
+
* Custom getter to resolve the relation values.
|
|
36
36
|
* The expression can reference 'Base' which will be replaced with the instance's base expression.
|
|
37
37
|
*/
|
|
38
38
|
getter?: string;
|
|
@@ -56,12 +56,24 @@ const propertyRegistry = new WeakMap<Function, Record<string, PropertyMetadataEn
|
|
|
56
56
|
/** Registry of relation metadata keyed by constructor → { propName → metadata } */
|
|
57
57
|
const relationRegistry = new WeakMap<Function, Record<string, RelationMetadataEntry>>();
|
|
58
58
|
|
|
59
|
+
/** Memoisation cache for getPropertiesMetadata — avoids repeated prototype-chain walks */
|
|
60
|
+
const propertiesMetadataCache = new WeakMap<Function, Record<string, PropertyMetadataEntry>>();
|
|
61
|
+
|
|
62
|
+
/** Memoisation cache for getRelationsMetadata — avoids repeated prototype-chain walks */
|
|
63
|
+
const relationsMetadataCache = new WeakMap<Function, Record<string, RelationMetadataEntry>>();
|
|
64
|
+
|
|
65
|
+
/** Memoisation cache for generateSHACL — avoids recomputing SHACL shapes */
|
|
66
|
+
const shaclCache = new WeakMap<Function, any>();
|
|
59
67
|
|
|
60
68
|
/**
|
|
61
69
|
* Retrieve property metadata for a given class constructor.
|
|
62
70
|
* Walks the prototype chain so subclass decorators compose with parent decorators.
|
|
71
|
+
* Results are memoised per class constructor.
|
|
63
72
|
*/
|
|
64
73
|
export function getPropertiesMetadata(ctor: Function): Record<string, PropertyMetadataEntry> {
|
|
74
|
+
const cached = propertiesMetadataCache.get(ctor);
|
|
75
|
+
if (cached) return cached;
|
|
76
|
+
|
|
65
77
|
const result: Record<string, PropertyMetadataEntry> = {};
|
|
66
78
|
const chain: Function[] = [];
|
|
67
79
|
let current = ctor;
|
|
@@ -73,14 +85,19 @@ export function getPropertiesMetadata(ctor: Function): Record<string, PropertyMe
|
|
|
73
85
|
const meta = propertyRegistry.get(c);
|
|
74
86
|
if (meta) Object.assign(result, meta);
|
|
75
87
|
}
|
|
88
|
+
propertiesMetadataCache.set(ctor, result);
|
|
76
89
|
return result;
|
|
77
90
|
}
|
|
78
91
|
|
|
79
92
|
/**
|
|
80
93
|
* Retrieve relation metadata for a given class constructor.
|
|
81
94
|
* Walks the prototype chain so subclass decorators compose with parent decorators.
|
|
95
|
+
* Results are memoised per class constructor.
|
|
82
96
|
*/
|
|
83
97
|
export function getRelationsMetadata(ctor: Function): Record<string, RelationMetadataEntry> {
|
|
98
|
+
const cached = relationsMetadataCache.get(ctor);
|
|
99
|
+
if (cached) return cached;
|
|
100
|
+
|
|
84
101
|
const result: Record<string, RelationMetadataEntry> = {};
|
|
85
102
|
const chain: Function[] = [];
|
|
86
103
|
let current = ctor;
|
|
@@ -92,6 +109,18 @@ export function getRelationsMetadata(ctor: Function): Record<string, RelationMet
|
|
|
92
109
|
const meta = relationRegistry.get(c);
|
|
93
110
|
if (meta) Object.assign(result, meta);
|
|
94
111
|
}
|
|
112
|
+
relationsMetadataCache.set(ctor, result);
|
|
113
|
+
return result;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Get or compute memoised SHACL for a class. Used by @Model decorator.
|
|
118
|
+
*/
|
|
119
|
+
export function getMemoizedSHACL(target: Function, compute: () => any): any {
|
|
120
|
+
const cached = shaclCache.get(target);
|
|
121
|
+
if (cached) return cached;
|
|
122
|
+
const result = compute();
|
|
123
|
+
shaclCache.set(target, result);
|
|
95
124
|
return result;
|
|
96
125
|
}
|
|
97
126
|
|
|
@@ -137,7 +166,7 @@ export interface Ad4mModelLike {
|
|
|
137
166
|
*
|
|
138
167
|
* Inspects the target class's property metadata to derive:
|
|
139
168
|
* - `conformanceConditions`: Structured, DB-agnostic conditions (flag & required checks)
|
|
140
|
-
* - `getter`: Pre-computed
|
|
169
|
+
* - `getter`: Pre-computed graph traversal expression that traverses outgoing links and filters
|
|
141
170
|
* target nodes to only those conforming to the target shape.
|
|
142
171
|
*
|
|
143
172
|
* @param relationPredicate - The relation's predicate URI (e.g. "flux://entry_type")
|
|
@@ -151,7 +180,8 @@ export function buildConformanceFilter(
|
|
|
151
180
|
try {
|
|
152
181
|
const targetProps = getPropertiesMetadata(targetClass);
|
|
153
182
|
const conditions: ConformanceCondition[] = [];
|
|
154
|
-
const
|
|
183
|
+
const sparqlConditions: string[] = [];
|
|
184
|
+
let varIdx = 0;
|
|
155
185
|
|
|
156
186
|
// 1. Flags — check predicate + value
|
|
157
187
|
for (const [_propName, propMeta] of Object.entries(targetProps)) {
|
|
@@ -161,8 +191,8 @@ export function buildConformanceFilter(
|
|
|
161
191
|
predicate: propMeta.through,
|
|
162
192
|
value: propMeta.initial,
|
|
163
193
|
});
|
|
164
|
-
|
|
165
|
-
|
|
194
|
+
sparqlConditions.push(
|
|
195
|
+
`?target <${escapeQueryString(propMeta.through)}> <${escapeQueryString(propMeta.initial)}> .`
|
|
166
196
|
);
|
|
167
197
|
}
|
|
168
198
|
}
|
|
@@ -175,8 +205,8 @@ export function buildConformanceFilter(
|
|
|
175
205
|
type: 'required',
|
|
176
206
|
predicate: propMeta.through,
|
|
177
207
|
});
|
|
178
|
-
|
|
179
|
-
|
|
208
|
+
sparqlConditions.push(
|
|
209
|
+
`?target <${escapeQueryString(propMeta.through)}> ?_v${varIdx++} .`
|
|
180
210
|
);
|
|
181
211
|
}
|
|
182
212
|
}
|
|
@@ -185,8 +215,7 @@ export function buildConformanceFilter(
|
|
|
185
215
|
return undefined;
|
|
186
216
|
}
|
|
187
217
|
|
|
188
|
-
const
|
|
189
|
-
const getter = `(->link[WHERE predicate = '${escapedPredicate}'].out[WHERE ${surrealConditions.join(' AND ')}].uri)`;
|
|
218
|
+
const getter = `SELECT ?target WHERE { <Base> <${escapeQueryString(relationPredicate)}> ?target . ${sparqlConditions.join(' ')} }`;
|
|
190
219
|
|
|
191
220
|
return { getter, conformanceConditions: conditions };
|
|
192
221
|
} catch (e) {
|
|
@@ -233,9 +262,9 @@ export interface PropertyOptions {
|
|
|
233
262
|
prologSetter?: string;
|
|
234
263
|
|
|
235
264
|
/**
|
|
236
|
-
* Custom
|
|
265
|
+
* Custom getter to resolve the property value. Use this for custom graph traversals.
|
|
237
266
|
* The expression can reference 'Base' which will be replaced with the instance's base expression.
|
|
238
|
-
* Example: "
|
|
267
|
+
* Example: "SELECT ?target WHERE { <Base> <flux://has_reply> ?target . } LIMIT 1"
|
|
239
268
|
*/
|
|
240
269
|
getter?: string;
|
|
241
270
|
|
|
@@ -268,8 +297,8 @@ function applyPropertyMetadata(opts: PropertyOptions) {
|
|
|
268
297
|
throw new Error("SubjectProperty requires an 'initial' option if 'required' is true");
|
|
269
298
|
}
|
|
270
299
|
|
|
271
|
-
if (!opts.through && !opts.prologGetter) {
|
|
272
|
-
throw new Error("SubjectProperty requires either 'through' or 'prologGetter' option")
|
|
300
|
+
if (!opts.through && !opts.prologGetter && !opts.getter) {
|
|
301
|
+
throw new Error("SubjectProperty requires either 'through' or 'prologGetter' or 'getter' option")
|
|
273
302
|
}
|
|
274
303
|
|
|
275
304
|
// Write to WeakMap registry (keyed by constructor)
|
|
@@ -492,13 +521,13 @@ export function Model(opts: ModelConfig) {
|
|
|
492
521
|
}
|
|
493
522
|
|
|
494
523
|
target.generateSHACL = function() {
|
|
495
|
-
return buildSHACL(
|
|
524
|
+
return getMemoizedSHACL(target, () => buildSHACL(
|
|
496
525
|
opts.name,
|
|
497
526
|
target,
|
|
498
527
|
getPropertiesMetadata(target),
|
|
499
528
|
getRelationsMetadata(target),
|
|
500
529
|
buildConformanceFilter,
|
|
501
|
-
);
|
|
530
|
+
));
|
|
502
531
|
}
|
|
503
532
|
|
|
504
533
|
Object.defineProperty(target, 'type', {configurable: true});
|
|
@@ -523,7 +552,7 @@ export function Model(opts: ModelConfig) {
|
|
|
523
552
|
* Properties are optional by default. When a model instance is created without
|
|
524
553
|
* providing a value for an optional property, no link is added to the graph.
|
|
525
554
|
* Set `required: true` explicitly when a property must always be present (this
|
|
526
|
-
* also adds a `"literal
|
|
555
|
+
* also adds a `"literal:string:uninitialized"` sentinel as the initial value
|
|
527
556
|
* so that the SDNA constructor creates a placeholder link).
|
|
528
557
|
*
|
|
529
558
|
* @example
|
|
@@ -562,7 +591,7 @@ export function Model(opts: ModelConfig) {
|
|
|
562
591
|
* @param {PropertyOptions} opts - Property configuration
|
|
563
592
|
* @param {string} opts.through - The predicate URI for the property
|
|
564
593
|
* @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
|
|
565
|
-
* @param {string} [opts.initial] - Initial value (defaults to "literal
|
|
594
|
+
* @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
|
|
566
595
|
* @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
|
|
567
596
|
* @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
|
|
568
597
|
* @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
|
|
@@ -575,7 +604,7 @@ export function Property(opts: PropertyOptions) {
|
|
|
575
604
|
required,
|
|
576
605
|
readOnly: opts.readOnly ?? false,
|
|
577
606
|
resolveLanguage: opts.resolveLanguage ?? "literal",
|
|
578
|
-
initial: opts.initial ?? (required ? "literal
|
|
607
|
+
initial: opts.initial ?? (required ? "literal:string:uninitialized" : undefined),
|
|
579
608
|
});
|
|
580
609
|
}
|
|
581
610
|
|
|
@@ -659,9 +688,9 @@ export interface RelationOptions {
|
|
|
659
688
|
* Cannot be combined with `getter`. */
|
|
660
689
|
target?: () => Ad4mModelLike;
|
|
661
690
|
/**
|
|
662
|
-
* Custom
|
|
691
|
+
* Custom getter to resolve the relation values. Use this for custom graph traversals.
|
|
663
692
|
* The expression can reference 'Base' which will be replaced with the instance's base expression.
|
|
664
|
-
* Example: "
|
|
693
|
+
* Example: "SELECT ?target WHERE { ?target <flux://has_reply> <Base> . }"
|
|
665
694
|
*
|
|
666
695
|
* Mutually exclusive with `through` and `target`. When `getter` is provided the
|
|
667
696
|
* relation is read-only (no adder/remover actions are generated).
|
|
@@ -750,7 +779,7 @@ function resolveRelationArgs(
|
|
|
750
779
|
if (opts.where) {
|
|
751
780
|
throw new Error(
|
|
752
781
|
'Relation decorator: `where` and `getter` are mutually exclusive. ' +
|
|
753
|
-
'Use `where` for DSL-based filtering, or `getter` for raw
|
|
782
|
+
'Use `where` for DSL-based filtering, or `getter` for raw getter expression.'
|
|
754
783
|
);
|
|
755
784
|
}
|
|
756
785
|
return opts;
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Batch hydration for SPARQL batch query results.
|
|
3
|
+
*
|
|
4
|
+
* Takes the flat rows returned by `buildBatchSPARQLQuery()` (each tagged
|
|
5
|
+
* with ?depth, ?parentBase, ?relationName) and reconstructs a tree of
|
|
6
|
+
* model instances.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { hydrateFromLinks, evaluateCustomGettersForInstance } from "./hydration";
|
|
12
|
+
import { getRelationsMetadata } from "./decorators";
|
|
13
|
+
import type { IncludeMap, ModelMetadata } from "./types";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* A row returned by the batch SPARQL query.
|
|
17
|
+
*/
|
|
18
|
+
interface BatchRow {
|
|
19
|
+
depth: string;
|
|
20
|
+
parentBase: string;
|
|
21
|
+
relationName: string;
|
|
22
|
+
source: string;
|
|
23
|
+
predicate: string;
|
|
24
|
+
target: string;
|
|
25
|
+
author: string;
|
|
26
|
+
timestamp: string;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Grouped link data for one instance (same shape as SPARQL grouped result).
|
|
31
|
+
*/
|
|
32
|
+
interface GroupedInstance {
|
|
33
|
+
source_uri: string;
|
|
34
|
+
parentBase: string;
|
|
35
|
+
relationName: string;
|
|
36
|
+
links: Array<{ predicate: string; target: string; author: string; timestamp: string }>;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Group batch rows by (depth, source) → array of links, preserving parentBase/relationName.
|
|
41
|
+
*/
|
|
42
|
+
function groupBatchRows(rows: BatchRow[]): Map<number, GroupedInstance[]> {
|
|
43
|
+
const byDepth = new Map<number, Map<string, GroupedInstance>>();
|
|
44
|
+
|
|
45
|
+
for (const row of rows) {
|
|
46
|
+
const depth = parseInt(row.depth, 10);
|
|
47
|
+
if (!byDepth.has(depth)) byDepth.set(depth, new Map());
|
|
48
|
+
const depthMap = byDepth.get(depth)!;
|
|
49
|
+
|
|
50
|
+
const key = row.source;
|
|
51
|
+
if (!depthMap.has(key)) {
|
|
52
|
+
depthMap.set(key, {
|
|
53
|
+
source_uri: key,
|
|
54
|
+
parentBase: row.parentBase,
|
|
55
|
+
relationName: row.relationName,
|
|
56
|
+
links: [],
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
depthMap.get(key)!.links.push({
|
|
60
|
+
predicate: row.predicate,
|
|
61
|
+
target: row.target,
|
|
62
|
+
author: row.author,
|
|
63
|
+
timestamp: row.timestamp,
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
const result = new Map<number, GroupedInstance[]>();
|
|
68
|
+
for (const [depth, map] of byDepth) {
|
|
69
|
+
result.set(depth, Array.from(map.values()));
|
|
70
|
+
}
|
|
71
|
+
return result;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Hydrate batch SPARQL results into a tree of model instances.
|
|
76
|
+
*
|
|
77
|
+
* @param rows - Flat rows from the batch SPARQL query
|
|
78
|
+
* @param rootClass - The root model class (extends Ad4mModel)
|
|
79
|
+
* @param includeMap - The include specification from the query
|
|
80
|
+
* @param perspective - The PerspectiveProxy for creating instances
|
|
81
|
+
* @returns Array of hydrated root instances with relations populated
|
|
82
|
+
*/
|
|
83
|
+
export async function hydrateBatchResult<T>(
|
|
84
|
+
rows: BatchRow[],
|
|
85
|
+
rootClass: any,
|
|
86
|
+
includeMap: IncludeMap,
|
|
87
|
+
perspective: any,
|
|
88
|
+
): Promise<T[]> {
|
|
89
|
+
if (!rows || rows.length === 0) return [];
|
|
90
|
+
|
|
91
|
+
const grouped = groupBatchRows(rows);
|
|
92
|
+
|
|
93
|
+
// Hydrate root instances (depth 0)
|
|
94
|
+
const rootInstances = grouped.get(0) || [];
|
|
95
|
+
const metadata: ModelMetadata = rootClass.getModelMetadata();
|
|
96
|
+
const instances: T[] = [];
|
|
97
|
+
const instanceMap = new Map<string, T>();
|
|
98
|
+
|
|
99
|
+
for (const group of rootInstances) {
|
|
100
|
+
const instance = new rootClass(perspective, group.source_uri) as any;
|
|
101
|
+
await hydrateFromLinks(instance, group.links, metadata, perspective);
|
|
102
|
+
await evaluateCustomGettersForInstance(instance, perspective, metadata);
|
|
103
|
+
instances.push(instance);
|
|
104
|
+
instanceMap.set(group.source_uri, instance);
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
// Hydrate each depth level and wire to parents
|
|
108
|
+
const relMeta = getRelationsMetadata(rootClass);
|
|
109
|
+
const maxDepth = Math.max(...Array.from(grouped.keys()), 0);
|
|
110
|
+
|
|
111
|
+
// Build a map of depth → (class, relMetadata, parentInstanceMap)
|
|
112
|
+
// For depth 1, parents are root instances; for deeper depths, we need
|
|
113
|
+
// the instances from the previous level.
|
|
114
|
+
const depthInstanceMaps = new Map<number, Map<string, any>>();
|
|
115
|
+
depthInstanceMaps.set(0, instanceMap);
|
|
116
|
+
|
|
117
|
+
// Build depth→class mapping from include tree
|
|
118
|
+
const depthClassMap = new Map<number, { targetClass: any; includeMap?: IncludeMap }>();
|
|
119
|
+
buildDepthClassMap(rootClass, includeMap, 0, { value: 1 }, depthClassMap);
|
|
120
|
+
|
|
121
|
+
for (let depth = 1; depth <= maxDepth; depth++) {
|
|
122
|
+
const depthGroups = grouped.get(depth) || [];
|
|
123
|
+
if (depthGroups.length === 0) continue;
|
|
124
|
+
|
|
125
|
+
const depthInfo = depthClassMap.get(depth);
|
|
126
|
+
if (!depthInfo) continue;
|
|
127
|
+
|
|
128
|
+
const TargetClass = depthInfo.targetClass;
|
|
129
|
+
const targetMetadata: ModelMetadata = TargetClass.getModelMetadata
|
|
130
|
+
? TargetClass.getModelMetadata()
|
|
131
|
+
: { className: "Unknown", properties: {}, relations: {} };
|
|
132
|
+
|
|
133
|
+
const currentDepthInstances = new Map<string, any>();
|
|
134
|
+
|
|
135
|
+
// Group by parentBase to wire children to parents
|
|
136
|
+
for (const group of depthGroups) {
|
|
137
|
+
const instance = new TargetClass(perspective, group.source_uri) as any;
|
|
138
|
+
await hydrateFromLinks(instance, group.links, targetMetadata, perspective);
|
|
139
|
+
await evaluateCustomGettersForInstance(instance, perspective, targetMetadata);
|
|
140
|
+
currentDepthInstances.set(group.source_uri, instance);
|
|
141
|
+
|
|
142
|
+
// Wire to parent
|
|
143
|
+
// Find the parent depth's instance map
|
|
144
|
+
// The parentBase should exist in one of the prior depth maps
|
|
145
|
+
for (let pd = depth - 1; pd >= 0; pd--) {
|
|
146
|
+
const parentMap = depthInstanceMaps.get(pd);
|
|
147
|
+
if (parentMap && parentMap.has(group.parentBase)) {
|
|
148
|
+
const parent = parentMap.get(group.parentBase)!;
|
|
149
|
+
const relName = group.relationName;
|
|
150
|
+
|
|
151
|
+
// Determine relation metadata to know if it's an array or single
|
|
152
|
+
const parentRelMeta = getRelationsMetadata(pd === 0 ? rootClass : (depthClassMap.get(pd)?.targetClass || rootClass));
|
|
153
|
+
const rel = parentRelMeta[relName];
|
|
154
|
+
|
|
155
|
+
if (rel) {
|
|
156
|
+
if (rel.kind === 'hasMany' || rel.kind === 'belongsToMany') {
|
|
157
|
+
if (!Array.isArray(parent[relName])) {
|
|
158
|
+
parent[relName] = [];
|
|
159
|
+
}
|
|
160
|
+
parent[relName].push(instance);
|
|
161
|
+
} else {
|
|
162
|
+
parent[relName] = instance;
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
break;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
depthInstanceMaps.set(depth, currentDepthInstances);
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
return instances;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Build a mapping from depth number to target class info.
|
|
178
|
+
*/
|
|
179
|
+
function buildDepthClassMap(
|
|
180
|
+
parentClass: any,
|
|
181
|
+
includeMap: IncludeMap,
|
|
182
|
+
_parentDepth: number,
|
|
183
|
+
nextDepth: { value: number },
|
|
184
|
+
result: Map<number, { targetClass: any; includeMap?: IncludeMap }>,
|
|
185
|
+
): void {
|
|
186
|
+
const relMeta = getRelationsMetadata(parentClass);
|
|
187
|
+
|
|
188
|
+
for (const [relName, includeValue] of Object.entries(includeMap)) {
|
|
189
|
+
const meta = relMeta[relName];
|
|
190
|
+
if (!meta || !meta.target) continue;
|
|
191
|
+
|
|
192
|
+
const TargetClass = meta.target();
|
|
193
|
+
const depth = nextDepth.value++;
|
|
194
|
+
|
|
195
|
+
const nestedInclude = typeof includeValue === 'object' && includeValue !== null
|
|
196
|
+
? (includeValue as any).include
|
|
197
|
+
: undefined;
|
|
198
|
+
|
|
199
|
+
result.set(depth, { targetClass: TargetClass, includeMap: nestedInclude });
|
|
200
|
+
|
|
201
|
+
if (nestedInclude) {
|
|
202
|
+
buildDepthClassMap(TargetClass, nestedInclude, depth, nextDepth, result);
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
}
|
package/src/model/hydration.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* hydration.ts — Instance hydration helpers extracted from Ad4mModel.
|
|
3
3
|
*
|
|
4
4
|
* Pure / stateless functions that populate Ad4mModel instances from
|
|
5
|
-
* raw link arrays, Prolog tuples, or
|
|
5
|
+
* raw link arrays, Prolog tuples, or query results. None of these
|
|
6
6
|
* functions depend on the `Ad4mModel` class at runtime — they accept
|
|
7
7
|
* the instance, metadata, or perspective as explicit parameters.
|
|
8
8
|
*/
|
|
@@ -12,8 +12,8 @@ import { LinkQuery } from "../perspectives/LinkQuery";
|
|
|
12
12
|
import type { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
|
|
13
13
|
import { getPropertiesMetadata, getRelationsMetadata, buildConformanceFilter } from "./decorators";
|
|
14
14
|
import type { RelationMetadataEntry } from "./decorators";
|
|
15
|
-
import {
|
|
16
|
-
import {
|
|
15
|
+
import { compileWhereClause } from "./query-utils";
|
|
16
|
+
import { escapeQueryString } from "../utils";
|
|
17
17
|
import type {
|
|
18
18
|
PropertyMetadata, RelationMetadata, ModelMetadata,
|
|
19
19
|
ValueTuple, WhereCondition, IncludeMap, RelationSubQuery,
|
|
@@ -131,7 +131,7 @@ export async function hydratePropertyValue(
|
|
|
131
131
|
propMeta.resolveLanguage != null &&
|
|
132
132
|
propMeta.resolveLanguage !== 'literal' &&
|
|
133
133
|
typeof target === 'string' &&
|
|
134
|
-
!target.startsWith('literal
|
|
134
|
+
!target.startsWith('literal:')
|
|
135
135
|
) {
|
|
136
136
|
try {
|
|
137
137
|
const expression = await perspective.getExpression(target);
|
|
@@ -146,7 +146,7 @@ export async function hydratePropertyValue(
|
|
|
146
146
|
else if (
|
|
147
147
|
propMeta.resolveLanguage === 'literal' &&
|
|
148
148
|
typeof target === 'string' &&
|
|
149
|
-
target.startsWith('literal
|
|
149
|
+
target.startsWith('literal:')
|
|
150
150
|
) {
|
|
151
151
|
try {
|
|
152
152
|
const parsed = Literal.fromUrl(target).get();
|
|
@@ -413,11 +413,11 @@ export async function assignValuesToInstance(
|
|
|
413
413
|
}
|
|
414
414
|
|
|
415
415
|
// ──────────────────────────────────────────────────────────
|
|
416
|
-
//
|
|
416
|
+
// SPARQL custom getter evaluation
|
|
417
417
|
// ──────────────────────────────────────────────────────────
|
|
418
418
|
|
|
419
419
|
/**
|
|
420
|
-
* Builds a
|
|
420
|
+
* Builds a SPARQL conformance getter for a relation whose `target` model
|
|
421
421
|
* is known but no explicit `getter` string was supplied.
|
|
422
422
|
*
|
|
423
423
|
* The generated getter traverses outgoing links matching the relation's
|
|
@@ -429,7 +429,7 @@ export async function assignValuesToInstance(
|
|
|
429
429
|
*
|
|
430
430
|
* @param relationPredicate - The relation's predicate URI (e.g. "flux://entry_type")
|
|
431
431
|
* @param targetClass - The target model class (result of calling the `target()` thunk)
|
|
432
|
-
* @returns A
|
|
432
|
+
* @returns A SPARQL expression string, or `undefined` if no conformance
|
|
433
433
|
* conditions could be derived from the target model.
|
|
434
434
|
*/
|
|
435
435
|
export function buildConformanceGetter(
|
|
@@ -451,13 +451,14 @@ export function buildConformanceGetter(
|
|
|
451
451
|
* For relations that declare a `target` but no explicit `getter`, a conformance
|
|
452
452
|
* getter is auto-generated from the target model's metadata (unless `filter: false`).
|
|
453
453
|
*/
|
|
454
|
+
|
|
454
455
|
export async function evaluateCustomGettersForInstance(
|
|
455
456
|
instance: any,
|
|
456
457
|
perspective: PerspectiveProxy,
|
|
457
458
|
metadata: ModelMetadata,
|
|
458
459
|
options?: { requestedProperties?: string[]; include?: Record<string, any> }
|
|
459
460
|
): Promise<void> {
|
|
460
|
-
const safeBaseExpression =
|
|
461
|
+
const safeBaseExpression = `<${instance.id}>`;
|
|
461
462
|
|
|
462
463
|
// Build projection filter — when requestedProperties is active, only
|
|
463
464
|
// evaluate getters for fields that are requested (or included).
|
|
@@ -469,14 +470,27 @@ export async function evaluateCustomGettersForInstance(
|
|
|
469
470
|
if (projectionSet && !projectionSet.has(propName)) continue;
|
|
470
471
|
if ((propMeta as any).getter) {
|
|
471
472
|
try {
|
|
472
|
-
|
|
473
|
-
const
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
)
|
|
478
|
-
|
|
479
|
-
|
|
473
|
+
const rawGetter = (propMeta as any).getter;
|
|
474
|
+
const getterWithBase = rawGetter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/Base/g, `<${instance.id}>`);
|
|
475
|
+
|
|
476
|
+
// If the getter is already SPARQL (starts with SELECT/ASK/CONSTRUCT), execute directly
|
|
477
|
+
const trimmed = getterWithBase.trim().toUpperCase();
|
|
478
|
+
if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
|
|
479
|
+
const result = await perspective.querySparql(getterWithBase);
|
|
480
|
+
if (trimmed.startsWith('ASK')) {
|
|
481
|
+
instance[propName] = result === true || result === 'true';
|
|
482
|
+
} else if (result && result.length > 0) {
|
|
483
|
+
// Get first binding's first value
|
|
484
|
+
const firstRow = result[0];
|
|
485
|
+
const firstKey = Object.keys(firstRow)[0];
|
|
486
|
+
const val = firstRow[firstKey]?.value ?? firstRow[firstKey];
|
|
487
|
+
if (val !== undefined && val !== null && val !== 'None' && val !== '') {
|
|
488
|
+
instance[propName] = val;
|
|
489
|
+
}
|
|
490
|
+
}
|
|
491
|
+
} else {
|
|
492
|
+
// Legacy SurrealDB-style getter — no longer supported
|
|
493
|
+
console.warn(`Unsupported legacy getter syntax for property ${propName} — use native SPARQL (SELECT/ASK): ${rawGetter.slice(0, 100)}`);
|
|
480
494
|
}
|
|
481
495
|
} catch (error) {
|
|
482
496
|
console.warn(`Failed to evaluate getter for ${propName}:`, error);
|
|
@@ -492,12 +506,11 @@ export async function evaluateCustomGettersForInstance(
|
|
|
492
506
|
|
|
493
507
|
// Determine the getter to execute:
|
|
494
508
|
// 1. Explicit `getter` always wins
|
|
495
|
-
// 2. `
|
|
496
|
-
// 3. If `target` is set and `filter !== false`, auto-generate from target metadata
|
|
509
|
+
// 2. If `target` is set and `filter !== false`, auto-generate conformance getter
|
|
497
510
|
// BUT skip auto-generation for reverse relations (belongsToMany / belongsToOne)
|
|
498
|
-
// because buildConformanceGetter traverses outgoing links
|
|
499
|
-
//
|
|
500
|
-
//
|
|
511
|
+
// because buildConformanceGetter traverses outgoing links which is wrong for
|
|
512
|
+
// reverse relations. Their values are already populated by the reverse link
|
|
513
|
+
// lookup in instancesFromQueryResult / getData.
|
|
501
514
|
let getter = meta.getter;
|
|
502
515
|
if (!getter && meta.where && meta.direction !== 'reverse') {
|
|
503
516
|
try {
|
|
@@ -505,13 +518,34 @@ export async function evaluateCustomGettersForInstance(
|
|
|
505
518
|
const targetMetadata = TargetClass
|
|
506
519
|
? (TargetClass as any).getModelMetadata?.() ?? null
|
|
507
520
|
: null;
|
|
508
|
-
|
|
509
|
-
if
|
|
510
|
-
|
|
511
|
-
|
|
521
|
+
|
|
522
|
+
// Check if all where conditions can be SPARQL-filtered.
|
|
523
|
+
// literal-resolved properties store signed expressions (literal:json:{…}),
|
|
524
|
+
// not raw literal:string: IRIs, so SPARQL exact-match fails for them.
|
|
525
|
+
let allSparqlFilterable = true;
|
|
526
|
+
if (targetMetadata) {
|
|
527
|
+
for (const propName of Object.keys(meta.where)) {
|
|
528
|
+
if (['id', 'author', 'timestamp'].includes(propName)) continue;
|
|
529
|
+
const propMeta = targetMetadata.properties[propName];
|
|
530
|
+
if (propMeta && (!propMeta.resolveLanguage || propMeta.resolveLanguage === 'literal')) {
|
|
531
|
+
allSparqlFilterable = false;
|
|
532
|
+
break;
|
|
533
|
+
}
|
|
534
|
+
}
|
|
535
|
+
} else {
|
|
536
|
+
allSparqlFilterable = false;
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
if (allSparqlFilterable) {
|
|
540
|
+
const conditions = compileWhereClause(meta.where, targetMetadata);
|
|
541
|
+
if (conditions.length > 0) {
|
|
542
|
+
const escapedPredicate = escapeQueryString(meta.predicate);
|
|
543
|
+
getter = `SELECT ?target WHERE { <Base> <${escapedPredicate}> ?target . ${conditions.join(' ')} }`;
|
|
544
|
+
}
|
|
512
545
|
}
|
|
546
|
+
// If not filterable, fall through to buildConformanceGetter + JS post-filter below
|
|
513
547
|
} catch (e) {
|
|
514
|
-
|
|
548
|
+
console.warn(`[Ad4mModel] where-clause compilation failed for relation "${relName}":`, e);
|
|
515
549
|
}
|
|
516
550
|
}
|
|
517
551
|
if (!getter && meta.target && meta.filter !== false && meta.direction !== 'reverse') {
|
|
@@ -528,23 +562,52 @@ export async function evaluateCustomGettersForInstance(
|
|
|
528
562
|
|
|
529
563
|
if (getter) {
|
|
530
564
|
try {
|
|
531
|
-
|
|
532
|
-
const
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
565
|
+
const getterWithBase = getter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/\bBase\b/g, `<${instance.id}>`);
|
|
566
|
+
const trimmed = getterWithBase.trim().toUpperCase();
|
|
567
|
+
|
|
568
|
+
if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
|
|
569
|
+
// Native SPARQL getter — execute directly
|
|
570
|
+
const result = await perspective.querySparql(getterWithBase);
|
|
571
|
+
if (result && result.length > 0) {
|
|
572
|
+
const values = result.map((r: any) => {
|
|
573
|
+
const firstKey = Object.keys(r)[0];
|
|
574
|
+
return r[firstKey]?.value ?? r[firstKey];
|
|
575
|
+
}).filter((v: any) => v !== undefined && v !== null && v !== '' && v !== 'None');
|
|
576
|
+
instance[relName] = values;
|
|
577
|
+
}
|
|
578
|
+
} else {
|
|
579
|
+
// Legacy SurrealDB-style getter — no longer supported
|
|
580
|
+
console.warn(`Unsupported legacy getter syntax for relation ${relName} — use native SPARQL (SELECT/ASK): ${getter.slice(0, 100)}`);
|
|
543
581
|
}
|
|
544
582
|
} catch (error) {
|
|
545
583
|
console.warn(`Failed to evaluate getter for ${relName}:`, error);
|
|
546
584
|
}
|
|
547
585
|
}
|
|
586
|
+
|
|
587
|
+
// JS post-filter for where conditions that couldn't be SPARQL-filtered
|
|
588
|
+
// (e.g. literal-resolved properties storing signed expressions)
|
|
589
|
+
const currentValues = instance[relName];
|
|
590
|
+
if (meta.where && Array.isArray(currentValues) && currentValues.length > 0) {
|
|
591
|
+
const TargetClass = meta.target?.();
|
|
592
|
+
if (TargetClass) {
|
|
593
|
+
const filtered: string[] = [];
|
|
594
|
+
for (const targetId of currentValues) {
|
|
595
|
+
try {
|
|
596
|
+
const inst = new (TargetClass as any)(perspective, targetId);
|
|
597
|
+
await inst.get();
|
|
598
|
+
let matches = true;
|
|
599
|
+
for (const [prop, expected] of Object.entries(meta.where)) {
|
|
600
|
+
if ((inst as any)[prop] !== expected) { matches = false; break; }
|
|
601
|
+
}
|
|
602
|
+
if (matches) filtered.push(targetId);
|
|
603
|
+
} catch {
|
|
604
|
+
// If we can't hydrate, keep the value (conservative)
|
|
605
|
+
filtered.push(targetId);
|
|
606
|
+
}
|
|
607
|
+
}
|
|
608
|
+
instance[relName] = filtered;
|
|
609
|
+
}
|
|
610
|
+
}
|
|
548
611
|
}
|
|
549
612
|
}
|
|
550
613
|
|
package/src/model/index.ts
CHANGED
|
@@ -14,8 +14,11 @@ export * from "./query-common";
|
|
|
14
14
|
export * from "./query-prolog";
|
|
15
15
|
export * from "./prolog-facts";
|
|
16
16
|
export * from "./json-schema";
|
|
17
|
-
export * from "./query-
|
|
17
|
+
export * from "./query-utils";
|
|
18
|
+
export * from "./query-sparql";
|
|
18
19
|
export * from "./hydration";
|
|
19
20
|
export * from "./ModelQueryBuilder";
|
|
20
21
|
export * from "./sdna";
|
|
21
22
|
export * from "./shacl-gen";
|
|
23
|
+
export * from "./query-cache";
|
|
24
|
+
export * from "./subscription-pool";
|