@coasys/ad4m 0.12.0-rc1-dev.4 → 0.12.0-rc2

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.
Files changed (166) hide show
  1. package/lib/index.cjs +5052 -4446
  2. package/lib/index.js +5019 -4442
  3. package/lib/src/agent/AgentClient.d.ts +4 -0
  4. package/lib/src/agent/AgentClient.js +34 -0
  5. package/lib/src/index.d.ts +2 -3
  6. package/lib/src/index.js +2 -3
  7. package/lib/src/model/Ad4mModel.d.ts +8 -782
  8. package/lib/src/model/Ad4mModel.js +160 -2354
  9. package/lib/src/model/ModelQueryBuilder.d.ts +370 -0
  10. package/lib/src/model/ModelQueryBuilder.js +556 -0
  11. package/lib/src/model/decorators.d.ts +71 -23
  12. package/lib/src/model/decorators.js +133 -384
  13. package/lib/src/model/hydration.d.ts +102 -0
  14. package/lib/src/model/hydration.js +709 -0
  15. package/lib/src/model/index.d.ts +20 -0
  16. package/lib/src/model/index.js +20 -0
  17. package/lib/src/model/{schema/fromJSONSchema.d.ts → json-schema.d.ts} +45 -12
  18. package/lib/src/model/json-schema.js +326 -0
  19. package/lib/src/model/prolog-facts.d.ts +37 -0
  20. package/lib/src/model/{prolog/generatePrologFacts.js → prolog-facts.js} +47 -52
  21. package/lib/src/model/query-common.d.ts +14 -0
  22. package/lib/src/model/query-common.js +36 -0
  23. package/lib/src/model/query-prolog.d.ts +15 -0
  24. package/lib/src/model/query-prolog.js +140 -0
  25. package/lib/src/model/query-surreal.d.ts +44 -0
  26. package/lib/src/model/query-surreal.js +249 -0
  27. package/lib/src/model/relation-filtering.test.js +838 -0
  28. package/lib/src/model/sdna.d.ts +14 -0
  29. package/lib/src/model/sdna.js +141 -0
  30. package/lib/src/model/shacl-gen.d.ts +31 -0
  31. package/lib/src/model/shacl-gen.js +246 -0
  32. package/lib/src/model/surreal-utils.d.ts +42 -0
  33. package/lib/src/model/surreal-utils.js +128 -0
  34. package/lib/src/model/types.d.ts +75 -96
  35. package/lib/src/model/types.js +4 -4
  36. package/lib/src/model/util.d.ts +4 -5
  37. package/lib/src/model/util.js +12 -32
  38. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -1
  39. package/lib/src/perspectives/PerspectiveProxy.d.ts +1 -1
  40. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +79 -0
  41. package/lib/src/perspectives/WakerSubscriptionManager.js +196 -0
  42. package/lib/src/runtime/RuntimeResolver.d.ts +14 -0
  43. package/lib/src/runtime/RuntimeResolver.js +73 -0
  44. package/lib/src/schema.gql +14 -0
  45. package/lib/src/shacl/SHACLShape.d.ts +23 -0
  46. package/lib/src/shacl/SHACLShape.js +45 -0
  47. package/lib/src/typeDefs.js +14 -0
  48. package/package.json +13 -8
  49. package/src/agent/AgentClient.ts +45 -0
  50. package/src/index.ts +2 -3
  51. package/src/model/Ad4mModel.ts +1089 -3686
  52. package/src/model/ModelQueryBuilder.ts +617 -0
  53. package/src/model/Subject.ts +1 -1
  54. package/src/model/decorators.ts +218 -453
  55. package/src/model/hydration.ts +796 -0
  56. package/src/model/index.ts +21 -0
  57. package/src/model/json-schema.ts +424 -0
  58. package/src/model/prolog-facts.ts +145 -0
  59. package/src/model/query-common.ts +48 -0
  60. package/src/model/query-prolog.ts +148 -0
  61. package/src/model/query-surreal.ts +280 -0
  62. package/src/model/relation-filtering.test.ts +803 -0
  63. package/src/model/sdna.ts +170 -0
  64. package/src/model/shacl-gen.ts +292 -0
  65. package/src/model/surreal-utils.ts +147 -0
  66. package/src/model/types.ts +182 -0
  67. package/src/model/util.ts +13 -36
  68. package/src/perspectives/PerspectiveClient.ts +1 -1
  69. package/src/perspectives/PerspectiveProxy.ts +1 -1
  70. package/src/perspectives/WakerSubscriptionManager.ts +292 -0
  71. package/src/runtime/RuntimeResolver.ts +53 -0
  72. package/src/shacl/SHACLShape.ts +83 -0
  73. package/lib/src/Ad4mClient.test.js +0 -1204
  74. package/lib/src/Literal.test.d.ts +0 -1
  75. package/lib/src/Literal.test.js +0 -41
  76. package/lib/src/model/mutation.d.ts +0 -81
  77. package/lib/src/model/mutation.js +0 -317
  78. package/lib/src/model/parentUtils.d.ts +0 -32
  79. package/lib/src/model/parentUtils.js +0 -64
  80. package/lib/src/model/prolog/generatePrologFacts.d.ts +0 -36
  81. package/lib/src/model/prolog/index.d.ts +0 -1
  82. package/lib/src/model/prolog/index.js +0 -1
  83. package/lib/src/model/query/ModelQueryBuilder.d.ts +0 -82
  84. package/lib/src/model/query/ModelQueryBuilder.js +0 -115
  85. package/lib/src/model/query/QueryBuilder.d.ts +0 -101
  86. package/lib/src/model/query/QueryBuilder.js +0 -193
  87. package/lib/src/model/query/SurrealQueryBuilder.d.ts +0 -48
  88. package/lib/src/model/query/SurrealQueryBuilder.js +0 -371
  89. package/lib/src/model/query/fetchInstance.d.ts +0 -24
  90. package/lib/src/model/query/fetchInstance.js +0 -144
  91. package/lib/src/model/query/hydration.d.ts +0 -54
  92. package/lib/src/model/query/hydration.js +0 -214
  93. package/lib/src/model/query/operations.d.ts +0 -59
  94. package/lib/src/model/query/operations.js +0 -384
  95. package/lib/src/model/query/snapshot.d.ts +0 -59
  96. package/lib/src/model/query/snapshot.js +0 -106
  97. package/lib/src/model/query/surrealCompiler.d.ts +0 -42
  98. package/lib/src/model/query/surrealCompiler.js +0 -304
  99. package/lib/src/model/schema/fromJSONSchema.js +0 -264
  100. package/lib/src/model/schema/metadata.d.ts +0 -15
  101. package/lib/src/model/schema/metadata.js +0 -112
  102. package/lib/src/model/subscription.d.ts +0 -47
  103. package/lib/src/model/subscription.js +0 -231
  104. package/lib/src/model/transaction.d.ts +0 -27
  105. package/lib/src/model/transaction.js +0 -32
  106. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  107. package/lib/src/shims/type-graphql.d.ts +0 -32
  108. package/lib/src/src/Ad4mClient.d.ts +0 -28
  109. package/lib/src/src/Address.d.ts +0 -1
  110. package/lib/src/src/DID.d.ts +0 -1
  111. package/lib/src/src/Exception.d.ts +0 -7
  112. package/lib/src/src/Literal.d.ts +0 -7
  113. package/lib/src/src/PubSub.d.ts +0 -17
  114. package/lib/src/src/SmartLiteral.d.ts +0 -12
  115. package/lib/src/src/agent/Agent.d.ts +0 -110
  116. package/lib/src/src/agent/AgentClient.d.ts +0 -62
  117. package/lib/src/src/agent/AgentResolver.d.ts +0 -30
  118. package/lib/src/src/agent/AgentStatus.d.ts +0 -8
  119. package/lib/src/src/ai/AIClient.d.ts +0 -32
  120. package/lib/src/src/ai/AIResolver.d.ts +0 -75
  121. package/lib/src/src/ai/Tasks.d.ts +0 -37
  122. package/lib/src/src/buildSchema.d.ts +0 -1
  123. package/lib/src/src/expression/Expression.d.ts +0 -28
  124. package/lib/src/src/expression/ExpressionClient.d.ts +0 -13
  125. package/lib/src/src/expression/ExpressionRef.d.ts +0 -9
  126. package/lib/src/src/expression/ExpressionResolver.d.ts +0 -10
  127. package/lib/src/src/index.d.ts +0 -35
  128. package/lib/src/src/jestSetup.d.ts +0 -1
  129. package/lib/src/src/language/Icon.d.ts +0 -4
  130. package/lib/src/src/language/Language.d.ts +0 -206
  131. package/lib/src/src/language/LanguageClient.d.ts +0 -17
  132. package/lib/src/src/language/LanguageContext.d.ts +0 -37
  133. package/lib/src/src/language/LanguageHandle.d.ts +0 -9
  134. package/lib/src/src/language/LanguageMeta.d.ts +0 -35
  135. package/lib/src/src/language/LanguageRef.d.ts +0 -6
  136. package/lib/src/src/language/LanguageResolver.d.ts +0 -19
  137. package/lib/src/src/links/Links.d.ts +0 -39
  138. package/lib/src/src/links/Links.test.d.ts +0 -1
  139. package/lib/src/src/model/Ad4mModel.d.ts +0 -1438
  140. package/lib/src/src/model/Ad4mModel.test.d.ts +0 -1
  141. package/lib/src/src/model/Subject.d.ts +0 -25
  142. package/lib/src/src/model/decorators.d.ts +0 -545
  143. package/lib/src/src/model/util.d.ts +0 -12
  144. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +0 -10
  145. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +0 -25
  146. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +0 -19
  147. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +0 -1
  148. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +0 -24
  149. package/lib/src/src/perspectives/LinkQuery.d.ts +0 -11
  150. package/lib/src/src/perspectives/Perspective.d.ts +0 -38
  151. package/lib/src/src/perspectives/Perspective.test.d.ts +0 -1
  152. package/lib/src/src/perspectives/PerspectiveClient.d.ts +0 -97
  153. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +0 -9
  154. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +0 -18
  155. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +0 -865
  156. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +0 -57
  157. package/lib/src/src/runtime/RuntimeClient.d.ts +0 -56
  158. package/lib/src/src/runtime/RuntimeResolver.d.ts +0 -132
  159. package/lib/src/src/shacl/SHACLFlow.d.ts +0 -171
  160. package/lib/src/src/shacl/SHACLFlow.test.d.ts +0 -1
  161. package/lib/src/src/shacl/SHACLShape.d.ts +0 -117
  162. package/lib/src/src/shacl/SHACLShape.test.d.ts +0 -1
  163. package/lib/src/src/typeDefs.d.ts +0 -1
  164. package/lib/src/src/unwrapApolloResult.d.ts +0 -2
  165. package/lib/src/src/utils.d.ts +0 -25
  166. /package/lib/src/{Ad4mClient.test.d.ts → model/relation-filtering.test.d.ts} +0 -0
@@ -1,5 +1,7 @@
1
- import { capitalize, propertyNameToSetterName, stringifyObjectLiteral } from "./util";
2
- import { SHACLShape } from "../shacl/SHACLShape";
1
+ import { capitalize } from "./util";
2
+ import { buildSDNA } from "./sdna";
3
+ import { buildSHACL } from "./shacl-gen";
4
+ import { escapeSurrealString } from "../utils";
3
5
  /** Registry of property metadata keyed by constructor → { propName → metadata } */
4
6
  const propertyRegistry = new WeakMap();
5
7
  /** Registry of relation metadata keyed by constructor → { propName → metadata } */
@@ -61,43 +63,55 @@ export function setRelationRegistryEntry(ctor, relName, meta) {
61
63
  relationRegistry.get(ctor)[relName] = meta;
62
64
  }
63
65
  /**
64
- * Convert a model instance to a plain serializable object.
65
- * Reads the property metadata and extracts values from the instance.
66
+ * Build a conformance filter for a relation whose target model is known.
67
+ *
68
+ * Inspects the target class's property metadata to derive:
69
+ * - `conformanceConditions`: Structured, DB-agnostic conditions (flag & required checks)
70
+ * - `getter`: Pre-computed SurrealQL expression that traverses outgoing links and filters
71
+ * target nodes to only those conforming to the target shape.
72
+ *
73
+ * @param relationPredicate - The relation's predicate URI (e.g. "flux://entry_type")
74
+ * @param targetClass - The target model class (resolved from the target() thunk)
75
+ * @returns `{ getter, conformanceConditions }` or `undefined` if no conditions could be derived
66
76
  */
67
- export function instanceToSerializable(instance) {
68
- const ctor = instance.constructor;
69
- const props = getPropertiesMetadata(ctor);
70
- const result = {};
71
- for (const [key, _meta] of Object.entries(props)) {
72
- result[key] = instance[key];
77
+ export function buildConformanceFilter(relationPredicate, targetClass) {
78
+ try {
79
+ const targetProps = getPropertiesMetadata(targetClass);
80
+ const conditions = [];
81
+ const surrealConditions = [];
82
+ // 1. Flags — check predicate + value
83
+ for (const [_propName, propMeta] of Object.entries(targetProps)) {
84
+ if (propMeta.flag && propMeta.initial && propMeta.through) {
85
+ conditions.push({
86
+ type: 'flag',
87
+ predicate: propMeta.through,
88
+ value: propMeta.initial,
89
+ });
90
+ surrealConditions.push(`count(->link[WHERE predicate = '${escapeSurrealString(propMeta.through)}' AND out.uri = '${escapeSurrealString(propMeta.initial)}']) > 0`);
91
+ }
92
+ }
93
+ // 2. Required (non-flag) properties — check predicate exists
94
+ // Skip properties with custom getters (they don't follow the standard link pattern)
95
+ for (const [_propName, propMeta] of Object.entries(targetProps)) {
96
+ if (propMeta.required && !propMeta.flag && !propMeta.getter && propMeta.through) {
97
+ conditions.push({
98
+ type: 'required',
99
+ predicate: propMeta.through,
100
+ });
101
+ surrealConditions.push(`count(->link[WHERE predicate = '${escapeSurrealString(propMeta.through)}']) > 0`);
102
+ }
103
+ }
104
+ if (conditions.length === 0) {
105
+ return undefined;
106
+ }
107
+ const escapedPredicate = escapeSurrealString(relationPredicate);
108
+ const getter = `(->link[WHERE predicate = '${escapedPredicate}'].out[WHERE ${surrealConditions.join(' AND ')}].uri)`;
109
+ return { getter, conformanceConditions: conditions };
73
110
  }
74
- return result;
75
- }
76
- /**
77
- * Generate a random identifier string (lowercase alpha).
78
- * Generate a random identifier string of the given length (lowercase alpha).
79
- */
80
- export function makeRandomId(length) {
81
- let result = '';
82
- const characters = 'abcdefghijklmnopqrstuvwxyz';
83
- const charactersLength = characters.length;
84
- for (let i = 0; i < length; i++) {
85
- result += characters.charAt(Math.floor(Math.random() * charactersLength));
111
+ catch (e) {
112
+ // Target class may not have property metadata
113
+ return undefined;
86
114
  }
87
- return result;
88
- }
89
- export class PerspectiveAction {
90
- }
91
- export function addLink(source, predicate, target) {
92
- return {
93
- action: "addLink",
94
- source,
95
- predicate,
96
- target,
97
- };
98
- }
99
- export function hasLink(predicate) {
100
- return `triple(this, "${predicate}", _)`;
101
115
  }
102
116
  /**
103
117
  * Internal core implementation for registering property metadata on the prototype.
@@ -295,322 +309,10 @@ export function Model(opts) {
295
309
  target.prototype.className = opts.name;
296
310
  target.className = opts.name;
297
311
  target.generateSDNA = function () {
298
- let sdna = "";
299
- let subjectName = opts.name;
300
- let obj = target.prototype;
301
- let uuid = makeRandomId(8);
302
- sdna += `subject_class("${subjectName}", ${uuid}).\n`;
303
- let classRemoverActions = [];
304
- let constructorActions = [];
305
- if (obj.subjectConstructor && obj.subjectConstructor.length) {
306
- constructorActions = constructorActions.concat(obj.subjectConstructor);
307
- }
308
- let instanceConditions = [];
309
- if (obj.isSubjectInstance && obj.isSubjectInstance.length) {
310
- instanceConditions = instanceConditions.concat(obj.isSubjectInstance);
311
- }
312
- let propertiesCode = [];
313
- let properties = getPropertiesMetadata(target);
314
- for (let property in properties) {
315
- let propertyCode = `property(${uuid}, "${property}").\n`;
316
- let { through, initial, required, resolveLanguage, writable, flag, prologGetter, prologSetter, local } = properties[property];
317
- if (resolveLanguage) {
318
- propertyCode += `property_resolve(${uuid}, "${property}").\n`;
319
- propertyCode += `property_resolve_language(${uuid}, "${property}", "${resolveLanguage}").\n`;
320
- }
321
- if (prologGetter) {
322
- propertyCode += `property_getter(${uuid}, Base, "${property}", Value) :- ${prologGetter}.\n`;
323
- }
324
- else if (through) {
325
- propertyCode += `property_getter(${uuid}, Base, "${property}", Value) :- triple(Base, "${through}", Value).\n`;
326
- if (required) {
327
- if (flag) {
328
- instanceConditions.push(`triple(Base, "${through}", "${initial}")`);
329
- }
330
- else {
331
- instanceConditions.push(`triple(Base, "${through}", _)`);
332
- }
333
- }
334
- }
335
- if (prologSetter) {
336
- propertyCode += `property_setter(${uuid}, "${property}", Actions) :- ${prologSetter}.\n`;
337
- }
338
- else if (writable && through) {
339
- let setter = obj[propertyNameToSetterName(property)];
340
- if (typeof setter === "function") {
341
- let action = [{
342
- action: "setSingleTarget",
343
- source: "this",
344
- predicate: through,
345
- target: "value",
346
- ...(local && { local: true })
347
- }];
348
- propertyCode += `property_setter(${uuid}, "${property}", '${stringifyObjectLiteral(action)}').\n`;
349
- }
350
- }
351
- propertiesCode.push(propertyCode);
352
- // Auto-derive effectiveInitial for required, writable, non-flag properties
353
- // so constructor/destructor always handle the property link.
354
- // Optional properties (required: false) are excluded — they should
355
- // remain unset (undefined) until explicitly assigned.
356
- const effectiveInitial = initial
357
- ?? (required && writable && !flag && through ? "literal://string:" : undefined);
358
- if (effectiveInitial) {
359
- constructorActions.push({
360
- action: "addLink",
361
- source: "this",
362
- predicate: through,
363
- target: effectiveInitial,
364
- });
365
- classRemoverActions.push({
366
- action: "removeLink",
367
- source: "this",
368
- predicate: through,
369
- target: "*",
370
- });
371
- }
372
- }
373
- let relationsCode = [];
374
- const allRelationsMeta = getRelationsMetadata(target);
375
- const relations = Object.fromEntries(Object.entries(allRelationsMeta).filter(([, r]) => r.kind === 'hasMany' || r.kind === 'belongsToMany'));
376
- for (let relation in relations) {
377
- let relationCode = `collection(${uuid}, "${relation}").\n`;
378
- let { predicate: through, local } = relations[relation];
379
- if (through) {
380
- relationCode += `collection_getter(${uuid}, Base, "${relation}", List) :- findall(C, triple(Base, "${through}", C), List).\n`;
381
- let relationAdderAction = [{
382
- action: "addLink",
383
- source: "this",
384
- predicate: through,
385
- target: "value",
386
- ...(local && { local: true })
387
- }];
388
- let relationRemoverAction = [{
389
- action: "removeLink",
390
- source: "this",
391
- predicate: through,
392
- target: "value",
393
- }];
394
- let relationSetterAction = [{
395
- action: "collectionSetter",
396
- source: "this",
397
- predicate: through,
398
- target: "value",
399
- ...(local && { local: true })
400
- }];
401
- relationCode += `collection_adder(${uuid}, "${relation}", '${stringifyObjectLiteral(relationAdderAction)}').\n`;
402
- relationCode += `collection_remover(${uuid}, "${relation}", '${stringifyObjectLiteral(relationRemoverAction)}').\n`;
403
- relationCode += `collection_setter(${uuid}, "${relation}", '${stringifyObjectLiteral(relationSetterAction)}').\n`;
404
- }
405
- relationsCode.push(relationCode);
406
- }
407
- let subjectContructorJSONString = stringifyObjectLiteral(constructorActions);
408
- sdna += `constructor(${uuid}, '${subjectContructorJSONString}').\n`;
409
- if (instanceConditions.length > 0) {
410
- let instanceConditionProlog = instanceConditions.join(", ");
411
- sdna += `instance(${uuid}, Base) :- ${instanceConditionProlog}.\n`;
412
- sdna += "\n";
413
- }
414
- sdna += `destructor(${uuid}, '${stringifyObjectLiteral(classRemoverActions)}').\n`;
415
- sdna += "\n";
416
- sdna += propertiesCode.join("\n");
417
- sdna += "\n";
418
- sdna += relationsCode.join("\n");
419
- return {
420
- sdna,
421
- name: subjectName
422
- };
312
+ return buildSDNA(opts.name, target.prototype, getPropertiesMetadata(target), getRelationsMetadata(target));
423
313
  };
424
- // Generate SHACL shape (W3C standard + AD4M action definitions)
425
314
  target.generateSHACL = function () {
426
- const subjectName = opts.name;
427
- const obj = target.prototype;
428
- // Determine namespace from first property or relation, or use default
429
- let namespace = "ad4m://";
430
- const properties = getPropertiesMetadata(target);
431
- const allRelationsMeta2 = getRelationsMetadata(target);
432
- const relations = Object.fromEntries(Object.entries(allRelationsMeta2).filter(([, r]) => r.kind === 'hasMany' || r.kind === 'belongsToMany'));
433
- // Try properties first
434
- if (Object.keys(properties).length > 0) {
435
- const firstProp = properties[Object.keys(properties)[0]];
436
- if (firstProp.through) {
437
- // Extract namespace from through predicate (e.g., "recipe://name" -> "recipe://")
438
- const match = firstProp.through.match(/^([^:]+:\/\/)/);
439
- if (match) {
440
- namespace = match[1];
441
- }
442
- }
443
- }
444
- // Fall back to relations if no properties
445
- else if (Object.keys(relations).length > 0) {
446
- const firstRel = relations[Object.keys(relations)[0]];
447
- if (firstRel.predicate) {
448
- const match = firstRel.predicate.match(/^([^:]+:\/\/)/);
449
- if (match) {
450
- namespace = match[1];
451
- }
452
- }
453
- }
454
- // Create SHACL shape
455
- const shapeUri = `${namespace}${subjectName}Shape`;
456
- const targetClass = `${namespace}${subjectName}`;
457
- const shape = new SHACLShape(shapeUri, targetClass);
458
- // Detect @Model inheritance — if the parent class also has
459
- // generateSHACL it is itself a @Model and we reference its shape
460
- // via sh:node so SHACL validators can walk the hierarchy.
461
- const parentCtor = Object.getPrototypeOf(target);
462
- if (parentCtor && typeof parentCtor.generateSHACL === 'function') {
463
- const parentSHACL = parentCtor.generateSHACL();
464
- if (parentSHACL?.shape?.nodeShapeUri) {
465
- shape.addParentShape(parentSHACL.shape.nodeShapeUri);
466
- }
467
- }
468
- // === Extract Constructor Actions (same logic as generateSDNA) ===
469
- let constructorActions = [];
470
- if (obj.subjectConstructor && obj.subjectConstructor.length) {
471
- constructorActions = constructorActions.concat(obj.subjectConstructor);
472
- }
473
- // === Extract Destructor Actions ===
474
- let destructorActions = [];
475
- // Convert properties to SHACL property shapes
476
- for (const propName in properties) {
477
- const propMeta = properties[propName];
478
- if (!propMeta.through)
479
- continue; // Skip properties without predicates
480
- const propShape = {
481
- name: propName,
482
- path: propMeta.through,
483
- };
484
- // Determine datatype from initial value or resolveLanguage
485
- if (propMeta.resolveLanguage === "literal") {
486
- // If it resolves via literal language, it's likely a string
487
- propShape.datatype = "xsd://string";
488
- }
489
- else if (propMeta.initial) {
490
- // Try to infer from initial value type
491
- const initialType = typeof obj[propName];
492
- if (initialType === "number") {
493
- propShape.datatype = "xsd://integer";
494
- }
495
- else if (initialType === "boolean") {
496
- propShape.datatype = "xsd://boolean";
497
- }
498
- else if (initialType === "string") {
499
- propShape.datatype = "xsd://string";
500
- }
501
- }
502
- // Cardinality constraints
503
- if (propMeta.required) {
504
- propShape.minCount = 1;
505
- }
506
- // Single-valued properties get maxCount 1
507
- // (relations are handled separately below)
508
- propShape.maxCount = 1;
509
- // Flag properties have fixed value
510
- if (propMeta.flag && propMeta.initial) {
511
- propShape.hasValue = propMeta.initial;
512
- }
513
- // AD4M-specific metadata
514
- if (propMeta.local !== undefined) {
515
- propShape.local = propMeta.local;
516
- }
517
- if (propMeta.writable !== undefined) {
518
- propShape.writable = propMeta.writable;
519
- }
520
- if (propMeta.resolveLanguage) {
521
- propShape.resolveLanguage = propMeta.resolveLanguage;
522
- }
523
- // === Extract Setter Actions (same logic as generateSDNA) ===
524
- if (propMeta.prologSetter) {
525
- // Custom Prolog setter defined - not yet supported in SHACL
526
- console.warn(`[SHACL Generation] Custom Prolog setter for property '${propName}' in class '${subjectName}' is not yet supported. ` +
527
- `The property will be created without setter actions. Consider using standard writable properties or provide explicit SHACL JSON.`);
528
- // TODO: Parse custom Prolog setter to extract actions
529
- }
530
- else if (propMeta.writable && propMeta.through) {
531
- let setter = obj[propertyNameToSetterName(propName)];
532
- if (typeof setter === "function") {
533
- propShape.setter = [{
534
- action: "setSingleTarget",
535
- source: "this",
536
- predicate: propMeta.through,
537
- target: "value",
538
- ...(propMeta.local && { local: true })
539
- }];
540
- }
541
- }
542
- // Add to constructor actions if property has initial value
543
- // Auto-derive effectiveInitial for required, writable, non-flag properties.
544
- // Optional properties (required: false) are excluded — they should
545
- // remain unset (undefined) until explicitly assigned.
546
- const effectiveInitial = propMeta.initial
547
- ?? (propMeta.required && propMeta.writable && !propMeta.flag && propMeta.through
548
- ? "literal://string:" : undefined);
549
- if (effectiveInitial) {
550
- constructorActions.push({
551
- action: "addLink",
552
- source: "this",
553
- predicate: propMeta.through,
554
- target: effectiveInitial,
555
- });
556
- // Add to destructor actions
557
- destructorActions.push({
558
- action: "removeLink",
559
- source: "this",
560
- predicate: propMeta.through,
561
- target: "*",
562
- });
563
- }
564
- shape.addProperty(propShape);
565
- }
566
- // Convert relations to SHACL property shapes
567
- // (relations variable already declared above for namespace inference)
568
- for (const relName in relations) {
569
- const relMeta = relations[relName];
570
- if (!relMeta.predicate)
571
- continue;
572
- const relShape = {
573
- name: relName,
574
- path: relMeta.predicate,
575
- // Relations have no maxCount (unlimited)
576
- // minCount defaults to 0 (optional)
577
- };
578
- // Determine node kind — relations typically contain IRIs
579
- relShape.nodeKind = 'IRI';
580
- // AD4M-specific metadata
581
- if (relMeta.local !== undefined) {
582
- relShape.local = relMeta.local;
583
- }
584
- // === Extract Relation Actions (adder/remover) ===
585
- // Adder action - adds a link to the relation
586
- relShape.adder = [{
587
- action: "addLink",
588
- source: "this",
589
- predicate: relMeta.predicate,
590
- target: "value",
591
- ...(relMeta.local && { local: true })
592
- }];
593
- // Remover action - removes a link from the relation
594
- relShape.remover = [{
595
- action: "removeLink",
596
- source: "this",
597
- predicate: relMeta.predicate,
598
- target: "value",
599
- ...(relMeta.local && { local: true })
600
- }];
601
- shape.addProperty(relShape);
602
- }
603
- // Always set constructor and destructor actions on the shape, even
604
- // when empty. An empty array serialises to `literal://string:[]`
605
- // which the Rust executor parses as a valid (no-op) command list,
606
- // avoiding "No SHACL constructor found" errors for models whose
607
- // properties are all optional and have no @Flag.
608
- shape.setConstructorActions(constructorActions);
609
- shape.setDestructorActions(destructorActions);
610
- return {
611
- shape,
612
- name: subjectName
613
- };
315
+ return buildSHACL(opts.name, target, getPropertiesMetadata(target), getRelationsMetadata(target), buildConformanceFilter);
614
316
  };
615
317
  Object.defineProperty(target, 'type', { configurable: true });
616
318
  };
@@ -758,10 +460,36 @@ export function ReadOnly(opts) {
758
460
  */
759
461
  function resolveRelationArgs(first, second) {
760
462
  const opts = typeof first === 'function'
761
- ? { ...second, target: first }
463
+ ? { ...(second || {}), target: first }
762
464
  : first;
465
+ // getter is mutually exclusive with through, target, and where
466
+ if (opts.getter) {
467
+ if (opts.through) {
468
+ throw new Error('Relation decorator: `getter` and `through` are mutually exclusive. ' +
469
+ 'Use `getter` alone for custom read-only relations, or `through` ' +
470
+ '(with optional `target`) for standard link-based relations.');
471
+ }
472
+ if (opts.target) {
473
+ throw new Error('Relation decorator: `getter` and `target` are mutually exclusive. ' +
474
+ '`target` auto-generates a conformance getter from the model shape; ' +
475
+ 'providing both is contradictory.');
476
+ }
477
+ if (opts.where) {
478
+ throw new Error('Relation decorator: `where` and `getter` are mutually exclusive. ' +
479
+ 'Use `where` for DSL-based filtering, or `getter` for raw SurrealQL.');
480
+ }
481
+ return opts;
482
+ }
483
+ // Default predicate when not provided
763
484
  if (!opts.through) {
764
- throw new Error(`Relation decorator requires a { through: '...' } option specifying the predicate URI.`);
485
+ opts.through = 'ad4m://has_child';
486
+ }
487
+ // where validation
488
+ if (opts.where) {
489
+ if (opts.filter === false) {
490
+ throw new Error('Relation decorator: `where` and `filter: false` are contradictory. ' +
491
+ '`where` adds filtering constraints; `filter: false` disables filtering.');
492
+ }
765
493
  }
766
494
  return opts;
767
495
  }
@@ -779,18 +507,23 @@ export function HasMany(first, second) {
779
507
  kind: 'hasMany',
780
508
  local: opts.local,
781
509
  ...(opts.getter && { getter: opts.getter }),
510
+ ...(opts.filter !== undefined && { filter: opts.filter }),
511
+ ...(opts.where && { where: opts.where }),
782
512
  };
783
- // Add prototype methods for add/remove/set
784
513
  const relKey = key;
785
- target[`add${capitalize(relKey)}`] = async function (arg, batchId) {
786
- return this.addRelationValue(relKey, arg, batchId);
787
- };
788
- target[`remove${capitalize(relKey)}`] = async function (arg, batchId) {
789
- return this.removeRelationValue(relKey, arg, batchId);
790
- };
791
- target[`set${capitalize(relKey)}`] = async function (arg, batchId) {
792
- return this.setRelationValues(relKey, arg, batchId);
793
- };
514
+ // Only add mutation methods when a predicate is available
515
+ // (getter-only relations are read-only)
516
+ if (opts.through) {
517
+ target[`add${capitalize(relKey)}`] = async function (arg, batchId) {
518
+ return this.addRelationValue(relKey, arg, batchId);
519
+ };
520
+ target[`remove${capitalize(relKey)}`] = async function (arg, batchId) {
521
+ return this.removeRelationValue(relKey, arg, batchId);
522
+ };
523
+ target[`set${capitalize(relKey)}`] = async function (arg, batchId) {
524
+ return this.setRelationValues(relKey, arg, batchId);
525
+ };
526
+ }
794
527
  Object.defineProperty(target, relKey, { configurable: true, writable: true });
795
528
  };
796
529
  }
@@ -807,24 +540,31 @@ export function HasOne(first, second) {
807
540
  kind: 'hasOne',
808
541
  maxCount: 1,
809
542
  local: opts.local,
543
+ ...(opts.filter !== undefined && { filter: opts.filter }),
544
+ ...(opts.where && { where: opts.where }),
810
545
  };
811
- // Register as a writable property
812
- applyPropertyMetadata({
813
- through: opts.through,
814
- readOnly: false,
815
- local: opts.local,
816
- })(target, key);
817
- // Add prototype methods for add/remove/set (mirroring @HasMany)
818
546
  const relKey = key;
819
- target[`add${capitalize(relKey)}`] = async function (arg) {
820
- return this.addRelationValue(relKey, arg);
821
- };
822
- target[`remove${capitalize(relKey)}`] = async function (arg) {
823
- return this.removeRelationValue(relKey, arg);
824
- };
825
- target[`set${capitalize(relKey)}`] = async function (arg) {
826
- return this.setRelationValues(relKey, arg);
827
- };
547
+ if (opts.through) {
548
+ // Register as a writable property
549
+ applyPropertyMetadata({
550
+ through: opts.through,
551
+ readOnly: false,
552
+ local: opts.local,
553
+ })(target, key);
554
+ // Add prototype methods for add/remove/set (mirroring @HasMany)
555
+ target[`add${capitalize(relKey)}`] = async function (arg) {
556
+ return this.addRelationValue(relKey, arg);
557
+ };
558
+ target[`remove${capitalize(relKey)}`] = async function (arg) {
559
+ return this.removeRelationValue(relKey, arg);
560
+ };
561
+ target[`set${capitalize(relKey)}`] = async function (arg) {
562
+ return this.setRelationValues(relKey, arg);
563
+ };
564
+ }
565
+ else {
566
+ Object.defineProperty(target, relKey, { configurable: true, writable: true });
567
+ }
828
568
  };
829
569
  }
830
570
  export function BelongsToOne(first, second) {
@@ -840,13 +580,20 @@ export function BelongsToOne(first, second) {
840
580
  kind: 'belongsToOne',
841
581
  maxCount: 1,
842
582
  local: opts.local,
583
+ ...(opts.filter !== undefined && { filter: opts.filter }),
584
+ ...(opts.where && { where: opts.where }),
843
585
  };
844
- // Read-only property (the owning side manages the link)
845
- applyPropertyMetadata({
846
- through: opts.through,
847
- readOnly: true,
848
- local: opts.local,
849
- })(target, key);
586
+ if (opts.through) {
587
+ // Read-only property (the owning side manages the link)
588
+ applyPropertyMetadata({
589
+ through: opts.through,
590
+ readOnly: true,
591
+ local: opts.local,
592
+ })(target, key);
593
+ }
594
+ else {
595
+ Object.defineProperty(target, key, { configurable: true, writable: true });
596
+ }
850
597
  };
851
598
  }
852
599
  export function BelongsToMany(first, second) {
@@ -862,6 +609,8 @@ export function BelongsToMany(first, second) {
862
609
  kind: 'belongsToMany',
863
610
  local: opts.local,
864
611
  ...(opts.getter && { getter: opts.getter }),
612
+ ...(opts.filter !== undefined && { filter: opts.filter }),
613
+ ...(opts.where && { where: opts.where }),
865
614
  };
866
615
  // @BelongsToMany is the inverse/read-only side — do NOT generate add*/remove*/set*
867
616
  // prototype methods. Mutation must go through the owning side's @HasMany decorator.