@coasys/ad4m 0.13.0-test-interpretation → 0.13.0-test-interpretation-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 +451 -149
- package/lib/index.js +449 -150
- package/lib/src/Literal.js +8 -0
- package/lib/src/generated/api/RunInterpretationRequest.d.ts +16 -0
- package/lib/src/model/Ad4mModel.d.ts +28 -11
- package/lib/src/model/Ad4mModel.js +57 -35
- package/lib/src/model/ModelQueryBuilder.js +2 -2
- package/lib/src/model/decorators.d.ts +52 -8
- package/lib/src/model/decorators.js +18 -8
- package/lib/src/model/json-schema.js +7 -21
- package/lib/src/model/query-common.d.ts +2 -2
- package/lib/src/model/query-sparql.d.ts +62 -0
- package/lib/src/model/query-sparql.js +78 -15
- package/lib/src/model/query-utils.d.ts +7 -2
- package/lib/src/model/query-utils.js +21 -11
- package/lib/src/model/shacl-gen.js +44 -15
- package/lib/src/model/types.d.ts +23 -8
- package/lib/src/perspectives/AutoProcessor.d.ts +132 -2
- package/lib/src/perspectives/InterpretationModels.d.ts +51 -3
- package/lib/src/perspectives/InterpretationModels.js +64 -26
- package/lib/src/perspectives/PerspectiveClient.d.ts +22 -2
- package/lib/src/perspectives/PerspectiveClient.js +35 -3
- package/lib/src/perspectives/PerspectiveProxy.d.ts +9 -1
- package/lib/src/perspectives/PerspectiveProxy.js +24 -14
- package/lib/src/perspectives/SparqlBindings.d.ts +24 -3
- package/lib/src/perspectives/SparqlBindings.js +57 -6
- package/lib/src/shacl/SHACLShape.d.ts +11 -3
- package/lib/src/shacl/SHACLShape.js +15 -1
- package/lib/src/shacl/index.d.ts +1 -1
- package/lib/src/shacl/index.js +1 -1
- package/package.json +2 -2
- package/src/Literal.ts +7 -0
- package/src/generated/api/RunInterpretationRequest.ts +19 -3
- package/src/model/Ad4mModel.test.ts +84 -22
- package/src/model/Ad4mModel.ts +61 -41
- package/src/model/ModelQueryBuilder.ts +2 -2
- package/src/model/decorators.ts +62 -9
- package/src/model/json-schema.ts +10 -25
- package/src/model/query-common.ts +2 -2
- package/src/model/query-sparql.test.ts +114 -13
- package/src/model/query-sparql.ts +83 -14
- package/src/model/query-utils.ts +22 -12
- package/src/model/shacl-gen.ts +42 -13
- package/src/model/shacl-roundtrip.test.ts +4 -2
- package/src/model/types.ts +23 -8
- package/src/perspectives/AutoProcessor.ts +133 -1
- package/src/perspectives/InterpretationModels.ts +103 -21
- package/src/perspectives/PerspectiveClient.ts +50 -4
- package/src/perspectives/PerspectiveProxy.ts +37 -21
- package/src/perspectives/SparqlBindings.test.ts +134 -0
- package/src/perspectives/SparqlBindings.ts +57 -6
- package/src/shacl/SHACLShape.test.ts +56 -4
- package/src/shacl/SHACLShape.ts +30 -6
- package/src/shacl/index.ts +1 -1
package/src/model/json-schema.ts
CHANGED
|
@@ -325,13 +325,7 @@ export function buildModelFromJSONSchema(
|
|
|
325
325
|
|
|
326
326
|
} else {
|
|
327
327
|
// Handle regular properties
|
|
328
|
-
let resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
|
|
329
|
-
// If no specific resolveLanguage for this property, use the global one
|
|
330
|
-
if (!resolveLanguage && options.resolveLanguage) {
|
|
331
|
-
resolveLanguage = options.resolveLanguage;
|
|
332
|
-
}
|
|
333
328
|
const local = getPropertyOption(propertyName, propertySchema, options, 'local');
|
|
334
|
-
// Determine readOnly: check PropertyOptions first, then x-ad4m.writable (inverted) for JSON Schema wire format
|
|
335
329
|
let readOnly = getPropertyOption(propertyName, propertySchema, options, 'readOnly');
|
|
336
330
|
if (readOnly === undefined) {
|
|
337
331
|
const xWritable = propertySchema["x-ad4m"]?.writable;
|
|
@@ -339,26 +333,17 @@ export function buildModelFromJSONSchema(
|
|
|
339
333
|
}
|
|
340
334
|
const writable = !readOnly;
|
|
341
335
|
let initial = getPropertyOption(propertyName, propertySchema, options, 'initial');
|
|
342
|
-
|
|
343
|
-
// Handle nested objects by serializing to JSON
|
|
344
|
-
if (isObjectType(propertySchema) && !resolveLanguage) {
|
|
345
|
-
resolveLanguage = 'literal';
|
|
346
|
-
console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
|
|
347
|
-
}
|
|
348
336
|
|
|
349
|
-
//
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
337
|
+
// Not defaulted — absence means "deterministic typed literal" (the
|
|
338
|
+
// perf default); an explicit `resolveLanguage: "literal"` selects the
|
|
339
|
+
// signed-envelope path; any other value selects a custom language.
|
|
340
|
+
// See effectiveLiteralStorage().
|
|
341
|
+
const resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
|
|
353
342
|
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
// stored as literal: URLs are returned unparsed.
|
|
357
|
-
if (resolveLanguage === undefined || resolveLanguage === null) {
|
|
358
|
-
resolveLanguage = 'literal';
|
|
343
|
+
if (isObjectType(propertySchema)) {
|
|
344
|
+
console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
|
|
359
345
|
}
|
|
360
|
-
|
|
361
|
-
// If property is required, ensure it has an initial value
|
|
346
|
+
|
|
362
347
|
if (isRequired && !initial) {
|
|
363
348
|
if (isObjectType(propertySchema)) {
|
|
364
349
|
initial = 'literal:json:{}';
|
|
@@ -366,12 +351,12 @@ export function buildModelFromJSONSchema(
|
|
|
366
351
|
initial = "ad4m://undefined";
|
|
367
352
|
}
|
|
368
353
|
}
|
|
369
|
-
|
|
354
|
+
|
|
370
355
|
properties[propertyName] = {
|
|
371
356
|
through: predicate,
|
|
372
357
|
required: isRequired,
|
|
373
358
|
writable: writable,
|
|
374
|
-
...(resolveLanguage && { resolveLanguage }),
|
|
359
|
+
...(resolveLanguage !== undefined && { resolveLanguage }),
|
|
375
360
|
...(local !== undefined && { local }),
|
|
376
361
|
...(initial && { initial })
|
|
377
362
|
};
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Shared query helpers used by both the Prolog and SPARQL query pipelines.
|
|
3
3
|
*/
|
|
4
4
|
|
|
5
|
-
import type {
|
|
5
|
+
import type { Scope } from "./types";
|
|
6
6
|
import { getRelationsMetadata } from "./decorators";
|
|
7
7
|
|
|
8
8
|
/**
|
|
@@ -15,7 +15,7 @@ import { getRelationsMetadata } from "./decorators";
|
|
|
15
15
|
* - Without `field`: scan for a relation whose `target()` matches `childCtor`
|
|
16
16
|
*/
|
|
17
17
|
export function resolveParentPredicate(
|
|
18
|
-
parent:
|
|
18
|
+
parent: Scope,
|
|
19
19
|
childCtor: Function,
|
|
20
20
|
): string {
|
|
21
21
|
// Raw form — explicit predicate
|
|
@@ -1,28 +1,29 @@
|
|
|
1
|
-
import { buildSPARQLQuery, buildPaginationSubquery, hasJsOnlyWhereFilters } from './query-sparql';
|
|
1
|
+
import { buildSPARQLQuery, buildPaginationSubquery, hasJsOnlyWhereFilters, looksLikeUri, valueToLiteralIri } from './query-sparql';
|
|
2
|
+
import { Literal } from '../Literal';
|
|
2
3
|
|
|
3
4
|
// Minimal stubs for ModelMetadata
|
|
4
5
|
const emptyMetadata: any = { properties: {}, relations: {} };
|
|
5
6
|
|
|
6
|
-
// Metadata with a
|
|
7
|
+
// Metadata with a deterministic-literal property (`name`), a signed-envelope
|
|
8
|
+
// property (`category`, `resolveLanguage: "literal"`), and another
|
|
9
|
+
// deterministic-literal property with an initial value (`description`).
|
|
7
10
|
const richMetadata: any = {
|
|
8
11
|
properties: {
|
|
9
12
|
name: {
|
|
10
13
|
name: 'name',
|
|
11
14
|
predicate: 'flux://name',
|
|
12
15
|
required: true,
|
|
13
|
-
resolveLanguage: 'literal',
|
|
14
16
|
},
|
|
15
17
|
category: {
|
|
16
18
|
name: 'category',
|
|
17
19
|
predicate: 'flux://category',
|
|
18
20
|
required: true,
|
|
19
|
-
resolveLanguage: '
|
|
21
|
+
resolveLanguage: 'literal', // envelope → expression URI stored
|
|
20
22
|
},
|
|
21
23
|
description: {
|
|
22
24
|
name: 'description',
|
|
23
25
|
predicate: 'flux://description',
|
|
24
26
|
initial: 'literal://string:empty',
|
|
25
|
-
resolveLanguage: 'literal',
|
|
26
27
|
},
|
|
27
28
|
},
|
|
28
29
|
relations: {},
|
|
@@ -41,7 +42,7 @@ describe('hasJsOnlyWhereFilters', () => {
|
|
|
41
42
|
|
|
42
43
|
it('returns true when where has literal-stored property with comparison operator', () => {
|
|
43
44
|
// gt/lt/gte/lte/between/contains remain JS-only
|
|
44
|
-
const meta: any = { properties: { rating: { name: 'rating', predicate: 'flux://rating', required: true
|
|
45
|
+
const meta: any = { properties: { rating: { name: 'rating', predicate: 'flux://rating', required: true } }, relations: {} };
|
|
45
46
|
expect(hasJsOnlyWhereFilters(meta, emptyRelations, { rating: { gt: 5 } })).toBe(true);
|
|
46
47
|
});
|
|
47
48
|
|
|
@@ -113,7 +114,7 @@ describe('buildSPARQLQuery — parse_literal push-down filters', () => {
|
|
|
113
114
|
it('does NOT use parse_literal for comparison operators (gt/lt)', () => {
|
|
114
115
|
const meta: any = {
|
|
115
116
|
properties: {
|
|
116
|
-
rating: { name: 'rating', predicate: 'flux://rating', required: true
|
|
117
|
+
rating: { name: 'rating', predicate: 'flux://rating', required: true },
|
|
117
118
|
},
|
|
118
119
|
relations: {},
|
|
119
120
|
};
|
|
@@ -204,8 +205,8 @@ describe('buildSPARQLQuery — mixed push-down + JS-only', () => {
|
|
|
204
205
|
const modelClass: any = {};
|
|
205
206
|
const mixedMeta: any = {
|
|
206
207
|
properties: {
|
|
207
|
-
name: { name: 'name', predicate: 'flux://name', required: true
|
|
208
|
-
rating: { name: 'rating', predicate: 'flux://rating', required: true
|
|
208
|
+
name: { name: 'name', predicate: 'flux://name', required: true },
|
|
209
|
+
rating: { name: 'rating', predicate: 'flux://rating', required: true },
|
|
209
210
|
},
|
|
210
211
|
relations: {},
|
|
211
212
|
};
|
|
@@ -224,10 +225,14 @@ describe('buildSPARQLQuery — mixed push-down + JS-only', () => {
|
|
|
224
225
|
describe('buildSPARQLQuery — non-literal and flag properties', () => {
|
|
225
226
|
const modelClass: any = {};
|
|
226
227
|
|
|
227
|
-
it('does NOT use parse_literal for
|
|
228
|
+
it('does NOT use parse_literal for envelope (resolveLanguage: "literal") properties', () => {
|
|
229
|
+
// Envelope properties store signed expression URIs in the target position,
|
|
230
|
+
// not raw literals — the value comparison happens on the unwrapped inner
|
|
231
|
+
// data via a different code path (Rust `parse_literal_fn`), not by the JS
|
|
232
|
+
// WHERE builder emitting a `<ad4m://fn/parse_literal>` filter here.
|
|
228
233
|
const meta: any = {
|
|
229
234
|
properties: {
|
|
230
|
-
avatar: { name: 'avatar', predicate: 'flux://avatar', required: true, resolveLanguage: '
|
|
235
|
+
avatar: { name: 'avatar', predicate: 'flux://avatar', required: true, resolveLanguage: 'literal' },
|
|
231
236
|
},
|
|
232
237
|
relations: {},
|
|
233
238
|
};
|
|
@@ -312,7 +317,7 @@ describe('SPARQL-level pagination', () => {
|
|
|
312
317
|
it('does NOT push pagination to SPARQL when JS-only where filters exist (gt operator)', () => {
|
|
313
318
|
const meta: any = {
|
|
314
319
|
properties: {
|
|
315
|
-
rating: { name: 'rating', predicate: 'flux://rating', required: true
|
|
320
|
+
rating: { name: 'rating', predicate: 'flux://rating', required: true },
|
|
316
321
|
},
|
|
317
322
|
relations: {},
|
|
318
323
|
};
|
|
@@ -340,7 +345,7 @@ describe('buildSPARQLQuery — set-difference patterns', () => {
|
|
|
340
345
|
it('generates global EXISTS without parent scoping when no parent filter', () => {
|
|
341
346
|
const meta: any = {
|
|
342
347
|
properties: {
|
|
343
|
-
status: { name: 'status', predicate: 'flux://status', required: true
|
|
348
|
+
status: { name: 'status', predicate: 'flux://status', required: true },
|
|
344
349
|
},
|
|
345
350
|
relations: {},
|
|
346
351
|
};
|
|
@@ -522,3 +527,99 @@ describe('buildSPARQLQuery — OR/AND/NOT not emitted as SPARQL (handled Rust-si
|
|
|
522
527
|
expect(sparql).not.toContain('LIMIT');
|
|
523
528
|
});
|
|
524
529
|
});
|
|
530
|
+
|
|
531
|
+
// ──────────────────────────────────────────────────────────
|
|
532
|
+
// valueToLiteralIri — object/array encoding parity with Rust
|
|
533
|
+
// ──────────────────────────────────────────────────────────
|
|
534
|
+
|
|
535
|
+
describe('valueToLiteralIri', () => {
|
|
536
|
+
it('encodes plain objects as literal:json:* and round-trips', () => {
|
|
537
|
+
const url = valueToLiteralIri({ a: 1 });
|
|
538
|
+
expect(url.startsWith('literal:json:')).toBe(true);
|
|
539
|
+
// Regression: previously fell through to String(value) → "[object Object]"
|
|
540
|
+
expect(url).not.toContain('object%20Object');
|
|
541
|
+
expect(Literal.fromUrl(url).get()).toEqual({ a: 1 });
|
|
542
|
+
});
|
|
543
|
+
|
|
544
|
+
it('encodes arrays as literal:json:* and round-trips', () => {
|
|
545
|
+
const url = valueToLiteralIri([1, 2, 3]);
|
|
546
|
+
expect(url.startsWith('literal:json:')).toBe(true);
|
|
547
|
+
// Regression: previously stringified to "1,2,3"
|
|
548
|
+
expect(url).not.toBe('literal:string:1%2C2%2C3');
|
|
549
|
+
expect(Literal.fromUrl(url).get()).toEqual([1, 2, 3]);
|
|
550
|
+
});
|
|
551
|
+
|
|
552
|
+
it('encodes nested objects and round-trips', () => {
|
|
553
|
+
const url = valueToLiteralIri({ nested: { b: 2 } });
|
|
554
|
+
expect(url.startsWith('literal:json:')).toBe(true);
|
|
555
|
+
expect(Literal.fromUrl(url).get()).toEqual({ nested: { b: 2 } });
|
|
556
|
+
});
|
|
557
|
+
|
|
558
|
+
it('preserves string encoding (non-URI)', () => {
|
|
559
|
+
const url = valueToLiteralIri('hello world');
|
|
560
|
+
expect(url).toBe('literal:string:hello%20world');
|
|
561
|
+
expect(Literal.fromUrl(url).get()).toBe('hello world');
|
|
562
|
+
});
|
|
563
|
+
|
|
564
|
+
it('returns URI-like strings unchanged', () => {
|
|
565
|
+
expect(valueToLiteralIri('https://example.com/thing')).toBe('https://example.com/thing');
|
|
566
|
+
});
|
|
567
|
+
|
|
568
|
+
it('encodes numbers as literal:number:*', () => {
|
|
569
|
+
const url = valueToLiteralIri(42);
|
|
570
|
+
expect(url).toBe('literal:number:42');
|
|
571
|
+
expect(Literal.fromUrl(url).get()).toBe(42);
|
|
572
|
+
});
|
|
573
|
+
|
|
574
|
+
it('encodes booleans as literal:boolean:*', () => {
|
|
575
|
+
const url = valueToLiteralIri(true);
|
|
576
|
+
expect(url).toBe('literal:boolean:true');
|
|
577
|
+
expect(Literal.fromUrl(url).get()).toBe(true);
|
|
578
|
+
});
|
|
579
|
+
|
|
580
|
+
it('encodes null via the String() fallthrough as literal:string:null', () => {
|
|
581
|
+
// `null` is `typeof 'object'` in JS, but `Literal.from(null).toUrl()`
|
|
582
|
+
// throws on the empty-literal check, so the `value !== null` guard
|
|
583
|
+
// deliberately keeps `null` on the historical fallthrough path.
|
|
584
|
+
const url = valueToLiteralIri(null);
|
|
585
|
+
expect(url).toBe('literal:string:null');
|
|
586
|
+
expect(Literal.fromUrl(url).get()).toBe('null');
|
|
587
|
+
});
|
|
588
|
+
});
|
|
589
|
+
|
|
590
|
+
|
|
591
|
+
// ---------------------------------------------------------------------------
|
|
592
|
+
// looksLikeUri — shared write-side predicate that MUST agree with the
|
|
593
|
+
// Rust-side `is_safe_iri_target` / `looks_like_absolute_iri`. See the
|
|
594
|
+
// doc comment on `looksLikeUri` for why drift produces silent no-match
|
|
595
|
+
// reads (PR #874).
|
|
596
|
+
// ---------------------------------------------------------------------------
|
|
597
|
+
describe('looksLikeUri', () => {
|
|
598
|
+
it('accepts well-formed absolute IRIs', () => {
|
|
599
|
+
expect(looksLikeUri('did:key:z6Mk123')).toBe(true);
|
|
600
|
+
expect(looksLikeUri('literal:string:hello')).toBe(true);
|
|
601
|
+
expect(looksLikeUri('http://example.com/foo')).toBe(true);
|
|
602
|
+
});
|
|
603
|
+
|
|
604
|
+
it('rejects scheme-lookalike prose that would fail Rust validate_iri', () => {
|
|
605
|
+
expect(looksLikeUri('Note: buy milk')).toBe(false);
|
|
606
|
+
expect(looksLikeUri('Re: standup')).toBe(false);
|
|
607
|
+
expect(looksLikeUri('TODO: fix this')).toBe(false);
|
|
608
|
+
});
|
|
609
|
+
|
|
610
|
+
it('rejects control chars, whitespace, and SPARQL-breaking chars', () => {
|
|
611
|
+
expect(looksLikeUri('tag:2025:new\nline')).toBe(false);
|
|
612
|
+
expect(looksLikeUri('tag:2025:tab\there')).toBe(false);
|
|
613
|
+
expect(looksLikeUri('http://example.com/foo bar')).toBe(false);
|
|
614
|
+
expect(looksLikeUri('foo:<bar>')).toBe(false);
|
|
615
|
+
expect(looksLikeUri('foo:{bar}')).toBe(false);
|
|
616
|
+
expect(looksLikeUri('foo:"quoted')).toBe(false);
|
|
617
|
+
});
|
|
618
|
+
|
|
619
|
+
it('rejects non-IRI shapes', () => {
|
|
620
|
+
expect(looksLikeUri('just plain text')).toBe(false);
|
|
621
|
+
expect(looksLikeUri('42')).toBe(false);
|
|
622
|
+
expect(looksLikeUri(':no-scheme')).toBe(false);
|
|
623
|
+
expect(looksLikeUri('1abc:foo')).toBe(false);
|
|
624
|
+
});
|
|
625
|
+
});
|
|
@@ -81,18 +81,53 @@ export function hasJsOnlyWhereFilters(
|
|
|
81
81
|
}
|
|
82
82
|
|
|
83
83
|
/**
|
|
84
|
-
* Check
|
|
84
|
+
* Check whether a string value is a well-formed absolute IRI that can be
|
|
85
|
+
* stored verbatim as a link target (raw `NamedNode`) instead of being
|
|
86
|
+
* wrapped in a `literal:string:*` URI.
|
|
87
|
+
*
|
|
88
|
+
* This mirrors the Rust `is_safe_iri_target` /
|
|
89
|
+
* `looks_like_absolute_iri` predicate in
|
|
90
|
+
* `rust-executor/src/perspectives/model_query/utils.rs` and is
|
|
91
|
+
* **load-bearing**: a value that returns `true` here MUST also be safely
|
|
92
|
+
* queryable on the Rust side (`validate_iri` gate on the SPARQL
|
|
93
|
+
* `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
|
|
94
|
+
* such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
|
|
95
|
+
* through the write regex, is stored as an invalid `NamedNode`, and
|
|
96
|
+
* becomes a silent no-match on read.
|
|
97
|
+
*
|
|
98
|
+
* Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
|
|
99
|
+
* same rejection set the Rust `validate_iri` applies: any Unicode
|
|
100
|
+
* whitespace, C0/C1 control chars, and the SPARQL-breaking characters
|
|
101
|
+
* `< > { } "`.
|
|
85
102
|
*/
|
|
86
|
-
function looksLikeUri(value: string): boolean {
|
|
87
|
-
|
|
103
|
+
export function looksLikeUri(value: string): boolean {
|
|
104
|
+
if (!/^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value)) return false;
|
|
105
|
+
// Reject anything the Rust-side `validate_iri` rejects so the two
|
|
106
|
+
// predicates stay in sync. `\s` covers ASCII whitespace *and*
|
|
107
|
+
// U+00A0/other Unicode whitespace under the default JS regex semantics.
|
|
108
|
+
if (/[\s<>{}"\u0000-\u001F\u007F-\u009F]/.test(value)) return false;
|
|
109
|
+
return true;
|
|
88
110
|
}
|
|
89
111
|
|
|
90
112
|
/**
|
|
91
113
|
* Convert a JS value to its literal: IRI form, matching how the Rust executor
|
|
92
|
-
* stores property values
|
|
93
|
-
* Strings that already look like URIs are returned
|
|
114
|
+
* stores property values in the default deterministic-literal path
|
|
115
|
+
* (`resolveLanguage` unset). Strings that already look like URIs are returned
|
|
116
|
+
* as-is.
|
|
117
|
+
*
|
|
118
|
+
* Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
|
|
119
|
+
* resolve path) can keep their on-disk form aligned with what
|
|
120
|
+
* `queryToSPARQL()` filters against — otherwise the same value can be
|
|
121
|
+
* stored as `<literal:string:https%3A...>` from one path while WHERE
|
|
122
|
+
* builders probe `<https://example.com>` from the other.
|
|
123
|
+
*
|
|
124
|
+
* The object/array arm mirrors Rust's `Literal::from_json` in
|
|
125
|
+
* `perspective_instance.rs::resolve_property_value` (which routes
|
|
126
|
+
* `Value::Object | Value::Array` through JSON encoding). Without it, JS
|
|
127
|
+
* would fall through to `String(value)` and turn `{a: 1}` into
|
|
128
|
+
* `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
|
|
94
129
|
*/
|
|
95
|
-
function valueToLiteralIri(value: any): string {
|
|
130
|
+
export function valueToLiteralIri(value: any): string {
|
|
96
131
|
if (typeof value === 'string') {
|
|
97
132
|
if (looksLikeUri(value)) return value;
|
|
98
133
|
return Literal.from(value).toUrl();
|
|
@@ -103,21 +138,55 @@ function valueToLiteralIri(value: any): string {
|
|
|
103
138
|
if (typeof value === 'boolean') {
|
|
104
139
|
return Literal.from(value).toUrl();
|
|
105
140
|
}
|
|
141
|
+
// Objects and arrays: route through Literal.from so we emit
|
|
142
|
+
// `literal:json:*` (mirrors Rust `Literal::from_json`). Without this
|
|
143
|
+
// arm we fall through to `String(value)` which turns objects into
|
|
144
|
+
// `"[object Object]"` and arrays into `"1,2"` — silently storing the
|
|
145
|
+
// wrong shape and breaking equality filters (`findAll({ where:
|
|
146
|
+
// { config: {...} } })` would match against `"[object Object]"`).
|
|
147
|
+
// The `value !== null` guard preserves the historical fallthrough for
|
|
148
|
+
// `null` (→ `literal:string:null`), since `Literal.from(null).toUrl()`
|
|
149
|
+
// throws on the empty-literal check.
|
|
150
|
+
if (value !== null && typeof value === 'object') {
|
|
151
|
+
return Literal.from(value).toUrl();
|
|
152
|
+
}
|
|
106
153
|
return Literal.from(String(value)).toUrl();
|
|
107
154
|
}
|
|
108
155
|
|
|
156
|
+
/** How a property's value is stored / resolved. */
|
|
157
|
+
export type LiteralStorageMode =
|
|
158
|
+
| { kind: "deterministic" } // deterministic literal: IRI (POS-index friendly, no signature)
|
|
159
|
+
| { kind: "envelope" } // signed expression on the built-in literal language
|
|
160
|
+
| { kind: "custom"; language: string }; // signed expression on a custom language
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* Derive the effective storage mode from a property's explicit options.
|
|
164
|
+
* `resolveLanguage` is the sole selector and is NOT defaulted at the
|
|
165
|
+
* decorator level:
|
|
166
|
+
* - unset → deterministic typed literal (the perf default
|
|
167
|
+
* for a plain `@Property()`)
|
|
168
|
+
* - `"literal"` → signed envelope on the built-in literal language
|
|
169
|
+
* (per-value provenance, e.g. Flux message bodies)
|
|
170
|
+
* - `<custom address>` → signed expression on that custom language
|
|
171
|
+
*/
|
|
172
|
+
export function effectiveLiteralStorage(meta: {
|
|
173
|
+
resolveLanguage?: string;
|
|
174
|
+
}): LiteralStorageMode {
|
|
175
|
+
const lang = meta.resolveLanguage;
|
|
176
|
+
if (lang === undefined) return { kind: "deterministic" };
|
|
177
|
+
if (lang === "literal") return { kind: "envelope" };
|
|
178
|
+
return { kind: "custom", language: lang };
|
|
179
|
+
}
|
|
180
|
+
|
|
109
181
|
/**
|
|
110
|
-
* Determine if a property stores values as literal: IRIs (
|
|
111
|
-
*
|
|
112
|
-
*
|
|
113
|
-
*
|
|
182
|
+
* Determine if a property stores values as deterministic literal: IRIs (so WHERE
|
|
183
|
+
* filters can match typed literals directly). Envelope / custom-language
|
|
184
|
+
* properties resolve through expressions, and flag properties store raw URIs —
|
|
185
|
+
* none is a deterministic literal.
|
|
114
186
|
*/
|
|
115
187
|
function isLiteralStoredProperty(propMeta: PropertyMetadata): boolean {
|
|
116
188
|
if (propMeta.flag) return false;
|
|
117
|
-
|
|
118
|
-
if (propMeta.resolveLanguage && propMeta.resolveLanguage !== "literal") return false;
|
|
119
|
-
// Everything else (resolveLanguage === "literal" or undefined) stores as literal: URIs
|
|
120
|
-
return true;
|
|
189
|
+
return effectiveLiteralStorage(propMeta).kind === "deterministic";
|
|
121
190
|
}
|
|
122
191
|
|
|
123
192
|
/**
|
package/src/model/query-utils.ts
CHANGED
|
@@ -47,20 +47,25 @@ export function formatQueryValue(value: any): string {
|
|
|
47
47
|
*
|
|
48
48
|
* @param predicate - The predicate URI for the property
|
|
49
49
|
* @param condition - The Where condition value
|
|
50
|
-
* @param opts - Optional settings
|
|
50
|
+
* @param opts - Optional settings. `isDeterministicLiteral` (default
|
|
51
|
+
* `true`) selects the direct typed-literal WHERE path.
|
|
52
|
+
* Set to `false` when the property stores a signed
|
|
53
|
+
* envelope (`resolveLanguage: "literal"`) or a
|
|
54
|
+
* custom-language expression — the envelope path unwraps
|
|
55
|
+
* with `parse_literal` before comparing.
|
|
51
56
|
* @returns A single SPARQL condition string
|
|
52
57
|
*/
|
|
53
58
|
export function buildWhereCondition(
|
|
54
59
|
predicate: string,
|
|
55
60
|
condition: WhereCondition,
|
|
56
|
-
opts?: {
|
|
61
|
+
opts?: { isDeterministicLiteral?: boolean; varIndex?: number },
|
|
57
62
|
): string {
|
|
58
63
|
const escapedPredicate = escapeQueryString(predicate);
|
|
59
|
-
// For literal
|
|
60
|
-
//
|
|
61
|
-
// For
|
|
62
|
-
//
|
|
63
|
-
const isLiteral =
|
|
64
|
+
// For deterministic-literal properties, values are stored as typed
|
|
65
|
+
// literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
|
|
66
|
+
// IRI form). For envelope / custom-language properties the target is a
|
|
67
|
+
// signed expression URI; comparisons need to unwrap via `parse_literal`.
|
|
68
|
+
const isLiteral = opts?.isDeterministicLiteral !== false;
|
|
64
69
|
|
|
65
70
|
const varSuffix = opts?.varIndex ?? 0;
|
|
66
71
|
|
|
@@ -183,23 +188,28 @@ export function compileWhereClause(
|
|
|
183
188
|
if (['id', 'author', 'timestamp'].includes(propertyName)) continue;
|
|
184
189
|
|
|
185
190
|
let predicate: string;
|
|
186
|
-
|
|
191
|
+
// Storage mode is derived from `resolveLanguage` alone:
|
|
192
|
+
// - undefined → deterministic typed literal (fast POS-index path)
|
|
193
|
+
// - "literal" → signed envelope on the literal language
|
|
194
|
+
// - custom address → expression on that custom language
|
|
195
|
+
// Envelope and custom-language properties both need the `parse_literal`
|
|
196
|
+
// unwrap path, so we treat any `resolveLanguage`-carrying property as
|
|
197
|
+
// non-deterministic here.
|
|
198
|
+
let isDeterministicLiteral: boolean | undefined;
|
|
187
199
|
|
|
188
200
|
if (metadata) {
|
|
189
201
|
const propMeta = metadata.properties[propertyName];
|
|
190
202
|
if (propMeta) {
|
|
191
203
|
predicate = propMeta.predicate;
|
|
192
|
-
|
|
204
|
+
isDeterministicLiteral = propMeta.resolveLanguage === undefined;
|
|
193
205
|
} else {
|
|
194
|
-
// Property not found in metadata — treat name as raw predicate URI
|
|
195
206
|
predicate = propertyName;
|
|
196
207
|
}
|
|
197
208
|
} else {
|
|
198
|
-
// No metadata — treat name as raw predicate URI
|
|
199
209
|
predicate = propertyName;
|
|
200
210
|
}
|
|
201
211
|
|
|
202
|
-
const cond = buildWhereCondition(predicate, condition, {
|
|
212
|
+
const cond = buildWhereCondition(predicate, condition, { isDeterministicLiteral, varIndex: conditions.length });
|
|
203
213
|
if (cond) {
|
|
204
214
|
conditions.push(cond);
|
|
205
215
|
}
|
package/src/model/shacl-gen.ts
CHANGED
|
@@ -129,17 +129,36 @@ export function buildSHACL(
|
|
|
129
129
|
path: propMeta.through,
|
|
130
130
|
};
|
|
131
131
|
|
|
132
|
-
// Determine datatype from
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
132
|
+
// Determine datatype from JS field value type; the resolve* options
|
|
133
|
+
// control storage mode (deterministic vs envelope), not scalar type.
|
|
134
|
+
// A value stored on the literal language (deterministic or envelope,
|
|
135
|
+
// i.e. resolveLanguage unset or "literal") gets a string datatype when
|
|
136
|
+
// no initial value pins a more specific type. A custom resolveLanguage
|
|
137
|
+
// yields an expression URI, not a literal.
|
|
138
|
+
//
|
|
139
|
+
// Skip auto-datatype for properties with a custom `getter` — those
|
|
140
|
+
// typically return URIs (e.g. `@Optional({ getter: "SELECT ?target ..." })`
|
|
141
|
+
// that hops through a link to another instance's URI). Autosetting
|
|
142
|
+
// `sh:datatype xsd:string` there would trip the hydration decode gate
|
|
143
|
+
// and silently transform `literal:string:<hex>` URIs into their inner
|
|
144
|
+
// plain-string form on read. Users who want a getter to return literal
|
|
145
|
+
// values can opt in explicitly by setting `datatype` on the property
|
|
146
|
+
// options (handled below).
|
|
147
|
+
if (propMeta.datatype) {
|
|
148
|
+
// Explicit opt-in from PropertyOptions always wins over inference.
|
|
149
|
+
propShape.datatype = propMeta.datatype;
|
|
150
|
+
} else {
|
|
151
|
+
const isLiteral =
|
|
152
|
+
propMeta.resolveLanguage === undefined || propMeta.resolveLanguage === "literal";
|
|
153
|
+
if ((propMeta.initial !== undefined || isLiteral) && !propMeta.getter) {
|
|
154
|
+
const initialType = typeof obj[propName];
|
|
155
|
+
if (initialType === "number") {
|
|
156
|
+
propShape.datatype = "xsd://integer";
|
|
157
|
+
} else if (initialType === "boolean") {
|
|
158
|
+
propShape.datatype = "xsd://boolean";
|
|
159
|
+
} else if (initialType === "string" || isLiteral) {
|
|
160
|
+
propShape.datatype = "xsd://string";
|
|
161
|
+
}
|
|
143
162
|
}
|
|
144
163
|
}
|
|
145
164
|
|
|
@@ -261,8 +280,18 @@ export function buildSHACL(
|
|
|
261
280
|
path: synthesizedPath,
|
|
262
281
|
};
|
|
263
282
|
|
|
264
|
-
//
|
|
265
|
-
|
|
283
|
+
// A relation with a declared `datatype` holds encoded literal
|
|
284
|
+
// values (e.g. `HasMany<string>` with `datatype: "xsd:string"`).
|
|
285
|
+
// Everything else is a URI relation pointing at another
|
|
286
|
+
// instance. The executor uses `sh:datatype` on hydration to
|
|
287
|
+
// decide whether to decode `literal:<type>:<value>` wire form
|
|
288
|
+
// (yes for literals, no for URIs).
|
|
289
|
+
if (relMeta.datatype) {
|
|
290
|
+
relShape.datatype = relMeta.datatype;
|
|
291
|
+
relShape.nodeKind = 'Literal';
|
|
292
|
+
} else {
|
|
293
|
+
relShape.nodeKind = 'IRI';
|
|
294
|
+
}
|
|
266
295
|
|
|
267
296
|
// Encode relation kind so the executor can derive direction and
|
|
268
297
|
// scalar-vs-collection rendering without consulting the JS class.
|
|
@@ -180,7 +180,7 @@ describe("Decorators → SHACL writer round-trip", () => {
|
|
|
180
180
|
it("emits scalar property predicates", () => {
|
|
181
181
|
@Model({ name: "Profile" })
|
|
182
182
|
class Profile extends Ad4mModel {
|
|
183
|
-
@Property({ through: "ns://name"
|
|
183
|
+
@Property({ through: "ns://name" })
|
|
184
184
|
name: string = "";
|
|
185
185
|
}
|
|
186
186
|
|
|
@@ -190,9 +190,11 @@ describe("Decorators → SHACL writer round-trip", () => {
|
|
|
190
190
|
expect(findLinkTarget(links, "ns://Profile.name", "sh://path")).toBe(
|
|
191
191
|
"ns://name",
|
|
192
192
|
);
|
|
193
|
+
// A bare @Property is deterministic-literal by default — no
|
|
194
|
+
// resolveLanguage link is emitted.
|
|
193
195
|
expect(
|
|
194
196
|
findLinkTarget(links, "ns://Profile.name", "ad4m://resolveLanguage"),
|
|
195
|
-
).
|
|
197
|
+
).toBeUndefined();
|
|
196
198
|
});
|
|
197
199
|
|
|
198
200
|
it("emits ad4m://interpretation_hint on the class shape and per property", () => {
|
package/src/model/types.ts
CHANGED
|
@@ -47,15 +47,25 @@ export type Where = {
|
|
|
47
47
|
export type Order = { [propertyName: string]: "ASC" | "DESC" };
|
|
48
48
|
|
|
49
49
|
/**
|
|
50
|
-
*
|
|
50
|
+
* A named subgraph scope: a parent node + linking predicate.
|
|
51
51
|
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
52
|
+
* Reusable across contexts that need to identify "the subtree under node X
|
|
53
|
+
* linked via predicate P": query-time filtering as a `parent` filter on a
|
|
54
|
+
* `ModelQuery` (the "all Messages belonging to Channel X" case) AND
|
|
55
|
+
* AutoProcessor's `existingScope` / `mintScope` fields — the former
|
|
56
|
+
* constrains dedup lookups; the latter turns each new mint into a child
|
|
57
|
+
* link under the given node.
|
|
58
|
+
*
|
|
59
|
+
* **Model form** (preferred for parent-filter queries) — predicate
|
|
60
|
+
* auto-resolved from the parent model's relation metadata. Use `field` to
|
|
61
|
+
* disambiguate when the parent has multiple relations targeting the same
|
|
62
|
+
* child class. AutoProcessor `mintScope` requires the **Raw form** because
|
|
63
|
+
* only Raw carries an explicit linking predicate; `Model` scopes have no
|
|
64
|
+
* predicate to write.
|
|
55
65
|
*
|
|
56
66
|
* **Raw form** — explicit predicate string, no metadata lookup.
|
|
57
67
|
*/
|
|
58
|
-
export type
|
|
68
|
+
export type Scope =
|
|
59
69
|
| { model: typeof Ad4mModel; id: string; field?: string }
|
|
60
70
|
| { id: string; predicate: string };
|
|
61
71
|
|
|
@@ -129,7 +139,7 @@ export function isIncludeProjection(val: unknown): val is IncludeProjection {
|
|
|
129
139
|
|
|
130
140
|
export type Query = {
|
|
131
141
|
/** Filter to instances that are the target of a link from a given parent. */
|
|
132
|
-
parent?:
|
|
142
|
+
parent?: Scope;
|
|
133
143
|
properties?: string[];
|
|
134
144
|
include?: IncludeMap;
|
|
135
145
|
/**
|
|
@@ -345,7 +355,7 @@ export type IncludeExtras<T extends Ad4mModel, I> =
|
|
|
345
355
|
// ---- Typed Query -------------------------------------------------------------
|
|
346
356
|
|
|
347
357
|
type StrictTypedQuery<T extends Ad4mModel> = {
|
|
348
|
-
parent?:
|
|
358
|
+
parent?: Scope;
|
|
349
359
|
properties?: PropertyKeysOf<T>[];
|
|
350
360
|
include?: TypedIncludeMap<T>;
|
|
351
361
|
includeAll?: boolean;
|
|
@@ -402,7 +412,12 @@ export interface PropertyMetadata {
|
|
|
402
412
|
readOnly: boolean;
|
|
403
413
|
/** Initial value if specified */
|
|
404
414
|
initial?: string;
|
|
405
|
-
/**
|
|
415
|
+
/** Sole selector of storage mode:
|
|
416
|
+
* - unset → deterministic typed literal (fast POS-index
|
|
417
|
+
* path, the default for a plain `@Property()`)
|
|
418
|
+
* - `"literal"` → signed envelope on the built-in literal language
|
|
419
|
+
* - `<custom address>` → expression on that custom language
|
|
420
|
+
*/
|
|
406
421
|
resolveLanguage?: string;
|
|
407
422
|
/** Custom Prolog getter code */
|
|
408
423
|
prologGetter?: string;
|