@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.
- package/lib/index.cjs +565 -122
- package/lib/index.js +565 -123
- package/lib/src/model/Ad4mModel.d.ts +33 -3
- package/lib/src/model/Ad4mModel.js +155 -37
- package/lib/src/model/decorators.d.ts +73 -7
- package/lib/src/model/decorators.js +188 -34
- package/lib/src/model/relation-filtering.test.d.ts +1 -0
- package/lib/src/model/relation-filtering.test.js +838 -0
- package/lib/src/model/surreal-utils.d.ts +42 -0
- package/lib/src/model/surreal-utils.js +128 -0
- package/lib/src/shacl/SHACLShape.d.ts +23 -0
- package/lib/src/shacl/SHACLShape.js +45 -0
- package/package.json +1 -1
- package/src/model/Ad4mModel.ts +177 -40
- package/src/model/decorators.ts +268 -45
- package/src/model/relation-filtering.test.ts +804 -0
- package/src/model/surreal-utils.ts +147 -0
- package/src/shacl/SHACLShape.ts +83 -0
|
@@ -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
|
-
|
|
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
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
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
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
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
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
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 {};
|