@coasys/ad4m 0.13.0-test-1 → 0.13.0-test-3
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 +2377 -849
- package/lib/index.js +2354 -846
- 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/index.d.ts +0 -1
- package/lib/src/index.js +0 -1
- package/lib/src/language/Language.d.ts +26 -176
- package/lib/src/language/Language.js +28 -2
- package/lib/src/model/Ad4mModel.d.ts +52 -28
- package/lib/src/model/Ad4mModel.js +255 -118
- package/lib/src/model/Ad4mModel.test.js +1727 -537
- package/lib/src/model/ModelQueryBuilder.d.ts +67 -34
- package/lib/src/model/ModelQueryBuilder.js +208 -79
- 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-batching.test.d.ts +7 -0
- package/lib/src/model/hydration-batching.test.js +456 -0
- package/lib/src/model/hydration.d.ts +4 -3
- package/lib/src/model/hydration.js +365 -86
- 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 +124 -0
- package/lib/src/model/query-sparql.js +767 -0
- package/lib/src/model/query-sparql.test.d.ts +1 -0
- package/lib/src/model/query-sparql.test.js +495 -0
- package/lib/src/model/{surreal-utils.d.ts → query-utils.d.ts} +12 -9
- package/lib/src/model/{surreal-utils.js → query-utils.js} +43 -27
- 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-delta.test.d.ts +24 -0
- package/lib/src/model/subscription-delta.test.js +180 -0
- package/lib/src/model/subscription-pool.d.ts +39 -0
- package/lib/src/model/subscription-pool.js +165 -0
- package/lib/src/model/types.d.ts +52 -4
- package/lib/src/model/types.js +1 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +3 -17
- package/lib/src/perspectives/PerspectiveClient.js +42 -66
- package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
- package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -30
- package/lib/src/perspectives/PerspectiveProxy.js +239 -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/Ad4mClient.test.ts +56 -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/index.ts +0 -1
- package/src/language/Language.ts +55 -231
- package/src/model/Ad4mModel.test.ts +1709 -572
- package/src/model/Ad4mModel.ts +274 -120
- package/src/model/ModelQueryBuilder.ts +234 -87
- 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-batching.test.ts +563 -0
- package/src/model/hydration.ts +349 -84
- 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.test.ts +568 -0
- package/src/model/query-sparql.ts +820 -0
- package/src/model/{surreal-utils.ts → query-utils.ts} +44 -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-delta.test.ts +207 -0
- package/src/model/subscription-pool.ts +211 -0
- package/src/model/types.ts +53 -4
- package/src/perspectives/PerspectiveClient.test.ts +204 -0
- package/src/perspectives/PerspectiveClient.ts +41 -68
- package/src/perspectives/PerspectiveProxy.ts +244 -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/lib/src/model/query-surreal.d.ts +0 -44
- package/lib/src/model/query-surreal.js +0 -249
- package/src/language/LanguageContext.ts +0 -37
- package/src/model/query-surreal.ts +0 -280
- package/tsconfig-browser.json +0 -82
|
@@ -2,15 +2,16 @@
|
|
|
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
|
*/
|
|
9
9
|
import { Literal } from "../Literal";
|
|
10
10
|
import { LinkQuery } from "../perspectives/LinkQuery";
|
|
11
11
|
import { getPropertiesMetadata, getRelationsMetadata, buildConformanceFilter } from "./decorators";
|
|
12
|
-
import {
|
|
13
|
-
import {
|
|
12
|
+
import { compileWhereClause } from "./query-utils";
|
|
13
|
+
import { escapeQueryString } from "../utils";
|
|
14
|
+
import { buildSPARQLGroupedCountQuery, parseSparqlGroupedCount } from "./query-sparql";
|
|
14
15
|
// ──────────────────────────────────────────────────────────
|
|
15
16
|
// Pure helpers
|
|
16
17
|
// ──────────────────────────────────────────────────────────
|
|
@@ -102,7 +103,7 @@ export async function hydratePropertyValue(target, propMeta, perspective, expect
|
|
|
102
103
|
if (propMeta.resolveLanguage != null &&
|
|
103
104
|
propMeta.resolveLanguage !== 'literal' &&
|
|
104
105
|
typeof target === 'string' &&
|
|
105
|
-
!target.startsWith('literal
|
|
106
|
+
!target.startsWith('literal:')) {
|
|
106
107
|
try {
|
|
107
108
|
const expression = await perspective.getExpression(target);
|
|
108
109
|
if (expression) {
|
|
@@ -121,7 +122,7 @@ export async function hydratePropertyValue(target, propMeta, perspective, expect
|
|
|
121
122
|
// Literal URI parsing
|
|
122
123
|
else if (propMeta.resolveLanguage === 'literal' &&
|
|
123
124
|
typeof target === 'string' &&
|
|
124
|
-
target.startsWith('literal
|
|
125
|
+
target.startsWith('literal:')) {
|
|
125
126
|
try {
|
|
126
127
|
const parsed = Literal.fromUrl(target).get();
|
|
127
128
|
value = parsed.data !== undefined ? parsed.data : parsed;
|
|
@@ -355,10 +356,10 @@ export async function assignValuesToInstance(perspective, instance, values) {
|
|
|
355
356
|
Object.assign(instance, writableProps);
|
|
356
357
|
}
|
|
357
358
|
// ──────────────────────────────────────────────────────────
|
|
358
|
-
//
|
|
359
|
+
// SPARQL custom getter evaluation
|
|
359
360
|
// ──────────────────────────────────────────────────────────
|
|
360
361
|
/**
|
|
361
|
-
* Builds a
|
|
362
|
+
* Builds a SPARQL conformance getter for a relation whose `target` model
|
|
362
363
|
* is known but no explicit `getter` string was supplied.
|
|
363
364
|
*
|
|
364
365
|
* The generated getter traverses outgoing links matching the relation's
|
|
@@ -370,7 +371,7 @@ export async function assignValuesToInstance(perspective, instance, values) {
|
|
|
370
371
|
*
|
|
371
372
|
* @param relationPredicate - The relation's predicate URI (e.g. "flux://entry_type")
|
|
372
373
|
* @param targetClass - The target model class (result of calling the `target()` thunk)
|
|
373
|
-
* @returns A
|
|
374
|
+
* @returns A SPARQL expression string, or `undefined` if no conformance
|
|
374
375
|
* conditions could be derived from the target model.
|
|
375
376
|
*/
|
|
376
377
|
export function buildConformanceGetter(relationPredicate, targetClass) {
|
|
@@ -389,30 +390,49 @@ export function buildConformanceGetter(relationPredicate, targetClass) {
|
|
|
389
390
|
* getter is auto-generated from the target model's metadata (unless `filter: false`).
|
|
390
391
|
*/
|
|
391
392
|
export async function evaluateCustomGettersForInstance(instance, perspective, metadata, options) {
|
|
392
|
-
const safeBaseExpression =
|
|
393
|
+
const safeBaseExpression = `<${instance.id}>`;
|
|
393
394
|
// Build projection filter — when requestedProperties is active, only
|
|
394
395
|
// evaluate getters for fields that are requested (or included).
|
|
395
396
|
const projectionActive = options?.requestedProperties && options.requestedProperties.length > 0;
|
|
396
397
|
const projectionSet = projectionActive ? new Set(options.requestedProperties) : null;
|
|
397
|
-
// Evaluate property getters
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
398
|
+
// Evaluate property getters (skip when caller only wants relation type-filtering)
|
|
399
|
+
if (!options?.skipPropertyGetters) {
|
|
400
|
+
for (const [propName, propMeta] of Object.entries(metadata.properties)) {
|
|
401
|
+
if (projectionSet && !projectionSet.has(propName))
|
|
402
|
+
continue;
|
|
403
|
+
if (propMeta.getter) {
|
|
404
|
+
try {
|
|
405
|
+
const rawGetter = propMeta.getter;
|
|
406
|
+
const getterWithBase = rawGetter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/Base/g, `<${instance.id}>`);
|
|
407
|
+
// If the getter is already SPARQL (starts with SELECT/ASK/CONSTRUCT), execute directly
|
|
408
|
+
const trimmed = getterWithBase.trim().toUpperCase();
|
|
409
|
+
if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
|
|
410
|
+
const result = await perspective.querySparql(getterWithBase);
|
|
411
|
+
if (trimmed.startsWith('ASK')) {
|
|
412
|
+
instance[propName] = result === true || result === 'true';
|
|
413
|
+
}
|
|
414
|
+
else if (result && result.length > 0) {
|
|
415
|
+
// Get first binding's first value
|
|
416
|
+
const firstRow = result[0];
|
|
417
|
+
const firstKey = Object.keys(firstRow)[0];
|
|
418
|
+
const val = firstRow[firstKey]?.value ?? firstRow[firstKey];
|
|
419
|
+
if (val !== undefined && val !== null && val !== 'None' && val !== '') {
|
|
420
|
+
instance[propName] = val;
|
|
421
|
+
}
|
|
422
|
+
}
|
|
423
|
+
}
|
|
424
|
+
else {
|
|
425
|
+
// Legacy SurrealDB-style getter — safety guard for getters that don't match
|
|
426
|
+
// SPARQL patterns (SELECT/ASK). Logs a warning but does not crash.
|
|
427
|
+
console.warn(`Unsupported legacy getter syntax for property ${propName} — use native SPARQL (SELECT/ASK): ${rawGetter.slice(0, 100)}`);
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
catch (error) {
|
|
431
|
+
console.warn(`Failed to evaluate getter for ${propName}:`, error);
|
|
409
432
|
}
|
|
410
|
-
}
|
|
411
|
-
catch (error) {
|
|
412
|
-
console.warn(`Failed to evaluate getter for ${propName}:`, error);
|
|
413
433
|
}
|
|
414
434
|
}
|
|
415
|
-
}
|
|
435
|
+
} // end skipPropertyGetters guard
|
|
416
436
|
// Evaluate relation getters (explicit or auto-generated from target)
|
|
417
437
|
for (const [relName, relMeta] of Object.entries(metadata.relations)) {
|
|
418
438
|
// Skip relations excluded by property projection (unless in include map)
|
|
@@ -421,12 +441,11 @@ export async function evaluateCustomGettersForInstance(instance, perspective, me
|
|
|
421
441
|
const meta = relMeta;
|
|
422
442
|
// Determine the getter to execute:
|
|
423
443
|
// 1. Explicit `getter` always wins
|
|
424
|
-
// 2. `
|
|
425
|
-
// 3. If `target` is set and `filter !== false`, auto-generate from target metadata
|
|
444
|
+
// 2. If `target` is set and `filter !== false`, auto-generate conformance getter
|
|
426
445
|
// BUT skip auto-generation for reverse relations (belongsToMany / belongsToOne)
|
|
427
|
-
// because buildConformanceGetter traverses outgoing links
|
|
428
|
-
//
|
|
429
|
-
//
|
|
446
|
+
// because buildConformanceGetter traverses outgoing links which is wrong for
|
|
447
|
+
// reverse relations. Their values are already populated by the reverse link
|
|
448
|
+
// lookup in instancesFromQueryResult / getData.
|
|
430
449
|
let getter = meta.getter;
|
|
431
450
|
if (!getter && meta.where && meta.direction !== 'reverse') {
|
|
432
451
|
try {
|
|
@@ -434,14 +453,35 @@ export async function evaluateCustomGettersForInstance(instance, perspective, me
|
|
|
434
453
|
const targetMetadata = TargetClass
|
|
435
454
|
? TargetClass.getModelMetadata?.() ?? null
|
|
436
455
|
: null;
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
456
|
+
// Check if all where conditions can be SPARQL-filtered.
|
|
457
|
+
// literal-resolved properties store signed expressions (literal:json:{…}),
|
|
458
|
+
// not raw literal:string: IRIs, so SPARQL exact-match fails for them.
|
|
459
|
+
let allSparqlFilterable = true;
|
|
460
|
+
if (targetMetadata) {
|
|
461
|
+
for (const propName of Object.keys(meta.where)) {
|
|
462
|
+
if (['id', 'author', 'timestamp'].includes(propName))
|
|
463
|
+
continue;
|
|
464
|
+
const propMeta = targetMetadata.properties[propName];
|
|
465
|
+
if (propMeta && (!propMeta.resolveLanguage || propMeta.resolveLanguage === 'literal')) {
|
|
466
|
+
allSparqlFilterable = false;
|
|
467
|
+
break;
|
|
468
|
+
}
|
|
469
|
+
}
|
|
470
|
+
}
|
|
471
|
+
else {
|
|
472
|
+
allSparqlFilterable = false;
|
|
441
473
|
}
|
|
474
|
+
if (allSparqlFilterable) {
|
|
475
|
+
const conditions = compileWhereClause(meta.where, targetMetadata);
|
|
476
|
+
if (conditions.length > 0) {
|
|
477
|
+
const escapedPredicate = escapeQueryString(meta.predicate);
|
|
478
|
+
getter = `SELECT ?target WHERE { <Base> <${escapedPredicate}> ?target . ${conditions.join(' ')} }`;
|
|
479
|
+
}
|
|
480
|
+
}
|
|
481
|
+
// If not filterable, fall through to buildConformanceGetter + JS post-filter below
|
|
442
482
|
}
|
|
443
483
|
catch (e) {
|
|
444
|
-
|
|
484
|
+
console.warn(`[Ad4mModel] where-clause compilation failed for relation "${relName}":`, e);
|
|
445
485
|
}
|
|
446
486
|
}
|
|
447
487
|
if (!getter && meta.target && meta.filter !== false && meta.direction !== 'reverse') {
|
|
@@ -458,23 +498,58 @@ export async function evaluateCustomGettersForInstance(instance, perspective, me
|
|
|
458
498
|
}
|
|
459
499
|
if (getter) {
|
|
460
500
|
try {
|
|
461
|
-
|
|
462
|
-
const
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
501
|
+
const getterWithBase = getter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/\bBase\b/g, `<${instance.id}>`);
|
|
502
|
+
const trimmed = getterWithBase.trim().toUpperCase();
|
|
503
|
+
if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
|
|
504
|
+
// Native SPARQL getter — execute directly
|
|
505
|
+
const result = await perspective.querySparql(getterWithBase);
|
|
506
|
+
if (result && result.length > 0) {
|
|
507
|
+
const values = result.map((r) => {
|
|
508
|
+
const firstKey = Object.keys(r)[0];
|
|
509
|
+
return r[firstKey]?.value ?? r[firstKey];
|
|
510
|
+
}).filter((v) => v !== undefined && v !== null && v !== '' && v !== 'None');
|
|
511
|
+
instance[relName] = values;
|
|
512
|
+
}
|
|
513
|
+
}
|
|
514
|
+
else {
|
|
515
|
+
// Legacy SurrealDB-style getter — safety guard for relation getters that don't
|
|
516
|
+
// match SPARQL patterns (SELECT/ASK). Logs a warning but does not crash.
|
|
517
|
+
console.warn(`Unsupported legacy getter syntax for relation ${relName} — use native SPARQL (SELECT/ASK): ${getter.slice(0, 100)}`);
|
|
472
518
|
}
|
|
473
519
|
}
|
|
474
520
|
catch (error) {
|
|
475
521
|
console.warn(`Failed to evaluate getter for ${relName}:`, error);
|
|
476
522
|
}
|
|
477
523
|
}
|
|
524
|
+
// JS post-filter for where conditions that couldn't be SPARQL-filtered
|
|
525
|
+
// (e.g. literal-resolved properties storing signed expressions)
|
|
526
|
+
const currentValues = instance[relName];
|
|
527
|
+
if (meta.where && Array.isArray(currentValues) && currentValues.length > 0) {
|
|
528
|
+
const TargetClass = meta.target?.();
|
|
529
|
+
if (TargetClass) {
|
|
530
|
+
const filtered = [];
|
|
531
|
+
for (const targetId of currentValues) {
|
|
532
|
+
try {
|
|
533
|
+
const inst = new TargetClass(perspective, targetId);
|
|
534
|
+
await inst.get();
|
|
535
|
+
let matches = true;
|
|
536
|
+
for (const [prop, expected] of Object.entries(meta.where)) {
|
|
537
|
+
if (inst[prop] !== expected) {
|
|
538
|
+
matches = false;
|
|
539
|
+
break;
|
|
540
|
+
}
|
|
541
|
+
}
|
|
542
|
+
if (matches)
|
|
543
|
+
filtered.push(targetId);
|
|
544
|
+
}
|
|
545
|
+
catch {
|
|
546
|
+
// If we can't hydrate, keep the value (conservative)
|
|
547
|
+
filtered.push(targetId);
|
|
548
|
+
}
|
|
549
|
+
}
|
|
550
|
+
instance[relName] = filtered;
|
|
551
|
+
}
|
|
552
|
+
}
|
|
478
553
|
}
|
|
479
554
|
}
|
|
480
555
|
/**
|
|
@@ -494,7 +569,166 @@ export async function hydrateRelations(modelClass, instances, perspective, inclu
|
|
|
494
569
|
if (!includeMap || Object.keys(includeMap).length === 0)
|
|
495
570
|
return;
|
|
496
571
|
const relMeta = getRelationsMetadata(modelClass);
|
|
572
|
+
// ── Projections ($-prefixed keys) ────────────────────────────────────────
|
|
573
|
+
// Collect all projection entries up-front so we can batch the count queries
|
|
574
|
+
// together per-projection before processing. Each projection key starts
|
|
575
|
+
// with '$' and has a descriptor with a `from` field.
|
|
576
|
+
const projectionEntries = [];
|
|
577
|
+
for (const [key, val] of Object.entries(includeMap)) {
|
|
578
|
+
if (key.startsWith('$') && val !== null && typeof val === 'object' && 'from' in val) {
|
|
579
|
+
projectionEntries.push([key, val]);
|
|
580
|
+
}
|
|
581
|
+
}
|
|
582
|
+
for (const [projKey, proj] of projectionEntries) {
|
|
583
|
+
const sourceMeta = relMeta[proj.from];
|
|
584
|
+
if (!sourceMeta) {
|
|
585
|
+
console.warn(`include projection "${projKey}": relation "${proj.from}" not found in metadata, skipping`);
|
|
586
|
+
for (const inst of instances)
|
|
587
|
+
inst[projKey] = proj.count ? 0 : [];
|
|
588
|
+
continue;
|
|
589
|
+
}
|
|
590
|
+
const TargetClass = sourceMeta.target();
|
|
591
|
+
const allParentIds = instances.map(inst => inst.id).filter(Boolean);
|
|
592
|
+
if (proj.count) {
|
|
593
|
+
// ── Path A: grouped SPARQL COUNT ─────────────────────────────────────
|
|
594
|
+
// One round-trip, zero instance hydration. Returns one row per parent.
|
|
595
|
+
const targetMetadata = TargetClass.getModelMetadata?.() ?? null;
|
|
596
|
+
const targetRelMeta = TargetClass.getAllRelationsMetadata?.() ?? {};
|
|
597
|
+
let countMap = new Map();
|
|
598
|
+
if (targetMetadata && allParentIds.length > 0) {
|
|
599
|
+
try {
|
|
600
|
+
const sparql = buildSPARQLGroupedCountQuery(targetMetadata, targetRelMeta, sourceMeta.predicate, allParentIds, proj.where);
|
|
601
|
+
const raw = await perspective.querySparql(sparql);
|
|
602
|
+
const rows = Array.isArray(raw) ? raw
|
|
603
|
+
: raw?.results?.bindings ?? raw?.bindings ?? [];
|
|
604
|
+
countMap = parseSparqlGroupedCount(rows);
|
|
605
|
+
}
|
|
606
|
+
catch (e) {
|
|
607
|
+
console.warn(`include projection "${projKey}" count query failed, falling back to 0:`, e);
|
|
608
|
+
}
|
|
609
|
+
}
|
|
610
|
+
for (const inst of instances) {
|
|
611
|
+
inst[projKey] = countMap.get(inst.id) ?? 0;
|
|
612
|
+
}
|
|
613
|
+
}
|
|
614
|
+
else {
|
|
615
|
+
// ── Path B: findAll + Map distribution ───────────────────────────────
|
|
616
|
+
// For reverse relations we don't have the child IDs on the instance,
|
|
617
|
+
// so fall back to a parent-scoped findAll per instance (uncommon path).
|
|
618
|
+
const isReverse = sourceMeta.kind === 'belongsToOne' || sourceMeta.kind === 'belongsToMany';
|
|
619
|
+
if (isReverse) {
|
|
620
|
+
// Reverse: the link goes child→parent, reuse the batched SPARQL pattern
|
|
621
|
+
// from the existing belongsTo path to collect source IDs per parent.
|
|
622
|
+
if (allParentIds.length > 0) {
|
|
623
|
+
const sparqlQuery = `SELECT ?source ?target WHERE {
|
|
624
|
+
GRAPH ?g { ?source <${sourceMeta.predicate}> ?target }
|
|
625
|
+
FILTER(?target IN (${allParentIds.map(id => `<${id}>`).join(', ')}))
|
|
626
|
+
}`;
|
|
627
|
+
const sourcesByTarget = new Map();
|
|
628
|
+
try {
|
|
629
|
+
const raw = await perspective.querySparql(sparqlQuery);
|
|
630
|
+
const bindings = Array.isArray(raw) ? raw : raw?.results?.bindings ?? raw?.bindings ?? [];
|
|
631
|
+
for (const row of bindings) {
|
|
632
|
+
const source = row.source?.value ?? row.source;
|
|
633
|
+
const target = row.target?.value ?? row.target;
|
|
634
|
+
if (!source || !target)
|
|
635
|
+
continue;
|
|
636
|
+
if (!sourcesByTarget.has(target))
|
|
637
|
+
sourcesByTarget.set(target, []);
|
|
638
|
+
sourcesByTarget.get(target).push(source);
|
|
639
|
+
}
|
|
640
|
+
}
|
|
641
|
+
catch (e) {
|
|
642
|
+
console.warn(`include projection "${projKey}" reverse SPARQL failed:`, e);
|
|
643
|
+
}
|
|
644
|
+
const allSourceIds = new Set();
|
|
645
|
+
for (const ids of sourcesByTarget.values())
|
|
646
|
+
for (const id of ids)
|
|
647
|
+
allSourceIds.add(id);
|
|
648
|
+
const hydratedMap = new Map();
|
|
649
|
+
if (allSourceIds.size > 0) {
|
|
650
|
+
const results = await TargetClass.findAll(perspective, {
|
|
651
|
+
where: { id: Array.from(allSourceIds), ...(proj.where ?? {}) },
|
|
652
|
+
});
|
|
653
|
+
for (const r of results)
|
|
654
|
+
hydratedMap.set(r.id, r);
|
|
655
|
+
}
|
|
656
|
+
for (const inst of instances) {
|
|
657
|
+
const sourceIds = sourcesByTarget.get(inst.id) ?? [];
|
|
658
|
+
let resolved = sourceIds.map(id => hydratedMap.get(id)).filter((v) => v != null);
|
|
659
|
+
if (proj.limit != null) {
|
|
660
|
+
if (proj.limit === 1) {
|
|
661
|
+
inst[projKey] = resolved[0] ?? null;
|
|
662
|
+
}
|
|
663
|
+
else {
|
|
664
|
+
inst[projKey] = resolved.slice(0, proj.limit);
|
|
665
|
+
}
|
|
666
|
+
}
|
|
667
|
+
else {
|
|
668
|
+
inst[projKey] = resolved;
|
|
669
|
+
}
|
|
670
|
+
}
|
|
671
|
+
}
|
|
672
|
+
else {
|
|
673
|
+
for (const inst of instances)
|
|
674
|
+
inst[projKey] = proj.limit === 1 ? null : [];
|
|
675
|
+
}
|
|
676
|
+
}
|
|
677
|
+
else {
|
|
678
|
+
// Forward: instance[from] holds raw child URIs — collect across all parents
|
|
679
|
+
const uriSet = new Set();
|
|
680
|
+
const rawCache = new Map();
|
|
681
|
+
for (const inst of instances) {
|
|
682
|
+
const raw = inst[proj.from];
|
|
683
|
+
const uris = [];
|
|
684
|
+
if (Array.isArray(raw)) {
|
|
685
|
+
for (const v of raw) {
|
|
686
|
+
const id = typeof v === 'string' ? v : v?.id;
|
|
687
|
+
if (id) {
|
|
688
|
+
uriSet.add(id);
|
|
689
|
+
uris.push(id);
|
|
690
|
+
}
|
|
691
|
+
}
|
|
692
|
+
}
|
|
693
|
+
else if (typeof raw === 'string') {
|
|
694
|
+
uriSet.add(raw);
|
|
695
|
+
uris.push(raw);
|
|
696
|
+
}
|
|
697
|
+
else if (raw?.id) {
|
|
698
|
+
uriSet.add(raw.id);
|
|
699
|
+
uris.push(raw.id);
|
|
700
|
+
}
|
|
701
|
+
rawCache.set(inst, uris);
|
|
702
|
+
}
|
|
703
|
+
const hydratedMap = new Map();
|
|
704
|
+
if (uriSet.size > 0) {
|
|
705
|
+
const results = await TargetClass.findAll(perspective, {
|
|
706
|
+
where: { id: Array.from(uriSet), ...(proj.where ?? {}) },
|
|
707
|
+
});
|
|
708
|
+
for (const r of results)
|
|
709
|
+
hydratedMap.set(r.id, r);
|
|
710
|
+
}
|
|
711
|
+
for (const inst of instances) {
|
|
712
|
+
const uris = rawCache.get(inst) ?? [];
|
|
713
|
+
const resolved = uris.map(id => hydratedMap.get(id)).filter((v) => v != null);
|
|
714
|
+
if (proj.limit === 1) {
|
|
715
|
+
inst[projKey] = resolved[0] ?? null;
|
|
716
|
+
}
|
|
717
|
+
else if (proj.limit != null) {
|
|
718
|
+
inst[projKey] = resolved.slice(0, proj.limit);
|
|
719
|
+
}
|
|
720
|
+
else {
|
|
721
|
+
inst[projKey] = resolved;
|
|
722
|
+
}
|
|
723
|
+
}
|
|
724
|
+
}
|
|
725
|
+
}
|
|
726
|
+
}
|
|
727
|
+
// ── Standard relations (non-projected) ───────────────────────────────────
|
|
497
728
|
for (const [relName, includeValue] of Object.entries(includeMap)) {
|
|
729
|
+
// Skip projection keys — already handled above
|
|
730
|
+
if (relName.startsWith('$') && typeof includeValue === 'object' && includeValue !== null && 'from' in includeValue)
|
|
731
|
+
continue;
|
|
498
732
|
const meta = relMeta[relName];
|
|
499
733
|
if (!meta) {
|
|
500
734
|
console.warn(`include: relation "${relName}" not found in metadata, skipping`);
|
|
@@ -509,57 +743,102 @@ export async function hydrateRelations(modelClass, instances, perspective, inclu
|
|
|
509
743
|
// ── Reverse relations (belongsToOne / belongsToMany) ──────────────────
|
|
510
744
|
// The link goes target→instance, so we query backwards:
|
|
511
745
|
// predicate = meta.predicate, target = inst.id → source is the related id
|
|
746
|
+
//
|
|
747
|
+
// PERF: Batch all reverse lookups into a single SPARQL query instead of
|
|
748
|
+
// N sequential perspective.get() calls (N+1 → 1 optimisation).
|
|
512
749
|
if (meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany') {
|
|
513
|
-
|
|
750
|
+
const allIds = instances.map(inst => inst.id).filter(Boolean);
|
|
751
|
+
// Batch query: find all (source, target) pairs for this predicate
|
|
752
|
+
// where target is one of our instance IDs
|
|
753
|
+
const sourcesByTarget = new Map();
|
|
754
|
+
if (allIds.length > 0) {
|
|
755
|
+
const sparqlQuery = `SELECT ?source ?target WHERE {
|
|
756
|
+
GRAPH ?g { ?source <${meta.predicate}> ?target }
|
|
757
|
+
FILTER(?target IN (${allIds.map(id => `<${id}>`).join(', ')}))
|
|
758
|
+
}`;
|
|
759
|
+
try {
|
|
760
|
+
const sparqlResult = await perspective.querySparql(sparqlQuery);
|
|
761
|
+
// Parse SPARQL results — querySparql returns a flat array of row objects
|
|
762
|
+
// e.g. [{ source: "uri1", target: "uri2" }, ...]
|
|
763
|
+
const bindings = Array.isArray(sparqlResult) ? sparqlResult
|
|
764
|
+
: sparqlResult?.results?.bindings ?? sparqlResult?.bindings ?? [];
|
|
765
|
+
for (const row of bindings) {
|
|
766
|
+
const source = row.source?.value ?? row.source;
|
|
767
|
+
const target = row.target?.value ?? row.target;
|
|
768
|
+
if (!source || !target)
|
|
769
|
+
continue;
|
|
770
|
+
if (!sourcesByTarget.has(target))
|
|
771
|
+
sourcesByTarget.set(target, []);
|
|
772
|
+
sourcesByTarget.get(target).push(source);
|
|
773
|
+
}
|
|
774
|
+
}
|
|
775
|
+
catch (e) {
|
|
776
|
+
// Fallback: sequential queries if SPARQL fails
|
|
777
|
+
console.warn('Batched reverse relation SPARQL failed, falling back to sequential:', e);
|
|
778
|
+
for (const inst of instances) {
|
|
779
|
+
const reverseLinks = await perspective.get(new LinkQuery({ predicate: meta.predicate, target: inst.id }));
|
|
780
|
+
const sourceIds = reverseLinks
|
|
781
|
+
.filter(l => l.data.target === inst.id)
|
|
782
|
+
.map(l => l.data.source);
|
|
783
|
+
if (sourceIds.length > 0) {
|
|
784
|
+
sourcesByTarget.set(inst.id, sourceIds);
|
|
785
|
+
}
|
|
786
|
+
}
|
|
787
|
+
}
|
|
788
|
+
}
|
|
789
|
+
// Collect ALL source IDs across all instances for batch hydration
|
|
790
|
+
const allSourceIds = new Set();
|
|
791
|
+
for (const ids of sourcesByTarget.values()) {
|
|
792
|
+
for (const id of ids)
|
|
793
|
+
allSourceIds.add(id);
|
|
794
|
+
}
|
|
795
|
+
// Batch-hydrate all related instances at once (1 findAll instead of N)
|
|
796
|
+
const hydratedMap = new Map();
|
|
797
|
+
if (allSourceIds.size > 0) {
|
|
798
|
+
const fetchQuery = {
|
|
799
|
+
where: {
|
|
800
|
+
id: Array.from(allSourceIds),
|
|
801
|
+
...(subQuery?.where ?? {}),
|
|
802
|
+
},
|
|
803
|
+
...(subQuery?.order && { order: subQuery.order }),
|
|
804
|
+
...(subQuery?.properties && { properties: subQuery.properties }),
|
|
805
|
+
};
|
|
806
|
+
try {
|
|
807
|
+
const allResults = await TargetClass.findAll(perspective, fetchQuery);
|
|
808
|
+
for (const r of allResults)
|
|
809
|
+
hydratedMap.set(r.id, r);
|
|
810
|
+
}
|
|
811
|
+
catch {
|
|
812
|
+
// Fallback: hydrate individually
|
|
813
|
+
await Promise.all(Array.from(allSourceIds).map(async (sid) => {
|
|
814
|
+
try {
|
|
815
|
+
const related = new TargetClass(perspective, sid);
|
|
816
|
+
await related.get(subQuery?.properties ? { properties: subQuery.properties } : undefined);
|
|
817
|
+
hydratedMap.set(sid, related);
|
|
818
|
+
}
|
|
819
|
+
catch { /* skip */ }
|
|
820
|
+
}));
|
|
821
|
+
}
|
|
822
|
+
}
|
|
823
|
+
// Assign hydrated instances to each parent
|
|
514
824
|
for (const inst of instances) {
|
|
515
|
-
const
|
|
516
|
-
|
|
517
|
-
// we only use links that genuinely point to this instance.
|
|
518
|
-
const sourceIds = reverseLinks
|
|
519
|
-
.filter(l => l.data.target === inst.id)
|
|
520
|
-
.map(l => l.data.source);
|
|
825
|
+
const instId = inst.id;
|
|
826
|
+
const sourceIds = sourcesByTarget.get(instId) ?? [];
|
|
521
827
|
if (meta.kind === 'belongsToOne') {
|
|
522
828
|
if (sourceIds.length === 0) {
|
|
523
829
|
inst[relName] = null;
|
|
524
830
|
continue;
|
|
525
831
|
}
|
|
526
832
|
const sourceId = sourceIds[sourceIds.length - 1]; // latest-wins
|
|
527
|
-
|
|
528
|
-
const related = new TargetClass(perspective, sourceId);
|
|
529
|
-
await related.get();
|
|
530
|
-
inst[relName] = related;
|
|
531
|
-
}
|
|
532
|
-
catch {
|
|
533
|
-
inst[relName] = null;
|
|
534
|
-
}
|
|
833
|
+
inst[relName] = hydratedMap.get(sourceId) ?? null;
|
|
535
834
|
}
|
|
536
835
|
else {
|
|
537
836
|
// belongsToMany — return array of hydrated instances
|
|
538
|
-
let hydrated =
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
...(subQuery.where ?? {}),
|
|
544
|
-
};
|
|
545
|
-
hydrated = await TargetClass.findAll(perspective, {
|
|
546
|
-
where: whereWithIds,
|
|
547
|
-
...(subQuery.order && { order: subQuery.order }),
|
|
548
|
-
...(subQuery.properties && { properties: subQuery.properties }),
|
|
549
|
-
});
|
|
550
|
-
}
|
|
551
|
-
else {
|
|
552
|
-
await Promise.all(sourceIds.map(async (sid) => {
|
|
553
|
-
try {
|
|
554
|
-
const related = new TargetClass(perspective, sid);
|
|
555
|
-
await related.get(subQuery?.properties ? { properties: subQuery.properties } : undefined);
|
|
556
|
-
hydrated.push(related);
|
|
557
|
-
}
|
|
558
|
-
catch { /* skip */ }
|
|
559
|
-
}));
|
|
560
|
-
}
|
|
561
|
-
// Apply order (client-side, if not already handled by findAll above)
|
|
562
|
-
if (subQuery?.order && !(subQuery.where || subQuery.properties)) {
|
|
837
|
+
let hydrated = sourceIds
|
|
838
|
+
.map(sid => hydratedMap.get(sid))
|
|
839
|
+
.filter((v) => v != null);
|
|
840
|
+
// Apply order (client-side)
|
|
841
|
+
if (subQuery?.order) {
|
|
563
842
|
const orderEntries = Object.entries(subQuery.order);
|
|
564
843
|
hydrated = hydrated.sort((a, b) => {
|
|
565
844
|
for (const [field, dir] of orderEntries) {
|
package/lib/src/model/index.d.ts
CHANGED
|
@@ -13,8 +13,11 @@ export * from "./query-common";
|
|
|
13
13
|
export * from "./query-prolog";
|
|
14
14
|
export * from "./prolog-facts";
|
|
15
15
|
export * from "./json-schema";
|
|
16
|
-
export * from "./query-
|
|
16
|
+
export * from "./query-utils";
|
|
17
|
+
export * from "./query-sparql";
|
|
17
18
|
export * from "./hydration";
|
|
18
19
|
export * from "./ModelQueryBuilder";
|
|
19
20
|
export * from "./sdna";
|
|
20
21
|
export * from "./shacl-gen";
|
|
22
|
+
export * from "./query-cache";
|
|
23
|
+
export * from "./subscription-pool";
|
package/lib/src/model/index.js
CHANGED
|
@@ -13,8 +13,11 @@ export * from "./query-common";
|
|
|
13
13
|
export * from "./query-prolog";
|
|
14
14
|
export * from "./prolog-facts";
|
|
15
15
|
export * from "./json-schema";
|
|
16
|
-
export * from "./query-
|
|
16
|
+
export * from "./query-utils";
|
|
17
|
+
export * from "./query-sparql";
|
|
17
18
|
export * from "./hydration";
|
|
18
19
|
export * from "./ModelQueryBuilder";
|
|
19
20
|
export * from "./sdna";
|
|
20
21
|
export * from "./shacl-gen";
|
|
22
|
+
export * from "./query-cache";
|
|
23
|
+
export * from "./subscription-pool";
|
|
@@ -263,14 +263,14 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
|
|
|
263
263
|
}
|
|
264
264
|
// Default resolveLanguage to 'literal' for all remaining property types,
|
|
265
265
|
// matching the @Property decorator behaviour. Without this, string values
|
|
266
|
-
// stored as literal
|
|
266
|
+
// stored as literal: URLs are returned unparsed.
|
|
267
267
|
if (resolveLanguage === undefined || resolveLanguage === null) {
|
|
268
268
|
resolveLanguage = 'literal';
|
|
269
269
|
}
|
|
270
270
|
// If property is required, ensure it has an initial value
|
|
271
271
|
if (isRequired && !initial) {
|
|
272
272
|
if (isObjectType(propertySchema)) {
|
|
273
|
-
initial = 'literal
|
|
273
|
+
initial = 'literal:json:{}';
|
|
274
274
|
}
|
|
275
275
|
else {
|
|
276
276
|
initial = "ad4m://undefined";
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Query Result TTL Cache
|
|
3
|
+
*
|
|
4
|
+
* Short-lived cache (200ms TTL) for SPARQL query results.
|
|
5
|
+
* Prevents redundant queries during rapid render cycles where
|
|
6
|
+
* multiple components issue the same query within milliseconds.
|
|
7
|
+
*
|
|
8
|
+
* Key: `perspectiveUUID + queryText`
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Get a cached query result if it exists and hasn't expired.
|
|
12
|
+
*/
|
|
13
|
+
export declare function getCachedResult(perspectiveUUID: string, queryText: string): any | undefined;
|
|
14
|
+
/**
|
|
15
|
+
* Store a query result in the cache with TTL.
|
|
16
|
+
*/
|
|
17
|
+
export declare function setCachedResult(perspectiveUUID: string, queryText: string, result: any, ttlMs?: number): void;
|
|
18
|
+
/**
|
|
19
|
+
* Invalidate all cache entries for a given perspective.
|
|
20
|
+
* Called after write operations to ensure stale data isn't served.
|
|
21
|
+
*/
|
|
22
|
+
export declare function invalidatePerspectiveCache(perspectiveUUID: string): void;
|
|
23
|
+
/**
|
|
24
|
+
* Clear all cache entries (useful for testing).
|
|
25
|
+
*/
|
|
26
|
+
export declare function clearQueryCache(): void;
|
|
27
|
+
/**
|
|
28
|
+
* Get the current size of the cache (useful for testing).
|
|
29
|
+
*/
|
|
30
|
+
export declare function queryCacheSize(): number;
|