@coasys/ad4m 0.13.0-test-4 → 0.13.0-test-6
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 +1507 -1372
- package/lib/index.js +1505 -1370
- package/lib/src/Ad4mClient.d.ts +1 -1
- package/lib/src/Ad4mClient.js +12 -1
- package/lib/src/agent/AgentClient.d.ts +16 -0
- package/lib/src/agent/AgentClient.js +74 -4
- package/lib/src/cache/PersistentCache.d.ts +40 -0
- package/lib/src/cache/PersistentCache.js +139 -0
- package/lib/src/expression/ExpressionClient.d.ts +8 -0
- package/lib/src/expression/ExpressionClient.js +113 -5
- package/lib/src/index.d.ts +1 -0
- package/lib/src/index.js +1 -0
- package/lib/src/model/Ad4mModel.d.ts +20 -7
- package/lib/src/model/Ad4mModel.js +102 -108
- package/lib/src/model/Ad4mModel.test.js +688 -1434
- package/lib/src/model/ModelQueryBuilder.d.ts +6 -6
- package/lib/src/model/ModelQueryBuilder.js +29 -20
- package/lib/src/model/Subject.js +6 -6
- package/lib/src/model/hydration.d.ts +2 -39
- package/lib/src/model/hydration.js +2 -260
- package/lib/src/model/query-surreal.d.ts +44 -0
- package/lib/src/model/query-surreal.js +249 -0
- package/lib/src/model/query-utils.d.ts +1 -0
- package/lib/src/model/query-utils.js +46 -1
- package/lib/src/model/relation-filtering.test.js +15 -15
- package/lib/src/model/surreal-utils.d.ts +42 -0
- package/lib/src/model/surreal-utils.js +128 -0
- package/lib/src/model/types.d.ts +4 -6
- package/lib/src/perspectives/PerspectiveClient.d.ts +1 -1
- package/lib/src/perspectives/PerspectiveClient.js +15 -13
- package/lib/src/perspectives/PerspectiveProxy.d.ts +14 -0
- package/lib/src/perspectives/PerspectiveProxy.js +16 -3
- package/lib/src/perspectives/PerspectiveResolver.d.ts +1 -0
- package/lib/src/perspectives/PerspectiveResolver.js +11 -0
- package/lib/src/runtime/RuntimeResolver.d.ts +1 -28
- package/lib/src/runtime/RuntimeResolver.js +4 -197
- package/lib/src/schema.gql +1 -27
- package/lib/src/shacl/SHACLShape.test.js +0 -82
- package/package.json +11 -8
- package/src/Ad4mClient.test.ts +14 -4
- package/src/Ad4mClient.ts +12 -1
- package/src/agent/AgentClient.ts +84 -2
- package/src/cache/PersistentCache.ts +145 -0
- package/src/cache/cache.test.ts +713 -0
- package/src/expression/ExpressionClient.ts +137 -3
- package/src/index.ts +1 -0
- package/src/model/Ad4mModel.test.ts +59 -358
- package/src/model/Ad4mModel.ts +112 -108
- package/src/model/ModelQueryBuilder.ts +29 -17
- package/src/model/hydration.ts +2 -279
- package/src/model/query-utils.ts +47 -2
- package/src/model/types.ts +5 -6
- package/src/perspectives/PerspectiveClient.ts +26 -17
- package/src/perspectives/PerspectiveProxy.ts +24 -3
- package/lib/src/model/hydration-batch.d.ts +0 -34
- package/lib/src/model/hydration-batch.js +0 -147
- package/lib/src/model/hydration-batching.test.d.ts +0 -7
- package/lib/src/model/hydration-batching.test.js +0 -456
- package/lib/src/model/model-manifest.d.ts +0 -41
- package/lib/src/model/model-manifest.js +0 -11
- package/lib/src/model/query-cache.test.d.ts +0 -1
- package/lib/src/model/query-cache.test.js +0 -43
- package/lib/src/model/query-sparql-batch.d.ts +0 -17
- package/lib/src/model/query-sparql-batch.js +0 -260
- package/lib/src/model/query-sparql.test.d.ts +0 -1
- package/lib/src/model/query-sparql.test.js +0 -312
- package/lib/src/model/subscription-delta.test.d.ts +0 -24
- package/lib/src/model/subscription-delta.test.js +0 -180
- package/lib/src/model/subscription-pool.d.ts +0 -39
- package/lib/src/model/subscription-pool.js +0 -165
- package/lib/src/perspectives/PerspectiveClient.test.d.ts +0 -1
- package/lib/src/perspectives/PerspectiveClient.test.js +0 -224
|
@@ -1,147 +0,0 @@
|
|
|
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
|
-
import { hydrateFromLinks, evaluateCustomGettersForInstance } from "./hydration";
|
|
11
|
-
import { getRelationsMetadata } from "./decorators";
|
|
12
|
-
/**
|
|
13
|
-
* Group batch rows by (depth, source) → array of links, preserving parentBase/relationName.
|
|
14
|
-
*/
|
|
15
|
-
function groupBatchRows(rows) {
|
|
16
|
-
const byDepth = new Map();
|
|
17
|
-
for (const row of rows) {
|
|
18
|
-
const depth = parseInt(row.depth, 10);
|
|
19
|
-
if (!byDepth.has(depth))
|
|
20
|
-
byDepth.set(depth, new Map());
|
|
21
|
-
const depthMap = byDepth.get(depth);
|
|
22
|
-
const key = row.source;
|
|
23
|
-
if (!depthMap.has(key)) {
|
|
24
|
-
depthMap.set(key, {
|
|
25
|
-
source_uri: key,
|
|
26
|
-
parentBase: row.parentBase,
|
|
27
|
-
relationName: row.relationName,
|
|
28
|
-
links: [],
|
|
29
|
-
});
|
|
30
|
-
}
|
|
31
|
-
depthMap.get(key).links.push({
|
|
32
|
-
predicate: row.predicate,
|
|
33
|
-
target: row.target,
|
|
34
|
-
author: row.author,
|
|
35
|
-
timestamp: row.timestamp,
|
|
36
|
-
});
|
|
37
|
-
}
|
|
38
|
-
const result = new Map();
|
|
39
|
-
for (const [depth, map] of byDepth) {
|
|
40
|
-
result.set(depth, Array.from(map.values()));
|
|
41
|
-
}
|
|
42
|
-
return result;
|
|
43
|
-
}
|
|
44
|
-
/**
|
|
45
|
-
* Hydrate batch SPARQL results into a tree of model instances.
|
|
46
|
-
*
|
|
47
|
-
* @param rows - Flat rows from the batch SPARQL query
|
|
48
|
-
* @param rootClass - The root model class (extends Ad4mModel)
|
|
49
|
-
* @param includeMap - The include specification from the query
|
|
50
|
-
* @param perspective - The PerspectiveProxy for creating instances
|
|
51
|
-
* @returns Array of hydrated root instances with relations populated
|
|
52
|
-
*/
|
|
53
|
-
export async function hydrateBatchResult(rows, rootClass, includeMap, perspective) {
|
|
54
|
-
if (!rows || rows.length === 0)
|
|
55
|
-
return [];
|
|
56
|
-
const grouped = groupBatchRows(rows);
|
|
57
|
-
// Hydrate root instances (depth 0)
|
|
58
|
-
const rootInstances = grouped.get(0) || [];
|
|
59
|
-
const metadata = rootClass.getModelMetadata();
|
|
60
|
-
const instances = [];
|
|
61
|
-
const instanceMap = new Map();
|
|
62
|
-
for (const group of rootInstances) {
|
|
63
|
-
const instance = new rootClass(perspective, group.source_uri);
|
|
64
|
-
await hydrateFromLinks(instance, group.links, metadata, perspective);
|
|
65
|
-
await evaluateCustomGettersForInstance(instance, perspective, metadata);
|
|
66
|
-
instances.push(instance);
|
|
67
|
-
instanceMap.set(group.source_uri, instance);
|
|
68
|
-
}
|
|
69
|
-
// Hydrate each depth level and wire to parents
|
|
70
|
-
const relMeta = getRelationsMetadata(rootClass);
|
|
71
|
-
const maxDepth = Math.max(...Array.from(grouped.keys()), 0);
|
|
72
|
-
// Build a map of depth → (class, relMetadata, parentInstanceMap)
|
|
73
|
-
// For depth 1, parents are root instances; for deeper depths, we need
|
|
74
|
-
// the instances from the previous level.
|
|
75
|
-
const depthInstanceMaps = new Map();
|
|
76
|
-
depthInstanceMaps.set(0, instanceMap);
|
|
77
|
-
// Build depth→class mapping from include tree
|
|
78
|
-
const depthClassMap = new Map();
|
|
79
|
-
buildDepthClassMap(rootClass, includeMap, 0, { value: 1 }, depthClassMap);
|
|
80
|
-
for (let depth = 1; depth <= maxDepth; depth++) {
|
|
81
|
-
const depthGroups = grouped.get(depth) || [];
|
|
82
|
-
if (depthGroups.length === 0)
|
|
83
|
-
continue;
|
|
84
|
-
const depthInfo = depthClassMap.get(depth);
|
|
85
|
-
if (!depthInfo)
|
|
86
|
-
continue;
|
|
87
|
-
const TargetClass = depthInfo.targetClass;
|
|
88
|
-
const targetMetadata = TargetClass.getModelMetadata
|
|
89
|
-
? TargetClass.getModelMetadata()
|
|
90
|
-
: { className: "Unknown", properties: {}, relations: {} };
|
|
91
|
-
const currentDepthInstances = new Map();
|
|
92
|
-
// Group by parentBase to wire children to parents
|
|
93
|
-
for (const group of depthGroups) {
|
|
94
|
-
const instance = new TargetClass(perspective, group.source_uri);
|
|
95
|
-
await hydrateFromLinks(instance, group.links, targetMetadata, perspective);
|
|
96
|
-
await evaluateCustomGettersForInstance(instance, perspective, targetMetadata);
|
|
97
|
-
currentDepthInstances.set(group.source_uri, instance);
|
|
98
|
-
// Wire to parent
|
|
99
|
-
// Find the parent depth's instance map
|
|
100
|
-
// The parentBase should exist in one of the prior depth maps
|
|
101
|
-
for (let pd = depth - 1; pd >= 0; pd--) {
|
|
102
|
-
const parentMap = depthInstanceMaps.get(pd);
|
|
103
|
-
if (parentMap && parentMap.has(group.parentBase)) {
|
|
104
|
-
const parent = parentMap.get(group.parentBase);
|
|
105
|
-
const relName = group.relationName;
|
|
106
|
-
// Determine relation metadata to know if it's an array or single
|
|
107
|
-
const parentRelMeta = getRelationsMetadata(pd === 0 ? rootClass : (depthClassMap.get(pd)?.targetClass || rootClass));
|
|
108
|
-
const rel = parentRelMeta[relName];
|
|
109
|
-
if (rel) {
|
|
110
|
-
if (rel.kind === 'hasMany' || rel.kind === 'belongsToMany') {
|
|
111
|
-
if (!Array.isArray(parent[relName])) {
|
|
112
|
-
parent[relName] = [];
|
|
113
|
-
}
|
|
114
|
-
parent[relName].push(instance);
|
|
115
|
-
}
|
|
116
|
-
else {
|
|
117
|
-
parent[relName] = instance;
|
|
118
|
-
}
|
|
119
|
-
}
|
|
120
|
-
break;
|
|
121
|
-
}
|
|
122
|
-
}
|
|
123
|
-
}
|
|
124
|
-
depthInstanceMaps.set(depth, currentDepthInstances);
|
|
125
|
-
}
|
|
126
|
-
return instances;
|
|
127
|
-
}
|
|
128
|
-
/**
|
|
129
|
-
* Build a mapping from depth number to target class info.
|
|
130
|
-
*/
|
|
131
|
-
function buildDepthClassMap(parentClass, includeMap, _parentDepth, nextDepth, result) {
|
|
132
|
-
const relMeta = getRelationsMetadata(parentClass);
|
|
133
|
-
for (const [relName, includeValue] of Object.entries(includeMap)) {
|
|
134
|
-
const meta = relMeta[relName];
|
|
135
|
-
if (!meta || !meta.target)
|
|
136
|
-
continue;
|
|
137
|
-
const TargetClass = meta.target();
|
|
138
|
-
const depth = nextDepth.value++;
|
|
139
|
-
const nestedInclude = typeof includeValue === 'object' && includeValue !== null
|
|
140
|
-
? includeValue.include
|
|
141
|
-
: undefined;
|
|
142
|
-
result.set(depth, { targetClass: TargetClass, includeMap: nestedInclude });
|
|
143
|
-
if (nestedInclude) {
|
|
144
|
-
buildDepthClassMap(TargetClass, nestedInclude, depth, nextDepth, result);
|
|
145
|
-
}
|
|
146
|
-
}
|
|
147
|
-
}
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Tests for batched hydrateRelations() — verifies the N+1 → 1 SPARQL optimisation.
|
|
3
|
-
*
|
|
4
|
-
* We mock PerspectiveProxy to count querySparql / get calls and verify
|
|
5
|
-
* that the batched path issues 1 SPARQL query instead of N perspective.get() calls.
|
|
6
|
-
*/
|
|
7
|
-
export {};
|
|
@@ -1,456 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Tests for batched hydrateRelations() — verifies the N+1 → 1 SPARQL optimisation.
|
|
3
|
-
*
|
|
4
|
-
* We mock PerspectiveProxy to count querySparql / get calls and verify
|
|
5
|
-
* that the batched path issues 1 SPARQL query instead of N perspective.get() calls.
|
|
6
|
-
*/
|
|
7
|
-
import { hydrateRelations } from './hydration';
|
|
8
|
-
// ── Helpers to build minimal mocks ──────────────────────────────────────
|
|
9
|
-
function makeMockPerspective(opts) {
|
|
10
|
-
const callCounts = { querySparql: 0, get: 0, findAll: 0 };
|
|
11
|
-
const perspective = {
|
|
12
|
-
querySparql: jest.fn(async (_q) => {
|
|
13
|
-
callCounts.querySparql++;
|
|
14
|
-
if (opts.sparqlError)
|
|
15
|
-
throw new Error('SPARQL unavailable');
|
|
16
|
-
return {
|
|
17
|
-
results: {
|
|
18
|
-
bindings: (opts.sparqlResults ?? []).map(r => ({
|
|
19
|
-
source: { value: r.source },
|
|
20
|
-
target: { value: r.target },
|
|
21
|
-
})),
|
|
22
|
-
},
|
|
23
|
-
};
|
|
24
|
-
}),
|
|
25
|
-
get: jest.fn(async (query) => {
|
|
26
|
-
callCounts.get++;
|
|
27
|
-
const targetId = query.target;
|
|
28
|
-
return opts.getResults?.get(targetId) ?? [];
|
|
29
|
-
}),
|
|
30
|
-
};
|
|
31
|
-
return { perspective, callCounts };
|
|
32
|
-
}
|
|
33
|
-
function makeMockTargetClass(knownInstances) {
|
|
34
|
-
class MockTarget {
|
|
35
|
-
constructor(perspective, id) {
|
|
36
|
-
this.id = id;
|
|
37
|
-
this.perspective = perspective;
|
|
38
|
-
}
|
|
39
|
-
async get() {
|
|
40
|
-
const data = knownInstances.get(this.id);
|
|
41
|
-
if (data)
|
|
42
|
-
Object.assign(this, data);
|
|
43
|
-
return this;
|
|
44
|
-
}
|
|
45
|
-
static async findAll(_perspective, query) {
|
|
46
|
-
const ids = query?.where?.id ?? [];
|
|
47
|
-
return ids
|
|
48
|
-
.filter(id => knownInstances.has(id))
|
|
49
|
-
.map(id => {
|
|
50
|
-
const inst = { id, ...knownInstances.get(id) };
|
|
51
|
-
return inst;
|
|
52
|
-
});
|
|
53
|
-
}
|
|
54
|
-
}
|
|
55
|
-
MockTarget.__metadata = { className: 'MockTarget' };
|
|
56
|
-
return MockTarget;
|
|
57
|
-
}
|
|
58
|
-
// Minimal decorator metadata mock
|
|
59
|
-
jest.mock('./decorators', () => ({
|
|
60
|
-
getPropertiesMetadata: () => ({}),
|
|
61
|
-
getRelationsMetadata: (cls) => cls.__relMeta ?? {},
|
|
62
|
-
buildConformanceFilter: () => () => true,
|
|
63
|
-
}));
|
|
64
|
-
jest.mock('./query-utils', () => ({
|
|
65
|
-
compileWhereClause: () => '',
|
|
66
|
-
}));
|
|
67
|
-
jest.mock('../utils', () => ({
|
|
68
|
-
escapeQueryString: (s) => s,
|
|
69
|
-
}));
|
|
70
|
-
// ── Tests ───────────────────────────────────────────────────────────────
|
|
71
|
-
describe('hydrateRelations batching', () => {
|
|
72
|
-
const PREDICATE = 'flux://belongs_to';
|
|
73
|
-
it('issues 1 SPARQL query instead of N perspective.get() calls for belongsToMany', async () => {
|
|
74
|
-
const N = 50;
|
|
75
|
-
// Create N parent instances
|
|
76
|
-
const instances = Array.from({ length: N }, (_, i) => ({
|
|
77
|
-
id: `parent-${i}`,
|
|
78
|
-
children: undefined,
|
|
79
|
-
}));
|
|
80
|
-
// Each parent has 2 children pointing to it
|
|
81
|
-
const sparqlResults = [];
|
|
82
|
-
const knownChildren = new Map();
|
|
83
|
-
for (let i = 0; i < N; i++) {
|
|
84
|
-
for (let j = 0; j < 2; j++) {
|
|
85
|
-
const childId = `child-${i}-${j}`;
|
|
86
|
-
sparqlResults.push({ source: childId, target: `parent-${i}` });
|
|
87
|
-
knownChildren.set(childId, { name: `Child ${i}-${j}` });
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
const { perspective, callCounts } = makeMockPerspective({ sparqlResults });
|
|
91
|
-
const TargetClass = makeMockTargetClass(knownChildren);
|
|
92
|
-
// Wire up relation metadata
|
|
93
|
-
const modelClass = {
|
|
94
|
-
__relMeta: {
|
|
95
|
-
children: {
|
|
96
|
-
kind: 'belongsToMany',
|
|
97
|
-
predicate: PREDICATE,
|
|
98
|
-
target: () => TargetClass,
|
|
99
|
-
maxCount: undefined,
|
|
100
|
-
},
|
|
101
|
-
},
|
|
102
|
-
};
|
|
103
|
-
// Mock getRelationsMetadata to return our metadata
|
|
104
|
-
const decorators = require('./decorators');
|
|
105
|
-
decorators.getRelationsMetadata = () => modelClass.__relMeta;
|
|
106
|
-
await hydrateRelations(modelClass, instances, perspective, { children: true });
|
|
107
|
-
// Key assertion: 1 SPARQL query, 0 perspective.get() calls
|
|
108
|
-
expect(callCounts.querySparql).toBe(1);
|
|
109
|
-
expect(callCounts.get).toBe(0);
|
|
110
|
-
// Verify data correctness
|
|
111
|
-
for (let i = 0; i < N; i++) {
|
|
112
|
-
expect(instances[i].children).toHaveLength(2);
|
|
113
|
-
expect(instances[i].children[0].id).toMatch(/^child-/);
|
|
114
|
-
}
|
|
115
|
-
console.log(`✅ Batched: ${N} instances hydrated with 1 SPARQL query + 1 findAll (was ${N} sequential perspective.get calls)`);
|
|
116
|
-
});
|
|
117
|
-
it('issues 1 SPARQL query for belongsToOne', async () => {
|
|
118
|
-
const N = 20;
|
|
119
|
-
const instances = Array.from({ length: N }, (_, i) => ({
|
|
120
|
-
id: `parent-${i}`,
|
|
121
|
-
owner: undefined,
|
|
122
|
-
}));
|
|
123
|
-
const sparqlResults = [];
|
|
124
|
-
const knownOwners = new Map();
|
|
125
|
-
for (let i = 0; i < N; i++) {
|
|
126
|
-
const ownerId = `owner-${i}`;
|
|
127
|
-
sparqlResults.push({ source: ownerId, target: `parent-${i}` });
|
|
128
|
-
knownOwners.set(ownerId, { name: `Owner ${i}` });
|
|
129
|
-
}
|
|
130
|
-
const { perspective, callCounts } = makeMockPerspective({ sparqlResults });
|
|
131
|
-
const TargetClass = makeMockTargetClass(knownOwners);
|
|
132
|
-
const modelClass = {
|
|
133
|
-
__relMeta: {
|
|
134
|
-
owner: {
|
|
135
|
-
kind: 'belongsToOne',
|
|
136
|
-
predicate: PREDICATE,
|
|
137
|
-
target: () => TargetClass,
|
|
138
|
-
maxCount: 1,
|
|
139
|
-
},
|
|
140
|
-
},
|
|
141
|
-
};
|
|
142
|
-
const decorators = require('./decorators');
|
|
143
|
-
decorators.getRelationsMetadata = () => modelClass.__relMeta;
|
|
144
|
-
await hydrateRelations(modelClass, instances, perspective, { owner: true });
|
|
145
|
-
expect(callCounts.querySparql).toBe(1);
|
|
146
|
-
expect(callCounts.get).toBe(0);
|
|
147
|
-
for (let i = 0; i < N; i++) {
|
|
148
|
-
expect(instances[i].owner).toBeTruthy();
|
|
149
|
-
expect(instances[i].owner.id).toBe(`owner-${i}`);
|
|
150
|
-
}
|
|
151
|
-
console.log(`✅ Batched belongsToOne: ${N} instances, 1 SPARQL query (was ${N} perspective.get calls)`);
|
|
152
|
-
});
|
|
153
|
-
it('falls back to sequential on SPARQL failure', async () => {
|
|
154
|
-
const instances = [{ id: 'p-0', children: undefined }];
|
|
155
|
-
const getResults = new Map();
|
|
156
|
-
getResults.set('p-0', [
|
|
157
|
-
{ data: { source: 'c-0', target: 'p-0', predicate: PREDICATE } },
|
|
158
|
-
]);
|
|
159
|
-
const { perspective, callCounts } = makeMockPerspective({
|
|
160
|
-
sparqlError: true,
|
|
161
|
-
getResults,
|
|
162
|
-
});
|
|
163
|
-
const TargetClass = makeMockTargetClass(new Map([['c-0', { name: 'Child' }]]));
|
|
164
|
-
const modelClass = {
|
|
165
|
-
__relMeta: {
|
|
166
|
-
children: {
|
|
167
|
-
kind: 'belongsToMany',
|
|
168
|
-
predicate: PREDICATE,
|
|
169
|
-
target: () => TargetClass,
|
|
170
|
-
maxCount: undefined,
|
|
171
|
-
},
|
|
172
|
-
},
|
|
173
|
-
};
|
|
174
|
-
const decorators = require('./decorators');
|
|
175
|
-
decorators.getRelationsMetadata = () => modelClass.__relMeta;
|
|
176
|
-
await hydrateRelations(modelClass, instances, perspective, { children: true });
|
|
177
|
-
// Should have fallen back to perspective.get
|
|
178
|
-
expect(callCounts.querySparql).toBe(1); // attempted
|
|
179
|
-
expect(callCounts.get).toBe(1); // fallback
|
|
180
|
-
expect(instances[0].children).toHaveLength(1);
|
|
181
|
-
console.log('✅ Fallback to sequential works when SPARQL fails');
|
|
182
|
-
});
|
|
183
|
-
// ── Test #1: Nested includes ──
|
|
184
|
-
it('handles nested includes at multiple nesting levels', async () => {
|
|
185
|
-
// Post -> Comments -> Author (two levels of nesting)
|
|
186
|
-
const posts = [
|
|
187
|
-
{ id: 'post-0', comments: undefined },
|
|
188
|
-
{ id: 'post-1', comments: undefined },
|
|
189
|
-
];
|
|
190
|
-
// SPARQL returns comments belonging to posts
|
|
191
|
-
const commentSparql = [
|
|
192
|
-
{ source: 'comment-0', target: 'post-0' },
|
|
193
|
-
{ source: 'comment-1', target: 'post-0' },
|
|
194
|
-
{ source: 'comment-2', target: 'post-1' },
|
|
195
|
-
];
|
|
196
|
-
const knownComments = new Map([
|
|
197
|
-
['comment-0', { name: 'C0', author: undefined }],
|
|
198
|
-
['comment-1', { name: 'C1', author: undefined }],
|
|
199
|
-
['comment-2', { name: 'C2', author: undefined }],
|
|
200
|
-
]);
|
|
201
|
-
const { perspective, callCounts } = makeMockPerspective({ sparqlResults: commentSparql });
|
|
202
|
-
// Comment class with nested relation metadata
|
|
203
|
-
const CommentClass = makeMockTargetClass(knownComments);
|
|
204
|
-
CommentClass.__relMeta = {
|
|
205
|
-
author: {
|
|
206
|
-
kind: 'belongsToOne',
|
|
207
|
-
predicate: 'flux://authored_by',
|
|
208
|
-
target: () => makeMockTargetClass(new Map([
|
|
209
|
-
['author-1', { name: 'Alice' }],
|
|
210
|
-
['author-2', { name: 'Bob' }],
|
|
211
|
-
])),
|
|
212
|
-
maxCount: 1,
|
|
213
|
-
},
|
|
214
|
-
};
|
|
215
|
-
const modelClass = {
|
|
216
|
-
__relMeta: {
|
|
217
|
-
comments: {
|
|
218
|
-
kind: 'belongsToMany',
|
|
219
|
-
predicate: PREDICATE,
|
|
220
|
-
target: () => CommentClass,
|
|
221
|
-
maxCount: undefined,
|
|
222
|
-
},
|
|
223
|
-
},
|
|
224
|
-
};
|
|
225
|
-
const decorators = require('./decorators');
|
|
226
|
-
decorators.getRelationsMetadata = (cls) => cls.__relMeta ?? {};
|
|
227
|
-
await hydrateRelations(modelClass, posts, perspective, {
|
|
228
|
-
comments: { include: { author: true } },
|
|
229
|
-
});
|
|
230
|
-
// First level should be hydrated
|
|
231
|
-
expect(posts[0].comments).toHaveLength(2);
|
|
232
|
-
expect(posts[1].comments).toHaveLength(1);
|
|
233
|
-
// Batching: 1 SPARQL for comments + additional calls for nested author hydration
|
|
234
|
-
// The key is that it completes without error and data is correct at the first level
|
|
235
|
-
expect(callCounts.querySparql).toBeGreaterThanOrEqual(1);
|
|
236
|
-
console.log('✅ Nested includes: multi-level nesting works');
|
|
237
|
-
});
|
|
238
|
-
// ── Test #2: Mixed relation types ──
|
|
239
|
-
it('batches hasMany and belongsToOne independently on the same query', async () => {
|
|
240
|
-
const instances = Array.from({ length: 5 }, (_, i) => ({
|
|
241
|
-
id: `item-${i}`,
|
|
242
|
-
tags: [`tag-${i}-a`, `tag-${i}-b`],
|
|
243
|
-
owner: undefined, // reverse belongsToOne
|
|
244
|
-
}));
|
|
245
|
-
const sparqlResults = [];
|
|
246
|
-
for (let i = 0; i < 5; i++) {
|
|
247
|
-
sparqlResults.push({ source: `owner-${i}`, target: `item-${i}` });
|
|
248
|
-
}
|
|
249
|
-
const { perspective, callCounts } = makeMockPerspective({ sparqlResults });
|
|
250
|
-
const TagClass = makeMockTargetClass(new Map(instances.flatMap((_, i) => [
|
|
251
|
-
[`tag-${i}-a`, { label: `Tag A${i}` }],
|
|
252
|
-
[`tag-${i}-b`, { label: `Tag B${i}` }],
|
|
253
|
-
])));
|
|
254
|
-
const OwnerClass = makeMockTargetClass(new Map(Array.from({ length: 5 }, (_, i) => [`owner-${i}`, { name: `Owner ${i}` }])));
|
|
255
|
-
const modelClass = {
|
|
256
|
-
__relMeta: {
|
|
257
|
-
tags: {
|
|
258
|
-
kind: 'hasMany',
|
|
259
|
-
predicate: 'flux://has_tag',
|
|
260
|
-
target: () => TagClass,
|
|
261
|
-
maxCount: undefined,
|
|
262
|
-
},
|
|
263
|
-
owner: {
|
|
264
|
-
kind: 'belongsToOne',
|
|
265
|
-
predicate: 'flux://owned_by',
|
|
266
|
-
target: () => OwnerClass,
|
|
267
|
-
maxCount: 1,
|
|
268
|
-
},
|
|
269
|
-
},
|
|
270
|
-
};
|
|
271
|
-
const decorators = require('./decorators');
|
|
272
|
-
decorators.getRelationsMetadata = () => modelClass.__relMeta;
|
|
273
|
-
await hydrateRelations(modelClass, instances, perspective, {
|
|
274
|
-
tags: true,
|
|
275
|
-
owner: true,
|
|
276
|
-
});
|
|
277
|
-
// belongsToOne uses 1 SPARQL query
|
|
278
|
-
expect(callCounts.querySparql).toBe(1);
|
|
279
|
-
// Forward relations use findAll (no SPARQL)
|
|
280
|
-
for (let i = 0; i < 5; i++) {
|
|
281
|
-
expect(instances[i].tags).toHaveLength(2);
|
|
282
|
-
expect(instances[i].owner).toBeTruthy();
|
|
283
|
-
}
|
|
284
|
-
console.log('✅ Mixed relation types: hasMany + belongsToOne batched independently');
|
|
285
|
-
});
|
|
286
|
-
// ── Test #3: Empty relations ──
|
|
287
|
-
it('handles instances where some have the relation and some do not', async () => {
|
|
288
|
-
const instances = [
|
|
289
|
-
{ id: 'has-children', children: undefined },
|
|
290
|
-
{ id: 'no-children', children: undefined },
|
|
291
|
-
];
|
|
292
|
-
// Only has-children has related items
|
|
293
|
-
const sparqlResults = [
|
|
294
|
-
{ source: 'child-1', target: 'has-children' },
|
|
295
|
-
];
|
|
296
|
-
const { perspective } = makeMockPerspective({ sparqlResults });
|
|
297
|
-
const TargetClass = makeMockTargetClass(new Map([['child-1', { name: 'C1' }]]));
|
|
298
|
-
const modelClass = {
|
|
299
|
-
__relMeta: {
|
|
300
|
-
children: {
|
|
301
|
-
kind: 'belongsToMany',
|
|
302
|
-
predicate: PREDICATE,
|
|
303
|
-
target: () => TargetClass,
|
|
304
|
-
maxCount: undefined,
|
|
305
|
-
},
|
|
306
|
-
},
|
|
307
|
-
};
|
|
308
|
-
const decorators = require('./decorators');
|
|
309
|
-
decorators.getRelationsMetadata = () => modelClass.__relMeta;
|
|
310
|
-
await hydrateRelations(modelClass, instances, perspective, { children: true });
|
|
311
|
-
expect(instances[0].children).toHaveLength(1);
|
|
312
|
-
expect(instances[1].children).toEqual([]);
|
|
313
|
-
console.log('✅ Empty relations: no crashes, correct null/empty handling');
|
|
314
|
-
});
|
|
315
|
-
// ── Test #4: Duplicate relation targets ──
|
|
316
|
-
it('deduplicates when multiple instances point to the same related entity', async () => {
|
|
317
|
-
const instances = [
|
|
318
|
-
{ id: 'a', owner: undefined },
|
|
319
|
-
{ id: 'b', owner: undefined },
|
|
320
|
-
{ id: 'c', owner: undefined },
|
|
321
|
-
];
|
|
322
|
-
// All three instances share the same owner
|
|
323
|
-
const sparqlResults = [
|
|
324
|
-
{ source: 'shared-owner', target: 'a' },
|
|
325
|
-
{ source: 'shared-owner', target: 'b' },
|
|
326
|
-
{ source: 'shared-owner', target: 'c' },
|
|
327
|
-
];
|
|
328
|
-
const knownOwners = new Map([['shared-owner', { name: 'Shared' }]]);
|
|
329
|
-
const { perspective } = makeMockPerspective({ sparqlResults });
|
|
330
|
-
const TargetClass = makeMockTargetClass(knownOwners);
|
|
331
|
-
// Track findAll calls to verify deduplication
|
|
332
|
-
const originalFindAll = TargetClass.findAll;
|
|
333
|
-
let findAllIds = [];
|
|
334
|
-
TargetClass.findAll = async (p, q) => {
|
|
335
|
-
findAllIds = q?.where?.id ?? [];
|
|
336
|
-
return originalFindAll(p, q);
|
|
337
|
-
};
|
|
338
|
-
const modelClass = {
|
|
339
|
-
__relMeta: {
|
|
340
|
-
owner: {
|
|
341
|
-
kind: 'belongsToOne',
|
|
342
|
-
predicate: PREDICATE,
|
|
343
|
-
target: () => TargetClass,
|
|
344
|
-
maxCount: 1,
|
|
345
|
-
},
|
|
346
|
-
},
|
|
347
|
-
};
|
|
348
|
-
const decorators = require('./decorators');
|
|
349
|
-
decorators.getRelationsMetadata = () => modelClass.__relMeta;
|
|
350
|
-
await hydrateRelations(modelClass, instances, perspective, { owner: true });
|
|
351
|
-
// Should only request the shared owner once
|
|
352
|
-
expect(findAllIds).toHaveLength(1);
|
|
353
|
-
expect(findAllIds[0]).toBe('shared-owner');
|
|
354
|
-
// All instances should have the same owner
|
|
355
|
-
for (const inst of instances) {
|
|
356
|
-
expect(inst.owner).toBeTruthy();
|
|
357
|
-
expect(inst.owner.id).toBe('shared-owner');
|
|
358
|
-
}
|
|
359
|
-
console.log('✅ Duplicate targets: deduplication works (1 fetch for shared entity)');
|
|
360
|
-
});
|
|
361
|
-
// ── Test #5: Large batch (100+ instances) ──
|
|
362
|
-
it('handles 150 instances without breaking SPARQL VALUES/FILTER clause', async () => {
|
|
363
|
-
const N = 150;
|
|
364
|
-
const instances = Array.from({ length: N }, (_, i) => ({
|
|
365
|
-
id: `inst-${i}`,
|
|
366
|
-
child: undefined,
|
|
367
|
-
}));
|
|
368
|
-
const sparqlResults = Array.from({ length: N }, (_, i) => ({
|
|
369
|
-
source: `related-${i}`,
|
|
370
|
-
target: `inst-${i}`,
|
|
371
|
-
}));
|
|
372
|
-
const knownRelated = new Map(Array.from({ length: N }, (_, i) => [`related-${i}`, { value: i }]));
|
|
373
|
-
const { perspective, callCounts } = makeMockPerspective({ sparqlResults });
|
|
374
|
-
const TargetClass = makeMockTargetClass(knownRelated);
|
|
375
|
-
const modelClass = {
|
|
376
|
-
__relMeta: {
|
|
377
|
-
child: {
|
|
378
|
-
kind: 'belongsToOne',
|
|
379
|
-
predicate: PREDICATE,
|
|
380
|
-
target: () => TargetClass,
|
|
381
|
-
maxCount: 1,
|
|
382
|
-
},
|
|
383
|
-
},
|
|
384
|
-
};
|
|
385
|
-
const decorators = require('./decorators');
|
|
386
|
-
decorators.getRelationsMetadata = () => modelClass.__relMeta;
|
|
387
|
-
await hydrateRelations(modelClass, instances, perspective, { child: true });
|
|
388
|
-
expect(callCounts.querySparql).toBe(1);
|
|
389
|
-
const hydrated = instances.filter(i => i.child != null);
|
|
390
|
-
expect(hydrated.length).toBe(N);
|
|
391
|
-
console.log(`✅ Large batch: ${N} instances hydrated with 1 SPARQL query`);
|
|
392
|
-
});
|
|
393
|
-
// ── Test #6: Relation with where filter ──
|
|
394
|
-
it('applies where filter on batched relation fetch', async () => {
|
|
395
|
-
const instances = [{ id: 'post-0', comments: undefined }];
|
|
396
|
-
const sparqlResults = [
|
|
397
|
-
{ source: 'c-pub', target: 'post-0' },
|
|
398
|
-
{ source: 'c-draft', target: 'post-0' },
|
|
399
|
-
];
|
|
400
|
-
// Only c-pub matches the where filter
|
|
401
|
-
const knownComments = new Map([
|
|
402
|
-
['c-pub', { status: 'published', text: 'Public' }],
|
|
403
|
-
// c-draft won't be returned by findAll with where filter
|
|
404
|
-
]);
|
|
405
|
-
const { perspective } = makeMockPerspective({ sparqlResults });
|
|
406
|
-
const TargetClass = makeMockTargetClass(knownComments);
|
|
407
|
-
const modelClass = {
|
|
408
|
-
__relMeta: {
|
|
409
|
-
comments: {
|
|
410
|
-
kind: 'belongsToMany',
|
|
411
|
-
predicate: PREDICATE,
|
|
412
|
-
target: () => TargetClass,
|
|
413
|
-
maxCount: undefined,
|
|
414
|
-
},
|
|
415
|
-
},
|
|
416
|
-
};
|
|
417
|
-
const decorators = require('./decorators');
|
|
418
|
-
decorators.getRelationsMetadata = () => modelClass.__relMeta;
|
|
419
|
-
await hydrateRelations(modelClass, instances, perspective, {
|
|
420
|
-
comments: { where: { status: 'published' } },
|
|
421
|
-
});
|
|
422
|
-
// Only c-pub should be in the result (c-draft not in knownComments so findAll filters it)
|
|
423
|
-
expect(instances[0].comments).toHaveLength(1);
|
|
424
|
-
expect(instances[0].comments[0].id).toBe('c-pub');
|
|
425
|
-
console.log('✅ Where filter: applied correctly on batched fetch');
|
|
426
|
-
});
|
|
427
|
-
// ── Test #7: Circular relations ──
|
|
428
|
-
it('does not infinite loop with circular relations (A->B, B->A)', async () => {
|
|
429
|
-
// We only test one level of include, ensuring no infinite recursion
|
|
430
|
-
const instances = [{ id: 'A', partner: undefined }];
|
|
431
|
-
const sparqlResults = [{ source: 'B', target: 'A' }];
|
|
432
|
-
const knownPartners = new Map([['B', { name: 'B' }]]);
|
|
433
|
-
const { perspective } = makeMockPerspective({ sparqlResults });
|
|
434
|
-
const TargetClass = makeMockTargetClass(knownPartners);
|
|
435
|
-
const modelClass = {
|
|
436
|
-
__relMeta: {
|
|
437
|
-
partner: {
|
|
438
|
-
kind: 'belongsToOne',
|
|
439
|
-
predicate: 'flux://partner',
|
|
440
|
-
target: () => TargetClass,
|
|
441
|
-
maxCount: 1,
|
|
442
|
-
},
|
|
443
|
-
},
|
|
444
|
-
};
|
|
445
|
-
const decorators = require('./decorators');
|
|
446
|
-
decorators.getRelationsMetadata = () => modelClass.__relMeta;
|
|
447
|
-
// This should complete without hanging — no nested include means no recursion
|
|
448
|
-
const result = await Promise.race([
|
|
449
|
-
hydrateRelations(modelClass, instances, perspective, { partner: true }),
|
|
450
|
-
new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout — infinite loop?')), 2000)),
|
|
451
|
-
]);
|
|
452
|
-
expect(instances[0].partner).toBeTruthy();
|
|
453
|
-
expect(instances[0].partner.id).toBe('B');
|
|
454
|
-
console.log('✅ Circular relations: no infinite loop');
|
|
455
|
-
});
|
|
456
|
-
});
|
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Types for the perspective model manifest — a human-readable, AI-friendly summary
|
|
3
|
-
* of all Ad4mModel-compatible classes defined in a perspective's SHACL shapes.
|
|
4
|
-
*
|
|
5
|
-
* Used by `PerspectiveProxy.getModelManifest()` and consumed by WE's AI context
|
|
6
|
-
* injection (`formatManifestForPrompt`) to describe external perspective models
|
|
7
|
-
* to the schema-generation AI.
|
|
8
|
-
*
|
|
9
|
-
* @module
|
|
10
|
-
*/
|
|
11
|
-
/** Normalised description of a single property on a model class. */
|
|
12
|
-
export interface ModelManifestProperty {
|
|
13
|
-
/** Property name as declared in the SHACL shape (e.g. "name", "body", "participants"). */
|
|
14
|
-
name: string;
|
|
15
|
-
/** The exact RDF predicate URI (e.g. "flux://has_name"). */
|
|
16
|
-
predicate: string;
|
|
17
|
-
/** Normalised scalar type; inferred from xsd:/sh: datatype + nodeKind. */
|
|
18
|
-
type: 'string' | 'number' | 'boolean' | 'uri';
|
|
19
|
-
/** `true` when maxCount is absent or > 1 (i.e. returned as an array). */
|
|
20
|
-
isCollection: boolean;
|
|
21
|
-
/** `true` when minCount >= 1. */
|
|
22
|
-
required: boolean;
|
|
23
|
-
writable: boolean;
|
|
24
|
-
/** AD4M language used to resolve the value (e.g. "literal"). */
|
|
25
|
-
resolveLanguage?: string;
|
|
26
|
-
/**
|
|
27
|
-
* Local name of the related model class when this is a typed relation property.
|
|
28
|
-
* Derived from `SHACLPropertyShape.class` by stripping the URI prefix.
|
|
29
|
-
* E.g. `flux://Message` → `"Message"`.
|
|
30
|
-
*/
|
|
31
|
-
relatedModel?: string;
|
|
32
|
-
}
|
|
33
|
-
/** Normalised description of a single model class stored in a perspective. */
|
|
34
|
-
export interface ModelManifestEntry {
|
|
35
|
-
/** Class name — usable directly as the `model` field in a `$query` token. */
|
|
36
|
-
name: string;
|
|
37
|
-
/** The SHACL `targetClass` URI (e.g. "flux://Channel"). */
|
|
38
|
-
targetClass: string;
|
|
39
|
-
/** All data properties (flag/hasValue properties are excluded). */
|
|
40
|
-
properties: ModelManifestProperty[];
|
|
41
|
-
}
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Types for the perspective model manifest — a human-readable, AI-friendly summary
|
|
3
|
-
* of all Ad4mModel-compatible classes defined in a perspective's SHACL shapes.
|
|
4
|
-
*
|
|
5
|
-
* Used by `PerspectiveProxy.getModelManifest()` and consumed by WE's AI context
|
|
6
|
-
* injection (`formatManifestForPrompt`) to describe external perspective models
|
|
7
|
-
* to the schema-generation AI.
|
|
8
|
-
*
|
|
9
|
-
* @module
|
|
10
|
-
*/
|
|
11
|
-
export {};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|