@coasys/ad4m 0.13.1-staging.1 → 0.13.1-staging.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.
Files changed (222) hide show
  1. package/lib/index.cjs +3789 -1192
  2. package/lib/index.js +3783 -1193
  3. package/lib/src/generated/api/AgentsByDidsRequest.d.ts +3 -0
  4. package/lib/src/generated/api/CallSessionInfo.d.ts +23 -0
  5. package/lib/src/generated/api/DiscardBatchRequest.d.ts +3 -0
  6. package/lib/src/generated/api/Events.d.ts +13 -3
  7. package/lib/src/generated/api/Events.js +1 -0
  8. package/lib/src/generated/api/FlowStateChangedEvent.d.ts +38 -0
  9. package/lib/src/generated/api/FlowStateEntry.d.ts +18 -0
  10. package/lib/src/generated/api/FlowStateEntry.js +2 -0
  11. package/lib/src/generated/api/IceServer.d.ts +18 -0
  12. package/lib/src/generated/api/IceServer.js +2 -0
  13. package/lib/src/generated/api/OnlineAgent.d.ts +4 -0
  14. package/lib/src/generated/api/PerspectiveDiscardBatchParams.d.ts +4 -0
  15. package/lib/src/generated/api/PerspectiveDiscardBatchParams.js +2 -0
  16. package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +8 -0
  17. package/lib/src/generated/api/PerspectiveFlowFiredParams.js +2 -0
  18. package/lib/src/generated/api/PerspectiveFlowStatesParams.d.ts +11 -0
  19. package/lib/src/generated/api/PerspectiveFlowStatesParams.js +2 -0
  20. package/lib/src/generated/api/PerspectiveGetAllShaclParams.d.ts +7 -0
  21. package/lib/src/generated/api/PerspectiveGetAllShaclParams.js +2 -0
  22. package/lib/src/generated/api/PerspectiveModelQueryParams.d.ts +6 -1
  23. package/lib/src/generated/api/PerspectiveRemoveSubjectParams.d.ts +6 -0
  24. package/lib/src/generated/api/PerspectiveRemoveSubjectParams.js +2 -0
  25. package/lib/src/generated/api/PerspectiveResynced.d.ts +8 -0
  26. package/lib/src/generated/api/PerspectiveResynced.js +2 -0
  27. package/lib/src/generated/api/PerspectiveSubscribed.d.ts +10 -0
  28. package/lib/src/generated/api/PerspectiveSubscribed.js +2 -0
  29. package/lib/src/generated/api/PerspectiveUpdateSubjectParams.d.ts +10 -0
  30. package/lib/src/generated/api/PerspectiveUpdateSubjectParams.js +2 -0
  31. package/lib/src/generated/api/QuerySubscriptionUpdate.d.ts +19 -0
  32. package/lib/src/generated/api/QuerySubscriptionUpdate.js +2 -0
  33. package/lib/src/generated/api/QuerySubscriptionUpdateEvent.d.ts +7 -0
  34. package/lib/src/generated/api/QuerySubscriptionUpdateEvent.js +1 -0
  35. package/lib/src/generated/api/QueryUpdatesLagged.d.ts +7 -0
  36. package/lib/src/generated/api/QueryUpdatesLagged.js +2 -0
  37. package/lib/src/generated/api/RemoveSubjectRequest.d.ts +9 -0
  38. package/lib/src/generated/api/RemoveSubjectRequest.js +2 -0
  39. package/lib/src/generated/api/ResyncSubscriptionRequest.d.ts +3 -0
  40. package/lib/src/generated/api/ResyncSubscriptionRequest.js +2 -0
  41. package/lib/src/generated/api/RpcMethods.d.ts +134 -14
  42. package/lib/src/generated/api/RpcMethods.js +12 -0
  43. package/lib/src/generated/api/SfuAddIceCandidateParams.d.ts +8 -0
  44. package/lib/src/generated/api/SfuAddIceCandidateParams.js +2 -0
  45. package/lib/src/generated/api/SfuAnswerServerOfferParams.d.ts +8 -0
  46. package/lib/src/generated/api/SfuAnswerServerOfferParams.js +2 -0
  47. package/lib/src/generated/api/SfuCallJoinParams.d.ts +14 -0
  48. package/lib/src/generated/api/SfuCallJoinParams.js +2 -0
  49. package/lib/src/generated/api/SfuCallRenegotiationOffer.d.ts +30 -0
  50. package/lib/src/generated/api/SfuCallRenegotiationOffer.js +1 -0
  51. package/lib/src/generated/api/SfuCascadePipe.d.ts +4 -0
  52. package/lib/src/generated/api/SfuCascadePipe.js +2 -0
  53. package/lib/src/generated/api/SfuCascadeStatus.d.ts +8 -0
  54. package/lib/src/generated/api/SfuCascadeStatus.js +1 -0
  55. package/lib/src/generated/api/SfuConfig.d.ts +52 -0
  56. package/lib/src/generated/api/SfuConfig.js +1 -0
  57. package/lib/src/generated/api/SfuDataMessage.d.ts +24 -0
  58. package/lib/src/generated/api/SfuDataMessage.js +2 -0
  59. package/lib/src/generated/api/SfuEnsureMembershipParams.d.ts +4 -0
  60. package/lib/src/generated/api/SfuEnsureMembershipParams.js +2 -0
  61. package/lib/src/generated/api/SfuMigrateEvent.d.ts +21 -0
  62. package/lib/src/generated/api/SfuMigrateEvent.js +2 -0
  63. package/lib/src/generated/api/SfuNeighbourhoodParams.d.ts +3 -0
  64. package/lib/src/generated/api/SfuNeighbourhoodParams.js +2 -0
  65. package/lib/src/generated/api/SfuParticipantQualityPreference.d.ts +7 -0
  66. package/lib/src/generated/api/SfuParticipantQualityPreference.js +2 -0
  67. package/lib/src/generated/api/SfuPerspectiveParams.d.ts +6 -0
  68. package/lib/src/generated/api/SfuPerspectiveParams.js +2 -0
  69. package/lib/src/generated/api/SfuQualityPreferenceParams.d.ts +8 -0
  70. package/lib/src/generated/api/SfuQualityPreferenceParams.js +2 -0
  71. package/lib/src/generated/api/SfuRoomInfo.d.ts +11 -0
  72. package/lib/src/generated/api/SfuRoomInfo.js +1 -0
  73. package/lib/src/generated/api/SfuRoomParams.d.ts +4 -0
  74. package/lib/src/generated/api/SfuRoomParams.js +2 -0
  75. package/lib/src/generated/api/SfuRoomParticipantInfo.d.ts +11 -0
  76. package/lib/src/generated/api/SfuRoomParticipantInfo.js +2 -0
  77. package/lib/src/generated/api/SfuRoomRoster.d.ts +13 -0
  78. package/lib/src/generated/api/SfuRoomRoster.js +2 -0
  79. package/lib/src/generated/api/SfuSendDataParams.d.ts +10 -0
  80. package/lib/src/generated/api/SfuSendDataParams.js +2 -0
  81. package/lib/src/generated/api/SfuSetConfigParams.d.ts +5 -0
  82. package/lib/src/generated/api/SfuSetConfigParams.js +1 -0
  83. package/lib/src/generated/api/SfuStatus.d.ts +24 -0
  84. package/lib/src/generated/api/SfuStatus.js +2 -0
  85. package/lib/src/generated/api/TrackMapEntry.d.ts +17 -0
  86. package/lib/src/generated/api/TrackMapEntry.js +2 -0
  87. package/lib/src/generated/api/UpdateSubjectRequest.d.ts +12 -0
  88. package/lib/src/generated/api/UpdateSubjectRequest.js +2 -0
  89. package/lib/src/generated/api/index.d.ts +3 -0
  90. package/lib/src/index.d.ts +7 -0
  91. package/lib/src/index.js +4 -0
  92. package/lib/src/model/Ad4mModel.d.ts +84 -0
  93. package/lib/src/model/Ad4mModel.js +234 -4
  94. package/lib/src/model/ModelQueryBuilder.d.ts +16 -35
  95. package/lib/src/model/ModelQueryBuilder.js +88 -270
  96. package/lib/src/model/decorators.d.ts +32 -0
  97. package/lib/src/model/decorators.js +40 -1
  98. package/lib/src/model/shacl-gen.d.ts +3 -1
  99. package/lib/src/model/shacl-gen.js +13 -1
  100. package/lib/src/model/types.d.ts +7 -0
  101. package/lib/src/neighbourhood/MeshManager.d.ts +384 -0
  102. package/lib/src/neighbourhood/MeshManager.js +1144 -0
  103. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +91 -0
  104. package/lib/src/neighbourhood/NeighbourhoodClient.js +196 -0
  105. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +55 -1
  106. package/lib/src/neighbourhood/NeighbourhoodProxy.js +170 -3
  107. package/lib/src/neighbourhood/Session.d.ts +105 -0
  108. package/lib/src/neighbourhood/Session.js +412 -0
  109. package/lib/src/neighbourhood/SfuManager.d.ts +174 -0
  110. package/lib/src/neighbourhood/SfuManager.js +619 -0
  111. package/lib/src/neighbourhood/SfuTypes.d.ts +35 -0
  112. package/lib/src/neighbourhood/SfuTypes.js +8 -0
  113. package/lib/src/perspectives/FlowInstance.d.ts +63 -24
  114. package/lib/src/perspectives/FlowInstance.js +74 -31
  115. package/lib/src/perspectives/FlowModels.d.ts +0 -16
  116. package/lib/src/perspectives/FlowModels.js +8 -16
  117. package/lib/src/perspectives/LiveQuery.d.ts +49 -0
  118. package/lib/src/perspectives/LiveQuery.js +169 -0
  119. package/lib/src/perspectives/PerspectiveClient.d.ts +24 -15
  120. package/lib/src/perspectives/PerspectiveClient.js +33 -36
  121. package/lib/src/perspectives/PerspectiveProxy.d.ts +67 -167
  122. package/lib/src/perspectives/PerspectiveProxy.js +121 -475
  123. package/lib/src/perspectives/TextContent.d.ts +31 -0
  124. package/lib/src/perspectives/TextContent.js +52 -0
  125. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +23 -0
  126. package/lib/src/perspectives/WakerSubscriptionManager.js +58 -17
  127. package/lib/src/shacl/SHACLFlow.d.ts +7 -4
  128. package/lib/src/shacl/SHACLFlow.js +7 -4
  129. package/lib/src/shacl/SHACLShape.d.ts +9 -0
  130. package/lib/src/shacl/SHACLShape.js +37 -0
  131. package/package.json +2 -2
  132. package/pnpm-workspace.yaml +4 -1
  133. package/src/Ad4mClient.test.ts +89 -17
  134. package/src/generated/api/AgentsByDidsRequest.ts +3 -0
  135. package/src/generated/api/CallSessionInfo.ts +20 -0
  136. package/src/generated/api/DiscardBatchRequest.ts +3 -0
  137. package/src/generated/api/Events.ts +14 -3
  138. package/src/generated/api/FlowStateChangedEvent.ts +36 -0
  139. package/src/generated/api/FlowStateEntry.ts +18 -0
  140. package/src/generated/api/IceServer.ts +19 -0
  141. package/src/generated/api/OnlineAgent.ts +6 -1
  142. package/src/generated/api/PerspectiveDiscardBatchParams.ts +3 -0
  143. package/src/generated/api/PerspectiveFlowFiredParams.ts +7 -0
  144. package/src/generated/api/PerspectiveFlowStatesParams.ts +11 -0
  145. package/src/generated/api/PerspectiveGetAllShaclParams.ts +6 -0
  146. package/src/generated/api/PerspectiveModelQueryParams.ts +5 -1
  147. package/src/generated/api/PerspectiveRemoveSubjectParams.ts +3 -0
  148. package/src/generated/api/PerspectiveResynced.ts +7 -0
  149. package/src/generated/api/PerspectiveSubscribed.ts +8 -0
  150. package/src/generated/api/PerspectiveUpdateSubjectParams.ts +7 -0
  151. package/src/generated/api/QuerySubscriptionUpdate.ts +10 -0
  152. package/src/generated/api/QuerySubscriptionUpdateEvent.ts +9 -0
  153. package/src/generated/api/QueryUpdatesLagged.ts +7 -0
  154. package/src/generated/api/RemoveSubjectRequest.ts +7 -0
  155. package/src/generated/api/ResyncSubscriptionRequest.ts +3 -0
  156. package/src/generated/api/RpcMethods.ts +68 -8
  157. package/src/generated/api/SfuAddIceCandidateParams.ts +7 -0
  158. package/src/generated/api/SfuAnswerServerOfferParams.ts +7 -0
  159. package/src/generated/api/SfuCallJoinParams.ts +13 -0
  160. package/src/generated/api/SfuCallRenegotiationOffer.ts +29 -0
  161. package/src/generated/api/SfuCascadePipe.ts +3 -0
  162. package/src/generated/api/SfuCascadeStatus.ts +7 -0
  163. package/src/generated/api/SfuConfig.ts +53 -0
  164. package/src/generated/api/SfuDataMessage.ts +23 -0
  165. package/src/generated/api/SfuEnsureMembershipParams.ts +3 -0
  166. package/src/generated/api/SfuMigrateEvent.ts +20 -0
  167. package/src/generated/api/{KeepAliveQueryRequest.ts → SfuNeighbourhoodParams.ts} +1 -1
  168. package/src/generated/api/SfuParticipantQualityPreference.ts +6 -0
  169. package/src/generated/api/{PerspectiveSubscribeQueryResult.ts → SfuPerspectiveParams.ts} +4 -1
  170. package/src/generated/api/SfuQualityPreferenceParams.ts +7 -0
  171. package/src/generated/api/SfuRoomInfo.ts +7 -0
  172. package/src/generated/api/SfuRoomParams.ts +3 -0
  173. package/src/generated/api/SfuRoomParticipantInfo.ts +8 -0
  174. package/src/generated/api/SfuRoomRoster.ts +12 -0
  175. package/src/generated/api/SfuSendDataParams.ts +7 -0
  176. package/src/generated/api/SfuSetConfigParams.ts +4 -0
  177. package/src/generated/api/SfuStatus.ts +24 -0
  178. package/src/generated/api/TrackMapEntry.ts +18 -0
  179. package/src/generated/api/UpdateSubjectRequest.ts +10 -0
  180. package/src/generated/api/index.ts +3 -0
  181. package/src/index.ts +7 -0
  182. package/src/model/Ad4mModel.test.ts +255 -231
  183. package/src/model/Ad4mModel.ts +271 -4
  184. package/src/model/ModelQueryBuilder.ts +103 -310
  185. package/src/model/abstract-classes.test.ts +225 -0
  186. package/src/model/decorators.ts +81 -0
  187. package/src/model/shacl-gen.ts +13 -0
  188. package/src/model/types.ts +7 -0
  189. package/src/neighbourhood/MeshManager.test.ts +2640 -0
  190. package/src/neighbourhood/MeshManager.ts +1350 -0
  191. package/src/neighbourhood/NeighbourhoodClient.ts +271 -0
  192. package/src/neighbourhood/NeighbourhoodProxy.test.ts +23 -0
  193. package/src/neighbourhood/NeighbourhoodProxy.ts +247 -1
  194. package/src/neighbourhood/Session.test.ts +800 -0
  195. package/src/neighbourhood/Session.ts +525 -0
  196. package/src/neighbourhood/SfuManager.test.ts +677 -0
  197. package/src/neighbourhood/SfuManager.ts +803 -0
  198. package/src/neighbourhood/SfuTypes.ts +40 -0
  199. package/src/perspectives/FlowInstance.ts +108 -31
  200. package/src/perspectives/FlowModels.ts +8 -18
  201. package/src/perspectives/LiveQuery.test.ts +197 -0
  202. package/src/perspectives/LiveQuery.ts +189 -0
  203. package/src/perspectives/PerspectiveClient.ts +51 -51
  204. package/src/perspectives/PerspectiveProxy.test.ts +85 -401
  205. package/src/perspectives/PerspectiveProxy.ts +126 -536
  206. package/src/perspectives/TextContent.test.ts +123 -0
  207. package/src/perspectives/TextContent.ts +36 -0
  208. package/src/perspectives/WakerSubscriptionManager.test.ts +88 -6
  209. package/src/perspectives/WakerSubscriptionManager.ts +69 -18
  210. package/src/shacl/SHACLFlow.ts +7 -4
  211. package/src/shacl/SHACLShape.test.ts +2 -1
  212. package/src/shacl/SHACLShape.ts +49 -0
  213. package/lib/src/generated/api/KeepAliveQueryRequest.d.ts +0 -3
  214. package/lib/src/generated/api/PerspectiveModelSubscribeResult.d.ts +0 -7
  215. package/lib/src/generated/api/PerspectiveQuerySubscriptionFilter.d.ts +0 -6
  216. package/lib/src/generated/api/PerspectiveSubscribeQueryResult.d.ts +0 -4
  217. package/src/generated/api/PerspectiveModelSubscribeResult.ts +0 -6
  218. package/src/generated/api/PerspectiveQuerySubscriptionFilter.ts +0 -3
  219. /package/lib/src/generated/api/{KeepAliveQueryRequest.js → AgentsByDidsRequest.js} +0 -0
  220. /package/lib/src/generated/api/{PerspectiveModelSubscribeResult.js → CallSessionInfo.js} +0 -0
  221. /package/lib/src/generated/api/{PerspectiveQuerySubscriptionFilter.js → DiscardBatchRequest.js} +0 -0
  222. /package/lib/src/generated/api/{PerspectiveSubscribeQueryResult.js → FlowStateChangedEvent.js} +0 -0
@@ -0,0 +1,225 @@
1
+ /**
2
+ * Abstract classes and aliases (#1435): what `@Model({ abstract })`,
3
+ * `@Property({ alias })` and `@Model({ implements })` put into the SHACL, the
4
+ * `implements` check, and where writes through an abstract class go.
5
+ */
6
+ import { Ad4mModel } from "./Ad4mModel";
7
+ import { Model, Property, HasMany } from "./decorators";
8
+ import { SHACLShape } from "../shacl/SHACLShape";
9
+
10
+ @Model({ name: "Readable", abstract: true })
11
+ class Readable extends Ad4mModel {
12
+ @Property({ through: "test://text" })
13
+ text: string = "";
14
+ }
15
+
16
+ @Model({ name: "Folderish", abstract: true })
17
+ class Folderish extends Ad4mModel {
18
+ @HasMany({ through: "test://child" })
19
+ children: string[] = [];
20
+ }
21
+
22
+ describe("abstract classes", () => {
23
+ it("writes one marker on the shape node, in JSON and in links", () => {
24
+ const { shape } = (Readable as any).generateSHACL();
25
+ expect((shape.toJSON() as any).abstract).toBe(true);
26
+ const markers = shape.toLinks().filter((l: any) => l.predicate === "ad4m://abstract");
27
+ expect(markers).toEqual([
28
+ { source: shape.nodeShapeUri, predicate: "ad4m://abstract", target: "literal:true" },
29
+ ]);
30
+ expect(SHACLShape.fromLinks(shape.toLinks(), shape.nodeShapeUri).isAbstract).toBe(true);
31
+ expect(SHACLShape.fromJSON(shape.toJSON()).isAbstract).toBe(true);
32
+ });
33
+
34
+ it("writes no marker on a concrete class", () => {
35
+ @Model({ name: "PlainNote" })
36
+ class PlainNote extends Ad4mModel {
37
+ @Property({ through: "test://text" })
38
+ text: string = "";
39
+ }
40
+ const { shape } = (PlainNote as any).generateSHACL();
41
+ expect((shape.toJSON() as any).abstract).toBeUndefined();
42
+ expect(shape.toLinks().some((l: any) => l.predicate === "ad4m://abstract")).toBe(false);
43
+ });
44
+
45
+ it("carries a property's and a relation's alias through JSON and links", () => {
46
+ @Model({ name: "AliasedMessage", implements: [Readable, Folderish] })
47
+ class AliasedMessage extends Ad4mModel {
48
+ @Property({ through: "test://body", alias: { Readable: "text" } })
49
+ body: string = "";
50
+
51
+ @HasMany({ through: "test://reply", alias: { Folderish: "children" } })
52
+ replies: string[] = [];
53
+ }
54
+ const { shape } = (AliasedMessage as any).generateSHACL();
55
+ const json: any = shape.toJSON();
56
+ expect(json.properties.find((p: any) => p.name === "body").alias).toEqual({ Readable: "text" });
57
+ expect(json.properties.find((p: any) => p.name === "replies").alias).toEqual({ Folderish: "children" });
58
+
59
+ const alias = shape.toLinks().find(
60
+ (l: any) => l.predicate === "ad4m://alias" && l.source.endsWith("AliasedMessage.body"),
61
+ );
62
+ expect(alias.target).toBe(`literal:string:${encodeURIComponent('{"Readable":"text"}')}`);
63
+
64
+ const back = SHACLShape.fromLinks(shape.toLinks(), shape.nodeShapeUri);
65
+ expect(back.properties.find((p) => p.name === "body")!.alias).toEqual({ Readable: "text" });
66
+ expect(SHACLShape.fromJSON(json).properties.find((p) => p.name === "replies")!.alias)
67
+ .toEqual({ Folderish: "children" });
68
+ });
69
+
70
+ it("implements: a property or relation name or alias must cover every name", () => {
71
+ expect(() => {
72
+ @Model({ name: "Mute", implements: [Readable] })
73
+ class Mute extends Ad4mModel {
74
+ @Property({ through: "test://body" })
75
+ body: string = "";
76
+ }
77
+ }).toThrow("Mute implements Readable but has no property or alias named `text`");
78
+
79
+ // An alias for another abstract class does not count.
80
+ expect(() => {
81
+ @Model({ name: "Elsewhere", implements: [Readable] })
82
+ class Elsewhere extends Ad4mModel {
83
+ @Property({ through: "test://body", alias: { Other: "text" } })
84
+ body: string = "";
85
+ }
86
+ }).toThrow("Elsewhere implements Readable but has no property or alias named `text`");
87
+
88
+ // A relation does not stand in for a property, nor a property for a relation.
89
+ expect(() => {
90
+ @Model({ name: "Crossed", implements: [Folderish] })
91
+ class Crossed extends Ad4mModel {
92
+ @Property({ through: "test://children" })
93
+ children: string = "";
94
+ }
95
+ }).toThrow("Crossed implements Folderish but has no relation or alias named `children`");
96
+
97
+ // Its own name is enough.
98
+ expect(() => {
99
+ @Model({ name: "Plain", implements: [Readable] })
100
+ class Plain extends Ad4mModel {
101
+ @Property({ through: "test://other_text" })
102
+ text: string = "";
103
+ }
104
+ }).not.toThrow();
105
+ });
106
+
107
+ it("implements: only abstract classes", () => {
108
+ @Model({ name: "Concrete" })
109
+ class Concrete extends Ad4mModel {
110
+ @Property({ through: "test://text" })
111
+ text: string = "";
112
+ }
113
+ expect(() => {
114
+ @Model({ name: "Wrong", implements: [Concrete] })
115
+ class Wrong extends Ad4mModel {
116
+ @Property({ through: "test://text" })
117
+ text: string = "";
118
+ }
119
+ }).toThrow("Wrong implements Concrete, which is not an abstract class");
120
+ });
121
+
122
+ it("save() refuses an abstract class before touching the perspective", async () => {
123
+ const perspective: any = new Proxy({}, {
124
+ get: () => () => { throw new Error("the perspective was touched"); },
125
+ });
126
+ const instance = new Readable(perspective);
127
+ await expect(instance.save()).rejects.toThrow("'Readable' is an abstract class and cannot be created");
128
+ });
129
+
130
+ it("save() and delete() through an abstract class go to the executor's dispatch", async () => {
131
+ const calls: any[][] = [];
132
+ const perspective: any = new Proxy({}, {
133
+ get: (_t, key) => async (...args: any[]) => {
134
+ calls.push([key, ...args]);
135
+ if (key === "modelQuery") {
136
+ return { instances: [{ id: "ad4m://m/1", __subjectClass: "Message", text: "hi" }], totalCount: 1 };
137
+ }
138
+ return [];
139
+ },
140
+ });
141
+ const [row] = await Readable.findAll(perspective);
142
+ row.text = "edited";
143
+ calls.length = 0;
144
+ await row.save("batch");
145
+ expect(calls).toEqual([["updateSubject", "Readable", "ad4m://m/1", { text: "edited" }, "batch"]]);
146
+
147
+ calls.length = 0;
148
+ await row.delete("batch");
149
+ expect(calls[0][0]).toBe("removeSubject");
150
+ expect(calls[0][2]).toBe("ad4m://m/1");
151
+ });
152
+
153
+ it("add/remove/set of a relation through an abstract class go to the executor's dispatch", async () => {
154
+ const calls: any[][] = [];
155
+ const perspective: any = new Proxy({}, {
156
+ get: (_t, key) => async (...args: any[]) => {
157
+ calls.push([key, ...args]);
158
+ if (key === "modelQuery") {
159
+ return { instances: [{ id: "ad4m://folder/1", __subjectClass: "Folder", children: [] }], totalCount: 1 };
160
+ }
161
+ return [];
162
+ },
163
+ });
164
+ const [row]: any[] = await Folderish.findAll(perspective);
165
+ calls.length = 0;
166
+ await row.addChildren("ad4m://child/1", "batch");
167
+ await row.removeChildren(["ad4m://child/1"], "batch");
168
+ await row.setChildren([{ id: "ad4m://child/2" }, "ad4m://child/3"], "batch");
169
+ // No link at the abstract predicate (test://child): only the dispatch.
170
+ expect(calls).toEqual([
171
+ ["updateSubject", "Folderish", "ad4m://folder/1", { children: { action: "adder", value: ["ad4m://child/1"] } }, "batch"],
172
+ ["updateSubject", "Folderish", "ad4m://folder/1", { children: { action: "remover", value: ["ad4m://child/1"] } }, "batch"],
173
+ ["updateSubject", "Folderish", "ad4m://folder/1", { children: { action: "setter", value: ["ad4m://child/2", "ad4m://child/3"] } }, "batch"],
174
+ ]);
175
+ });
176
+
177
+ it("save() through an abstract class sends a changed relation's members as IDs", async () => {
178
+ const calls: any[][] = [];
179
+ const perspective: any = new Proxy({}, {
180
+ get: (_t, key) => async (...args: any[]) => {
181
+ calls.push([key, ...args]);
182
+ if (key === "modelQuery") {
183
+ return { instances: [{ id: "ad4m://folder/1", __subjectClass: "Folder", children: [] }], totalCount: 1 };
184
+ }
185
+ return [];
186
+ },
187
+ });
188
+ const [row]: any[] = await Folderish.findAll(perspective);
189
+ row.children = [{ id: "ad4m://child/2" }, "ad4m://child/3"];
190
+ calls.length = 0;
191
+ await row.save("batch");
192
+ expect(calls).toEqual([
193
+ ["updateSubject", "Folderish", "ad4m://folder/1", { children: ["ad4m://child/2", "ad4m://child/3"] }, "batch"],
194
+ ]);
195
+ });
196
+
197
+ it("save() through an abstract class keeps a relation's action envelope", async () => {
198
+ const calls: any[][] = [];
199
+ const perspective: any = new Proxy({}, {
200
+ get: (_t, key) => async (...args: any[]) => {
201
+ calls.push([key, ...args]);
202
+ if (key === "modelQuery") {
203
+ return { instances: [{ id: "ad4m://folder/1", __subjectClass: "Folder", children: ["ad4m://child/1"] }], totalCount: 1 };
204
+ }
205
+ return [];
206
+ },
207
+ });
208
+ const [row]: any[] = await Folderish.findAll(perspective);
209
+ const sent = async (children: any) => {
210
+ row.children = children;
211
+ calls.length = 0;
212
+ await row.save("batch");
213
+ return calls.find((c) => c[0] === "updateSubject")?.[3];
214
+ };
215
+ expect(await sent({ action: "adder", value: [{ id: "ad4m://child/2" }] })).toEqual({
216
+ children: { action: "adder", value: ["ad4m://child/2"] },
217
+ });
218
+ expect(await sent({ action: "remover", value: "ad4m://child/1" })).toEqual({
219
+ children: { action: "remover", value: "ad4m://child/1" },
220
+ });
221
+ expect(await sent({ action: "other", value: ["ad4m://child/3"] })).toEqual({
222
+ children: { action: "setter", value: ["ad4m://child/3"] },
223
+ });
224
+ });
225
+ });
@@ -74,6 +74,8 @@ export interface RelationMetadataEntry {
74
74
  * memoized registry copy.
75
75
  */
76
76
  interpretationHint?: string;
77
+ /** Names for abstract classes — see `RelationOptions.alias`. */
78
+ alias?: Record<string, string>;
77
79
  }
78
80
 
79
81
  /** Registry of property metadata keyed by constructor → { propName → metadata } */
@@ -216,6 +218,8 @@ export function setRelationRegistryEntry(
216
218
  export interface Ad4mModelLike {
217
219
  new (...args: any[]): any;
218
220
  className?: string;
221
+ /** Set by `@Model({ abstract: true })`. */
222
+ isAbstract?: boolean;
219
223
  generateSDNA?: () => any;
220
224
  generateSHACL?: () => any;
221
225
  }
@@ -401,6 +405,14 @@ export interface PropertyOptions {
401
405
  * (e.g. `"xsd://string"`) and enables the hydration decode gate.
402
406
  */
403
407
  datatype?: string;
408
+
409
+ /**
410
+ * The name this property answers to through an abstract class, keyed by
411
+ * its name: `alias: { TextContent: "text" }` reads (and writes) `body` as
412
+ * `text` through `TextContent`. Registering fails if the class already
413
+ * uses that name.
414
+ */
415
+ alias?: Record<string, string>;
404
416
  }
405
417
 
406
418
 
@@ -573,6 +585,23 @@ export interface ModelConfig {
573
585
  */
574
586
  name: string;
575
587
 
588
+ /**
589
+ * An abstract class names properties a record has, not what it is.
590
+ * Querying it reads every installed class that has all of its names (or
591
+ * aliases for them), matched by name, never by `through`; rows keep
592
+ * their `__subjectClass`. It cannot be created. `save()` and `delete()`
593
+ * on a row read through it run the setters and destructors of the
594
+ * record's own classes; values are not converted between them.
595
+ */
596
+ abstract?: boolean;
597
+
598
+ /**
599
+ * Abstract classes this class is meant to be read through: checked at
600
+ * declaration (every name of each must be a name or alias here). The
601
+ * executor matches by structure, listed or not.
602
+ */
603
+ implements?: Ad4mModelLike[];
604
+
576
605
  /**
577
606
  * Natural-language hint that steers the generic LLM extractor when
578
607
  * turning a transcript into instances of this class. Emitted as an
@@ -582,6 +611,42 @@ export interface ModelConfig {
582
611
  interpretationHint?: string;
583
612
  }
584
613
 
614
+ /**
615
+ * `@Model({ implements })`: every property and relation name of
616
+ * `abstractClass` must be a name or an alias (for it) on `target`.
617
+ */
618
+ function checkImplements(name: string, target: any, abstractClass: any) {
619
+ const abstractName: string | undefined = abstractClass?.className ?? abstractClass?.prototype?.className;
620
+ if (!abstractName || !abstractClass.isAbstract) {
621
+ throw new Error(
622
+ `${name} implements ${abstractName ?? abstractClass?.name ?? String(abstractClass)}, ` +
623
+ `which is not an abstract class: declare it with @Model({ abstract: true })`
624
+ );
625
+ }
626
+ const names = (ctor: any) => {
627
+ const relations = getRelationsMetadata(ctor);
628
+ const properties = Object.keys(getPropertiesMetadata(ctor)).filter(p => !relations[p]);
629
+ return { properties, relations: Object.keys(relations) };
630
+ };
631
+ const answersTo = (entries: Record<string, { alias?: Record<string, string> }>, keys: string[]) =>
632
+ new Set(keys.map(k => entries[k]?.alias?.[abstractName] ?? k));
633
+
634
+ const wanted = names(abstractClass);
635
+ const own = names(target);
636
+ const ownProperties = answersTo(getPropertiesMetadata(target), own.properties);
637
+ const ownRelations = answersTo(getRelationsMetadata(target), own.relations);
638
+ for (const p of wanted.properties) {
639
+ if (!ownProperties.has(p)) {
640
+ throw new Error(`${name} implements ${abstractName} but has no property or alias named \`${p}\``);
641
+ }
642
+ }
643
+ for (const r of wanted.relations) {
644
+ if (!ownRelations.has(r)) {
645
+ throw new Error(`${name} implements ${abstractName} but has no relation or alias named \`${r}\``);
646
+ }
647
+ }
648
+ }
649
+
585
650
  /**
586
651
  * Decorator for defining model classes in AD4M.
587
652
  *
@@ -642,6 +707,10 @@ export function Model(opts: ModelConfig) {
642
707
  return function (target: any) {
643
708
  target.prototype.className = opts.name;
644
709
  target.className = opts.name;
710
+ target.isAbstract = !!opts.abstract;
711
+ for (const abstractClass of opts.implements ?? []) {
712
+ checkImplements(opts.name, target, abstractClass);
713
+ }
645
714
 
646
715
  target.generateSDNA = function() {
647
716
  return buildSDNA(
@@ -661,6 +730,7 @@ export function Model(opts: ModelConfig) {
661
730
  buildConformanceFilter,
662
731
  seed,
663
732
  opts.interpretationHint,
733
+ !!opts.abstract,
664
734
  ));
665
735
  }
666
736
 
@@ -1018,6 +1088,13 @@ export interface RelationOptions {
1018
1088
  * ```
1019
1089
  */
1020
1090
  interpretationHint?: string;
1091
+
1092
+ /**
1093
+ * The name this relation answers to when its class is read through an
1094
+ * abstract class, keyed by the abstract class's name. See
1095
+ * `PropertyOptions.alias`.
1096
+ */
1097
+ alias?: Record<string, string>;
1021
1098
  }
1022
1099
 
1023
1100
  /**
@@ -1187,6 +1264,7 @@ export function HasMany(
1187
1264
  ...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
1188
1265
  ...(opts.ordering && { ordering: opts.ordering }),
1189
1266
  ...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
1267
+ ...(opts.alias && { alias: opts.alias }),
1190
1268
  ...(opts.readOnly && { readOnly: true }),
1191
1269
  };
1192
1270
 
@@ -1265,6 +1343,7 @@ export function HasOne(
1265
1343
  ...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
1266
1344
  ...(opts.ordering && { ordering: opts.ordering }),
1267
1345
  ...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
1346
+ ...(opts.alias && { alias: opts.alias }),
1268
1347
  ...(opts.readOnly && { readOnly: true }),
1269
1348
  };
1270
1349
 
@@ -1355,6 +1434,7 @@ export function BelongsToOne(
1355
1434
  ...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
1356
1435
  ...(opts.ordering && { ordering: opts.ordering }),
1357
1436
  ...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
1437
+ ...(opts.alias && { alias: opts.alias }),
1358
1438
  };
1359
1439
 
1360
1440
  if (opts.through) {
@@ -1418,6 +1498,7 @@ export function BelongsToMany(
1418
1498
  ...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
1419
1499
  ...(opts.ordering && { ordering: opts.ordering }),
1420
1500
  ...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
1501
+ ...(opts.alias && { alias: opts.alias }),
1421
1502
  };
1422
1503
 
1423
1504
  // @BelongsToMany is the inverse/read-only side — do NOT generate add*/remove*/set*
@@ -52,6 +52,8 @@ export function buildSHACL(
52
52
  * an `ad4m://interpretation_hint` link by `SHACLShape.toLinks()`.
53
53
  */
54
54
  interpretationHint?: string,
55
+ /** `@Model({ abstract: true })`: emitted as one `ad4m://abstract` link. */
56
+ isAbstract?: boolean,
55
57
  ): { shape: SHACLShape; name: string } {
56
58
  const obj = target.prototype;
57
59
 
@@ -86,6 +88,9 @@ export function buildSHACL(
86
88
  if (interpretationHint) {
87
89
  shape.interpretationHint = interpretationHint;
88
90
  }
91
+ if (isAbstract) {
92
+ shape.isAbstract = true;
93
+ }
89
94
 
90
95
  // ── Seed the memoisation cache while we keep building ──────────────
91
96
  // Any subsequent `target.generateSHACL()` call from inside this
@@ -238,6 +243,11 @@ export function buildSHACL(
238
243
  propShape.identity = true;
239
244
  }
240
245
 
246
+ // Names for abstract classes (emitted as `ad4m://alias`).
247
+ if (propMeta.alias) {
248
+ propShape.alias = propMeta.alias;
249
+ }
250
+
241
251
  // ── Setter actions ──────────────────────────────────────────────
242
252
  if (propMeta.prologSetter) {
243
253
  console.warn(
@@ -350,6 +360,9 @@ export function buildSHACL(
350
360
  if (relMeta.interpretationHint) {
351
361
  relShape.interpretationHint = relMeta.interpretationHint;
352
362
  }
363
+ if (relMeta.alias) {
364
+ relShape.alias = relMeta.alias;
365
+ }
353
366
 
354
367
  // Adder / Remover actions — only meaningful for relations backed
355
368
  // by a real link predicate. Getter-only relations are read-only,
@@ -335,6 +335,13 @@ export type Query = {
335
335
  * Individual relations can still be overridden via `include` (explicit entries take precedence).
336
336
  */
337
337
  includeAll?: boolean;
338
+ /**
339
+ * For a query over several classes (`Ad4mModel.findAllOf` / `queryOf`):
340
+ * the class names a record that conforms to several of them is read as,
341
+ * most wanted first. Without it the most specific requested class wins.
342
+ * Ranks, never excludes. Ignored by a single-class query.
343
+ */
344
+ preferClasses?: string[];
338
345
  where?: Where;
339
346
  order?: Order;
340
347
  offset?: number;