@coasys/ad4m 0.13.0-test-interpretation-1 → 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 +449 -149
- package/lib/index.js +447 -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 +13 -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 +30 -4
- package/src/shacl/SHACLShape.ts +28 -6
- package/src/shacl/index.ts +1 -1
package/lib/src/Literal.js
CHANGED
|
@@ -70,6 +70,14 @@ export class Literal {
|
|
|
70
70
|
const numberString = body.substring(7);
|
|
71
71
|
return parseFloat(numberString);
|
|
72
72
|
}
|
|
73
|
+
if (body.startsWith("boolean:")) {
|
|
74
|
+
const boolString = decodeURIComponent(body.substring(8));
|
|
75
|
+
if (boolString === "true")
|
|
76
|
+
return true;
|
|
77
|
+
if (boolString === "false")
|
|
78
|
+
return false;
|
|
79
|
+
throw new Error(`Can't parse boolean literal: ${boolString}`);
|
|
80
|
+
}
|
|
73
81
|
if (body.startsWith("json:")) {
|
|
74
82
|
const json = body.substring(5);
|
|
75
83
|
return JSON.parse(decodeURIComponent(json));
|
|
@@ -16,4 +16,20 @@ export type RunInterpretationRequest = {
|
|
|
16
16
|
* `None`/empty selects all subject classes registered in the perspective.
|
|
17
17
|
*/
|
|
18
18
|
classes: Array<string> | null;
|
|
19
|
+
/**
|
|
20
|
+
* Optional parent-scope filter for the dedup lookup: when set, only
|
|
21
|
+
* existing instances of the target classes that live under this scope
|
|
22
|
+
* are candidates for upsert. `None` = whole-perspective dedup set (the
|
|
23
|
+
* pre-scope default). Same semantics as `AutoProcessorConfig.existingScope`.
|
|
24
|
+
*/
|
|
25
|
+
existingScope?: any;
|
|
26
|
+
/**
|
|
27
|
+
* Optional parent-scope target for newly minted instances: when set,
|
|
28
|
+
* every base URI the pass CREATES is additionally linked as a child of
|
|
29
|
+
* `mintScope.id` via the scope's predicate. Upserts of pre-existing
|
|
30
|
+
* instances are NOT linked (would multi-parent unrelated graph state).
|
|
31
|
+
* Must be the `Raw` variant of `Scope` (id + predicate). Same semantics
|
|
32
|
+
* as `AutoProcessorConfig.mintScope`.
|
|
33
|
+
*/
|
|
34
|
+
mintScope?: any;
|
|
19
35
|
};
|
|
@@ -2,7 +2,7 @@ import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
|
|
|
2
2
|
import type { SHACLShape } from "../shacl/SHACLShape";
|
|
3
3
|
import type { JSONSchema, JSONSchemaToModelOptions } from "./json-schema";
|
|
4
4
|
import { ModelQueryBuilder } from "./ModelQueryBuilder";
|
|
5
|
-
import type {
|
|
5
|
+
import type { Scope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata, TypedQuery, IncludeExtras, IncludeOf } from "./types";
|
|
6
6
|
/**
|
|
7
7
|
* Base class for defining data models in AD4M.
|
|
8
8
|
*
|
|
@@ -24,12 +24,28 @@ import type { ParentScope, IncludeMap, Query, GetOptions, ResultsWithTotalCount,
|
|
|
24
24
|
* // Define a recipe model
|
|
25
25
|
* @Model({ name: "Recipe" })
|
|
26
26
|
* class Recipe extends Ad4mModel {
|
|
27
|
-
* //
|
|
27
|
+
* // Plain property — no `resolveLanguage` → deterministic typed literal
|
|
28
|
+
* // storage (fast POS-index path). This is the perf default.
|
|
29
|
+
* @Property({ through: "recipe://name" })
|
|
30
|
+
* name: string = "";
|
|
31
|
+
*
|
|
32
|
+
* // Property that needs per-value provenance (e.g. a signed message body):
|
|
33
|
+
* // `resolveLanguage: "literal"` routes values through expression_create on
|
|
34
|
+
* // the built-in literal language, producing a signed envelope URI
|
|
35
|
+
* // (author/timestamp/proof) instead of a bare typed literal.
|
|
28
36
|
* @Property({
|
|
29
|
-
* through: "recipe://
|
|
37
|
+
* through: "recipe://signed_note",
|
|
30
38
|
* resolveLanguage: "literal"
|
|
31
39
|
* })
|
|
32
|
-
*
|
|
40
|
+
* signedNote: string = "";
|
|
41
|
+
*
|
|
42
|
+
* // Property resolved through a custom language: values are routed through
|
|
43
|
+
* // expression_create on that language (signed expression URIs).
|
|
44
|
+
* @Optional({
|
|
45
|
+
* through: "recipe://photo",
|
|
46
|
+
* resolveLanguage: "QmFileStorageLanguageAddress..."
|
|
47
|
+
* })
|
|
48
|
+
* photo: string = "";
|
|
33
49
|
*
|
|
34
50
|
* // Optional property with custom initial value
|
|
35
51
|
* @Optional({
|
|
@@ -157,7 +173,7 @@ export declare class Ad4mModel {
|
|
|
157
173
|
* ```typescript
|
|
158
174
|
* @Model({ name: "Recipe" })
|
|
159
175
|
* class Recipe extends Ad4mModel {
|
|
160
|
-
* @Property({ through: "recipe://name"
|
|
176
|
+
* @Property({ through: "recipe://name" })
|
|
161
177
|
* name: string = "";
|
|
162
178
|
*
|
|
163
179
|
* @HasMany({ through: "recipe://ingredient" })
|
|
@@ -176,7 +192,9 @@ export declare class Ad4mModel {
|
|
|
176
192
|
*
|
|
177
193
|
* @param perspective - The perspective where this model will be stored
|
|
178
194
|
* @param baseExpression - Optional expression URI for this instance.
|
|
179
|
-
* If omitted, a random
|
|
195
|
+
* If omitted, a random `ad4m://obj/<id>` IRI is generated,
|
|
196
|
+
* independent of any property content — this is what keeps
|
|
197
|
+
* two instances with identical property values distinct.
|
|
180
198
|
* @param source - Optional source expression this instance is linked to
|
|
181
199
|
*
|
|
182
200
|
* @example
|
|
@@ -185,7 +203,7 @@ export declare class Ad4mModel {
|
|
|
185
203
|
* const recipe = new Recipe(perspective);
|
|
186
204
|
*
|
|
187
205
|
* // Create with specific base expression
|
|
188
|
-
* const recipe = new Recipe(perspective, "
|
|
206
|
+
* const recipe = new Recipe(perspective, "ad4m://obj/existing-id");
|
|
189
207
|
* ```
|
|
190
208
|
*/
|
|
191
209
|
constructor(perspective: PerspectiveProxy, baseExpression?: string);
|
|
@@ -537,7 +555,7 @@ export declare class Ad4mModel {
|
|
|
537
555
|
* @param perspective - The perspective to create the instance in
|
|
538
556
|
* @param data - Property values to assign before saving
|
|
539
557
|
* @param options - Optional settings:
|
|
540
|
-
* - `parent` — a `
|
|
558
|
+
* - `parent` — a `Scope` (model form or raw form) whose `id` will
|
|
541
559
|
* be used to create an incoming link from the parent to the new instance.
|
|
542
560
|
* - `batchId` — an existing batch id; when provided the link write and
|
|
543
561
|
* `save()` are added to the batch instead of committed immediately.
|
|
@@ -563,7 +581,7 @@ export declare class Ad4mModel {
|
|
|
563
581
|
* ```
|
|
564
582
|
*/
|
|
565
583
|
static create<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, data?: Record<string, any>, options?: {
|
|
566
|
-
parent?:
|
|
584
|
+
parent?: Scope;
|
|
567
585
|
batchId?: string;
|
|
568
586
|
}): Promise<T>;
|
|
569
587
|
/**
|
|
@@ -717,8 +735,7 @@ export declare class Ad4mModel {
|
|
|
717
735
|
* // With explicit configuration
|
|
718
736
|
* const PersonClass = Ad4mModel.fromJSONSchema(schema, {
|
|
719
737
|
* name: "Person",
|
|
720
|
-
* namespace: "person://"
|
|
721
|
-
* resolveLanguage: "literal"
|
|
738
|
+
* namespace: "person://"
|
|
722
739
|
* });
|
|
723
740
|
*
|
|
724
741
|
* // With property mapping
|
|
@@ -1,11 +1,10 @@
|
|
|
1
|
-
import { Literal } from "../Literal";
|
|
2
1
|
import { Link } from "../links/Links";
|
|
3
2
|
import { LinkQuery } from "../perspectives/LinkQuery";
|
|
4
3
|
import { makeRandomId } from "./util";
|
|
5
4
|
import { getPropertiesMetadata, getRelationsMetadata, setPropertyRegistryEntry, setRelationRegistryEntry, Model } from "./decorators";
|
|
6
5
|
import { resolveParentPredicate } from "./query-common";
|
|
7
6
|
import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
|
|
8
|
-
import { buildSPARQLQuery } from "./query-sparql";
|
|
7
|
+
import { buildSPARQLQuery, valueToLiteralIri, effectiveLiteralStorage } from "./query-sparql";
|
|
9
8
|
import { ModelQueryBuilder } from "./ModelQueryBuilder";
|
|
10
9
|
import { normalizeValue, } from "./hydration";
|
|
11
10
|
// ---------------------------------------------------------------------------
|
|
@@ -108,12 +107,28 @@ function jsonToModelInstance(ModelClass, perspective, json, include, properties)
|
|
|
108
107
|
* // Define a recipe model
|
|
109
108
|
* @Model({ name: "Recipe" })
|
|
110
109
|
* class Recipe extends Ad4mModel {
|
|
111
|
-
* //
|
|
110
|
+
* // Plain property — no `resolveLanguage` → deterministic typed literal
|
|
111
|
+
* // storage (fast POS-index path). This is the perf default.
|
|
112
|
+
* @Property({ through: "recipe://name" })
|
|
113
|
+
* name: string = "";
|
|
114
|
+
*
|
|
115
|
+
* // Property that needs per-value provenance (e.g. a signed message body):
|
|
116
|
+
* // `resolveLanguage: "literal"` routes values through expression_create on
|
|
117
|
+
* // the built-in literal language, producing a signed envelope URI
|
|
118
|
+
* // (author/timestamp/proof) instead of a bare typed literal.
|
|
112
119
|
* @Property({
|
|
113
|
-
* through: "recipe://
|
|
120
|
+
* through: "recipe://signed_note",
|
|
114
121
|
* resolveLanguage: "literal"
|
|
115
122
|
* })
|
|
116
|
-
*
|
|
123
|
+
* signedNote: string = "";
|
|
124
|
+
*
|
|
125
|
+
* // Property resolved through a custom language: values are routed through
|
|
126
|
+
* // expression_create on that language (signed expression URIs).
|
|
127
|
+
* @Optional({
|
|
128
|
+
* through: "recipe://photo",
|
|
129
|
+
* resolveLanguage: "QmFileStorageLanguageAddress..."
|
|
130
|
+
* })
|
|
131
|
+
* photo: string = "";
|
|
117
132
|
*
|
|
118
133
|
* // Optional property with custom initial value
|
|
119
134
|
* @Optional({
|
|
@@ -253,7 +268,7 @@ export class Ad4mModel {
|
|
|
253
268
|
* ```typescript
|
|
254
269
|
* @Model({ name: "Recipe" })
|
|
255
270
|
* class Recipe extends Ad4mModel {
|
|
256
|
-
* @Property({ through: "recipe://name"
|
|
271
|
+
* @Property({ through: "recipe://name" })
|
|
257
272
|
* name: string = "";
|
|
258
273
|
*
|
|
259
274
|
* @HasMany({ through: "recipe://ingredient" })
|
|
@@ -342,7 +357,7 @@ export class Ad4mModel {
|
|
|
342
357
|
predicate: predicate,
|
|
343
358
|
required: isRequired,
|
|
344
359
|
readOnly: propertySchema["x-ad4m"]?.writable === false,
|
|
345
|
-
...(propertySchema["x-ad4m"]?.resolveLanguage && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
|
|
360
|
+
...(propertySchema["x-ad4m"]?.resolveLanguage !== undefined && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
|
|
346
361
|
...(propertySchema["x-ad4m"]?.initial && { initial: propertySchema["x-ad4m"].initial }),
|
|
347
362
|
...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
|
|
348
363
|
};
|
|
@@ -361,7 +376,9 @@ export class Ad4mModel {
|
|
|
361
376
|
*
|
|
362
377
|
* @param perspective - The perspective where this model will be stored
|
|
363
378
|
* @param baseExpression - Optional expression URI for this instance.
|
|
364
|
-
* If omitted, a random
|
|
379
|
+
* If omitted, a random `ad4m://obj/<id>` IRI is generated,
|
|
380
|
+
* independent of any property content — this is what keeps
|
|
381
|
+
* two instances with identical property values distinct.
|
|
365
382
|
* @param source - Optional source expression this instance is linked to
|
|
366
383
|
*
|
|
367
384
|
* @example
|
|
@@ -370,12 +387,21 @@ export class Ad4mModel {
|
|
|
370
387
|
* const recipe = new Recipe(perspective);
|
|
371
388
|
*
|
|
372
389
|
* // Create with specific base expression
|
|
373
|
-
* const recipe = new Recipe(perspective, "
|
|
390
|
+
* const recipe = new Recipe(perspective, "ad4m://obj/existing-id");
|
|
374
391
|
* ```
|
|
375
392
|
*/
|
|
376
393
|
constructor(perspective, baseExpression) {
|
|
377
394
|
this._snapshot = null;
|
|
378
|
-
|
|
395
|
+
// Use a dedicated `ad4m://obj/<id>` scheme for auto-generated
|
|
396
|
+
// baseExpressions instead of `Literal.from(...).toUrl()`'s
|
|
397
|
+
// `literal:string:<id>`. After typed-literal storage lands, the storage
|
|
398
|
+
// layer translates any `literal:string:X` target into a typed
|
|
399
|
+
// `"X"^^xsd:string` literal — which is correct for property values but
|
|
400
|
+
// wrong for relation targets (which must remain NamedNode IRIs). Using
|
|
401
|
+
// a distinct scheme keeps auto-generated instance IDs unambiguously
|
|
402
|
+
// IRIs, so relation links like `<post> --has_comment--> <comment-id>`
|
|
403
|
+
// round-trip correctly through the SPARQL store.
|
|
404
|
+
this._baseExpression = baseExpression ? baseExpression : `ad4m://obj/${makeRandomId(24)}`;
|
|
379
405
|
this._perspective = perspective;
|
|
380
406
|
}
|
|
381
407
|
/**
|
|
@@ -937,14 +963,22 @@ export class Ad4mModel {
|
|
|
937
963
|
}
|
|
938
964
|
// Generate actions from metadata (replaces Prolog query)
|
|
939
965
|
const actions = this.generatePropertySetterAction(key, metadata);
|
|
940
|
-
// Get resolve language from metadata (replaces Prolog query)
|
|
941
|
-
let resolveLanguage = metadata.resolveLanguage;
|
|
942
966
|
// Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
|
|
943
967
|
if (value === undefined || value === null || value === "") {
|
|
944
968
|
return;
|
|
945
969
|
}
|
|
946
|
-
|
|
947
|
-
|
|
970
|
+
const mode = effectiveLiteralStorage(metadata);
|
|
971
|
+
if (mode.kind === "custom") {
|
|
972
|
+
// Custom language: route through expression_create on that language.
|
|
973
|
+
value = await this._perspective.createExpression(value, mode.language);
|
|
974
|
+
}
|
|
975
|
+
else if (mode.kind === "envelope") {
|
|
976
|
+
// Built-in literal language: signed-envelope expression (provenance).
|
|
977
|
+
value = await this._perspective.createExpression(value, "literal");
|
|
978
|
+
}
|
|
979
|
+
else {
|
|
980
|
+
// Deterministic literal: IRI (POS-index friendly).
|
|
981
|
+
value = valueToLiteralIri(value);
|
|
948
982
|
}
|
|
949
983
|
await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value }], batchId);
|
|
950
984
|
}
|
|
@@ -1063,41 +1097,30 @@ export class Ad4mModel {
|
|
|
1063
1097
|
// entirely and let innerUpdate write the links directly.
|
|
1064
1098
|
const metadata = this.constructor.getModelMetadata();
|
|
1065
1099
|
const hasConstructor = Object.values(metadata.properties).some((p) => p.required || p.flag || p.initial !== undefined);
|
|
1066
|
-
// Track properties
|
|
1067
|
-
//
|
|
1068
|
-
|
|
1100
|
+
// Track properties resolved through expression_create — a signed literal
|
|
1101
|
+
// envelope or a custom (non-"literal") resolveLanguage. These may fail
|
|
1102
|
+
// inside a batch context, so defer them to setProperty after createSubject.
|
|
1103
|
+
const deferredExpressionProps = [];
|
|
1069
1104
|
if (hasConstructor) {
|
|
1070
|
-
// First filter out the properties that are not relations (arrays)
|
|
1071
1105
|
const initialValues = {};
|
|
1072
1106
|
for (const [key, value] of Object.entries(this)) {
|
|
1073
1107
|
if (value !== undefined && value !== null && !(Array.isArray(value) && value.length > 0) && !value?.action) {
|
|
1074
|
-
// Check if this property requires language resolution (e.g. file storage).
|
|
1075
|
-
// If so, resolve the expression *before* passing to createSubject so
|
|
1076
|
-
// the constructor receives a valid URI instead of raw data.
|
|
1077
1108
|
const propMeta = metadata.properties[key];
|
|
1078
|
-
if (propMeta
|
|
1079
|
-
|
|
1080
|
-
// fail inside a batch context on some languages. We'll set them
|
|
1081
|
-
// via setProperty after createSubject.
|
|
1082
|
-
deferredResolveLanguageProps.push(key);
|
|
1109
|
+
if (propMeta && effectiveLiteralStorage(propMeta).kind !== "deterministic") {
|
|
1110
|
+
deferredExpressionProps.push(key);
|
|
1083
1111
|
continue;
|
|
1084
1112
|
}
|
|
1085
1113
|
initialValues[key] = value;
|
|
1086
1114
|
}
|
|
1087
1115
|
}
|
|
1088
|
-
// Get the class name instead of passing the instance to avoid Prolog query generation
|
|
1089
1116
|
const className = await this.perspective.stringOrTemplateObjectToSubjectClassName(this);
|
|
1090
|
-
// Create the subject with the initial values
|
|
1091
1117
|
await this.perspective.createSubject(className, this._baseExpression, initialValues, batchId);
|
|
1092
1118
|
}
|
|
1093
1119
|
// Set properties and relations via innerUpdate.
|
|
1094
1120
|
// When createSubject was skipped (no constructor actions), we must enable
|
|
1095
1121
|
// property writing so that scalar values are persisted as links.
|
|
1096
1122
|
await this.innerUpdate(!hasConstructor, batchId);
|
|
1097
|
-
|
|
1098
|
-
// from initialValues. setProperty will call createExpression to upload
|
|
1099
|
-
// the data to the appropriate language and store the resulting URI.
|
|
1100
|
-
for (const key of deferredResolveLanguageProps) {
|
|
1123
|
+
for (const key of deferredExpressionProps) {
|
|
1101
1124
|
const value = this[key];
|
|
1102
1125
|
if (value !== undefined && value !== null) {
|
|
1103
1126
|
await this.setProperty(key, value, batchId);
|
|
@@ -1392,7 +1415,7 @@ export class Ad4mModel {
|
|
|
1392
1415
|
* @param perspective - The perspective to create the instance in
|
|
1393
1416
|
* @param data - Property values to assign before saving
|
|
1394
1417
|
* @param options - Optional settings:
|
|
1395
|
-
* - `parent` — a `
|
|
1418
|
+
* - `parent` — a `Scope` (model form or raw form) whose `id` will
|
|
1396
1419
|
* be used to create an incoming link from the parent to the new instance.
|
|
1397
1420
|
* - `batchId` — an existing batch id; when provided the link write and
|
|
1398
1421
|
* `save()` are added to the batch instead of committed immediately.
|
|
@@ -1624,8 +1647,7 @@ export class Ad4mModel {
|
|
|
1624
1647
|
* // With explicit configuration
|
|
1625
1648
|
* const PersonClass = Ad4mModel.fromJSONSchema(schema, {
|
|
1626
1649
|
* name: "Person",
|
|
1627
|
-
* namespace: "person://"
|
|
1628
|
-
* resolveLanguage: "literal"
|
|
1650
|
+
* namespace: "person://"
|
|
1629
1651
|
* });
|
|
1630
1652
|
*
|
|
1631
1653
|
* // With property mapping
|
|
@@ -169,11 +169,11 @@ export class ModelQueryBuilder {
|
|
|
169
169
|
}
|
|
170
170
|
const field = options?.field;
|
|
171
171
|
if (typeof modelOrPredicate === 'string') {
|
|
172
|
-
// Raw predicate string → raw form of
|
|
172
|
+
// Raw predicate string → raw form of Scope
|
|
173
173
|
this.queryParams.parent = { id, predicate: modelOrPredicate };
|
|
174
174
|
}
|
|
175
175
|
else if (typeof modelOrPredicate === 'function') {
|
|
176
|
-
// Model class → model form of
|
|
176
|
+
// Model class → model form of Scope
|
|
177
177
|
this.queryParams.parent = { id, model: modelOrPredicate, ...(field && { field }) };
|
|
178
178
|
}
|
|
179
179
|
else if (typeof idOrInstance !== 'string') {
|
|
@@ -35,6 +35,15 @@ export interface RelationMetadataEntry {
|
|
|
35
35
|
* Overrides auto-derived conformance when set.
|
|
36
36
|
*/
|
|
37
37
|
where?: Where;
|
|
38
|
+
/**
|
|
39
|
+
* SHACL `sh:datatype` for the relation's target values. Set when the
|
|
40
|
+
* relation holds encoded literal values (e.g. `"xsd:string"` for a
|
|
41
|
+
* `HasMany<string>` that stores plain strings). Emitted into SHACL
|
|
42
|
+
* so the executor knows to decode `literal:<type>:<value>` wire form
|
|
43
|
+
* on hydration. Omit for URI relations that point at other model
|
|
44
|
+
* instances — those pass through byte-for-byte.
|
|
45
|
+
*/
|
|
46
|
+
datatype?: string;
|
|
38
47
|
}
|
|
39
48
|
/**
|
|
40
49
|
* Retrieve property metadata for a given class constructor.
|
|
@@ -127,7 +136,16 @@ export interface PropertyOptions {
|
|
|
127
136
|
*/
|
|
128
137
|
readOnly?: boolean;
|
|
129
138
|
/**
|
|
130
|
-
* The language used to store the property
|
|
139
|
+
* The language used to resolve/store the property value — and the sole
|
|
140
|
+
* selector of storage mode. Not defaulted:
|
|
141
|
+
* - unset (the default for a plain `@Property()`) → deterministic
|
|
142
|
+
* typed literal storage (`literal:string:` / `:number:` / `:boolean:` /
|
|
143
|
+
* `:json:` IRIs stored as XSD-typed RDF literals; POS-index friendly).
|
|
144
|
+
* - `"literal"` → the built-in literal language: values go through
|
|
145
|
+
* `expression_create`, producing a signed-envelope URI with
|
|
146
|
+
* author/timestamp/proof (per-value provenance, e.g. Flux message
|
|
147
|
+
* bodies).
|
|
148
|
+
* - a custom language address → `expression_create` on that language.
|
|
131
149
|
*/
|
|
132
150
|
resolveLanguage?: string;
|
|
133
151
|
/**
|
|
@@ -197,6 +215,16 @@ export interface PropertyOptions {
|
|
|
197
215
|
* should set this.
|
|
198
216
|
*/
|
|
199
217
|
identity?: boolean;
|
|
218
|
+
/**
|
|
219
|
+
* Explicit SHACL `sh:datatype` for the property value. When set, this
|
|
220
|
+
* overrides auto-inference and — importantly — lets custom `getter`
|
|
221
|
+
* properties opt into typed-literal decoding. Auto-inference is disabled
|
|
222
|
+
* for properties with a `getter` (see `shacl-gen.ts`) because such
|
|
223
|
+
* getters typically return URIs; setting `datatype` explicitly declares
|
|
224
|
+
* that this getter returns literal values of the given XSD type
|
|
225
|
+
* (e.g. `"xsd://string"`) and enables the hydration decode gate.
|
|
226
|
+
*/
|
|
227
|
+
datatype?: string;
|
|
200
228
|
}
|
|
201
229
|
/**
|
|
202
230
|
* Convenience decorator for defining optional (not required) properties.
|
|
@@ -205,7 +233,7 @@ export interface PropertyOptions {
|
|
|
205
233
|
*
|
|
206
234
|
* @description
|
|
207
235
|
* Equivalent to `@Property` but defaults `required` to `false` and does not
|
|
208
|
-
* apply
|
|
236
|
+
* apply any `initial` defaults. Use this when a property
|
|
209
237
|
* may or may not have a value, and you want full control over its configuration.
|
|
210
238
|
*
|
|
211
239
|
* @example
|
|
@@ -317,8 +345,7 @@ export interface ModelConfig {
|
|
|
317
345
|
* @Model({ name: "Recipe" })
|
|
318
346
|
* class Recipe extends Ad4mModel {
|
|
319
347
|
* @Property({
|
|
320
|
-
* through: "recipe://name"
|
|
321
|
-
* resolveLanguage: "literal"
|
|
348
|
+
* through: "recipe://name"
|
|
322
349
|
* })
|
|
323
350
|
* name: string = "";
|
|
324
351
|
*
|
|
@@ -363,7 +390,9 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
|
|
|
363
390
|
* Smart defaults (all overridable):
|
|
364
391
|
* - `required` → `false`
|
|
365
392
|
* - `readOnly` → `false`
|
|
366
|
-
* - `resolveLanguage` →
|
|
393
|
+
* - `resolveLanguage` → unset → deterministic typed literal storage
|
|
394
|
+
* (the perf default). Set `resolveLanguage: "literal"` for a signed-envelope
|
|
395
|
+
* value, or a custom language address to resolve through that language.
|
|
367
396
|
* - `initial` → `undefined` (no link created until a value is explicitly set)
|
|
368
397
|
*
|
|
369
398
|
* Properties are optional by default. When a model instance is created without
|
|
@@ -396,7 +425,8 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
|
|
|
396
425
|
* })
|
|
397
426
|
* role: string = "";
|
|
398
427
|
*
|
|
399
|
-
* // Optional property with literal
|
|
428
|
+
* // Optional property with signed-envelope literal storage
|
|
429
|
+
* // (per-value provenance)
|
|
400
430
|
* @Property({
|
|
401
431
|
* through: "user://bio",
|
|
402
432
|
* resolveLanguage: "literal"
|
|
@@ -409,7 +439,7 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
|
|
|
409
439
|
* @param {string} opts.through - The predicate URI for the property
|
|
410
440
|
* @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
|
|
411
441
|
* @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
|
|
412
|
-
* @param {string} [opts.resolveLanguage] -
|
|
442
|
+
* @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
|
|
413
443
|
* @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
|
|
414
444
|
* @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
|
|
415
445
|
* @param {boolean} [opts.local] - Whether the property should only be stored locally
|
|
@@ -466,7 +496,7 @@ export declare function Property(opts: PropertyOptions): <T>(target: T, key: key
|
|
|
466
496
|
* @param {PropertyOptions} opts - Property configuration
|
|
467
497
|
* @param {string} opts.through - The predicate URI for the property
|
|
468
498
|
* @param {string} [opts.initial] - Initial value (if property should have one)
|
|
469
|
-
* @param {string} [opts.resolveLanguage] -
|
|
499
|
+
* @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
|
|
470
500
|
* @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
|
|
471
501
|
* @param {boolean} [opts.local] - Whether the property should only be stored locally
|
|
472
502
|
*/
|
|
@@ -523,6 +553,20 @@ export interface RelationOptions {
|
|
|
523
553
|
* ```
|
|
524
554
|
*/
|
|
525
555
|
where?: Where;
|
|
556
|
+
/**
|
|
557
|
+
* SHACL `sh:datatype` for the relation's target values. Set when the
|
|
558
|
+
* relation holds encoded literal values (e.g. `"xsd:string"` for a
|
|
559
|
+
* `HasMany<string>` that stores plain strings). The executor uses
|
|
560
|
+
* this to decode `literal:<type>:<value>` wire form on hydration.
|
|
561
|
+
* Omit for URI relations that point at other model instances.
|
|
562
|
+
*
|
|
563
|
+
* @example
|
|
564
|
+
* ```typescript
|
|
565
|
+
* @HasMany({ through: "run://source", datatype: "xsd:string" })
|
|
566
|
+
* sources: string[] = [];
|
|
567
|
+
* ```
|
|
568
|
+
*/
|
|
569
|
+
datatype?: string;
|
|
526
570
|
}
|
|
527
571
|
/**
|
|
528
572
|
* Utility type that describes the auto-generated helper methods for a HasMany
|
|
@@ -206,7 +206,7 @@ function applyPropertyMetadata(opts) {
|
|
|
206
206
|
*
|
|
207
207
|
* @description
|
|
208
208
|
* Equivalent to `@Property` but defaults `required` to `false` and does not
|
|
209
|
-
* apply
|
|
209
|
+
* apply any `initial` defaults. Use this when a property
|
|
210
210
|
* may or may not have a value, and you want full control over its configuration.
|
|
211
211
|
*
|
|
212
212
|
* @example
|
|
@@ -329,8 +329,7 @@ export function Flag(opts) {
|
|
|
329
329
|
* @Model({ name: "Recipe" })
|
|
330
330
|
* class Recipe extends Ad4mModel {
|
|
331
331
|
* @Property({
|
|
332
|
-
* through: "recipe://name"
|
|
333
|
-
* resolveLanguage: "literal"
|
|
332
|
+
* through: "recipe://name"
|
|
334
333
|
* })
|
|
335
334
|
* name: string = "";
|
|
336
335
|
*
|
|
@@ -387,7 +386,9 @@ export function Model(opts) {
|
|
|
387
386
|
* Smart defaults (all overridable):
|
|
388
387
|
* - `required` → `false`
|
|
389
388
|
* - `readOnly` → `false`
|
|
390
|
-
* - `resolveLanguage` →
|
|
389
|
+
* - `resolveLanguage` → unset → deterministic typed literal storage
|
|
390
|
+
* (the perf default). Set `resolveLanguage: "literal"` for a signed-envelope
|
|
391
|
+
* value, or a custom language address to resolve through that language.
|
|
391
392
|
* - `initial` → `undefined` (no link created until a value is explicitly set)
|
|
392
393
|
*
|
|
393
394
|
* Properties are optional by default. When a model instance is created without
|
|
@@ -420,7 +421,8 @@ export function Model(opts) {
|
|
|
420
421
|
* })
|
|
421
422
|
* role: string = "";
|
|
422
423
|
*
|
|
423
|
-
* // Optional property with literal
|
|
424
|
+
* // Optional property with signed-envelope literal storage
|
|
425
|
+
* // (per-value provenance)
|
|
424
426
|
* @Property({
|
|
425
427
|
* through: "user://bio",
|
|
426
428
|
* resolveLanguage: "literal"
|
|
@@ -433,18 +435,22 @@ export function Model(opts) {
|
|
|
433
435
|
* @param {string} opts.through - The predicate URI for the property
|
|
434
436
|
* @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
|
|
435
437
|
* @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
|
|
436
|
-
* @param {string} [opts.resolveLanguage] -
|
|
438
|
+
* @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
|
|
437
439
|
* @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
|
|
438
440
|
* @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
|
|
439
441
|
* @param {boolean} [opts.local] - Whether the property should only be stored locally
|
|
440
442
|
*/
|
|
441
443
|
export function Property(opts) {
|
|
442
444
|
const required = opts.required ?? false;
|
|
445
|
+
// `resolveLanguage` is intentionally NOT defaulted here.
|
|
446
|
+
// The effective storage mode is derived from what the user explicitly set:
|
|
447
|
+
// - unset → deterministic typed literal (the perf default)
|
|
448
|
+
// - "literal" → signed literal envelope (per-value provenance)
|
|
449
|
+
// - <custom address> → expression on that custom language
|
|
443
450
|
return applyPropertyMetadata({
|
|
444
451
|
...opts,
|
|
445
452
|
required,
|
|
446
453
|
readOnly: opts.readOnly ?? false,
|
|
447
|
-
resolveLanguage: opts.resolveLanguage ?? "literal",
|
|
448
454
|
initial: opts.initial ?? (required ? "literal:string:uninitialized" : undefined),
|
|
449
455
|
});
|
|
450
456
|
}
|
|
@@ -499,7 +505,7 @@ export function Property(opts) {
|
|
|
499
505
|
* @param {PropertyOptions} opts - Property configuration
|
|
500
506
|
* @param {string} opts.through - The predicate URI for the property
|
|
501
507
|
* @param {string} [opts.initial] - Initial value (if property should have one)
|
|
502
|
-
* @param {string} [opts.resolveLanguage] -
|
|
508
|
+
* @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
|
|
503
509
|
* @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
|
|
504
510
|
* @param {boolean} [opts.local] - Whether the property should only be stored locally
|
|
505
511
|
*/
|
|
@@ -567,6 +573,7 @@ export function HasMany(first, second) {
|
|
|
567
573
|
...(opts.getter && { getter: opts.getter }),
|
|
568
574
|
...(opts.filter !== undefined && { filter: opts.filter }),
|
|
569
575
|
...(opts.where && { where: opts.where }),
|
|
576
|
+
...(opts.datatype && { datatype: opts.datatype }),
|
|
570
577
|
};
|
|
571
578
|
const relKey = key;
|
|
572
579
|
// Only add mutation methods when a predicate is available
|
|
@@ -600,6 +607,7 @@ export function HasOne(first, second) {
|
|
|
600
607
|
local: opts.local,
|
|
601
608
|
...(opts.filter !== undefined && { filter: opts.filter }),
|
|
602
609
|
...(opts.where && { where: opts.where }),
|
|
610
|
+
...(opts.datatype && { datatype: opts.datatype }),
|
|
603
611
|
};
|
|
604
612
|
const relKey = key;
|
|
605
613
|
if (opts.through) {
|
|
@@ -640,6 +648,7 @@ export function BelongsToOne(first, second) {
|
|
|
640
648
|
local: opts.local,
|
|
641
649
|
...(opts.filter !== undefined && { filter: opts.filter }),
|
|
642
650
|
...(opts.where && { where: opts.where }),
|
|
651
|
+
...(opts.datatype && { datatype: opts.datatype }),
|
|
643
652
|
};
|
|
644
653
|
if (opts.through) {
|
|
645
654
|
// Read-only property (the owning side manages the link)
|
|
@@ -669,6 +678,7 @@ export function BelongsToMany(first, second) {
|
|
|
669
678
|
...(opts.getter && { getter: opts.getter }),
|
|
670
679
|
...(opts.filter !== undefined && { filter: opts.filter }),
|
|
671
680
|
...(opts.where && { where: opts.where }),
|
|
681
|
+
...(opts.datatype && { datatype: opts.datatype }),
|
|
672
682
|
};
|
|
673
683
|
// @BelongsToMany is the inverse/read-only side — do NOT generate add*/remove*/set*
|
|
674
684
|
// prototype methods. Mutation must go through the owning side's @HasMany decorator.
|
|
@@ -238,13 +238,7 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
|
|
|
238
238
|
}
|
|
239
239
|
else {
|
|
240
240
|
// Handle regular properties
|
|
241
|
-
let resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
|
|
242
|
-
// If no specific resolveLanguage for this property, use the global one
|
|
243
|
-
if (!resolveLanguage && options.resolveLanguage) {
|
|
244
|
-
resolveLanguage = options.resolveLanguage;
|
|
245
|
-
}
|
|
246
241
|
const local = getPropertyOption(propertyName, propertySchema, options, 'local');
|
|
247
|
-
// Determine readOnly: check PropertyOptions first, then x-ad4m.writable (inverted) for JSON Schema wire format
|
|
248
242
|
let readOnly = getPropertyOption(propertyName, propertySchema, options, 'readOnly');
|
|
249
243
|
if (readOnly === undefined) {
|
|
250
244
|
const xWritable = propertySchema["x-ad4m"]?.writable;
|
|
@@ -252,22 +246,14 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
|
|
|
252
246
|
}
|
|
253
247
|
const writable = !readOnly;
|
|
254
248
|
let initial = getPropertyOption(propertyName, propertySchema, options, 'initial');
|
|
255
|
-
//
|
|
256
|
-
|
|
257
|
-
|
|
249
|
+
// Not defaulted — absence means "deterministic typed literal" (the
|
|
250
|
+
// perf default); an explicit `resolveLanguage: "literal"` selects the
|
|
251
|
+
// signed-envelope path; any other value selects a custom language.
|
|
252
|
+
// See effectiveLiteralStorage().
|
|
253
|
+
const resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
|
|
254
|
+
if (isObjectType(propertySchema)) {
|
|
258
255
|
console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
|
|
259
256
|
}
|
|
260
|
-
// Ensure numeric properties use literal language for correct typing
|
|
261
|
-
if ((resolveLanguage === undefined || resolveLanguage === null) && isNumericType(propertySchema)) {
|
|
262
|
-
resolveLanguage = 'literal';
|
|
263
|
-
}
|
|
264
|
-
// Default resolveLanguage to 'literal' for all remaining property types,
|
|
265
|
-
// matching the @Property decorator behaviour. Without this, string values
|
|
266
|
-
// stored as literal: URLs are returned unparsed.
|
|
267
|
-
if (resolveLanguage === undefined || resolveLanguage === null) {
|
|
268
|
-
resolveLanguage = 'literal';
|
|
269
|
-
}
|
|
270
|
-
// If property is required, ensure it has an initial value
|
|
271
257
|
if (isRequired && !initial) {
|
|
272
258
|
if (isObjectType(propertySchema)) {
|
|
273
259
|
initial = 'literal:json:{}';
|
|
@@ -280,7 +266,7 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
|
|
|
280
266
|
through: predicate,
|
|
281
267
|
required: isRequired,
|
|
282
268
|
writable: writable,
|
|
283
|
-
...(resolveLanguage && { resolveLanguage }),
|
|
269
|
+
...(resolveLanguage !== undefined && { resolveLanguage }),
|
|
284
270
|
...(local !== undefined && { local }),
|
|
285
271
|
...(initial && { initial })
|
|
286
272
|
};
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Shared query helpers used by both the Prolog and SPARQL query pipelines.
|
|
3
3
|
*/
|
|
4
|
-
import type {
|
|
4
|
+
import type { Scope } from "./types";
|
|
5
5
|
/**
|
|
6
6
|
* Resolves the predicate for a parent query.
|
|
7
7
|
*
|
|
@@ -11,4 +11,4 @@ import type { ParentScope } from "./types";
|
|
|
11
11
|
* - With `field`: direct key lookup
|
|
12
12
|
* - Without `field`: scan for a relation whose `target()` matches `childCtor`
|
|
13
13
|
*/
|
|
14
|
-
export declare function resolveParentPredicate(parent:
|
|
14
|
+
export declare function resolveParentPredicate(parent: Scope, childCtor: Function): string;
|