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

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.
@@ -1,5 +1,7 @@
1
1
  import { capitalize, propertyNameToSetterName, stringifyObjectLiteral } from "./util";
2
2
  import { SHACLShape } from "../shacl/SHACLShape";
3
+ import { escapeSurrealString } from "../utils";
4
+ import { compileWhereClause } from "./surreal-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 } */
@@ -60,6 +62,57 @@ export function setRelationRegistryEntry(ctor, relName, meta) {
60
62
  relationRegistry.set(ctor, {});
61
63
  relationRegistry.get(ctor)[relName] = meta;
62
64
  }
65
+ /**
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
76
+ */
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 };
110
+ }
111
+ catch (e) {
112
+ // Target class may not have property metadata
113
+ return undefined;
114
+ }
115
+ }
63
116
  /**
64
117
  * Convert a model instance to a plain serializable object.
65
118
  * Reads the property metadata and extracts values from the instance.
@@ -598,6 +651,60 @@ export function Model(opts) {
598
651
  target: "value",
599
652
  ...(relMeta.local && { local: true })
600
653
  }];
654
+ // === Build Getter (conformance filter) ===
655
+ // Priority chain:
656
+ // 1. Explicit getter string → use verbatim
657
+ // 2. `where` clause → compile DSL to SurrealQL getter
658
+ // 3. target + filter !== false → auto-derive from shape
659
+ if (relMeta.getter) {
660
+ relShape.getter = relMeta.getter;
661
+ }
662
+ else if (relMeta.where) {
663
+ // Compile Where DSL → SurrealQL getter
664
+ try {
665
+ const TargetClass = relMeta.target?.();
666
+ const targetMetadata = TargetClass
667
+ ? TargetClass.getModelMetadata?.() ?? null
668
+ : null;
669
+ const conditions = compileWhereClause(relMeta.where, targetMetadata);
670
+ if (conditions.length > 0) {
671
+ const escapedPredicate = escapeSurrealString(relMeta.predicate);
672
+ relShape.getter = `(->link[WHERE predicate = '${escapedPredicate}'].out[WHERE ${conditions.join(' AND ')}].uri)`;
673
+ }
674
+ }
675
+ catch (e) {
676
+ // Target metadata may not be available yet
677
+ }
678
+ }
679
+ else if (relMeta.target && relMeta.filter !== false) {
680
+ try {
681
+ const TargetClass = relMeta.target();
682
+ const filter = buildConformanceFilter(relMeta.predicate, TargetClass);
683
+ if (filter) {
684
+ relShape.getter = filter.getter;
685
+ relShape.conformanceConditions = filter.conformanceConditions;
686
+ }
687
+ }
688
+ catch (e) {
689
+ // Target class may not be available yet — getter will be
690
+ // absent and runtime will fall back to unfiltered get_links
691
+ }
692
+ }
693
+ // === sh:class — target shape reference ===
694
+ // Always set when a target model is declared, regardless of filter.
695
+ // This enables typed construction on the Rust/MCP side.
696
+ if (relMeta.target) {
697
+ try {
698
+ const TargetClass = relMeta.target();
699
+ const targetSHACL = TargetClass.generateSHACL?.();
700
+ if (targetSHACL?.shape?.nodeShapeUri) {
701
+ relShape.class = targetSHACL.shape.nodeShapeUri;
702
+ }
703
+ }
704
+ catch (e) {
705
+ // Target class may not be available yet
706
+ }
707
+ }
601
708
  shape.addProperty(relShape);
602
709
  }
603
710
  // Always set constructor and destructor actions on the shape, even
@@ -758,10 +865,36 @@ export function ReadOnly(opts) {
758
865
  */
759
866
  function resolveRelationArgs(first, second) {
760
867
  const opts = typeof first === 'function'
761
- ? { ...second, target: first }
868
+ ? { ...(second || {}), target: first }
762
869
  : first;
870
+ // getter is mutually exclusive with through, target, and where
871
+ if (opts.getter) {
872
+ if (opts.through) {
873
+ throw new Error('Relation decorator: `getter` and `through` are mutually exclusive. ' +
874
+ 'Use `getter` alone for custom read-only relations, or `through` ' +
875
+ '(with optional `target`) for standard link-based relations.');
876
+ }
877
+ if (opts.target) {
878
+ throw new Error('Relation decorator: `getter` and `target` are mutually exclusive. ' +
879
+ '`target` auto-generates a conformance getter from the model shape; ' +
880
+ 'providing both is contradictory.');
881
+ }
882
+ if (opts.where) {
883
+ throw new Error('Relation decorator: `where` and `getter` are mutually exclusive. ' +
884
+ 'Use `where` for DSL-based filtering, or `getter` for raw SurrealQL.');
885
+ }
886
+ return opts;
887
+ }
888
+ // Default predicate when not provided
763
889
  if (!opts.through) {
764
- throw new Error(`Relation decorator requires a { through: '...' } option specifying the predicate URI.`);
890
+ opts.through = 'ad4m://has_child';
891
+ }
892
+ // where validation
893
+ if (opts.where) {
894
+ if (opts.filter === false) {
895
+ throw new Error('Relation decorator: `where` and `filter: false` are contradictory. ' +
896
+ '`where` adds filtering constraints; `filter: false` disables filtering.');
897
+ }
765
898
  }
766
899
  return opts;
767
900
  }
@@ -779,18 +912,23 @@ export function HasMany(first, second) {
779
912
  kind: 'hasMany',
780
913
  local: opts.local,
781
914
  ...(opts.getter && { getter: opts.getter }),
915
+ ...(opts.filter !== undefined && { filter: opts.filter }),
916
+ ...(opts.where && { where: opts.where }),
782
917
  };
783
- // Add prototype methods for add/remove/set
784
918
  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
- };
919
+ // Only add mutation methods when a predicate is available
920
+ // (getter-only relations are read-only)
921
+ if (opts.through) {
922
+ target[`add${capitalize(relKey)}`] = async function (arg, batchId) {
923
+ return this.addRelationValue(relKey, arg, batchId);
924
+ };
925
+ target[`remove${capitalize(relKey)}`] = async function (arg, batchId) {
926
+ return this.removeRelationValue(relKey, arg, batchId);
927
+ };
928
+ target[`set${capitalize(relKey)}`] = async function (arg, batchId) {
929
+ return this.setRelationValues(relKey, arg, batchId);
930
+ };
931
+ }
794
932
  Object.defineProperty(target, relKey, { configurable: true, writable: true });
795
933
  };
796
934
  }
@@ -807,24 +945,31 @@ export function HasOne(first, second) {
807
945
  kind: 'hasOne',
808
946
  maxCount: 1,
809
947
  local: opts.local,
948
+ ...(opts.filter !== undefined && { filter: opts.filter }),
949
+ ...(opts.where && { where: opts.where }),
810
950
  };
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
951
  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
- };
952
+ if (opts.through) {
953
+ // Register as a writable property
954
+ applyPropertyMetadata({
955
+ through: opts.through,
956
+ readOnly: false,
957
+ local: opts.local,
958
+ })(target, key);
959
+ // Add prototype methods for add/remove/set (mirroring @HasMany)
960
+ target[`add${capitalize(relKey)}`] = async function (arg) {
961
+ return this.addRelationValue(relKey, arg);
962
+ };
963
+ target[`remove${capitalize(relKey)}`] = async function (arg) {
964
+ return this.removeRelationValue(relKey, arg);
965
+ };
966
+ target[`set${capitalize(relKey)}`] = async function (arg) {
967
+ return this.setRelationValues(relKey, arg);
968
+ };
969
+ }
970
+ else {
971
+ Object.defineProperty(target, relKey, { configurable: true, writable: true });
972
+ }
828
973
  };
829
974
  }
830
975
  export function BelongsToOne(first, second) {
@@ -840,13 +985,20 @@ export function BelongsToOne(first, second) {
840
985
  kind: 'belongsToOne',
841
986
  maxCount: 1,
842
987
  local: opts.local,
988
+ ...(opts.filter !== undefined && { filter: opts.filter }),
989
+ ...(opts.where && { where: opts.where }),
843
990
  };
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);
991
+ if (opts.through) {
992
+ // Read-only property (the owning side manages the link)
993
+ applyPropertyMetadata({
994
+ through: opts.through,
995
+ readOnly: true,
996
+ local: opts.local,
997
+ })(target, key);
998
+ }
999
+ else {
1000
+ Object.defineProperty(target, key, { configurable: true, writable: true });
1001
+ }
850
1002
  };
851
1003
  }
852
1004
  export function BelongsToMany(first, second) {
@@ -862,6 +1014,8 @@ export function BelongsToMany(first, second) {
862
1014
  kind: 'belongsToMany',
863
1015
  local: opts.local,
864
1016
  ...(opts.getter && { getter: opts.getter }),
1017
+ ...(opts.filter !== undefined && { filter: opts.filter }),
1018
+ ...(opts.where && { where: opts.where }),
865
1019
  };
866
1020
  // @BelongsToMany is the inverse/read-only side — do NOT generate add*/remove*/set*
867
1021
  // prototype methods. Mutation must go through the owning side's @HasMany decorator.
@@ -0,0 +1 @@
1
+ export {};